Jenkins 在 Linux 配置中的常见问题与排查要点
一 服务与端口
- 端口被占用：修改 /etc/sysconfig/jenkins 中的 JENKINS_PORT（如改为 8081/8888），或排查占用并释放端口后重启服务。
- 启动失败 Job for jenkins.service failed：优先检查 Java 路径是否在 /etc/init.d/jenkins 的候选路径中；若修改了系统配置或 unit 文件，执行 systemctl daemon-reload 再启动；查看 systemctl status jenkins 与 journalctl -xe 获取具体报错。
- 访问不了：确认服务已启动（systemctl status jenkins），并开放防火墙端口（firewalld/iptables）；云服务器还需在安全组放行对应端口。
二 Java 与版本兼容
- 版本不匹配：新版本 Jenkins 要求 Java 8 或更高；若 java -version 过低，需升级 JDK 或选择与之匹配的 Jenkins WAR 版本。
- 找不到 Java：在 /etc/init.d/jenkins 中显式加入本机 $JAVA_HOME/bin/java 路径，或建立软链到系统 PATH 可达位置；修改后重载并重启。
- 多 JDK 并存：用 update-alternatives 设置默认 java，或在 Jenkins 的“全局工具配置”中指定 JAVA_HOME。
三 插件与更新源
- 更新站点超时：将插件更新源切换为可达镜像（如 清华 TUNA：https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json），在“插件管理 → 高级”设置 Update Site；必要时清理插件目录缓存后重试。
- 安装失败或依赖不满足：检查网络与依赖插件，先升级 Jenkins 版本再装；离线环境可先在联网机下载 .hpi 插件，在“高级 → Deploy Plugin”手动上传安装。
- 首次解锁：查看初始管理员密码 cat /var/lib/jenkins/secrets/initialAdminPassword。
四 构建与权限
- 权限不足/目录不可写：构建用户（默认 jenkins）对 /var/lib/jenkins /var/cache/jenkins /var/log/jenkins 等目录需具备读写权限；必要时执行 chown -R jenkins:jenkins 相关目录（不建议直接改为 root 运行，存在安全风险）。
- 构建进程被杀死：在构建脚本中使用 BUILD_ID=dontKillMe 防止被 Jenkins 回收；确保脚本中使用的工具在 PATH 中或使用绝对路径。
- 环境变量缺失：在“系统管理 → 系统配置 → 全局属性 → 环境变量”补充 JAVA_HOME/M2_HOME/PATH 等；或在节点/任务级配置工具路径。
- Maven 流水线报错：如 “missing server JVM” 等，检查 Maven 与 JDK 可用、工作空间与挂载盘（如 XFS > 1T 场景）是否存在 I/O 异常，必要时更换构建节点或调整挂载策略。
五 网络与代理及离线环境
- 公司代理导致连接失败：在“插件管理 → 高级”配置 HTTP Proxy；确保 /etc/yum.repos.d/jenkins.repo 等仓库地址可达，必要时导入 GPG 并安装 ca-certificates。
- 无法访问更新站点：临时方案为手动下载所需插件 .hpi 离线安装；或先行下载 Jenkins 安装包与插件集合后内网部署。
- 云主机访问：除本机防火墙外，还需在云平台安全组放行 8080/自定义端口。