GitLab Runner 教程

下面是一份超完整、深入且实战级的 GitLab Runner 教程，覆盖：

核心概念
架构原理
安装与注册
常用 Executor（Docker、Shell、Kubernetes）全讲解
配置文件详解（config.toml）
Runner 标签与调度
高级功能（Cache、Artifacts、并发、限流、镜像加速）
企业级部署方案（Docker、K8s、生产架构）
最佳实践
常见问题排查

GitLab Runner 是什么？
Runner 的工作原理
Runner 分类：Shared / Group / Project
Runner 安装（Linux、Docker、K8s）
Runner 注册与配置
Executor 类型详解
config.toml 配置详解
缓存 cache 与 artifacts
Runner 高级能力（并发、限流、隔离、安全）
企业级部署（全 Docker、K8s）
最佳实践
常见故障排查

1. GitLab Runner 是什么？

GitLab Runner 是一个 独立于 GitLab 的任务执行器，专门用来执行 .gitlab-ci.yml 中的 job。

它负责：

拉取代码
执行 CI/CD 脚本
上传 artifacts
提供日志
执行部署

Runner 实际是一个 Agent，由 GitLab 调度。

2. Runner 的工作原理

流程：

GitLab CI -> 调度 job -> 分配给 Runner -> Runner 执行 -> 上传结果 -> Pipeline 完成

更详细步骤：

.gitlab-ci.yml 生成 Pipeline
GitLab 调度器调度 job
Job 与标签（tags）匹配
找到合适 Runner（可用状态）
Runner 拉取代码
执行脚本
上传 artifacts / cache
上报结果
pipeline 继续下一个 stage

3. Runner 分类：Shared / Group / Project

类型	用途
Shared Runner（共享 Runner）	整个 GitLab 实例都能使用（推荐）
Group Runner	一个 group 中的所有项目共享
Project Runner	只给单个项目使用

企业强烈建议：使用 Shared Runner + 标签（tags）区分环境

4. GitLab Runner 安装

4.1 Linux 安装

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt install gitlab-runner

检查：

gitlab-runner --version

4.2 Docker 方式安装（推荐）

docker run -d --name gitlab-runner --restart always \
    -v /srv/gitlab-runner/config:/etc/gitlab-runner \
    -v /var/run/docker.sock:/var/run/docker.sock \
    gitlab/gitlab-runner:latest

优点：维护成本最低，扩容简单。

4.3 Kubernetes 方式安装（企业级）

Helm Chart：

helm repo add gitlab https://charts.gitlab.io
helm install gitlab-runner gitlab/gitlab-runner -n gitlab

此方式适用于：

大规模 Runner 集群
大量并发 Pipeline
动态 Pod 执行 job

5. Runner 注册

命令：

gitlab-runner register

流程：

GitLab URL -> Runner Token -> 描述 -> 标签(tags) -> executor -> 保存

示例：

gitlab-runner register \
    --url "https://gitlab.example.com/" \
    --registration-token "PROJECT_TOKEN" \
    --executor "docker" \
    --description "docker-runner-1" \
    --tag-list "docker,prod,build" \
    --docker-image "alpine:latest"

6. Executor 类型详解

Runner 执行 job 的方式叫 Executor。

GitLab 支持：

6.1 Shell Executor（不推荐）

直接在主机执行：

executor = "shell"

缺点：

无隔离
易污染环境
安全风险大

6.2 Docker Executor（最常用）

executor = "docker"

[runners.docker]
  image = "alpine:latest"
  privileged = true
  volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]

privileged 模式用于：CI 里需要 docker build 的情况（Docker in Docker）

6.3 Kubernetes Executor（企业级）

特点：

每个 job 自动创建 Pod
Pod 可以自定义镜像
最适合大规模 CI 集群

配置示例：

executor = "kubernetes"

[runners.kubernetes]
  image = "alpine:latest"
  namespace = "ci"
  privileged = true
  poll_timeout = 1800

7. config.toml 配置详解

文件位置：

/etc/gitlab-runner/config.toml

核心字段说明：

concurrent = 10        # runner 并发数
check_interval = 0

[[runners]]
  name = "docker-runner"
  url = "https://gitlab.example.com"
  token = "xxx"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = true
    volumes = ["/cache"]

7.1 并发（重要）

concurrent = 10

意味着 Runner 可以同时执行 10 个 job。

单机不要设置太大，否则会打爆 CPU。

7.2 tags 匹配（核心调度机制）

在 .gitlab-ci.yml 中：

build-job:
  tags:
    - docker

Runner：

tags = ["docker","build"]

匹配后才会执行。

tags 用来区分：

语言环境（python / go / node）
环境（dev / prod）
执行方式（docker / k8s）

8. 缓存 cache 与 artifacts

cache（跨 job 缓存）

用于加速构建，例如 node_modules、pip cache：

cache:
  paths:
    - node_modules/

Runner 会把缓存放到：

/cache

artifacts（构建产物）

例如构建出来的包、二进制：

artifacts:
  paths:
    - build/
  expire_in: 7 days

9. Runner 高级能力

9.1 并发与限流

config.toml 设置：

concurrent = 10

单 Runner 限制：

limit = 3

9.2 禁用特定项目执行

allowed_projects = ["group/project"]

9.3 使用自定义 Docker 镜像仓库

pull_policy = "if-not-present"

9.4 自动清理容器（Docker executor）

disable_cache = false

10. 企业级部署方案

10.1 多 Runner 架构

GitLab
  │
  ├── Docker Runner（构建）
  ├── Docker Runner（测试）
  ├── Kubernetes Runner（动态扩容，大量 Pipeline）
  └── Shell Runner（内网部署）

10.2 Docker in Docker（DinD）

用于需要构建镜像的项目：

services:
  - docker:dind

variables:
  DOCKER_DRIVER: overlay2

10.3 Kubernetes 动态扩缩容 Runner

企业级特点：

每个 job 一个 Pod
自动扩容
自动回收资源
最稳定（无污染环境）

11. 最佳实践

开发环境

普通 Docker Runner 即可
pool 2C/4G -> 并发 2

企业环境

Docker Executor（构建机）
Kubernetes Executor（大规模 CI）
Runner 镜像放在本地 Harbor 镜像仓库
artifacts 缓存放到 S3（MinIO / AWS）

.gitlab-ci.yml 最佳实践

每个 job 必须写 tags
分级 Stage：Lint -> Build -> Test -> Deploy
生产环境必须使用 manual

12. 常见故障排查

① Runner offline

检查：

gitlab-runner status
gitlab-runner verify

② Docker 里 CI 不能访问 Docker

缺少：

-v /var/run/docker.sock:/var/run/docker.sock

③ “no matching runner”

原因：

job 没有标签
runner 标签不匹配
runner 禁用了本项目

④ Cache 不生效

可能原因：

路径写错
Worker 清理机制
缓存太大