GitLab Runner 在 GNU/Linux 上的手动安装指南
本文档根据 GitLab 官方文档整理，提供了在 GNU/Linux 系统上手动安装 GitLab Runner 的完整步骤，适用于无法通过官方软件仓库安装或使用不受支持操作系统的情况。
1. 概述
1.1 适用范围与版本
- 产品层级：Free, Premium, Ultimate
- 产品形态：GitLab.com, GitLab Self-Managed, GitLab Dedicated
1.2 何时选择手动安装
手动安装 GitLab Runner 指的是使用 .deb 或 .rpm 包，或者直接使用二进制文件进行安装。请在以下情况下考虑此方法：
- 无法使用 deb/rpm 官方仓库安装 GitLab Runner。
- 您使用的 GNU/Linux 发行版不受官方支持。
2. 前提条件
在手动安装 GitLab Runner 之前，请确保： - 如果您计划使用 Docker 执行器，请先安装 Docker。 - 建议预先查阅 FAQ 部分，了解常见问题与解决方案。
3. 使用 deb/rpm 包安装
3.1 下载
访问以下链接，查找适合您系统的最新软件包文件名和选项：
https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/index.html
下载与您的包管理器或架构相匹配的包和 runner-helper 镜像。
Debian / Ubuntu 示例：
# 将 ${arch} 替换为支持的架构，如 amd64, arm, arm64
# 完整架构列表请参考上述链接
curl -LJO "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/deb/gitlab-runner-helper-images.deb"
curl -LJO "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/deb/gitlab-runner_${arch}.deb"
CentOS / RHEL 示例：
curl -LJO "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/rpm/gitlab-runner-helper-images.rpm"
curl -LJO "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/rpm/gitlab-runner_${arch}.rpm"
RHEL FIPS 兼容版本示例：
# 目前仅支持 amd64 架构。FIPS 兼容包内已包含辅助镜像。
curl -LJO "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/rpm/gitlab-runner_amd64-fips.rpm"
3.2 安装
Debian / Ubuntu 示例：
dpkg -i gitlab-runner-helper-images.deb gitlab-runner_<arch>.deb
CentOS / RHEL 示例：
dnf install -y gitlab-runner-helper-images.rpm gitlab-runner_<arch>.rpm
3.3 升级
下载最新的软件包后，执行以下命令进行升级：
Debian / Ubuntu 示例：
dpkg -i gitlab-runner_<arch>.deb
CentOS / RHEL 示例：
dnf install -y gitlab-runner-helper-images.rpm gitlab-runner_<arch>.rpm
4. 使用二进制文件安装
4.1 安装
-
下载二进制文件：根据您的系统架构，选择以下命令之一下载。
bash # Linux x86-64 sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64" # Linux x86 sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-386" # Linux arm sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-arm" # Linux arm64 sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-arm64" # Linux s390x sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-s390x" # Linux ppc64le sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-ppc64le" # Linux riscv64 sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-riscv64" # Linux loong64 sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-loong64" # Linux x86-64 FIPS Compliant sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64-fips" -
授予执行权限：
bash sudo chmod +x /usr/local/bin/gitlab-runner -
创建 GitLab Runner 用户：
bash sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash -
安装并注册为系统服务：
bash sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner sudo gitlab-runner start
重要提示： - 确保
root用户的$PATH环境变量中包含/usr/local/bin/，否则可能出现“命令未找到”错误。 - 您也可以将gitlab-runner安装到其他位置，例如/usr/bin/。 - 当gitlab-runner以服务形式运行时，它本身以root权限运行，但实际执行作业的用户由安装命令中的--user参数指定。这意味着某些作业功能（如缓存和产物）需要执行/usr/local/bin/gitlab-runner命令。因此，运行作业的用户必须对该可执行文件有访问权限。
4.2 升级
- 停止服务：
bash sudo gitlab-runner stop - 下载新的二进制文件覆盖旧的可执行文件（以 amd64 为例）：
bash sudo curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64" - 授予执行权限：
bash sudo chmod +x /usr/local/bin/gitlab-runner - 启动服务：
bash sudo gitlab-runner start
5. 后续步骤
安装完成后，您需要 注册 Runner 以完成最终配置。
请注意：二进制安装包不包含预构建的辅助镜像 (helper images)。您可以使用以下命令下载对应版本的辅助镜像压缩包，并复制到相应位置：
mkdir -p /usr/local/bin/out/helper-images
cd /usr/local/bin/out/helper-images
5.1 Ubuntu 辅助镜像
根据架构下载对应的镜像：
# Linux x86-64 ubuntu
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-x86_64.tar.xz
# Linux x86-64 ubuntu pwsh
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-x86_64-pwsh.tar.xz
# Linux s390x ubuntu
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-s390x.tar.xz
# Linux ppc64le ubuntu
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-ppc64le.tar.xz
# Linux arm64 ubuntu
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-arm64.tar.xz
# Linux arm ubuntu
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-ubuntu-arm.tar.xz
# Linux x86-64 ubuntu 特定版本 - v17.10.0
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/v17.10.0/helper-images/prebuilt-ubuntu-x86_64.tar.xz
5.2 Alpine 辅助镜像
根据架构下载对应的镜像：
# Linux x86-64 alpine
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-x86_64.tar.xz
# Linux x86-64 alpine pwsh
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-x86_64-pwsh.tar.xz
# Linux s390x alpine
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-s390x.tar.xz
# Linux riscv64 alpine edge
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-edge-riscv64.tar.xz
# Linux arm64 alpine
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-arm64.tar.xz
# Linux arm alpine
wget https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/helper-images/prebuilt-alpine-arm.tar.xz
文档来源：GitLab 官方文档 - Install GitLab Runner manually on GNU/Linux
整理日期：2026年1月2日
归档说明：此中文 Markdown 文档为官方英文文档的忠实翻译与整理，用于技术存档与参考。