1. GitLab Runner 环境搭建

GitLab Runner 是 GitLab CI/CD 的核心执行单元，负责接收来自 GitLab 服务器的作业指令，并在指定的执行器环境中完成编译、测试、打包等任务。本章将引导你完成 Runner 的安装、注册与执行器选择，为后续的持续集成流水线打下基础。

1.1 核心概念与运行机制

GitLab Runner 以 Agent 模式运行，与 GitLab 实例（Community Edition 或 Enterprise Edition）通过 HTTP/HTTPS 通信。流水线中的每一个 Job 都会被调度到可用的 Runner 上执行。Runner 可以运行在与 GitLab 相同的主机上，也可以分布在不同的物理机、虚拟机或容器中。

关键原则：Runner 本身是无状态的，它的行为完全由注册时配置的 、URL 以及配置文件 `config.toml` 决定。

1.2 执行器对比与选择

执行器（Executor）决定了 Job 运行时的隔离方式和环境。下表对比了三种最常用的执行器，你可以根据项目需求选择合适的类型。

执行器 隔离级别 典型场景 注意事项
Shell 无隔离（主机级） 简单脚本、本地测试、快速验证 环境易污染；用户目录权限敏感
Docker 容器级 多语言构建、依赖隔离、标准 CI 需提前安装 Docker；image 拉取影响耗时
Kubernetes Pod 级 大规模集群、动态扩展、云原生项目 K8s 集群管理与 RBAC 复杂
推荐方案：对于大多数中小型团队，Docker 执行器提供了隔离性、可重复性与灵活性的最佳平衡。本课程后续章节均以 Docker 执行器作为主要实验环境。

1.3 安装 GitLab Runner

以下步骤以 Ubuntu 20.04/22.04 LTS 操作系统为例。其他 Linux 发行版或 macOS 的安装方式可参考 GitLab 官方文档。

  1. 添加官方仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
  1. 安装最新版本
sudo apt-get install gitlab-runner -y
  1. 验证安装
sudo gitlab-runner --version

如果输出类似 Version: 16.10.0 的信息，说明安装成功。

1.4 注册 Runner

注册过程将 Runner 与 GitLab 实例关联，并指定执行器类型。你需要在 GitLab 项目或组设置的 CI/CD → Runners 页面中复制注册令牌（registration ）和 GitLab 实例 URL。

执行注册命令并交互式填写参数：

sudo gitlab-runner register

注册过程中需要填写的关键参数：

参数 示例值 说明
gitlab-ci coordinator URL https://gitlab.example.com GitLab 实例的访问地址
registration GR1348941yZcCXMzYzL5 从 GitLab 界面复制的令牌
description docker-runner-01 在 GitLab 界面中显示的名称
tags docker,linux,x86_64 用于在 .gitlab-ci.yml 中精准调度
executor docker 选择执行器类型
default image ruby:3.2 Docker 执行器默认拉取的镜像
安全提示：Registration 属于敏感信息，不要在公开文档、代码仓库或日志中泄露。如果发现泄露，应立即在 GitLab 设置中重置 。

1.5 Runner 配置组件解析

注册完成后，所有配置会被写入 /etc/gitlab-runner/config.toml（系统级）或 ~/.gitlab-runner/config.toml（用户级）。

[[runners]]
  name = "docker-runner-01"
  url = "https://gitlab.example.com"
   = "xxxxxxxxxxxxxxxxxxxx"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "ruby:3.2"
    privileged = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

核心字段说明：

  • [[runners]]：每个注册的 Runner 对应一个该区块。
  • ：由 GitLab 自动分配，与 registration 不同。
  • [runners.docker]：Docker 执行器的专属配置块。
  • privileged：是否以特权模式运行容器。开启后可以使用 Docker-in-Docker (DinD) 功能。

1.6 调试与验证

配置完成后，可以通过以下命令检查 Runner 状态：

sudo gitlab-runner status

如果输出 gitlab-runner: Runner is running and waiting for jobs.，说明服务正常运行。

手动执行一个 Job 进行端到端验证：

sudo gitlab-runner exec docker echo "Hello from Runner"

调试日志查看：

sudo gitlab-runner --debug run

1.7 常见错误与排查

错误现象 可能原因 解决方案
注册时提示 403 Forbidden Registration 错误或权限不足 检查 是否过期；确认用户拥有 Maintainer 以上角色
Runner 显示 never contacted GitLab 实例与 Runner 之间网络不通 检查防火墙、代理或 TLS 配置
Docker 执行器报 Cannot connect to the Docker daemon Runner 用户未加入 docker 组 执行 sudo usermod -aG docker gitlab-runner 并重启服务
Job 运行时间异常长 Docker 镜像拉取慢或缓存未生效 使用自建镜像仓库；配置 persist_volumes

1.8 性能与稳定性建议

  • 并发控制：在 config.toml 中设置 concurrent = 4，避免资源耗尽。
  • 缓存卷持久化：配置 volumes = ["/cache"]，减少重复依赖下载。
  • 镜像拉取策略：在 [runners.docker] 中设置 pull_policy = "if-not-present"，避免每次都拉取最新镜像。
  • 定期维护：清理 Docker 系统残留 docker system prune -f，延长磁盘寿命。

1.9 本章流程图

下图展示了从安装 Runner 到 Job 执行完成的完整流程：

GitLab Runner 环境搭建与执行流程 GitLab 实例 注册 Runner 配置 persist Push / Merge 调度 → 执行器 Docker 容器 结果回传 GitLab 说明： 注册后 Runner 持续轮询 GitLab；作业触发后，调度器根据 tags 选择 Runner；Docker 执行器拉取镜像并运行脚本。

1.10 课后实践清单

  1. 在 Ubuntu 虚拟机中完成 GitLab Runner 的安装与注册。
  2. 分别使用 Shell 和 Docker 执行器注册两个不同的 Runner。
  3. 在 GitLab 项目设置中将不同 Job 的 tags 指向不同 Runner，观察调度结果。
  4. 修改 config.toml 中的 concurrent 值，测试并发 Job 的执行效果。
← 上一章 📖 返回目录 下一章 →