Jenkins Pipeline 故障排查与构建加速实战

Jenkins Pipeline 出问题时,Jenkinsfile 本身往往是最后才需要怀疑的东西:构建卡在排队里、Agent 连不上、某个 stage 随机失败、构建时间越跑越长,这些问题的根因大多在 Agent 资源、插件版本、凭证与并发配置上。本文按“排队、执行、产物”三段定位,再讲构建加速的常用手段。

先定排查顺序:构建状态页先看卡在哪一个 stage,再看该 stage 的控制台输出,最后看 Jenkins 系统日志与 Agent 日志。控制台输出只显示流水线层面的日志,Agent 侧的系统问题(磁盘满、内存不足、Docker 守护进程挂了)要到 Agent 机器上看。

一、构建卡在排队:Agent 不足与标签错配

构建长时间处于“等待下一个可用的执行器”状态,根因通常是三类:Agent 数量不够、label 写错导致没有 Agent 匹配、某个构建占住了执行器不释放。先看构建队列与执行器状态,再对 label。

<pre class="wp-block-syntaxhighlighter-code"># 看队列与执行器状态(Jenkins 内置 API,无需插件)
curl -s -u admin:TOKEN http://jenkins:8080/queue/api/json | python3 -m json.tool | grep -E '"why"|"task"|"blocked"'
curl -s -u admin:TOKEN http://jenkins:8080/computer/api/json | python3 -c "import json,sys; d=json.load(sys.stdin); [print(c['displayName'], 'offline:', c['offline'], 'executors:', len(c['executors'])) for c in d['computer']]"
# Agent 在线但 label 不匹配:看 Agent 的标签
curl -s -u admin:TOKEN http://jenkins:8080/computer/<agent>/api/json | python3 -m json.tool | grep -i label
# 占住执行器的构建:看谁跑了最久
curl -s -u admin:TOKEN http://jenkins:8080/api/json?tree=jobs[name,builds[number,duration,timestamp,building]] | head -c 1000</pre>

修复方法:label 拼写错误最常见(大小写、连字符),对照 Agent 配置逐字核对;长期排队要加 Agent 或把构建按 label 分流;被占住的执行器先看是不是某个构建死锁(比如等人工输入的 input 步骤没人点),input 步骤要配 timeout 自动放行。

二、Stage 随机失败:先分清是代码问题还是环境问题

同一个流水线这次过、下次不过,随机失败的根因大多在环境:测试依赖外部服务抖动、并发构建抢同一个端口或目录、磁盘空间不足导致中途失败、网络超时。区分方法是看失败的 stage 是否固定:固定在某个 stage 是代码或配置问题,随机出现在不同 stage 是环境问题。

// 随机失败的 stage 加重试与超时(只对已知抖动的步骤用,不要全流水线加)
stage('Integration Test') {
    options {
        timeout(time: 20, unit: 'MINUTES')
        retry(2)
    }
    steps {
        sh 'make test-integration'
    }
}
// input 步骤必须配 timeout,否则会一直占住执行器
stage('Deploy Approve') {
    options { timeout(time: 30, unit: 'MINUTES') }
    steps { input message: '确认发布到生产?' }
}
// 并发构建隔离:每个构建用独立的工作目录与端口
// pipeline { agent { label 'docker' } options { skipDefaultCheckout() } }

环境类根因的排查:Agent 磁盘用量(df -h,看 workspace 是不是被旧构建堆满)、Docker 守护进程状态(docker ps 能不能列出容器)、外部服务连通性(从 Agent 上 curl 依赖服务)。构建历史里看失败 stage 的分布,随机分布就是环境问题。

三、Agent 连不上与掉线:JNLP、SSH 与资源耗尽

Agent 掉线分三种:JNLP Agent 连不上 Jenkins(端口或反向代理问题)、SSH Agent 认证失败(密钥或账号问题)、Agent 进程被系统杀掉(内存不足)。看 Agent 页面的日志能区分:连接超时是网络问题,认证失败是凭证问题,进程消失先查 Agent 机器的系统日志。

