故障排查
Jenkins 故障大体分四类：构建失败、Agent 异常、平台异常（Master 卡、磁盘满）、插件问题。本篇按类给出排查路径。
本篇目标：能按证据链定位构建失败原因，处理 Agent 离线与磁盘问题，识别插件冲突。
1. 构建失败排查路径
先界定范围，再取证据：
构建失败
├── 是环境问题还是代码问题？ → 换一个 Agent/环境重跑
├── 编译失败？ → 看编译日志（依赖、版本）
├── 测试失败？ → 看测试报告（flaky 还是真失败）
├── 环境/依赖问题？ → 检查镜像、依赖源、工具版本
└── 发布/部署失败？ → 见第 11 篇，看集群侧事件
1.1 第一轮证据
# 控制台输出尾部
# 构建页面 → Console Output → 拉到失败处
# 失败 stage 高亮，从最后一个失败的 sh/步骤开始看
# 重跑失败的构建，开「-verbose」级别日志
# 或对比同 Job 上一次成功/失败的构建差异
常见原因：
| 现象 | 原因与处理 |
|---|---|
mvn compile 报依赖下载失败 | 内网 Maven 镜像配置、凭据、版本冲突 |
| 测试 flaky | 先判断是偶发（重跑通过）还是稳定失败 |
| Docker 构建失败 | Dockerfile、网络、镜像 tag、docker in docker 配置 |
permission denied | Agent 用户权限、挂载卷、sudo 缺失 |
| 环境依赖不一致 | Agent 间工具版本不同，用容器/K8s Agent 统一 |
1.2 让构建可复现
生产排查的最大障碍是"这次过了下次挂"。手段：
- 用容器 / K8s Agent 固化构建环境（第 10 篇）；
- 锁定工具版本（tools 、容器镜像 tag）；
- 记录环境指纹：
uname -a、mvn -version、node -v打到日志开头。
2. Agent 离线 / 不可用
Agent 离线
├── 网络不通？ → 50000 端口、Master 与 Agent 双向可达
├── Agent 进程挂了？ → 检查 Agent 服务 / 容器
├── 凭证/连接方式错误？ → JNLP token、SSH 私钥
├── 标签不匹配？ → Job 要的 label 没有 Agent 提供
└── 动态 Agent 创建失败？ → 见第 10 篇（RBAC、镜像、资源）
# 查看 Agent 状态
# Manage Jenkins → Manage Nodes → 点击离线节点查看日志
# Agent 的控制台/服务日志
docker logs <jenkins-agent-container>
journalctl -u jenkins-agent
常见：
| 现象 | 处理 |
|---|---|
Connection refused 50000 | 防火墙放行 Agent 连接端口，确认 Master 监听 |
| Agent 连上又断开 | Master URL、代理、JNLP 版本不匹配 |
| 动态 Agent Pod CrashLoop | 镜像无 cat/sh、command 配置错 |
| 标签无匹配节点 | 给 Agent 加标签，或 Job 用对标签 |
3. Master 卡顿 / 无响应
Master 无响应
├── CPU/内存被构建挤占？ → 内置节点执行器设 0，构建全走 Agent
├── JVM 内存不足？ → -Xmx 调大，查 Full GC
├── 磁盘满？ → 清理 Workspace / 构建记录 / 日志
├── 并发过高？ → 限制并发、检查排队
└── 插件卡死？ → 最近更新了什么插件，回滚验证
# 查看 Master 内存与 GC
docker exec jenkins jcmd <pid> GC.heap_info
# 或看 Prometheus 的 jenkins_jvm 指标（第 13 篇）
# 磁盘
df -h /var/jenkins_home
4. 磁盘满
# 定位大目录
du -sh /var/jenkins_home/* | sort -rh | head -10
du -sh /var/jenkins_home/jobs/* | sort -rh | head -10
| 大目录 | 处理 |
|---|---|
jobs/*/workspace | 加 cleanWs()，或批量清理 |
jobs/*/builds | 配置 buildDiscarder 保留策略 |
jobs/*/lastSuccessful 等 | 定期清理过时符号链接 |
logs/ | 清理历史日志 |
plugins/ | 清理无用插件 |
紧急处理：
# 找到超大 Job 的 workspace 后手动清理
rm -rf /var/jenkins_home/jobs/big-job/workspace/*
磁盘满会让 Jenkins 停止写入
磁盘满时 Jenkins 可能无法保存构建记录、凭证、配置——这是高优先级故障。配置磁盘告警（>80%），并在系统层面设置 DiskThresholdMonitor。
5. 插件冲突
| 现象 | 处理 |
|---|---|
| 更新插件后功能异常 | 回滚插件版本，或还原 $JENKINS_HOME 中的插件 |
Job 报 No such DSL method | 插件未装 / 版本不支持该步骤 |
| 启动失败 | 查看 $JENKINS_HOME/logs 错误日志，移除冲突插件目录 |
# 插件冲突应急：停服移除最近安装的插件目录
rm -rf /var/jenkins_home/plugins/<problem-plugin>.jpi
docker restart jenkins
升级前先备份插件目录
更新插件前备份 $JENKINS_HOME/plugins/，出问题能快速回滚。用一个带 plugins.txt 的自定义镜像（第 2 篇）做版本锁定更稳。
6. 定位工具与信息收集
| 工具 | 用途 |
|---|---|
| Jenkins System Info | 环境变量、系统属性、节点信息 |
| Load Statistics | 排队、执行器、构建时长历史 |
| Manage Jenkins → Log Recorders | 按 logger 记录运行日志 |
$JENKINS_HOME/logs/ | Master 运行日志 |
| Prometheus 指标 | 队列、Agent、JVM（第 13 篇） |
# 开启详细日志定位
# Manage Jenkins → System Log → Add new log recorder
# 添加 jenkins.*、hudson.*、org.jenkinsci.plugins.* 等 logger 观察
7. 练习与验收
练习 A
- 故意让一个构建失败（如改错镜像 tag），用控制台日志定位到失败 stage
- 制造一次"无匹配标签"，观察 Agent 排队和报错
- 用
du找到最大的 Workspace 并清理，配置cleanWs
练习 B
- 模拟 Agent 离线（停掉一个 Agent 容器），排查连接问题
- 安装一个不兼容的插件，观察报错并回滚
- 配置 Log Recorder 抓取一个插件的运行日志
验收清单
- 能按证据链定位构建失败（编译/测试/环境/发布）
- 会排查 Agent 离线的四类原因
- 知道 Master 卡顿的排查顺序和磁盘清理手段
- 能识别并回滚插件冲突
- 会用 System Info、Log Recorder、Prometheus 定位问题
下一篇：企业最佳实践。