GitLab Runner 持久化与配置指南

1. 数据持久化 (Persistence)

在使用 Docker 部署 GitLab Runner 时，为了防止容器重启导致数据丢失，建议持久化以下数据：

• 构建缓存 (Build Cache)：
  • 建议：强烈推荐持久化。
  • 作用：重用依赖包和构建产物，显著提高构建效率。
  • 路径：通常挂载到容器内的 /cache 目录。
• 配置文件 (Configuration)：
  • 建议：必须持久化。
  • 作用：保存 Runner 的注册信息和运行配置，防止重启后丢失连接。
  • 文件：/etc/gitlab-runner/config.toml。
• 构建日志 (Build Logs)：
  • 建议：视需求而定。如果需要长期保留或审计历史日志则需要持久化。

Docker 启动示例：

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

2. 部署数量建议 (Sizing)

根据项目规模和并发需求，建议的 Runner 数量配置：

• 小型项目 (个人或小团队)：1-2 个 Runner。单实例部署即可满足需求。
• 中型项目/多仓库：2-5 个 Runner。可以为前端、后端或不同环境分配独立的 Runner，避免资源竞争。
• 大型项目/高并发：5 个以上或自动扩展。建议结合 Kubernetes 或 Docker Autoscaler 实现根据负载动态伸缩。

3. Kubernetes 部署指南 (Helm)

在 K8s 集群中部署 GitLab Runner 的标准流程：

1. 准备工作：确保已有 K8s 集群、kubectl 和 helm 工具。
2. 添加仓库：helm repo add gitlab https://charts.gitlab.io
3. 配置 values.yaml：
   • 设置 gitlabUrl 和 runnerRegistrationToken。
   • 配置 concurrent (并发数)。
   • 启用 RBAC (rbac: create: true)。
   • 配置 Runner 标签 (tags) 和执行环境 (image: alpine:latest)。
4. 安装：helm install --namespace gitlab gitlab-runner -f values.yaml gitlab/gitlab-runner
5. 扩展：通过调整 replicas 副本数来水平扩展 Runner。

4. 执行器选择 (Executor Selection)

根据构建环境需求选择合适的 Executor：

• Docker (推荐)：最常用。环境隔离好，可重复性高，适合大多数 CI/CD 场景。
• Shell：简单，直接在宿主机运行。适合本地调试或极其简单的任务，但无环境隔离。
• Kubernetes：适合云原生环境，每个 Job 启动一个 Pod，自动伸缩能力强。
• SSH / VirtualBox / Parallels：特殊场景使用，如跨机器构建或需要特定虚拟机环境。

5. 常见配置与故障排查

Docker 镜像选择

• Alpine (alpine:latest)：极简，体积小，适合基础任务。
• Ubuntu (ubuntu:latest)：功能全，适合依赖较复杂的环境。
• 语言特定：node:latest, python:latest, openjdk:latest 等，省去安装环境的时间。

解决 "Long polling issues" 警告

如果在日志中看到 request_concurrency 相关的警告，表示并发处理请求受限。

• 解决方法：在 config.toml 的 [runners] 部分将 request_concurrency 增加到 2 或更高。
• 自适应配置：添加环境变量 FF_USE_ADAPTIVE_REQUEST_CONCURRENCY=true 让 Runner 自动调整。

修改配置文件的 4 种方法

当 Runner 运行在 Docker 容器中时，如何修改 config.toml：

1. Docker Exec + Vi：进入容器 docker exec -it <container_id> bash，然后用 vi 或 nano 编辑。
2. Docker Cp：复制出来修改再覆盖回去 (docker cp <container>:/path/to/file . -> 编辑 -> docker cp file <container>:/path/to/file)
3. 挂载卷 (推荐)：启动时直接将宿主机文件挂载进去，直接在宿主机编辑即可生效。
4. Echo/Cat：在容器内使用 echo "content" >> config.toml 追加或覆盖内容（应急用）。

Nano 编辑器小贴士

如果容器内只有 nano 编辑器：

• 保存：Ctrl + O -> Enter
• 退出：Ctrl + X
• 中文乱码：设置环境变量 export LANG=zh_CN.UTF-8 和 export LC_ALL=zh_CN.UTF-8。

6. 进阶配置与最佳实践 (Advanced Configuration)

对于生产环境和复杂场景，以下高级配置能显著提升 CI/CD 的效率与稳定性：

6.1 分布式缓存 (Distributed Caching)

在 Kubernetes 或自动扩缩容环境下，本地 volumes 缓存失效。建议配置 S3 (AWS) 或 MinIO (自建) 实现分布式缓存，实现跨 Runner 实例共享 node_modules 等依赖。

配置示例 (config.toml)：

[runners.cache]
  Type = "s3"
  Path = "runner"
  Shared = true
  [runners.cache.s3]
    ServerAddress = "minio.example.com"
    AccessKey = "YOUR_ACCESS_KEY"
    SecretKey = "YOUR_SECRET_KEY"
    BucketName = "runner-cache"
    Insecure = false # 如果是 http 则为 true

6.2 镜像构建方案对比

在 CI 中构建 Docker 镜像的几种主流方案：

6.3 镜像拉取策略 (Pull Policy)

避免频繁拉取或镜像不更新的问题：

• always: 每次构建都拉取。最安全，但速度慢，依赖网络。
• if-not-present (推荐): 本地有就不拉取。速度最快，兼顾效率。

配置位置：

[runners.docker]
  pull_policy = ["if-not-present"]

6.4 磁盘清理与维护 (Disk Cleanup)

痛点：Runner 产生大量镜像和缓存导致磁盘爆满。 建议：

1. 在宿主机设置 cron 定时任务：docker system prune -af (如每天凌晨)。
2. 使用 GitLab 官方提供的清理脚本或配置 Runner 的自动清理策略。

6.5 标签管理 (Tags)

通过 Tag 合理分配资源，实现“专机专用”：

• High-CPU Runner (tags: [high-cpu])：跑编译、打包等重活。
• Deploy Runner (tags: [deploy])：拥有生产环境部署权限的 Runner。

6.6 IaC 视角 (Infrastructure as Code)

在现代化运维中，不建议手动持久化并修改 config.toml。 推荐做法：使用 Ansible、Terraform 或 K8s ConfigMap 管理配置。每次部署时自动注入标准配置文件，仅需持久化 /cache 目录。