CentOS 上 Jenkins 部署故障排除手册
一 快速定位流程
- 检查服务状态与启动日志：执行systemctl status jenkins；若失败，用journalctl -xe查看详细错误，并查看**/var/log/jenkins/jenkins.log**定位根因。
- 校验 Java：执行java -version，确认已安装且版本满足要求（Jenkins 2.357+ 通常需要 Java 11+，老版本可用 Java 8）。
- 排查端口：默认端口8080，用netstat -tulnp | grep 8080或ss -ltnp | grep 8080确认是否被占用；若冲突，改端口或释放占用进程。
- 防火墙与安全组：在 firewalld 放行对应端口（如firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload），云服务器还需检查安全组规则。
- 修改配置后重载：调整 /etc/sysconfig/jenkins 或 systemd 单元后执行systemctl daemon-reload再启动。
二 常见故障与修复对照表
| 症状 |
快速检查 |
修复建议 |
| 服务起不来，提示“Job for jenkins.service failed …” |
systemctl status、journalctl -xe、/var/log/jenkins/jenkins.log |
依据日志逐项修复（端口冲突/Java 缺失/配置错误），完成后 daemon-reload 并重启 |
| 启动日志报“bash: /usr/bin/java: No such file or directory” |
which java、ls /usr/bin/java |
安装 JDK，或在 /etc/sysconfig/jenkins 设置 JENKINS_JAVA_CMD 指向正确的 java 可执行文件 |
| 日志报“failed to find a valid Java installation” |
java -version、echo $JAVA_HOME |
安装 Java 8/11+ 并正确配置 JAVA_HOME 与 PATH |
| 端口 8080 无法访问 |
本机 curl http://127.0.0.1:8080、ss/ netstat 查占用、firewall-cmd --list-ports |
释放占用端口或改 JENKINS_PORT，并放行防火墙/安全组 |
| 首次启动一直卡在“Please wait while Jenkins is getting ready to work…” |
查看工作目录文件 |
替换 /var/lib/jenkins/hudson.model.UpdateCenter.xml 的更新源为国内镜像，必要时调整 default.json，重启服务 |
| 插件更新页空白或超时 |
浏览器开发者工具 Network |
将插件源换为国内镜像（如清华/中科大）以加速与连通 |
| HTTP 403 No valid crumb was included |
近期是否开启 CSRF 保护 |
临时在 /etc/sysconfig/jenkins 的 JENKINS_JAVA_OPTIONS 添加 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true（仅测试环境），或正确配置代理与 CSRF |
| 反向代理/域名下出现跨域或 X-Frame-Options 拦截 |
浏览器控制台报错、curl -I 响应头 |
代理层正确设置 CORS 与 X-Frame-Options: SAMEORIGIN，避免重复或冲突的跨域头 |
| systemd 报错 Unknown lvalue ‘StartLimitBurst’ |
systemctl status 指向服务文件 |
编辑 /usr/lib/systemd/system/jenkins.service，删除/注释不兼容参数，执行 daemon-reload 重启 |
三 关键配置文件与路径
- Java 与启动命令：在 /etc/sysconfig/jenkins 设置 JENKINS_JAVA_CMD=“/usr/bin/java” 或指向 $JAVA_HOME/bin/java，确保与已安装 JDK 一致。
- 服务端口：在 /etc/sysconfig/jenkins 修改 JENKINS_PORT=“8080”（或改为未占用端口）。
- 更新源：替换 /var/lib/jenkins/hudson.model.UpdateCenter.xml 中的 URL 为可用镜像，必要时调整 /var/lib/jenkins/updates/default.json。
- 日志与数据：服务日志 /var/log/jenkins/jenkins.log；工作目录 /var/lib/jenkins（权限问题请确认 jenkins 用户对目录可读写）。
- systemd 单元：如存在老版本不兼容参数，编辑 /usr/lib/systemd/system/jenkins.service 后执行 systemctl daemon-reload。
四 访问与安全加固建议
- 访问与连通：确认本机能访问后，再测试从外部浏览器访问 http://服务器IP:端口；若通过域名/反向代理访问，确保代理转发正确且端口一致。
- 防火墙与安全组：在 firewalld 放行对应端口（如8080/tcp），云上实例同步放通安全组入站规则。
- 反向代理与嵌入：如需在 iframe 中嵌入或配置域名访问，代理需设置 X-Frame-Options: SAMEORIGIN 与合适的 CORS 头，避免与 Jenkins 自身策略冲突。
- 安全提示：禁用 CSRF 仅用于临时排障，生产环境应保持开启并按需配置代理与凭据。
五 最小化验证步骤
- 安装并验证 Java：安装 Java 11（或 Java 8 对应老版本），执行java -version确认。
- 安装与启动：yum 安装后执行systemctl start jenkins && systemctl enable jenkins。
- 放行端口：执行firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload。
- 首次解锁：查看**/var/lib/jenkins/secrets/initialAdminPassword**，在浏览器完成初始化。
- 插件与更新：如遇超时，将插件源切换为国内镜像后更新。
