Ubuntu Jenkins故障排查指南

Ubuntu 上 Jenkins 故障排查指南

一 快速定位路径

• 服务状态与单元日志
  • 查看状态：sudo systemctl status jenkins
  • 查看单元日志：sudo journalctl -u jenkins -xe
• 应用日志
  • 实时查看：sudo tail -f /var/log/jenkins/jenkins.log
• 端口与监听
  • 检查端口占用：ss -tulnp | grep 8080 或 sudo netstat -tulnp | grep 8080
  • 定位占用进程：sudo lsof -i :8080 与 kill -9 <PID>
• Java 环境
  • 版本检查：java -version
  • 多版本切换：sudo update-alternatives --config java
• 防火墙与云安全组
  • UFW 放行：sudo ufw allow 8080/tcp 与 sudo ufw status
  • 云上需同时在安全组放行 8080/TCP。

二 常见故障与修复

• 服务无法启动

  • 典型现象：systemctl status jenkins 显示 Active: failed，或 journalctl 提示 Failed with result ‘exit-code’。
  • 处理步骤：
    • 查看详细日志：journalctl -u jenkins -xe 与 /var/log/jenkins/jenkins.log
    • 确认 Java 版本匹配（Jenkins 2.346+ 建议 Java 11）：sudo apt install openjdk-11-jdk 与 update-alternatives --config java
    • 在 systemd 单元中显式设置 JAVA_HOME（示例）：
      • sudo systemctl edit jenkins 添加：
        • [Service]
        • Environment="JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64"
    • 重载并重启：sudo systemctl daemon-reload && sudo systemctl restart jenkins
    • 若仍失败，检查是否因插件更新导致启动异常，优先回滚最近插件或进入安全模式启动（见第四节）。

• 无法访问 Web 界面

  • 排查顺序：
    • 服务是否运行：systemctl status jenkins
    • 端口是否监听：ss -tulnp | grep 8080
    • 防火墙与云安全组是否放行 8080/TCP
    • 监听地址是否正确：编辑 /etc/default/jenkins，确保包含
      • JENKINS_ARGS="--webroot=/var/cache/jenkins/war --httpPort=8080 --httpListenAddress=0.0.0.0"
      • 修改后重启：sudo systemctl restart jenkins

• 端口冲突

  • 现象：启动失败或日志提示端口被占用。
  • 处理：
    • 查找占用：sudo lsof -i :8080 或 ss -tulnp | grep 8080
    • 结束进程：kill -9 <PID>
    • 或改用其他端口并同步修改 /etc/default/jenkins 中的 –httpPort，重启服务。

• 权限与目录问题

  • 现象：启动日志出现无法写入日志或工作目录等 IO 异常。
  • 处理：
    • 修正目录属主：sudo chown -R jenkins:jenkins /var/lib/jenkins /var/cache/jenkins /var/log/jenkins
    • 如曾改动运行用户为 root，需同步检查相应目录权限与 SELinux/AppArmor 策略（不建议长期使用 root 运行）。

• 插件兼容性导致启动或构建失败

  • 现象：升级后无法启动、插件部署失败，或构建时报 NoSuchMethodError、Failed to deploy 等。
  • 处理：
    • 回滚最近插件或进入安全模式启动，逐个恢复定位问题插件
    • 升级相关插件与依赖到与当前 Jenkins 核心兼容的版本
    • 清理损坏插件目录后重装

三 Docker 场景要点

• 关闭终端后容器退出
  • 使用 -d 后台运行：docker run -d -p 8080:8080 jenkins/jenkins:lts
  • 配置重启策略：restart: always
  • 示例 compose：
    • version: ‘3’
    • services:
      • jenkins:
        • image: jenkins/jenkins:lts
        • ports:
          • “8080:8080”
        • volumes:
          • jenkins_home:/var/jenkins_home
        • restart: always
    • volumes:
      • jenkins_home:
• 进入容器排查：docker exec -it <container> bash，随后按“快速定位路径”检查服务、日志与端口。

四 高频命令与配置速查

• 服务与日志
  • sudo systemctl status jenkins
  • sudo journalctl -u jenkins -xe
  • sudo tail -f /var/log/jenkins/jenkins.log
• 端口与进程
  • ss -tulnp | grep 8080
  • sudo lsof -i :8080 与 kill -9 <PID>
• Java
  • java -version
  • sudo update-alternatives --config java
• 防火墙
  • sudo ufw allow 8080/tcp
  • sudo ufw status
• 配置文件
  • 监听地址与端口：/etc/default/jenkins
    • JENKINS_ARGS="--webroot=/var/cache/jenkins/war --httpPort=8080 --httpListenAddress=0.0.0.0"
  • systemd 单元覆写
    • sudo systemctl edit jenkins
    • 添加：Environment="JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64"