GitLab Runner Windows 安装指南

本文档源自 GitLab 官方文档，提供了在 Windows 系统上安装、配置、升级、卸载 GitLab Runner 的完整指南，并包含详细的故障排除方案。

本指南详细说明了如何在 Windows 操作系统上安装和运行 GitLab Runner。

📋 系统要求

在 Windows 上安装和运行 GitLab Runner 需要满足以下条件：

  • Git：可从 Git 官网 下载安装。
  • 用户账户密码：如果你计划使用用户账户（而非内置系统账户）来运行 Runner，则需要知道该账户的密码。
  • 系统区域设置：建议将系统区域设置为 英语（美国），以避免潜在的字符编码问题。更多信息请参阅 issue 38702。

1. 安装步骤

1.1 创建专用目录

首先，在你的系统上创建一个专用文件夹，例如 C:\GitLab-Runner。

1.2 下载 Runner 可执行文件

根据你的系统架构，下载对应的 64 位或 32 位二进制文件，并将其放入上一步创建的文件夹中。

64位程序: https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-windows-amd64.exe 32位程序: https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-windows-386.exe

此处假设你已将可执行文件重命名为 gitlab-runner.exe（此步骤为可选操作）。你可以按照 “Bleeding Edge - 下载其他标记版本” 中的说明，下载任何可用版本的二进制文件。

重要安全提示：务必限制 GitLab Runner 目录及其可执行文件的 写入权限。如果未设置这些权限，普通用户可能会替换该可执行文件，并以提升的权限运行任意代码。

1.3 安装并启动服务（两种方式）

你可以选择使用内置系统账户（推荐）或用户账户来运行 GitLab Runner 服务。

请注意：以下命令示例均基于步骤 1.1 中创建的目录 C:\GitLab-Runner。

方式一：使用内置系统账户运行服务 这是推荐的方式，无需提供用户凭据。

cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start

方式二：使用用户账户运行服务 如果你选择使用特定用户账户运行，需要提供该账户的用户名和密码。

cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start

如果在安装过程中遇到任何错误，请参阅本文档的 故障排除 部分。

1.4 （可选）高级配置

安装完成后，你可以根据需要调整 Runner 的配置。

  • 修改并发作业数：编辑 C:\GitLab-Runner\config.toml 文件，修改 concurrent 值以允许同时运行多个作业。详细配置请参考 高级配置详情。
  • 更改 Shell 执行器：你同样可以通过高级配置，将默认的 shell 执行器从 Batch 更改为 Bash 或 PowerShell。

完成以上步骤后，Runner 即安装成功并开始运行，且会在每次系统重启后自动启动。相关日志存储在 Windows 事件查看器 中。

2. 升级指南

要升级 GitLab Runner，请按以下步骤操作：

  1. 停止服务（需要使用提升权限的命令提示符）： shell cd C:\GitLab-Runner .\gitlab-runner.exe stop
  2. 下载并替换可执行文件：下载对应系统架构（64位或32位）的新版二进制文件，替换掉原有的 Runner 可执行文件。同样，可参考 “Bleeding Edge” 下载所需版本。
  3. 启动服务： shell .\gitlab-runner.exe start

3. 卸载指南

若要完全卸载 GitLab Runner，请执行以下命令：

cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner

4. 查看运行日志

使用 .\gitlab-runner.exe install 命令安装后，gitlab-runner 会作为一个 Windows 服务运行。你可以通过以下方式查看日志：

  • 图形界面：在 事件查看器 中查找提供程序名为 gitlab-runner 的日志。
  • PowerShell（若无图形界面访问权限）： powershell PS C:\> Get-WinEvent -ProviderName gitlab-runner

5. 故障排除

在开始前，建议先阅读 FAQ 部分，其中描述了 GitLab Runner 最常见的一些问题。

5.1 账户名无效

如果遇到类似 “The account name is invalid” 的错误，请尝试在用户名前添加 .\：

.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

5.2 服务因登录失败而无法启动

如果在启动服务时遇到 “The service did not start due to a logon failure” 错误，通常是因为执行服务的用户缺少 SeServiceLogonRight 权限。请按以下步骤添加权限：

  1. 进入 控制面板 > 系统和安全 > 管理工具。
  2. 打开 本地安全策略 工具。
  3. 在左侧列表中选择 安全设置 > 本地策略 > 用户权限分配。
  4. 在右侧列表中打开 作为服务登录。
  5. 点击 添加用户或组...。
  6. 添加相应用户（手动或使用 高级...），并应用设置。

