CentOS 上部署 Jenkins 的常见错误与排查要点
一 环境与仓库问题
- 证书校验失败导致无法下载仓库元数据：执行 yum install -y ca-certificates 更新 CA 证书后再添加 Jenkins 官方仓库与导入 GPG 密钥。若仍异常，可临时使用 –no-check-certificate 下载仓库文件，事后务必恢复校验。官方仓库与密钥示例：wget https://pkg.jenkins.io/redhat-stable/jenkins.repo 与 rpm –import https://pkg.jenkins.io/redhat-stable/jenkins.io.key。
- GPG 校验失败：安装命令后加 –nogpgcheck 或临时将 /etc/yum.conf 中的 gpgcheck=0，完成安装后再改回 1 并导入系统 RPM-GPG-KEY-centosofficial。
- 依赖缺失：安装时提示如 Requires: daemonize，先通过 *yum provides /daemonize 找到提供包并安装，再装 Jenkins。
- 系统兼容与依赖库：CentOS 7 自带软件较旧，新版 Jenkins 常需 Java 11+；若插件或 HTTPS 调用报 SSL/TLS 相关错误，考虑安装 openssl11 与 openssl11-libs 并更新库链接。
二 Java 与启动故障
- Java 版本不兼容：新版 Jenkins 要求 Java 11 或更高；CentOS 7/8 可能默认是 Java 8。使用 alternatives --config java 切换默认 Java，或在 /usr/lib/systemd/system/jenkins.service 中设置 Environment=“JAVA_HOME=/usr/lib/jvm/java-11-openjdk”，随后执行 systemctl daemon-reexec && systemctl restart jenkins。
- 启动脚本找不到 Java：报错如 bash: /usr/bin/java: No such file or directory，在 /etc/init.d/jenkins（或 systemd 单元）里显式配置 JENKINS_JAVA_CMD 或 JAVA_HOME 指向正确的 java 可执行文件，再 systemctl daemon-reload 重启。
- systemd 单元加载异常：出现 Unit jenkins.service failed to load: Unknown unit，多为单元文件损坏或未正确安装，执行 systemctl status jenkins、必要时重装 Jenkins 包并 daemon-reload。
- 端口冲突：默认 8080 被占用会导致 Address already in use/Bind on port 8080 failed。用 netstat -tulnp | grep 8080 查占用进程并释放，或在 /etc/sysconfig/jenkins 中修改 JENKINS_PORT 后重启。
三 网络访问与权限配置
- 防火墙未放行：CentOS 7 使用 firewalld，需放行 8080（或自定义端口）：firewall-cmd –permanent --zone=public --add-port=8080/tcp 与 firewall-cmd --reload；用 firewall-cmd --list-ports 核对。
- 云服务器安全组：除本机防火墙外，还需在云平台安全组放行对应 TCP 端口。
- 首次启动卡在 “Please wait while Jenkins is getting ready to work…”：修改 /var/lib/jenkins/hudson.model.UpdateCenter.xml，将更新源改为可用镜像（如 http://mirror.xmission.com/jenkins/updates/update-center.json），必要时检查 /var/lib/jenkins/updates/default.json 中的地址，重启服务。
- 权限不足导致写入失败：日志出现无权限错误时，检查 /var/lib/jenkins /var/cache/jenkins /var/log/jenkins 属主与权限；必要时在 /etc/sysconfig/jenkins 将 JENKINS_USER 设为具备权限的用户并修正目录属主，再重启。
四 反向代理与跨域相关错误
- HTTP 403 No valid crumb was included in the request：CSRF 保护引起。临时方案（不建议长期生产）可在 /etc/sysconfig/jenkins 增加 JENKINS_JAVA_OPTIONS=“-Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true”；更优做法是保持 CSRF 开启并正确配置代理与请求头。
- 嵌入 iframe 报跨域或空白：由 X-Frame-Options 导致。可在 Nginx 侧设置 X-Frame-Options SAMEORIGIN，或在 Jenkins 安装 X-Frame-Options Plugin 后调整为允许同源嵌套。
- Nginx 反向代理常见要点：设置 proxy_pass 到 Jenkins，传递 Host 与协议头，按需配置 X-Forwarded-For/X-Real-IP，并统一 Access-Control-Allow-Origin/Headers/Methods 以避免浏览器跨域限制。
五 快速排查清单
- 服务状态与日志：systemctl status jenkins；journalctl -u jenkins.service -xe；tail /var/log/jenkins/jenkins.log。
- Java 与端口：java -version；alternatives –config java；netstat -tulnp | grep 8080；必要时修改 /etc/sysconfig/jenkins 的 JENKINS_PORT 与 JENKINS_JAVA_CMD/JAVA_HOME。
- 防火墙与安全组：firewall-cmd –list-ports；确认云厂商安全组放行对应 TCP 端口。
- 仓库与依赖：yum repolist；yum install -y ca-certificates；处理 GPG 与缺失依赖（如 daemonize）。
- 初始化与插件：首次解锁密码在 /var/lib/jenkins/secrets/initialAdminPassword；若更新源慢或失败，替换为可用镜像后重启。