<pre class="wp-block-syntaxhighlighter-code"># Agent 机器上:Jenkins Agent 进程在吗
ps aux | grep -i remoting | grep -v grep
# JNLP 端口通不通(默认 50000,或随机端口要看 Jenkins 配置)
nc -vz jenkins 50000
# SSH Agent:手动验证密钥登录
ssh -i /var/lib/jenkins/.ssh/id_rsa jenkins@<agent> 'echo ok'
# Agent 机器资源:磁盘满与内存不足是掉线的常见原因
df -h /var/lib/jenkins; free -h; dmesg -T | grep -i -E 'oom|killed process' | tail -5
# 清理旧 workspace(保留最近 5 次构建的工作目录)
find /var/lib/jenkins/workspace -maxdepth 1 -type d -mtime +30 | head
# Jenkins 内置的 workspace 清理:Job 配置里勾选 "Delete workspace before build starts"
# 或在 pipeline 里加 ws-cleanup 步骤</pre>

经验:Agent 的 Java 堆内存要单独配(-Xmx),默认堆太小会在大构建时 OOM;JNLP Agent 建议固定端口而不是随机端口,否则反向代理与防火墙规则没法配;SSH Agent 的 known_hosts 变了(机器重装)会导致认证失败,要删旧记录重加。

四、构建加速:缓存、并行与增量

构建慢的优化有三板斧:依赖缓存、stage 并行、增量构建。Maven/Gradle/npm 的依赖目录要挂缓存卷,否则每次构建都重新下载;能并行的 stage(单元测试、代码扫描、镜像构建)用 parallel 一起跑;只有改了相关模块才跑对应测试,而不是每次全量跑。

// 并行 stage:测试与扫描同时跑
stage('Parallel Checks') {
    parallel {
        stage('Unit Test') { steps { sh 'mvn -o test' } }
        stage('Code Scan') { steps { sh 'sonar-scanner' } }
        stage('Build Image') { steps { sh 'docker build -t app:${BUILD_NUMBER} .' } }
    }
}
// 依赖缓存:Maven 本地仓库挂到 Agent 的固定目录(声明式 pipeline 里用 cache 思路)
// docker run -v /data/m2:/root/.m2 maven:3.9 mvn -o package
// 只在代码变化时跑测试:用 changeset 条件
// stage('Test') { when { changeset "src/**" } steps { sh 'make test' } }

加速前先度量:Jenkins 的 Timestamper 插件能给每行日志打时间戳,一眼看出哪个 stage 最耗时;构建时间趋势图在 Job 页的“构建时间趋势”里看。优化顺序:先解决最耗时的 stage,再考虑并行化;缓存失效(比如每次都清缓存)比没缓存更慢,先确认缓存真的命中了。

五、凭证与插件:两类“昨天还好好的”故障

“昨天还好好的,今天突然全失败”大多是凭证过期或插件升级:Git 凭证过期、镜像仓库 token 过期、插件升级后 API 变了。排查方法是看失败日志里的 401/403(凭证问题)与 NoSuchMethodError(插件版本冲突),再看 Jenkins 系统日志里的插件加载错误。