根据微软文档，此方法适用于 Windows Vista、7、8/8.1、10 及其对应的 Server 版本。某些 Windows 版本（如“家庭版”）可能不提供“本地安全策略”工具。

添加权限后，再次运行 gitlab-runner start 命令应能成功启动服务。

5.3 Windows 构建时出现 PathTooLongException

此错误通常由 npm 等工具生成超过 260 个字符的路径结构引起。解决方案如下：

  • 启用 Git 的 core.longpaths：
    1. 在命令行中运行：git config --system core.longpaths true
    2. 在 GitLab CI 项目设置页面中，将项目设置为使用 git fetch。
  • 使用 PowerShell 的 NTFSSecurity 工具：安装 NTFSSecurity PowerShell 模块后，其提供的 Remove-Item2 方法支持长路径。GitLab Runner 检测到该模块会自动使用它。
  • 针对特定版本的变通方案（GitLab Runner 16.9.1 至 17.10.0 之前存在相关缺陷）：
    • 使用 pre_get_sources_script 重新启用 Git 系统级设置（通过取消设置 GIT_CONFIG_NOSYSTEM），这会默认在 Windows 上启用 core.longpaths。
    • 构建自定义的 gitlab-runner-helper 镜像。

5.4 Windows 批处理脚本错误

如果批处理脚本报错 “The system cannot find the batch label specified - buildscript”，你需要在 .gitlab-ci.yml 文件的批处理调用前加上 call 关键字。

例如：

before_script:
  - call C:\path\to\test.bat

更多信息请参阅 issue 1025。

5.5 如何获取彩色输出？

  • 简答：确保你的程序输出中包含 ANSI 颜色代码。出于文本格式化目的，请假设你运行在一个 UNIX ANSI 终端模拟器中（因为这是 Web 界面的输出环境）。
  • 详解：GitLab CI 的 Web 界面模拟了一个 UNIX ANSI 终端。gitlab-runner 将构建输出直接传输到 Web 界面，因此任何存在的 ANSI 颜色代码都会生效。某些 Windows 程序（如使用 Colorama 库）会进行 ANSI 到 Win32 调用的转换，在 CI 构建中，你需要禁用此转换，以保留 ANSI 代码。

5.6 作业被错误地标记为成功或失败

许多 Windows 程序使用 exit code 0 表示成功，但有些程序（如 robocopy）并非如此。这可能导致 CI 作业判断错误。

示例问题：以下作业即使 robocopy 成功执行，也会被标记为失败：

test:
  script:
    - robocopy ./source ./dest

解决方案：创建一个 PowerShell 脚本手动检查退出码，并在 .gitlab-ci.yml 中调用该脚本。

示例 PowerShell 脚本 (robocopyCommand.ps1)：

$exitCodes = 0,1 # robocopy 返回 0 或 1 表示成功
robocopy ./source ./dest
if ( $exitCodes.Contains($LastExitCode) ) {
    exit 0
} else {
    exit 1
}

注意：在 PowerShell 函数中，注意 exit 和 return 的区别。exit 1 会将作业标记为失败，而 return 1 不会。

5.7 其他常见问题速查

问题场景 可能原因/解决方案
没有 Windows 密码 无法启动使用用户账户的服务，请改用内置系统账户。
使用映射网络驱动器时提示“系统找不到指定的路径” 服务登录会话在访问资源时存在安全限制。请使用驱动器的 UNC 路径 替代映射盘符。
Docker 执行器报错 “unsupported Windows Version” Docker 版本可能过旧。请升级到与 Windows Server 发行版时间相近或更新的 Docker 版本。
Kubernetes 执行器报错 “unsupported Windows Version” 在 GitLab Runner 配置文件的 [runners.kubernetes.node_selector] 部分，添加 "node.kubernetes.io/windows-build" = "10.0.17763" 等节点选择器。
使用 Windows 子系统 Linux (WSL) 时作业日志输出为空白行 默认情况下，WSL 的 STDOUT 输出未使用 UTF8 编码。在作业变量中设置 WSL_UTF8: "1" 可强制使用 UTF8 编码。
Docker-Windows 执行器作业失败，提示“Permission denied” 请确保运行 Docker 引擎的用户对 C:\ProgramData\Docker 目录拥有完全控制权限。

文档来源：GitLab 官方文档 - Install GitLab Runner on Windows 整理日期：2026年1月2日
归档说明：此中文 Markdown 文档为官方英文文档的忠实翻译与整理，用于技术存档与参考。