GitLab Runner 管理

GitLab Runner 是独立安装的 CI 执行代理，与 GitLab 服务器分离。Pipeline Job 由 GitLab Rails 调度，Runner 长轮询 GitLab API 领取任务并在本地 Executor 中运行脚本。

1. Runner架构介绍

Runner 主动通过长轮询从 GitLab API 获取作业，再启动 Docker、Kubernetes 或 Shell Executor；日志、状态和制品也由 Runner 主动回传。

• GitLab：决定 何时 跑、跑什么镜像/脚本；
• Runner：决定 在哪台机器、用什么隔离 执行；
• 一个 Runner 可服务 Instance / Group / Project；多个 Runner 可共享 tag 做专用节点（如 gpu、deploy）。

2. Runner安装

以 Linux x86_64 + 二进制 + systemd 为例（官方包仓库 亦可）。

# 下载与 GitLab 版本匹配的 runner（示例 17.5.2）
export RUNNER_VERSION=v17.5.2
sudo curl -fsSL --output /usr/local/bin/gitlab-runner \
  "https://gitlab-runner-downloads.s3.amazonaws.com/${RUNNER_VERSION}/binaries/gitlab-runner-linux-amd64"
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash 2>/dev/null || true

安装 systemd 服务：

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
sudo gitlab-runner status

Docker Executor 还需在 Runner 主机安装 Docker 并将 gitlab-runner 加入 docker 组：

sudo usermod -aG docker gitlab-runner
sudo systemctl restart gitlab-runner

3. Runner注册

GitLab 17+ 推荐使用 Runner authentication token（前缀 glrt-），在 Admin/Group/Project → Settings → CI/CD → Runners 创建。

3.1 交互式注册

sudo gitlab-runner register

按提示输入：

GitLab URL: https://gitlab.example.com
Registration token: glrt-xxxxxxxxxxxxxxxxxxxx   # 从 UI 复制
Description: docker-runner-01
Tags: docker,linux
Executor: docker
Default Docker image: alpine:3.20

配置写入 /etc/gitlab-runner/config.toml。

3.2 非交互式注册

sudo gitlab-runner register --non-interactive \
  --url "https://gitlab.example.com" \
  --token "glrt-xxxxxxxxxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:3.20" \
  --description "docker-runner-01" \
  --tag-list "docker,linux" \
  --run-untagged="false" \
  --locked="false"

验证：

sudo gitlab-runner list
sudo gitlab-runner verify

提示

--run-untagged="false" 避免专用 Runner 抢走无 tag 的 Job；生产按环境打 tag，如 prod-deploy。

4. Instance Runner

Admin Area → CI/CD → Runners，注册到实例级，默认对所有 Project 可见（可关闭 Turn on instance runners for new projects）。

适用：共享构建农场、统一 Docker 镜像缓存。限制滥用：

• 设置 Maximum job timeout；
• 配合 Network outbound 防火墙；
• 监控 Runner 主机 CPU/磁盘。

5. Group Runner

Group → Settings → CI/CD → Runners，仅该 Group 及子 Group/Project 可用。

适用：部门独立构建资源、隔离敏感 Variable 环境（如 finance Group 专用 Runner 在内网 VLAN）。

6. Project Runner

Project → Settings → CI/CD → Runners，仅单个 Project 使用，locked=true 常见。

适用：生产部署 Runner 仅服务单一应用，降低其他 Project 误用风险。

# config.toml 片段
[[runners]]
  name = "project-deploy"
  url = "https://gitlab.example.com"
  token = "glrt-..."
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    MaxUploadedArchiveSize = 0

7. Executor类型介绍

Executor	隔离性	典型场景
shell	无，直接在 Runner 主机执行	简单脚本、内网部署（需信任代码）
docker	容器隔离	最常用 CI 构建
docker+machine	动态起 VM 跑 Docker	弹性峰值（需云 API）
kubernetes	Pod 隔离	K8s 内 CI，资源配额清晰
ssh	远程 SSH 到固定机器	遗留裸机
parallels/virtualbox	VM	macOS/Windows 桌面测试

选择原则：不可信代码用 docker/k8s；部署生产若需访问内网 kubeconfig，用专用 Project Runner + 最小权限 ServiceAccount。

8. Docker Runner

/etc/gitlab-runner/config.toml 示例：

concurrent = 4

[[runners]]
  name = "docker-runner-01"
  url = "https://gitlab.example.com"
  token = "glrt-xxxxxxxx"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:3.20"
    privileged = false
    disable_cache = false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    pull_policy = ["if-not-present"]
  [runners.cache]
    Type = "local"
    Path = "/cache"
    Shared = true

.gitlab-ci.yml 指定镜像：

build:
  tags: [docker]
  image: golang:1.22
  script:
    - go test ./...

注意

挂载 docker.sock 等价于主机 root 权限；仅可信 Pipeline 使用，或改用 Kaniko/BuildKit 无特权构建。

9. Kubernetes Runner

Runner 在集群内，Executor 为 kubernetes，每个 Job 一个 Pod。

config.toml 核心：

[[runners]]
  executor = "kubernetes"
  [runners.kubernetes]
    namespace = "gitlab-runner"
    image = "alpine:3.20"
    cpu_limit = "1"
    memory_limit = "2Gi"
    service_account = "gitlab-runner"
    poll_timeout = 600

需 RBAC：Role 允许在 gitlab-runner namespace 创建 Pod、Secret、Log。Helm chart gitlab/gitlab-runner 可一键部署。

适合：已有 K8s、需弹性并发、与部署同一集群。注意：集群资源配额与 镜像拉取 Secret（image_pull_secrets）。

10. Runner故障排查

10.1 Job 一直 pending

1. Project Settings → CI/CD → Runners 是否有可用 Runner（绿点）；
2. Job 的 tags 是否与 Runner tag 匹配；
3. Runner 是否 paused；
4. GitLab Sidekiq 是否正常（非 Runner 问题）。

sudo gitlab-runner verify
sudo journalctl -u gitlab-runner -n 100 --no-pager

10.2 Job 失败但 Runner 已接任务

# Runner 侧日志
sudo gitlab-runner --debug run   # 临时前台调试，勿与 systemd 并行
docker ps -a | head              # docker executor 残留容器

常见原因：镜像拉取失败、磁盘满、Docker 权限、VPN/内网 DNS 不可达。

10.3 并发与资源

concurrent = 4   # 全局最多 4 个 Job 同时跑

过高会导致 OOM；过低会排队。观察 htop、df -h 与 GitLab Admin → Monitoring → CI/CD analytics。

10.4 清理

docker system prune -f    # 谨慎：清理未使用镜像
sudo gitlab-runner restart

10.5 对照表

现象	检查
pending	tags、Runner online、instance runner 开关
401 unauthorized	token 过期，重新 register
docker: not found	gitlab-runner 用户 docker 权限
no space left	/var/lib/docker、Runner cache 目录
超时	timeout in config.toml、Job timeout keyword

完成 Runner 部署后，在 Project 添加最小 .gitlab-ci.yml 做 smoke test：

test-runner:
  tags: [docker]
  script:
    - echo "Runner OK on $(hostname)"
    - uname -a

返回 GitLab 运维手册上一章：配置管理 或回到 安装部署。