一、 初识Runner：它是什么，为什么会“生病”？

想象一下，你有一个非常智能的厨房（GitLab），里面存满了菜谱（代码）。但光有菜谱不行，你得有个勤劳的厨师（GitLab Runner）来按照菜谱的步骤（.gitlab-ci.yml文件）自动炒菜、炖汤、摆盘（构建、测试、部署）。这个厨师就是Runner，它负责执行持续集成/持续部署（CI/CD）流水线中的每一个任务。

Runner“生病”了，最常见的就是它罢工了，或者干活出错了。这通常表现为：流水线任务一直卡在“Pending”（等待中）状态没人认领，或者任务刚跑起来就失败，报出一堆你看不懂的错误信息。别慌，大部分问题都有套路可循，我们一步步来排查。

二、 基础体检：Runner还活着吗？能联系上吗？

当流水线卡住时，首先要检查Runner的基本生命体征。

1. 检查Runner注册与连接状态 登录到你的GitLab实例，进入 “项目设置” -> “CI/CD” -> “Runners”。在这里，你可以看到所有能为这个项目服务的Runner。一个健康的Runner应该显示绿色的圆圈和“在线”状态。如果它显示为灰色并“离线”，那说明它已经和GitLab服务器失联了。

2. Runner服务运行状态检查（以Linux系统为例） Runner通常以后台服务的形式运行。我们需要登录到安装Runner的机器上，检查它的服务状态。

# 技术栈：Linux / Systemd
# 查看Runner服务的运行状态
sudo systemctl status gitlab-runner

# 期望看到类似这样的输出，关键点是 `active (running)`
# ● gitlab-runner.service - GitLab Runner
#    Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
#    Active: active (running) since Mon 2023-10-09 10:00:00 CST; 1 weeks 0 days ago
#    ... (其他信息)

# 如果状态不是 `active (running)`，尝试重启它
sudo systemctl restart gitlab-runner

# 查看重启后的日志，寻找错误线索
sudo journalctl -u gitlab-runner -n 50 --no-pager

3. Runner本身配置检查 Runner的配置文件通常位于 /etc/gitlab-runner/config.toml。我们可以检查其配置是否正确，特别是coordinator_url（GitLab服务器地址）和token（注册令牌）。

# 技术栈：Linux / GitLab Runner
# 查看Runner的配置信息（注意，直接cat可能包含敏感token，请在生产环境谨慎操作）
sudo cat /etc/gitlab-runner/config.toml | head -20

# 更安全的方式是使用Runner命令查看已注册的Runner列表
sudo gitlab-runner list
# 输出会显示Runner标签、状态和所属项目，确认其是否正常注册。

三、 任务执行失败：深入“案发现场”找线索

如果Runner在线，但任务一执行就失败，我们需要把目光转向具体的任务日志和运行环境。

1. 善用GitLab CI作业日志 GitLab UI提供了最直接的错误信息。点击失败的作业（Job），查看其输出日志。错误信息通常非常直白，比如：

  • bash: line 1: npm: command not found -> 执行环境缺少必要的软件。
  • fatal: repository ‘xxx’ not found -> 克隆代码仓库时权限或地址有问题。
  • ERROR: Job failed (system failure): execution took longer than 3600 seconds -> 任务执行超时。

2. 检查Runner的执行器（Executor） Runner支持多种执行器，如shell、docker、kubernetes等。这是故障高发区。

  • Shell执行器：任务直接在Runner所在机器的Shell中运行。问题往往出在环境变量、用户权限和软件依赖上。确保运行Runner服务的用户（通常是gitlab-runner）有权限访问所需的目录、命令和文件。
  • Docker执行器（最常用）：每个任务都会启动一个全新的Docker容器来执行。问题常出在镜像拉取、目录挂载和容器内环境。

示例：一个典型的Docker执行器问题排查 假设我们有一个Node.js项目，任务是在Docker容器内运行npm install和npm test。

# 技术栈：GitLab CI / Docker / Node.js
# .gitlab-ci.yml 文件片段
test-job:
  image: node:16-alpine # 指定使用的Docker镜像
  script:
    - npm ci
    - npm run test

如果这个任务失败，我们可以从以下几个方面排查：

# 1. 手动模拟Runner行为：在Runner主机上，尝试拉取镜像
sudo docker pull node:16-alpine
# 如果拉取失败，可能是网络问题（需要配置Docker镜像加速器）或镜像标签不存在。

# 2. 检查Runner的config.toml，看Docker执行器的配置
sudo cat /etc/gitlab-runner/config.toml
# 关注 `[runners.docker]` 部分：
#   volumes = ["/cache"] # 挂载的卷，如果项目需要访问主机文件，这里可能需要添加，如`/var/run/docker.sock:/var/run/docker.sock`用于Docker in Docker。
#   pull_policy = "if-not-present" # 拉取策略，`always`表示总是拉取，可能因网络慢导致超时。

