DevOps构建发布问题排查指南

通用排查思路

1. 查看详细日志
   • DevOps 后端日志
   • Jenkins 控制台输出（流水线详情页）
   • K8s 事件日志：kubectl describe pod xxx
2. 确认环境配置
   • Jenkins 服务器是否安装必要工具（git、java、maven、docker）
   • 环境变量是否配置（PATH、JAVA_HOME、MAVEN_HOME）
   • 资源凭证是否配置正确（账号密码、Token、SSH 密钥）
   • 执行用户是谁（root/普通用户）
   • PATH 是否包含所需命令
   • 代码库、介质库、镜像仓库地址、账号密码是否正确
3. 检查网络连通性
   • Jenkins 能否访问 Git 仓库、Nexus 仓库、镜像仓库
   • 目标服务器能否被 Jenkins 访问（SSH）
   • 是否存在防火墙、代理限制
   • 检查 kubeconfig 文件权限和有效期

---

代码拉取失败

1. 权限认证失败

典型报错信息：

The project you were looking for could not be found or you don't have permission to view it.

Authentication failed for https://gitlab.com/xxx.git

排查步骤：

1. 检查 Token 有效性：登录 GitLab，检查 Personal Access Token 是否过期
2. 检查凭证配置：DevOps 平台 → 个人设置 → 凭证管理，确认 Token/密码正确

解决方案： 登录 GitLab 生成新的 Personal Access Token，在 DevOps 平台 → 个人设置 → 凭证管理中更新凭证信息

---

构建工具找不到

构建工具未找到

典型报错信息： ant: command not found

Cannot run program ‘git’ (in directory "xxx" ）error=2, No such file or directory

JAVA_HOME is not defined correctly

现象：指定的构建工具版本不生效

排查步骤：

1. 检查 构建工具是否安装
2. 检查环境变量 PATH 中是否包含构建工具可执行路径
3. 检查Devops平台管理 ->业务字典中构建工具版本配置

解决方案：

• **方案 1：**安装构建工具

  例如：Jenkins 系统管理 → 全局工具配置 → Ant → 新增 Ant

• 方案 2： 若 Jenkins 服务器已安装构建工具，则可以在 jenkins 的 PATH+EXTRA 中配置构建工具的环境变量

• **方案 3：**构建工具版本扩展开发参考链接： 构建工具版本扩展开发 (opens new window)

---

容器与 K8s 相关问题

1. 镜像构建与推送失败

典型报错信息： docker login failed 现象： 构建成功但推送失败

排查步骤：

1. 检查 Jenkins 服务器 Docker 服务状态
2. 确认 Jenkins 用户是否有 Docker 权限
3. 检查配置Docker后是否重启Jenkins使配置生效
4. 检查 Dockerfile 语法
5. 在 Jenkins 所在服务器手动执行 Docker 命令测试
6. 查看 Jenkins 控制台日志

解决方案：

• 方案 1： Jenkins 启动用户添加到 Docker 组，重启 Jenkins
• 方案 2： 根据详细错误提示修正 Dockerfile；确保基础镜像可拉取

2. K8s 资源部署问题

典型报错信息：

• The connection to the server localhost:8080 was refused
• You must be logged in to the server (the server has asked for the client to provide credentials)

现象： 部署成功但应用不显示

排查步骤：

1. 在 Jenkins 服务器执行 kubectl get nodes，确认 kubeconfig 有效
2. 当前 jenkins 启动用户是否有读取 kubeconfig 文件权限
3. Devops 6.5 及之前版本检查 certificate-authority, client-certificate, client-key 配置是否正确

解决方案：

• 方案 1： Devops 6.5 及之前版本 certificate-authority, client-certificate, client-key 配置参考链接：配置指南 (opens new window)
• 方案 2： 使用 yaml 部署不会在“应用模块”展示，可以用“Kubernetes 容器云应用部署”原子任务。

---

脚本执行问题

1. 脚本卡死/流水线停滞

问题现象：

• 流水线卡在 99% 不结束
• 脚本执行成功但流水线不继续
• 原子任务一直运行中

排查步骤：

1. 查看 Jenkins 控制台完整日志
2. 检查脚本中是否有大量 echo 输出
3. 检查脚本中是否有交互式命令
4. 检查脚本中是否有后台进程
5. 在服务器手动执行相同脚本

解决方案：

• 方案 1： 优化脚本减少输出；或将输出重定向：command > /dev/null 2>&1
• 方案 2： 移除交互式命令；使用非交互式方式替代
• 方案 3： 确保脚本最后有 exit 0；避免死循环

2. 前后置脚本执行异常

问题现象：

• 前置后置脚本中执行 Shell 失败
• 前后置脚本中变量无效

排查步骤：

1. 检查 Shell 命令格式
2. 检查变量引用方式
3. 添加调试输出，打印执行命令和结果

解决方案：

• 方案 1： 前后置脚本通过 groovy 发起对 shell 的调用，单行 Shell 命令 使用：sh "shell 脚本"，多行 Shell 命令 使用：sh """shell 脚本内容"""
• 方案 2： 变量引用参考链接：变量定义指南 (opens new window)

---

原子任务调试指南

原子任务脚本位置

• Devops 6.6 以及之前版本标准原子任务： /WEB-INF/_srv/work/user/com.primeton.devops.engine/META-INF/pipeline/stages/
• Devops 6.7 版本标准原子任务： /config/DEVOPS/work/user/com.primeton.devops.engine/META-INF/pipeline/stages/

以下脚本调试技巧仅供参考：

Groovy 脚本调试技巧

// 添加调试输出
println "========== 调试开始 =========="
println "当前工作目录: ${pwd()}"
println "构建参数: ${params}"

// 捕获异常
try {
    // 执行主要逻辑
    sh "your command"
} catch (Exception e) {
    println "执行失败: ${e.getMessage()}"
    // 根据需要决定是否抛出异常
    throw e
}
println "========== 调试结束 =========="

Shell 脚本调试技巧

#!/bin/bash
set -x # 显示执行的命令
set -e # 出错时退出

echo "当前用户: $(whoami)"
echo "当前目录: $(pwd)"
echo "PATH: $PATH"

# 检查命令是否存在，如果不存在则脚本报错退出 (利用 set -e 或显式退出)
if ! command -v docker &> /dev/null; then
    echo "错误: docker 未找到，请安装 Docker。"
    exit 1      # 显式退出，触发 set -e 机制
fi

# 执行主要逻辑
your_command

echo "命令执行成功！"

set +x # 关闭调试

Python 脚本调试技巧

#!/usr/bin/env python
import os
import sys
import logging

# 配置日志
logging.basicConfig(
    level=logging.INFO, # 生产环境建议用 INFO，调试时改为 DEBUG
    format='%(asctime)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)
logger = logging.getLogger(__name__)

logger.debug("当前用户: %s", os.getenv('USER', 'unknown'))
logger.debug("当前目录: %s", os.getcwd())
logger.debug("环境变量: %s", dict(os.environ))

# 获取 DevOps 变量
build_id = os.getenv('BUILD_ID')
logger.debug("BUILD_ID: %s", build_id)

try:
    # 执行主要逻辑
    result = your_function()
    logger.info("执行成功: %s", result)
except Exception as e:
    logger.error("执行失败: %s", str(e))
    sys.exit(1)