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

cicd Troubleshooting

Jenkins 构建卡住排查方法

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

先看队列里有没有积压和 executor 是否 offline，构建卡死时用 jstack 抓 Jenkins 主线程定位阻塞，多数是节点掉线或死锁。

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

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

Scenario

这篇文章解决什么问题

适用于“Jenkins 构建卡住排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先看队列里有没有积压和 executor 是否 offline，构建卡死时用 jstack 抓 Jenkins 主线程定位阻塞，多数是节点掉线或死锁。

Symptoms

典型现象

  • Jenkins 构建卡在队列不动或执行中挂起时，用 queue/api/json 查看队列 why 阻塞原因，computer/api/json 检查 executor 是否 offline，卡死用 jstack 抓 Jenkins 主线程转储，多数是节点掉线、标签不匹配或 Quiet Period 延迟。
  • 相关日志、命令或页面中反复出现 jenkins、构建卡住、队列 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

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. 固定现场，避免追着变化状态跑

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

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
java -jar jenkins-cli.jar -s http://localhost:8080/ -auth user:token list-jobs
curl -s http://localhost:8080/queue/api/json

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

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

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
curl -s http://localhost:8080/queue/api/json
curl -s http://localhost:8080/computer/api/json
jstack -l $(pgrep -f jenkins.war) > jenkins-thread-dump.txt

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

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

  • 通过 queue/api/json 确认构建是否卡在队列，查看 why 字段说明阻塞原因。
  • 通过 computer/api/json 检查各节点和 executor 是否 offline、idle 数量是否为 0。
  • 如果是执行中挂起，用 jstack 抓取 Jenkins 进程线程转储，查找 BLOCKED、死锁或长时间等待的线程。
3. 读取服务端证据，而不是只看客户端提示
curl -s http://localhost:8080/computer/api/json
jstack -l $(pgrep -f jenkins.war) > jenkins-thread-dump.txt
sudo systemctl status jenkins

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

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

  • 如果是执行中挂起，用 jstack 抓取 Jenkins 进程线程转储，查找 BLOCKED、死锁或长时间等待的线程。
  • 检查 agent 节点与 master 的连通性、磁盘空间和内存，节点掉线会导致 job 一直等待。
  • 确认是否被资源限制、并发数或 Quiet Period 延迟挡住，必要时调整 executor 数或重启节点。
4. 做最小修复并立即回归验证
jstack -l $(pgrep -f jenkins.war) > jenkins-thread-dump.txt
sudo systemctl status jenkins

Commands

排查命令与使用意图

命令 1

用于补充“Jenkins 构建卡住排查方法”的排查证据链。java 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 1
java -jar jenkins-cli.jar -s http://localhost:8080/ -auth user:token list-jobs

命令 2

用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。

命令 2
curl -s http://localhost:8080/queue/api/json

命令 3

用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。

命令 3
curl -s http://localhost:8080/computer/api/json

命令 4

用于补充“Jenkins 构建卡住排查方法”的排查证据链。jstack 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
jstack -l $(pgrep -f jenkins.war) > jenkins-thread-dump.txt

命令 5

用于确认服务当前运行状态、退出码和最近日志。重点看 Active 行和 Main PID。

命令 5
sudo systemctl status jenkins

Risk Notes

容易踩坑的地方

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

Verification

修复后怎么确认

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

Prevention

后续预防

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

常见问题

构建一直在队列里不动是什么原因？

常见是所有 executor 都忙碌或 offline、节点标签不匹配、被上游 job 占用，或 Quiet Period 延迟未到。

jstack 抓不到线程怎么办？

确认用与 Jenkins 相同的用户执行，容器部署时需要进入容器或用 docker exec 抓取，PID 要对应 jenkins.war 进程。

Long-tail SEO

你可能正在搜索这些报错

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

  • Jenkins 构建卡在队列不动
  • Jenkins build stuck in queue
  • Jenkins 构建挂起无响应
  • Jenkins executor offline
  • Jenkins 构建卡住 排查
  • Jenkins job 一直等待
  • jstack jenkins 线程死锁
  • Jenkins 节点掉线 job 卡住

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排障

GitLab CI 流水线失败排查方法

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

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排障

GitHub Actions Runner 离线排查方法

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

cicd