CI/CD / 系统课时

从控制台日志定位失败步骤

从控制台日志定位失败步骤

流水线失败后,最有效的做法不是从头阅读全部日志,而是先确定失败阶段,再围绕异常信息、命令退出码和阶段上下文缩小范围。本节建立一套从 Stage 到具体命令的定位顺序,让一次失败能够快速落到可验证的原因上。

学习目标

  • 根据 Stage 状态快速确定失败发生在哪个阶段
  • 从控制台日志中识别异常、退出码和真正的失败命令
  • 使用 Jenkinsfile 增强失败步骤的可观测性并验证修复结果

先找到第一个真正失败的阶段

Declarative Pipeline 会按 Stage 展示执行结果。看到后续阶段显示未执行时,不要把它们当作故障点,应向前寻找第一个失败的 Stage。例如 Test 失败后 Deploy 被跳过,排查入口仍然是 Test。

从失败阶段逐层定位到具体命令

下面的流水线故意让测试命令返回非零状态,用它观察 Jenkins 如何暴露失败位置。

groovy
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'build completed'
            }
        }
        stage('Test') {
            steps {
                sh '''
                    echo "running tests"
                    exit 2
                '''
            }
        }
        stage('Deploy') {
            steps {
                echo 'deploying'
            }
        }
    }
}

预期输出中最关键的是失败命令对应的退出码;Jenkins 的附加日志文本可能随版本和执行环境不同。

text
build completed
running tests
script returned exit code 2

这里可以直接得到三个事实:Build 已完成,失败发生在 Test,Shell 最终返回了退出码 2。Deploy 没有执行只是前序失败的结果,不是新的故障。

从日志末尾向上寻找根因

确定 Stage 后,先查看该阶段日志末尾,因为失败命令、异常和退出状态通常集中在这里。找到 Jenkins 报出的最终错误后,再向上追溯对应命令及其业务输出,而不是只盯着最后一行。

对于 sh 步骤,非零退出码通常意味着命令执行失败。退出码只能告诉你失败发生了,具体原因仍要结合命令前面的输出判断。例如测试工具可能因为断言失败返回 1,也可能因为配置错误返回其他状态。

Java 构建还应优先搜索 ERROR、异常类型以及 Caused by;Shell 脚本则重点检查命令本身、标准错误输出和退出码。凭证、网络或权限问题往往也会在失败命令之前留下明确线索。

让关键步骤更容易定位

长脚本一次塞进一个 sh 步骤,会让失败边界变模糊。可以把构建、测试、打包等动作放入语义明确的 Stage 或独立步骤,并在关键动作前输出必要上下文。日志应帮助定位问题,但不要输出密码、Token 或完整凭证。

如果某个命令的非零状态属于业务分支而不是立即终止条件,可以显式取得状态码,再决定是否让流水线失败。

groovy
script {
    int status = sh(script: './health-check.sh', returnStatus: true)
    echo "health check exit code: ${status}"
    if (status != 0) {
        error("health check failed with exit code ${status}")
    }
}

这是 Jenkinsfile 中的片段示例,需要放在 Declarative Pipeline 的 steps 内,并依赖工作区中存在可执行的 health-check.sh。生效后,日志会明确记录捕获到的状态码,再由 error 主动终止当前构建。

修复后验证同一条执行链

修复故障后,应重新执行原来失败的流水线,并确认三个结果:原失败 Stage 已成功、后续 Stage 能继续运行、控制台中不再出现原异常。只在服务器上手工执行一次命令成功,不能证明 Jenkins 的工作目录、环境变量、凭证和执行用户也已经恢复正常。

如果失败仍然存在,就继续沿“第一个失败 Stage → 最终异常 → 对应命令 → 命令前置输出 → 退出码”的顺序收敛范围。这样可以把大量控制台文本转换成一条可重复的故障定位路径,而不是依赖逐行猜测。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

从控制台日志定位失败步骤

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通