真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

cicd Troubleshooting

GitLab CI 流水线失败排查方法

GitLab CI 流水线失败、job 报错或 pending 不执行时，用 gitlab-runner verify 测试 Runner 与 GitLab 连接，检查 Runner tags 是否匹配 job、executor 类型（shell/docker/kubernetes）配置和 registration token，再用 journalctl 看 gitlab-runner 服务日志定位脚本或镜像问题。

先 gitlab-runner verify 确认 Runner 能连上 GitLab，再看 job 日志和 runner 服务日志，pipeline 失败多在脚本、镜像拉取或 Runner 未注册。

适用环境Jenkins / GitLab CI / GitHub Actions
风险等级低
最后验证2026-07-04
建议权限普通用户 + sudo

2026-07-04 更新·约 3 分钟阅读

Scenario

这篇文章解决什么问题

适用于“GitLab CI 流水线失败排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先 gitlab-runner verify 确认 Runner 能连上 GitLab，再看 job 日志和 runner 服务日志，pipeline 失败多在脚本、镜像拉取或 Runner 未注册。

Symptoms

典型现象

  • GitLab CI 流水线失败、job 报错或 pending 不执行时，用 gitlab-runner verify 测试 Runner 与 GitLab 连接，检查 Runner tags 是否匹配 job、executor 类型（shell/docker/kubernetes）配置和 registration token，再用 journalctl 看 gitlab-runner 服务日志定位脚本或镜像问题。
  • 相关日志、命令或页面中反复出现 gitlab-ci、pipeline、runner 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 先确认是流水线配置问题，还是 Runner / 执行环境问题，避免在 YAML 和基础设施之间来回横跳。
  • 保留失败 job 的完整日志、触发上下文、分支和 commit，而不是只看最后几行报错。
  • 区分本地能复现但 CI 不行的问题，重点对比环境、密钥、缓存和网络差异。

Root Causes

常见根因分层

Runner 离线或标签不匹配

job 一直 pending 通常是可用 Runner 不足、标签没匹配上或 Runner 被并发占满，而不是流水线语法错误。

  • 查看 Runner 在线状态和标签
  • 确认 job 声明的 runs-on/tags
  • 看并发队列和 executor 资源

缓存失效或 key 计算错误

缓存 key 用了时间戳或分支变量、路径没覆盖真实依赖目录，会让命中率为零甚至复用错误产物。

  • 用 lockfile hash 做 key
  • 核对 cache path 与真实路径
  • 看 restore 日志是否命中

构建环境差异

Docker socket 没挂载、网络走不了内网、secrets 没注入、镜像架构不一致，都会让 CI 表现和本地不同。

  • 确认 secrets 作用域和变量
  • 检查 docker socket 与网络
  • 对比本地与 CI 镜像架构

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。GitLab CI 流水线失败排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
sudo gitlab-runner verify
sudo gitlab-runner status

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
sudo gitlab-runner status
sudo gitlab-runner list
sudo journalctl -u gitlab-runner -n 200 --no-pager

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 在 GitLab 项目设置里确认 Runner 已注册且未被禁用，标签是否匹配 job 的 tags。
  • 用 gitlab-runner verify 测试 Runner 与 GitLab 的连接，失败则检查 URL 和 registration token。
  • 查看 pipeline 中失败 job 的完整日志，定位脚本错误、镜像拉取失败或依赖安装问题。
3. 读取服务端证据，而不是只看客户端提示
sudo gitlab-runner list
sudo journalctl -u gitlab-runner -n 200 --no-pager
sudo gitlab-runner verify --debug

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 查看 pipeline 中失败 job 的完整日志，定位脚本错误、镜像拉取失败或依赖安装问题。
  • 用 journalctl 查看 gitlab-runner 服务日志，排查 executor 启动失败或权限问题。
  • 确认 executor 类型（shell/docker/kubernetes）和镜像、权限配置，必要时用 --debug 复现。
4. 做最小修复并立即回归验证
sudo journalctl -u gitlab-runner -n 200 --no-pager
sudo gitlab-runner verify --debug

Commands

排查命令与使用意图

命令 1

