CentOS 上部署与运行 Jenkins 的常见问题解答
一 环境准备与版本兼容
- 确认 Java 版本：Jenkins 2.3+ 要求 Java 11 或更高版本；CentOS 7 常见为 Java 8，需升级。建议安装 OpenJDK 11 或 JDK 17，并使用 alternatives 切换默认 Java。示例：sudo yum install -y java-11-openjdk-devel；sudo alternatives --config java。若使用 JDK 17，可下载安装后验证 java -version。
- 升级系统与依赖：执行 sudo yum update -y；必要时启用 EPEL 仓库（sudo yum install -y epel-release）以获取更新依赖。
- 安装字体依赖：部分环境首次启动需要 fontconfig（sudo yum install -y fontconfig），避免启动异常。
二 安装与启动
- 添加官方仓库并安装：sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo；sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key；sudo yum install -y jenkins。
- 启动与开机自启：sudo systemctl enable --now jenkins；检查状态：systemctl status jenkins。
- 首次解锁：查看初始管理员密码：sudo cat /var/lib/jenkins/secrets/initialAdminPassword，在浏览器访问 http://服务器IP:8080 完成初始化。
三 访问与网络连通
- 防火墙放行：开放 8080/tcp（或自定义端口），例如：sudo firewall-cmd --permanent --add-port=8080/tcp；sudo firewall-cmd --reload。也可创建自定义 firewalld service 并放行。
- 端口冲突排查：检查是否被占用（ss -tulnp | grep 8080 或 netstat -tulnp | grep 8080），必要时修改 Jenkins 端口后重启。
- 云服务器与安全组：除系统防火墙外，还需在云厂商控制台放行对应 TCP 端口。
- 反向代理与上下文路径：若通过 Nginx/Apache 代理，确认代理配置与 Jenkins 的 JENKINS_PREFIX 一致；常见现象是访问返回 404 或跳转异常。
四 插件与更新
- 更新站点超时/速度慢：在 Manage Jenkins → Manage Plugins → Advanced 将 Update Site 改为国内镜像，例如：https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json；保存后重启 Jenkins。
- 离线或首次启动卡住：检查并更新工作目录中的更新中心配置，例如编辑 /var/lib/jenkins/hudson.model.UpdateCenter.xml，将 URL 调整为可用镜像；如仍有问题，检查 /var/lib/jenkins/updates/default.json 中的下载地址。修改后重启服务。
五 服务启动失败与权限错误
- 查看日志定位：journalctl -u jenkins -n 50 --no-pager 或 tail -n 50 /var/log/jenkins/jenkins.log，优先从日志获取具体报错。
- Java 路径不正确：编辑 /usr/lib/systemd/system/jenkins.service，设置 Environment=“JAVA_HOME=/usr/lib/jvm/java-11-openjdk”；修改后执行 systemctl daemon-reload 并重启。
- 配置文件变更需重载：修改 systemd 或 sysconfig 后执行 systemctl daemon-reload。
- 目录权限问题：确保 /var/lib/jenkins /var/cache/jenkins /var/log/jenkins 归属 jenkins:jenkins，必要时执行 chown -R jenkins:jenkins。
- 端口被占用：更换 JENKINS_PORT 或停止占用该端口的进程后重启。
- CSRF 报错 403：在 /etc/sysconfig/jenkins 的 JENKINS_JAVA_OPTIONS 中临时加入 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true（仅用于排障，生产环境不建议长期关闭）。
- 构建与运行权限：若以 root 运行（不推荐），需同步调整相关目录属主；更优做法是保持 jenkins 用户并通过 sudo 或代理授权执行特权操作。