第2章 GitLab Runner安装与配置归纳总结

上一章我们聊了CI/CD的基本理念，也看了GitLab CI的流水线长什么样。但有个关键问题：谁来执行你的Job？这个“人”就是GitLab Runner。说白了，Runner就是GitLab派出去的打工机器，负责接收任务、运行脚本、再上报结果。

安装Runner本身不复杂，无非是下载、注册、启动。但真到了生产环境，里面坑还挺多的。我这几年跟Runner打交道下来，掉过的坑能写个小本子。这一章我就把我踩过的点、总结的经验都倒出来，帮你少走弯路。

2.1 Runner的分类

在动手安装之前，先搞明白一件事：Runner分几种？GitLab官方把Runner从作用域上分成三类。

类型	作用域	适合场景
Shared Runner	整个GitLab实例	大型团队、多项目共用资源
Group Runner	某个用户组	部门级项目、权限可控
Specific Runner	单个项目	项目需专用资源、跑Nextflow任务

我一开始图省事，直接装了个Shared Runner，想着所有项目都能用。结果有个Nextflow流程特别吃内存，两个大任务同时跑，直接把服务器搞崩了。后来老老实实给那个项目配了Specific Runner，反而清静了。

2.2 安装方式

安装Runner的方法有好几种。我列了最常用的四种：

• Linux通用二进制安装
• macOS Homebrew安装
• Windows Powershell安装
• Docker方式安装

我个人最推荐Linux二进制安装。为啥？没依赖，稳。我见过有人用Docker装Runner，Docker一升级，Runner就挂了。虽然是偶发事件，但生产环境里碰上一次就很麻烦。

下面我以Ubuntu 22.04为例，把步骤写出来。

步骤一：下载二进制文件

sudo curl -L --output /usr/local/bin/gitlab-runner \
  "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"

步骤二：赋予执行权限

sudo chmod +x /usr/local/bin/gitlab-runner

步骤三：创建GitLab CI用户并安装

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner \
  --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner

步骤四：启动Runner

sudo gitlab-runner start

嗯，这里有个小细节要注意。我见过有人创建用户时忘了指定`--shell`，结果Runner启动日志里疯狂报错：找不到shell。都是泪。

2.3 注册Runner

安装完成只是第一步，你还得告诉Runner：你要去哪儿接任务。这个动作叫“注册”。

你需要从你的GitLab项目里拿到两个东西：

• GitLab URL：一般是 https://gitlab.com/，如果是自托管，换成你自己的地址。
• Registration Token：在项目设置 > CI/CD > Runners 里找。

执行注册命令：

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "你的Token" \
  --executor "shell" \
  --description "nextflow-runner-01" \
  --tag-list "nextflow,hpc" \
  --run-untagged="false" \
  --locked="false"

参数拆开讲一下，你想想看：

参数	说明	推荐值
--executor	Runner用什么方式运行脚本	shell / docker / kubernetes
--tag-list	Job挑选Runner时的标签	nextflow、gpu、highmem
--run-untagged	没有标签的Job能否使用	false（按需设定）
--locked	是否锁定到当前项目	true（推荐特定Runner）

我一直用`shell` executor跑Nextflow。为什么？因为Nextflow需要直接调度本地资源，shell模式最直接。Docker模式虽然隔离性好，但Nextflow再套一层Docker，配置起来会比较啰嗦。

2.4 配置调优

注册完了，跑一个Sample Job，发现没问题。但一旦上生产，Nextflow一跑几百个任务，Runner自个儿扛不住了。怎么办？调。

Runner的配置在 /etc/gitlab-runner/config.toml。

我贴一份常用的调优配置：

[[runners]]
  name = "nextflow-runner-01"
  url = "https://gitlab.com/"
  token = "xxxxxxxx"
  executor = "shell"
  [runners.custom_build_dir]
    enabled = true
  [runners.cache]
    Type = "s3"
    Path = "nextflow-cache"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      AccessKey = "AKIA..."
      SecretKey = "..."
      BucketName = "my-cache-bucket"
  [runners.custom_cleanup]
    enabled = true
  concurrent = 4

有几个关键点你一定要注意：

• concurrent：控制Runner能同时跑几个Job。我之前设了10，结果5个Nextflow任务一起跑，CPU飙到100%，所有任务都没跑完，全超时了。后来改成4，稳了。
• custom_build_dir：开启后每次Job单独建工作目录，避免多个Job互相覆盖文件。这个对Nextflow很重要，因为Nextflow会生成一堆临时文件在目录里。
• custom_cleanup：Job跑完自动删除工作目录。磁盘空间是小事，但Run目录堆满后，文件数太多，ls都卡。我吃过这个亏。

2.5 验证安装

最后一步，验证Runner是不是真的在工作。你可以在项目里创建一个最简单的 .gitlab-ci.yml：

test-runner:
  stage: test
  tags:
    - nextflow
  script:
    - echo "Runner is alive!"
    - whoami
    - gitlab-runner --version

提交到GitLab，等Pipeline跑完。如果看到输出里有Runner版本号，说明安装和注册都成功了。

我记得有一次，我配了台新机器注册了Runner，但怎么都接不到任务。折腾了半天，才发现忘了加tag，而Job又指定了tags字段。根本匹配不上。你想想看，这么简单的错误，有时候就是不注意。

2.6 清理与重置Runner

有时候你可能会遇到Runner状态异常，或者跑完一次实验性任务后用不上这台机器了。这时建议做一次清理。

停止并卸载：

sudo gitlab-runner stop
sudo gitlab-runner uninstall
sudo rm -rf /home/gitlab-runner

在GitLab页面上移除对应的Runner条目。这样就彻底清干净，下次重装不会冲突。