# 3. 检查网络：如果作业中需要访问内部仓库（如Nexus）或特定API，确保容器内网络通畅。
#    可以在`script`中临时添加命令测试：
#    - ping -c 4 your-internal-server.com
#    - curl -I https://registry.npmjs.org/

# 4. 检查资源：如果任务复杂，可能容器内存或CPU不足导致进程被杀死。
#    查看Runner主机资源使用情况：`free -h`, `df -h`, `docker stats`。

3. 缓存与制品（Artifacts）问题 缓存用得好可以极大加速流水线，但配置不当会导致奇怪的问题，比如依赖版本不对。

# 技术栈：GitLab CI / Node.js
# .gitlab-ci.yml 缓存配置示例
cache:
  key: ${CI_COMMIT_REF_SLUG} # 按分支缓存
  paths:
    - node_modules/ # 缓存node_modules目录

build-job:
  script:
    - npm ci # 使用`npm ci`而不是`npm install`，它严格依赖package-lock.json，与缓存配合更稳定
    - npm run build
  artifacts:
    paths:
      - dist/ # 将构建产物dist目录保存为制品，供后续作业使用

注意事项：如果某次构建的node_modules被污染（比如安装了全局包），它会被缓存并影响下一次构建。此时可以在GitLab作业页面手动清除Runner缓存，或者修改cache:key（例如加上-${CI_PIPELINE_ID}）使其失效，重新构建。

四、 高级疑难杂症与性能调优

解决了常见问题后，一些更深层次的问题可能需要更系统的排查。

1. 并发与资源竞争 一个Runner可以设置concurrent参数来控制同时执行的任务数。如果设得过高，超过主机（CPU、内存、IO）负载能力，会导致所有任务都变慢甚至失败。在config.toml中调整这个值，根据主机配置找到平衡点。

2. Docker-in-Docker (dind) 场景 需要在CI作业中构建或运行Docker镜像时（例如构建应用镜像），会用到dind。这需要特殊的Runner配置。

# 技术栈：GitLab Runner config.toml (Docker执行器 + dind)
[[runners]]
  name = “my-dind-runner”
  url = “https://gitlab.example.com”
  executor = “docker”
  [runners.docker]
    image = “docker:20.10.16” # 使用包含Docker客户端的镜像
    privileged = true # 必须设置为true，以特权模式运行容器，这是dind工作的关键
    volumes = [“/cache”, “/var/run/docker.sock:/var/run/docker.sock”]
    # 挂载主机docker socket是一种更轻量的替代dind的方案，但安全性需要考虑。

3. 私有依赖拉取认证 如果作业需要从私有仓库拉取镜像（如私有Docker Registry、私有NPM），需要在作业中配置认证。

# 技术栈：GitLab CI / Docker / 私有仓库
# 方法1：使用GitLab CI变量（推荐）
# 在GitLab项目设置 -> CI/CD -> Variables中，添加 `DOCKER_AUTH_CONFIG` 变量
# 值为：`{“auths”: {“registry.example.com”: {“auth”: “你的Base64编码的认证字符串”}}}`

# 方法2：在作业script中动态登录
deploy-job:
  image: docker:latest
  services:
    - docker:dind # 使用dind服务
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: “”
  script:
    - echo $DOCKER_PASSWORD | docker login registry.example.com -u $DOCKER_USER --password-stdin # 使用CI变量存储用户名密码
    - docker pull registry.example.com/my-app:${CI_COMMIT_SHA}
    - docker run ...

应用场景与优缺点： GitLab Runner是GitLab CI/CD的核心引擎，应用场景覆盖从个人项目的自动化测试到企业级复杂的多阶段部署流水线。其优点在于与GitLab深度集成、配置灵活（支持多执行器）、开源且活跃。缺点主要是需要自行维护Runner基础设施（服务器、网络、安全），在大规模高并发场景下，自建Runner集群的性能调优和稳定性保障有一定复杂度。

文章总结： 排查GitLab Runner故障，就像医生看病，要遵循“望闻问切”的流程。先从宏观（Runner状态、服务）入手，再聚焦微观（具体作业日志、执行环境）。核心思路是：隔离与模拟——将CI作业中的命令拿到对应的运行环境（主机Shell或指定Docker容器）中手动执行，往往能立刻复现和定位问题。熟练掌握对config.toml、.gitlab-ci.yml以及各类执行器原理的理解，是成为CI/CD故障排查高手的关键。记住，清晰的日志和循序渐进的排查方法是解决所有技术问题的不二法门。