用于确认 Git/SSH 的最终配置和认证链路。注意输出中可能包含仓库地址、用户名或代理信息，分享前应脱敏。

命令 1
sudo gitlab-runner verify

命令 2

用于确认 Git/SSH 的最终配置和认证链路。注意输出中可能包含仓库地址、用户名或代理信息，分享前应脱敏。

命令 2
sudo gitlab-runner status

命令 3

用于确认 Git/SSH 的最终配置和认证链路。注意输出中可能包含仓库地址、用户名或代理信息，分享前应脱敏。

命令 3
sudo gitlab-runner list

命令 4

用于读取 systemd 或内核在故障时间附近记录的真实错误，比 status 摘要更完整。重点看时间、退出码、权限、路径和依赖失败。

命令 4
sudo journalctl -u gitlab-runner -n 200 --no-pager

命令 5

用于确认 Git/SSH 的最终配置和认证链路。注意输出中可能包含仓库地址、用户名或代理信息，分享前应脱敏。

命令 5
sudo gitlab-runner verify --debug

Risk Notes

容易踩坑的地方

  • 不要在日志里打印 secrets 或 token，CI 日志常被长期留存，泄露后难以追溯。
  • 不要用 latest tag 做缓存 key，会导致产物不可复现甚至复用错误缓存。
  • 不要在流水线中执行不安全的 shell 命令或从不可信源下载脚本。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 GitLab CI 流水线失败 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 把 secrets 和环境变量在流水线里显式声明，避免依赖运行时隐式注入导致不一致。
  • 为关键 job 加超时上限，防止卡死占用 Runner 影响其他流水线执行。
  • 缓存 key 统一用 lockfile hash，不要用 latest tag 或时间变量，确保缓存可复现。
  • 在流水线中增加构建产物验证步骤，如类型检查、lint 和测试，尽早发现质量问题。

常见问题

job 一直 pending 不执行？

通常是没在线的 Runner 或标签不匹配，检查 Runner tags 和 job tags 是否一致，以及 Runner 是否被设为受保护分支限定。

gitlab-runner verify 报 401 怎么办？

多为 token 失效或配置错误，重新在 GitLab 生成 registration token 并用 gitlab-runner register 更新，或检查 config.toml 中的 url 和 token。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • GitLab CI pipeline failed
  • gitlab runner 连不上
  • gitlab-ci job 报错
  • gitlab-runner verify 失败
  • gitlab job pending 不执行
  • gitlab runner 401 unauthorized
  • gitlab runner 标签不匹配
  • gitlab-ci 脚本失败 排查

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

速查

CI/CD 常用命令速查表

GitHub Actions、GitLab CI 和 Jenkins 三大 CI/CD 流水线一页速查：gh run/rerun/cancel 调试、gitlab-runner list/verify 与 CI Lint、jenkins-cli 构建日志、Runner 在线状态与缓存磁盘排查，覆盖 job 卡顿和构建失败主路径。

cicd命令

CI/CD 常用排障命令

CI/CD 排障常用命令合集，Jenkins 用 jenkins-cli 与 queue/computer API 查队列和 executor，GitLab 用 gitlab-runner verify/list 检查 Runner，GitHub Actions 用 gh run list、gh run view --log-failed、gh cache 定位失败步骤和缓存。

cicd排障

GitHub Actions Runner 离线排查方法

GitHub Actions 自托管 Runner 显示 offline、job 一直 waiting for runner 时，用 systemctl status actions.runner.* 确认服务状态，查看 ~/actions-runner/_diag 日志中的连接错误，排查 registration token 过期和到 github.com 的网络代理与证书。

cicd排障

Jenkins 构建卡住排查方法

Jenkins 构建卡在队列不动或执行中挂起时，用 queue/api/json 查看队列 why 阻塞原因，computer/api/json 检查 executor 是否 offline，卡死用 jstack 抓 Jenkins 主线程转储，多数是节点掉线、标签不匹配或 Quiet Period 延迟。

cicd排障

CI 中 Docker 构建失败排查方法

CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。

cicd排障

CI 缓存失效排查方法

CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。

cicd