适用场景：在阿里云 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 CPU：4 核 内存：8 GB 磁盘：100 GB 用途：部署 GitLab Runner 服务这个配置可以满足当前项目的 CI 编译需求。
2.2 推荐配置
Windows Server 2019 / 2022 / Windows 11 CPU：4 核以上 内存：8 GB 以上 磁盘：100 GB 以上如果后续多个项目同时跑流水线，建议提升到：
CPU：8 核以上 内存：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 SDK |
| GitLab 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验证 Runner
cd C:\GitLabRunner .\gitlab-runner.exe --version正常会显示版本信息，例如：
Version: 19.0.1 Runtime platform arch=amd64 os=windows6. 重启服务器是否必要
安装 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 TTL=59如果能 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 自带的 PowerShell：
shell = "powershell"然后重启 Runner：
cd C:\GitLabRunner .\gitlab-runner.exe restart后续更优处理
因为后续使用shell = "powershell"时出现了 GitLab Runner 注入环境变量脚本解析异常，所以最终建议安装 PowerShell 7，再改回：
shell = "pwsh"powershell -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正确做法：只填 token：
glrt-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 验证 Runner
cd 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 注册 Runner
cd 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-sdks"C:\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，验证项目是否能正常编译、打包和发布。