<pre class="wp-block-syntaxhighlighter-code"># 凭证验证:手动用凭证拉一次代码
git ls-remote https://<token>@github.com/org/repo.git HEAD
# 镜像仓库登录验证
docker login registry.example.com -u <user> -p <token>
# 插件版本:看最近升级了哪些插件(Jenkins 系统日志)
grep -i -E 'plugin.*updat|failed to load' /var/log/jenkins/jenkins.log | tail -20
# 插件冲突:Jenkins → 系统管理 → 插件管理,看有没有依赖版本警告
# 应急回滚:插件目录 /var/lib/jenkins/plugins 里有 .jpi 备份,停 Jenkins 后替换回旧版本
ls /var/lib/jenkins/plugins/*.jpi | head</pre>

预防措施:凭证设过期提醒(提前 7 天轮换),插件升级先在测试 Jenkins 上验证,生产 Jenkins 的插件目录定期备份。token 类凭证建议用 Jenkins Credentials 统一管理,不要写进 Jenkinsfile。

六、Jenkins 主节点故障:磁盘满、插件冲突与升级回滚

流水线跑得好好的、主节点突然起不来或页面打不开时,先看三处:JENKINS_HOME 所在磁盘满了没有(构建产物与日志最能吃盘)、最近装的插件有没有冲突(升级后页面 500 多半是它)、Java 堆内存够不够。主节点故障的恢复优先级最高——所有流水线都依赖它,恢复前先别动 Agent。

# 磁盘:JENKINS_HOME 下谁最占空间(构建记录与工作区是重灾区)
df -h /var/lib/jenkins
du -sh /var/lib/jenkins/jobs/* 2>/dev/null | sort -rh | head -10
du -sh /var/lib/jenkins/workspace/* 2>/dev/null | sort -rh | head -10
# 日志:主节点最近一次报错(启动失败先看这个)
tail -100 /var/log/jenkins/jenkins.log | grep -i -E 'error|exception|failed' | tail -20
systemctl status jenkins --no-pager | head -30
# 插件冲突:进安全模式启动(不加载插件),确认是插件问题再逐个排查
# systemctl stop jenkins
# java -jar /usr/share/java/jenkins.war --httpPort=8080 --enable-future-java &
# 升级前备份(JENKINS_HOME 全量 + 插件列表,升级失败直接回滚)
# tar czf /backup/jenkins-home-$(date +%F).tar.gz /var/lib/jenkins
# 堆内存:JENKINS_HOME 之外的另一常见死因,/etc/default/jenkins 里调 JAVA_OPTS
# JAVA_OPTS="-Xms2g -Xmx4g"

磁盘满的根治办法是配构建记录保留策略:每个 Job 的“丢弃旧的构建”设保留天数与个数(比如 30 天、50 个),定期清理工作区;插件升级要先在测试环境装一遍,确认与现有插件版本兼容再上生产。JENKINS_HOME 的备份要定期做——主节点盘坏了,没有备份就等于所有 Job 配置都要重建。

七、流水线可观测与复现:失败要能重放,而不是靠猜

一次失败的构建如果不能复现,排查就是碰运气。可观测要做三件事:日志里加时间戳(知道哪一步慢、哪一步卡)、失败的构建保留现场(归档产物与测试报告)、能用 Replay 功能重放同一份 Jenkinsfile。通知也要配:失败了立刻告警到群里,别等有人手动去看构建历史才发现。

// Jenkinsfile:时间戳 + 超时 + 失败通知,三件套缺一不可
pipeline {
  options {
    timestamps()          // 每行日志带时间戳,慢在哪一步一目了然
    timeout(time: 30, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '20'))  // 只留最近 20 次构建
  }
  stages {
    stage('Build') {
      steps { sh 'make build' }
    }
    stage('Test') {
      steps { sh 'make test' }
      post {
        always {
          junit 'reports/*.xml'   // 测试报告归档,失败用例直接能看到
          archiveArtifacts artifacts: 'dist/*.tar.gz', fingerprint: true
        }
      }
    }
  }
  post {
    failure {
      // 失败通知:按团队习惯接钉钉/企业微信/邮件,别只依赖 Jenkins 页面
      echo "构建失败:${env.JOB_NAME} #${env.BUILD_NUMBER}"
    }
  }
}

Replay 是排查随机失败的神器:在构建页面点 Replay,可以改 Jenkinsfile 里的个别参数重跑,不用改仓库代码。注意 Replay 跑的是修改后的脚本、不是原始提交,复现出来的问题要回到仓库里的 Jenkinsfile 修,不要只在 Replay 里改完就以为修好了。失败通知里要带构建链接与失败的 stage 名,收到通知的人点开就能定位,不用再翻构建历史。

八、排查检查清单

  • 先定段:排队、执行、产物三段,先看卡在哪一段再动手。
  • 排队:label 逐字核对、执行器占用看 input 超时、长期排队加 Agent。
  • 随机失败:失败 stage 随机分布就是环境问题,先查磁盘、Docker 与外部依赖。
  • Agent 掉线:JNLP 查端口、SSH 查密钥、进程消失查 OOM 与磁盘。
  • 加速:依赖缓存、stage 并行、增量构建,先度量最耗时的 stage 再优化。
  • 凭证插件:401/403 先查凭证过期,NoSuchMethodError 先查插件版本冲突。

发表回复

后才能评论