适用场景在阿里云 Windows ECS 上部署 GitLab Runner用于 GitLab CI/CD 编译 WPF / .NET 项目。1. 部署目标本次部署的目标是让阿里云 Windows 服务器作为 GitLab Runner自动执行 GitLab CI/CD 流水线。你的项目 CI 大致会做这些事情GitLab 推送代码 ↓ GitLab Runner 接收任务 ↓ 拉取仓库1 ↓ 拉取仓库2 ↓ 执行 dotnet restore / dotnet publish ↓ 生成 zip 更新包 ↓ 上传更新包 ↓ 调用 MES 接口登记版本因为项目是 WPF / Windows 桌面程序所以 Runner 必须使用 Windows 环境推荐使用shell executor不要使用 Linux Docker。2. 服务器配置要求2.1 你的服务器配置你的阿里云服务器配置为系统Windows CPU4 核 内存8 GB 磁盘100 GB 用途部署 GitLab Runner 服务这个配置可以满足当前项目的 CI 编译需求。2.2 推荐配置Windows Server 2019 / 2022 / Windows 11 CPU4 核以上 内存8 GB 以上 磁盘100 GB 以上如果后续多个项目同时跑流水线建议提升到CPU8 核以上 内存16 GB 以上3. 服务器需要安装的软件需要安装 4 类软件1. Git for Windows 2. .NET 8 SDK 3. Visual Studio Build Tools 4. GitLab Runner for Windows其中软件作用Git for Windows让 Runner 可以执行git clone、git fetch、git checkout.NET 8 SDK编译 .NET 8 项目Visual Studio Build Tools提供 MSBuild、WPF 编译工具、Windows SDKGitLab Runner接收 GitLab CI/CD 任务并执行脚本4. 下载内容说明4.1 Git for Windows下载Git for Windows x64 Setup不要下载PortableGit ARM64 Source Code安装路径保持默认即可C:\Program Files\Git安装时推荐保持默认选项尤其注意 PATH 选项应选择Git from the command line and also from 3rd-party software安装后验证git --version正常示例git version 2.54.0.windows.14.2 .NET 8 SDK下载.NET 8 SDK Windows x64 Installer注意必须是SDK不是 Runtime。不要只下载.NET Runtime .NET Desktop Runtime ASP.NET Core Runtime安装后验证dotnet --list-sdks正常示例8.0.422 [C:\Program Files\dotnet\sdk] 10.0.301 [C:\Program Files\dotnet\sdk]只要能看到8.0.xxx说明 .NET 8 SDK 已经可用。4.3 Visual Studio Build Tools在 Visual Studio 下载页面中应该选择Visual Studio 2026 生成工具也就是英文中的Build Tools for Visual Studio不要选Visual Studio 2026 远程工具 Visual Studio Community Visual Studio Professional Visual Studio EnterpriseRunner 服务器只负责编译不需要完整 IDE。安装路径Build Tools 安装路径可以保持默认C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools不用改路径。默认路径最稳定MSBuild、vswhere 等工具都能自动识别。工作负载勾选必须勾选.NET 桌面生成工具英文一般是.NET desktop build tools这个工作负载会安装 WPF 编译所需的组件。单个组件建议建议保留.NET SDK .NET Framework 4.8 开发工具 MSBuild 工具 Windows SDK这些组件对 WPF / Windows 桌面项目比较关键。你看到的这些选项可以保留.NET Framework 4.8 开发工具 .NET SDK Windows Communication Foundation 生成工具 测试工具核心功能 - 生成工具 ClickOnce 生成工具其中真正必要的是.NET SDK .NET Framework 4.8 开发工具 .NET 桌面生成工具 MSBuild Windows SDK如果磁盘空间够保持默认勾选即可避免以后因为缺组件重新安装。验证 MSBuild安装完成后如果直接执行msbuild -version提示msbuild 不是内部或外部命令不一定代表安装失败可能只是 PATH 没有刷新。可以用完整路径验证C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin\MSBuild.exe -version正常示例MSBuild 版本 18.7.1如果完整路径可以运行说明 Build Tools 已安装成功。4.4 GitLab Runner for Windows下载gitlab-runner-windows-amd64.exe你的阿里云 Windows ECS 是 Intel / AMD 64 位架构所以选amd64。不要下载gitlab-runner-windows-arm64.exe gitlab-runner-windows-386.exe linux-amd64 darwin-amd64双击gitlab-runner-windows-amd64.exe会一闪而过这是正常的。它不是图形界面安装程序而是命令行程序必须在 CMD / PowerShell 中运行。5. GitLab Runner 文件放置位置如果服务器只有 C 盘推荐放在C:\GitLabRunner不要放在C:\Users\Administrator\Downloads C:\Users\Administrator\Desktop原因1. 下载目录容易被清理 2. 用户目录权限可能变化 3. Windows 服务长期运行时不稳定 4. 维护不方便创建目录管理员 CMD 中执行mkdir C:\GitLabRunner复制并重命名 Runner假设下载文件在C:\Users\Administrator\Downloads\gitlab-runner-windows-amd64.exe执行copy C:\Users\Administrator\Downloads\gitlab-runner-windows-amd64.exe C:\GitLabRunner\gitlab-runner.exe验证 Runnercd C:\GitLabRunner .\gitlab-runner.exe --version正常会显示版本信息例如Version: 19.0.1 Runtime platform archamd64 oswindows6. 重启服务器是否必要安装 Git、.NET SDK、Build Tools 后不强制要求立刻重启。但建议在注册 Runner 前重启一次原因是Git、dotnet、MSBuild 安装后会修改环境变量。 Runner 安装成 Windows 服务后会读取系统环境变量。 重启可以避免服务读取不到新环境变量。Windows Server 重启时可能会出现选择一个最能说明你要关闭这台计算机的原因这是 Windows Server 正常的关机/重启原因记录不是报错。可以选择其他计划内然后点击继续7. 注册 Runner 前的网络检查Runner 必须能访问 GitLab。你的 GitLab 地址是http://gitlab.xxxx注意注册 Runner 时填的是 GitLab 根地址不是项目地址。正确http://gitlab.xxxx7.1 测试 GitLab 域名是否可用管理员 CMD 中执行ping gitlab.xxxx如果出现lookup gitlab.xxxx: no such host或Ping 请求找不到主机 gitlab.xxxx说明阿里云服务器解析不了公司内网域名。8. 配置 hosts 解决 GitLab 域名解析问题你的服务器最终解析到了gitlab.xxxx - 10.xxx.xx.xx可以通过 hosts 文件固定解析。8.1 添加 hosts 记录管理员 CMD 执行echo 10.xxx.xx.xx gitlab.xxxx C:\Windows\System32\drivers\etc\hosts8.2 刷新 DNS 缓存ipconfig /flushdns8.3 验证ping gitlab.xxxx正确结果类似正在 Ping gitlab.xxxx [10.xxx.xx.xx] 具有 32 字节的数据: 来自 10.xxx.xx.xx 的回复: 字节32 时间3ms TTL59如果能 ping 通说明域名解析和网络都正常。如果 ping IP 也不通说明不是 hosts 问题而是阿里云服务器和公司内网不通需要运维处理 VPN、专线、NAT 或公网访问。9. 在 GitLab 页面创建 Runner进入 GitLab 项目项目名称 ↓ 设置 ↓ CI/CD ↓ Runner ↓ 新建项目 runner平台选择Windows这是正确的因为服务器是 Windows。创建后页面会显示一条命令类似.\gitlab-runner.exe register --url http://gitlab.xxxx --token glrt-xxxxxxxx这里的glrt-xxxxxxxx就是 Runner 身份验证令牌。10. 注册 Runner在服务器管理员 CMD 中执行cd C:\GitLabRunner .\gitlab-runner.exe register也可以直接使用 GitLab 页面给的完整命令.\gitlab-runner.exe register --url http://gitlab.xxxx --token glrt-你的token10.1 交互式填写说明GitLab instance URL填写http://gitlab.xxxx不要填项目地址也不要填gitlab-runner install命令。Registration token只填 token 本身glrt-xxxxxxxx不要填整条命令。错误示例.\gitlab-runner.exe register --url http://gitlab.xxxx --token glrt-xxxx这个不能填在 token 输入框里。Description / Name可以填aliyun-windows-runner也可以直接回车使用默认值。Tags必须填windows因为你的.gitlab-ci.yml中使用tags:-windows如果 Runner 没有windows标签流水线会一直 Pending。Maintenance note可以不填直接回车。Executor必须填shell不要选docker ssh kubernetes virtualbox parallels当前项目是 WPF / .NET Windows 项目需要在 Windows 本机环境编译所以使用shell。后续如果出现错误Runner 使用pwsh报错executable file not found in %PATH%错误现象第一次触发 CI 时Job 在Preparing environment阶段失败Using Shell (pwsh) executor... ERROR: Job failed (system failure): prepare environment: failed to start process: starting OS command: exec: pwsh: executable file not found in %PATH%原因GitLab Runner 的config.toml中配置了executor shell shell pwsh但是服务器没有安装 PowerShell 7或者pwsh.exe没有加入系统 PATH。pwsh是 PowerShell 7 / PowerShell Core 的命令不是 Windows Server 默认自带的powershell.exe。临时处理先把 Runner shell 改成 Windows 自带的 PowerShellshell powershell然后重启 Runnercd C:\GitLabRunner .\gitlab-runner.exe restart后续更优处理因为后续使用shell powershell时出现了 GitLab Runner 注入环境变量脚本解析异常所以最终建议安装 PowerShell 7再改回shell pwshpowershell -version命令报错错误现象在 CMD 中执行powershell -version提示参数 version 缺少参数。原因powershell -version不是查看 PowerShell 版本的正确命令。-Version参数用于指定启动的 PowerShell 版本不是输出版本号。正确验证命令在 CMD 中执行powershell -NoProfile -Command $PSVersionTable.PSVersion安装 PowerShell 7 后验证pwsh -NoLogo -NoProfile -Command $PSVersionTable.PSVersion确认pwsh路径where pwsh正常应输出C:\Program Files\PowerShell\7\pwsh.exe10.2 注册成功标志如果看到Runner registered successfully. Configuration was saved in C:\GitLabRunner\config.toml说明 Runner 已经成功注册。11. 安装 Runner 为 Windows 服务注册成功后还需要安装并启动服务。注意顺序必须先install再start。11.1 安装服务cd C:\GitLabRunner .\gitlab-runner.exe install11.2 启动服务.\gitlab-runner.exe start11.3 查看状态.\gitlab-runner.exe status正常结果类似gitlab-runner: Service is running12. 常见错误与解决方式12.1 双击 GitLab Runner 闪退原因gitlab-runner.exe 是命令行程序不是图形安装器。解决cd C:\GitLabRunner .\gitlab-runner.exe --version不要双击运行。12.2系统找不到指定的驱动器示例mkdir D:\GitLabRunner 系统找不到指定的驱动器。原因服务器没有 D 盘。解决改用 C 盘mkdir C:\GitLabRunner12.3 GitLab URL 填错正确填法http://gitlab.xxxx12.4 Token 输入错误错误做法在 token 输入处填写整条命令.\gitlab-runner.exe register --url http://gitlab.xxxx --token glrt-xxxx正确做法只填 tokenglrt-xxxx如果使用完整命令注册则直接在 CMD 中执行完整命令不要再逐项输入。12.5lookup gitlab.xxxx: no such host原因服务器不能解析 GitLab 域名。解决配置 hosts。echo 10.xxx.xx.xx gitlab.xxxx C:\Windows\System32\drivers\etc\hosts ipconfig /flushdns ping gitlab.xxxx12.6The specified service does not exist as an installed service错误FATAL: Failed to start gitlab-runner: The specified service does not exist as an installed service.原因你直接执行了.\gitlab-runner.exe start但还没有先安装服务。解决.\gitlab-runner.exe install .\gitlab-runner.exe start .\gitlab-runner.exe status12.7msbuild 不是内部或外部命令原因Build Tools 安装完成但 MSBuild 没加入 PATH或者终端没有刷新环境变量。解决方式一使用完整路径C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin\MSBuild.exe -version解决方式二重启服务器后再试msbuild -version13. Runner 注册完成后的检查13.1 在服务器检查cd C:\GitLabRunner .\gitlab-runner.exe status正常应显示Service is running13.2 在 GitLab 页面检查进入项目 ↓ 设置 ↓ CI/CD ↓ Runner应该能看到aliyun-windows-runner Online / 绿色状态 Tag: windows Executor: shell14. 与当前 CI 的关系你的.gitlab-ci.yml中任务使用了tags:-windows所以只有带有windows标签的 Runner 才会接收这些 Job。如果 Runner 没有windows标签Pipeline 会一直 Pending。当前项目是 WPF / .NET Windows 项目所以 Runner 使用Windows shell executor这是正确选择。15. 后续建议15.1 不建议部署在数据库服务器虽然数据库服务器也可以安装 Runner但不推荐。原因1. CI 编译会占用 CPU、内存、磁盘 IO 2. Runner 会执行 CI 脚本有一定安全风险 3. 数据库服务器应尽量保持稳定、隔离你现在使用阿里云独立 Windows 服务器部署 Runner是更合适的方案。15.2 Token 泄露处理如果 Runner token 已经截图或发送给别人建议1. 删除当前 Runner 2. 重新创建 Runner 3. 使用新的 token 注册15.3 网络必须长期可用Runner 必须能访问GitLab: http://gitlab.xxxx MES: http://39.xxx.xx.xx:81 更新服务器: http://10.xxx.xx.xxx:5111其中 GitLab 是最基础的。如果 Runner 访问不了 GitLab就无法拉代码和接收 CI 任务。16. 最终完整命令清单以下是从已有安装包开始的完整命令流程。16.1 创建 Runner 目录mkdir C:\GitLabRunner16.2 复制 Runner 文件copy C:\Users\Administrator\Downloads\gitlab-runner-windows-amd64.exe C:\GitLabRunner\gitlab-runner.exe16.3 验证 Runnercd C:\GitLabRunner .\gitlab-runner.exe --version16.4 配置 GitLab 域名解析echo 10.xxx.xx.xx gitlab.xxxx C:\Windows\System32\drivers\etc\hosts ipconfig /flushdns ping gitlab.xxxx16.5 注册 Runnercd C:\GitLabRunner .\gitlab-runner.exe register --url http://gitlab.xxxx --token glrt-你的token交互项Description: aliyun-windows-runner Tags: windows Maintenance note: 直接回车 Executor: shell16.6 安装并启动服务.\gitlab-runner.exe install .\gitlab-runner.exe start .\gitlab-runner.exe status17. 环境验证命令汇总git --versiondotnet --list-sdksC:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin\MSBuild.exe -versionping gitlab.xxxxcd C:\GitLabRunner .\gitlab-runner.exe --version .\gitlab-runner.exe status全部正常后Runner 环境基本可用。18. 判断部署是否完成满足以下条件即认为 Runner 部署完成√ Git 可以执行 √ dotnet 可以执行并能看到 .NET 8 SDK √ MSBuild 可以执行 √ gitlab.xxxx 可以 ping 通 √ GitLab Runner 注册成功 √ GitLab Runner 服务正在运行 √ GitLab 页面显示 Runner Online √ Runner 标签包含 windows √ Executor 为 shell完成后就可以开始触发 GitLab CI Pipeline验证项目是否能正常编译、打包和发布。