CentOS 上 Jenkins 部署故障排查清单
一 快速定位与通用检查
- 查看服务状态与最新日志：执行systemctl status jenkins -l，并用journalctl -u jenkins -n 50 --no-pager或tail -n 50 /var/log/jenkins/jenkins.log定位报错关键字（如 Java、端口、权限、配置）。
- 确认 Java 可用：执行java -version；Jenkins 2.357+ 建议使用Java 11 或 Java 17，老版本可能支持 Java 8。若未安装或版本不符，安装并更新默认 Java。
- 检查端口与连通：用ss -tulnp | grep 8080或netstat -tulnp | grep 8080确认端口占用；云服务器还需确认安全组/本机防火墙已放行。
- 防火墙放行：对 firewalld 执行firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload。
- 配置文件与目录权限：核对**/etc/sysconfig/jenkins**（如 JENKINS_PORT、JENKINS_JAVA_CMD），确保**/var/lib/jenkins /var/cache/jenkins /var/log/jenkins属主为jenkins:jenkins**。
- 无法启动时做最小化验证：直接运行java -jar /usr/share/java/jenkins.war --httpPort=8080（路径以实际安装为准），以排除 systemd 配置干扰。
二 常见症状与对应处理
| 症状 |
快速检查 |
处理要点 |
| 服务起不来，日志含 “failed to find a valid Java installation” |
java -version 为空或路径不对 |
安装合适版本 Java（建议 Java 11/17），必要时在 /etc/sysconfig/jenkins 设置 JENKINS_JAVA_CMD 指向 $JAVA_HOME/bin/java |
| 端口被占用 |
ss -tulnp |
grep 8080 有输出 |
| 访问 http://IP:8080 报 404 |
systemctl status jenkins、ps -ef |
grep jenkins、tail 日志 |
| 插件安装/更新超时或失败 |
浏览器开发者工具看 update-center.json 请求 |
更换更新站点为国内镜像（如清华源），或临时使用 http 源；离线环境可手动上传 .hpi 插件 |
| 安装 RPM 时报 “No such file or directory” 指向 /var/cache/jenkins 等 |
rpm -ivh 日志 |
旧 /etc/sysconfig/jenkins 残留导致脚本失败；备份后删除该文件再重装 |
| systemd 启动报错 “Unknown lvalue … in section ‘Unit’” |
systemctl status jenkins |
编辑 /usr/lib/systemd/system/jenkins.service，删除不兼容参数（如 StartLimitBurst/StartLimitIntervalSec），执行 systemctl daemon-reload 后重启 |
| 忘记管理员密码 |
文件是否存在 |
查看 /var/lib/jenkins/secrets/initialAdminPassword 获取初始密码；或临时将 config.xml 中 useSecurity 设为 false 后重启（记得恢复） |
三 配置与网络关键点
- Java 与路径：确认 java -version 输出满足要求；若 Jenkins 找不到 Java，在 /etc/sysconfig/jenkins 显式设置 JENKINS_JAVA_CMD。
- 端口与防火墙：默认 8080；如需变更，修改 /etc/sysconfig/jenkins 的 JENKINS_PORT 并重启；同时放行 firewalld 或云安全组。
- 反向代理：Nginx/Apache 需正确设置 X-Forwarded-For/X-Forwarded-Proto，以及 JENKINS_PREFIX（如部署在子路径），否则会出现登录或静态资源异常。
- 更新站点：在 系统管理 → 管理插件 → 高级 将 升级站点 改为可用源（如 https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json），解决网络超时。
- SELinux：若启用且访问异常，可临时执行 setenforce 0 验证是否为 SELinux 策略问题，再按需配置策略或保持 permissive。
四 性能与稳定性排查
- 资源瓶颈：监控 CPU/堆内存/磁盘 I/O；堆过小或 GC 停顿长会导致 CPS 超时、流水线卡死；$JENKINS_HOME 放在 NFS/SMB 等延迟高的存储会显著变慢。
- 并发任务：大量 MultiBranch 项目启动后批量 Branch Indexing 会抢占资源；可限制并发、优化 SCM 轮询、错峰执行。
- 网络连通：无法解析 updates.jenkins.io 等域名会造成线程阻塞与超时；检查 DNS/代理/出口策略，必要时使用镜像源与离线插件包。
五 一键排查命令清单
- 服务与日志：
- systemctl status jenkins -l
- journalctl -u jenkins -n 50 --no-pager
- tail -n 50 /var/log/jenkins/jenkins.log
- Java 与端口：
- java -version
- ss -tulnp | grep 8080
- 防火墙与安全组：
- firewall-cmd --list-ports
- firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload
- 权限与目录：
- ls -ld /var/lib/jenkins /var/cache/jenkins /var/log/jenkins
- chown -R jenkins:jenkins /var/lib/jenkins /var/cache/jenkins /var/log/jenkins
- 配置与验证：
- grep -E ‘^JENKINS_PORT|^JENKINS_JAVA_CMD’ /etc/sysconfig/jenkins
- systemctl daemon-reload && systemctl restart jenkins
- java -jar /usr/share/java/jenkins.war --httpPort=8080（最小化验证）