18.9.2 构建与流水线失败的定位方法

围绕“构建与流水线失败的定位方法”，排查应从失败阶段、日志、环境与外部依赖四个维度快速收敛。优先确认失败发生在 Checkout、Build、Test、Archive、Deploy 哪个阶段，并对比最近一次成功构建的变更范围（代码、Jenkinsfile、工具链、插件、节点）。

原理草图（定位路径）：

文章图片

一、基础准备与必要安装（日志与调试插件）
1) 在 Jenkins 全局配置中安装并启用增强日志插件（以 Pipeline Utility Steps、AnsiColor 为例）：

# 在 Jenkins 系统中访问: 管理 Jenkins -> 插件管理 -> 可选插件
# 勾选: Pipeline Utility Steps, AnsiColor, Timestamper
# 安装后重启 Jenkins

2) 在 Pipeline 中启用 timestamps 与 ansiColor：

pipeline {
  agent any
  options {
    timestamps()
    ansiColor('xterm')
  }
  stages {
    stage('Build') {
      steps {
        sh 'echo "build start"'
      }
    }
  }
}

预期效果：Console Output 中出现时间戳与彩色输出，便于定位报错时间与步骤。

二、标准定位流程（含可执行示例）
1) 复现与对比（复用参数触发）

# Jenkins Web: 构建历史 -> 失败构建 -> 重新构建（Replay/Build with Parameters）
# 若有参数，保持参数一致后重新触发

预期效果：确认失败可复现，排除短暂抖动。

2) 识别失败点（Console Output 快速定位）

# Jenkins Web: 失败构建 -> Console Output
# 查找关键字：ERROR、FAILURE、Exception、script returned exit code

示例日志片段（注意首条错误）：

[Build] sh
+ mvn -U -Dmaven.test.skip=false test
[ERROR] Failed to execute goal ...
script returned exit code 1

结论：失败发生在 Build/Test 阶段，maven test 步骤。

3) 分类诊断（按类型缩小范围）
- 语法错误：Jenkinsfile 语法或插件不支持
- 环境问题：JDK/Maven/Node/Docker 不匹配
- 权限/凭据：SCM/制品库/镜像仓库授权失败
- 依赖/网络：DNS/代理/防火墙/外部服务不可用
- 资源瓶颈：磁盘满、内存不足、CPU 抢占

三、关键命令与排错示例（含解释）
1) Pipeline 语法校验与回放

# Jenkins Web: Pipeline Syntax -> 校验 Jenkinsfile
# 或使用 Replay（需权限）：构建历史 -> Replay -> 临时修改 Jenkinsfile

预期效果：校验失败会提示具体行号与错误原因。

2) 构建环境检查（Agent 节点）

# 在构建 Agent 上执行
java -version           # 检查 JDK 版本
mvn -v                  # 检查 Maven 版本
node -v && npm -v       # 检查 Node 环境
docker version          # 检查 Docker 引擎

常见问题：全局工具配置与 Agent 实际工具版本不一致。

3) 凭据与 SCM 拉取失败

# Jenkinsfile 示例：使用凭据拉取私有仓库
pipeline {
  agent any
  stages {
    stage('Checkout') {
      steps {
        git credentialsId: 'git-ssh-key',
            url: 'git@github.com:org/repo.git',
            branch: 'main'
      }
    }
  }
}

排错命令（Agent 上验证网络与权限）：

ssh -T git@github.com     # 验证 SSH 凭据与连通性
git ls-remote git@github.com:org/repo.git  # 验证仓库访问

4) 制品推送失败（以 Nexus 为例）

# 检查 Nexus 连通与权限
curl -u user:pass https://nexus.example.com/service/rest/v1/status

若返回 401/403：检查凭据与角色权限；若 5xx：检查 Nexus 服务状态与磁盘配额。

5) Docker/镜像问题

# Agent 上检查镜像仓库可用性与拉取权限
docker login registry.example.com
docker pull registry.example.com/app:latest
systemctl status docker   # 检查 Docker 服务

6) 资源不足快速定位

df -h        # 磁盘空间
free -m      # 内存
top -c       # CPU 与进程占用

建议：构建空间不足时清理 workspace 或制品缓存。

四、日志收集与定位入口
- Jenkins 系统日志：管理 Jenkins -> 系统日志
- 构建日志：构建历史 -> Console Output
- Agent 日志：/var/log/jenkins/agent.log 或节点服务日志
- 容器日志：docker logs <container_id>

示例：开启流水线失败时输出上下文信息

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh '''
          set -euo pipefail
          echo "JAVA_HOME=$JAVA_HOME"
          echo "MAVEN_HOME=$MAVEN_HOME"
          mvn -U test
        '''
      }
    }
  }
  post {
    failure {
      sh '''
        echo "=== ENV ==="
        env | sort
        echo "=== DISK ==="
        df -h
      '''
    }
  }
}

预期效果：失败时输出环境变量与磁盘信息，辅助定位。

五、典型问题示例（含解决思路）
1) Pipeline 语法错误（插件版本不支持）

WorkflowScript: 12: Unknown stage section "steps"

处理：升级 Pipeline 插件或调整 Jenkinsfile 语法为当前支持版本。

2) Maven 版本不一致导致编译失败

[ERROR] invalid source release: 17

处理：检查 Agent JDK 版本与 maven-compiler-plugin 配置一致。

3) 拉取镜像失败

Error response from daemon: pull access denied

处理：确认 registry 凭据、镜像标签与访问权限。

六、练习与自检
1) 练习：故意制造失败并定位
- 将 Jenkinsfile 中分支名改为不存在的分支
- 触发构建并定位失败阶段与错误日志
- 修复后再次构建

2) 练习：模拟资源不足
- 在 Agent 上创建大文件占满空间（测试环境）

fallocate -l 5G /tmp/bigfile
df -h
  • 触发构建，观察失败日志并清理
rm -f /tmp/bigfile

七、最佳实践清单（可直接落地）
- 固化构建环境：Docker 化构建，固定工具版本。
- 增强日志：timestamps、ansiColor、失败时输出上下文信息。
- 外部依赖重试与超时：对 SCM/制品库/镜像仓库设置重试。
- 失败分类与知识库：沉淀“错误码—原因—解决方案”映射。
- 变更可追踪：记录 Jenkinsfile 与插件变更历史，便于回滚。