Ubuntu 上 Jenkins 故障排查清单
一 快速定位流程
sudo systemctl status jenkins、sudo journalctl -u jenkins -xe。sudo tail -f /var/log/jenkins/jenkins.log。java -version、sudo update-alternatives --config java。ss -tulnp | grep 8080 或 sudo netstat -tulnp | grep 8080。curl -I http://127.0.0.1:8080 测试。二 常见症状与对应处理
| 症状 | 快速检查 | 处理要点 |
|---|---|---|
| 无法访问 http://IP:8080 | systemctl status jenkins、`ss -tulnp |
grep 8080、curl -I 127.0.0.1:8080` |
| 页面空白或报 JS 错误 | 浏览器开发者工具 Console/Network | 清理浏览器缓存与 Jenkins 临时目录；逐步回退最近插件或主题变更 |
| 启动失败或反复重启 | journalctl -u jenkins -xe、tail -f /var/log/jenkins/jenkins.log |
从日志抓取首条报错；常见为 Java 不匹配、端口冲突、权限不足、JVM 内存不足 |
| 插件安装/更新失败 | 系统日志与 /var/log/jenkins/jenkins.log |
切换镜像源或离线安装；暂时禁用冲突插件；确保网络与时间同步 |
| 构建报权限错误 | 构建日志、ls -ld 工作空间与目录 |
确认工作空间与工具链目录对 jenkins 用户可读写；必要时 chown -R jenkins:jenkins <dir> |
| 系统资源不足 | free -h、`dmesg |
tail` |
以上检查点涉及的命令与路径为 Ubuntu 上常用的故障定位手段与默认配置位置，可据此快速缩小问题范围。
三 关键配置与命令速查
sudo systemctl status jenkins、sudo journalctl -u jenkins -xe、sudo tail -f /var/log/jenkins/jenkins.log。java -version、sudo update-alternatives --config java。JENKINS_ARGS 中加入 --javaOptions=-Xmx512m（或更高，视内存而定），然后重启。ss -tulnp | grep 8080 或 sudo netstat -tulnp | grep 8080。sudo ufw allow 8080/tcp、sudo ufw status；云服务器需同时放行安全组 8080/tcp。JENKINS_ARGS="--webroot=/var/cache/jenkins/war --httpPort=8080 --httpListenAddress=0.0.0.0"，使外部可访问。sudo systemctl daemon-reload、sudo systemctl restart jenkins。sudo chown -R jenkins:jenkins /var/lib/jenkins /var/cache/jenkins /var/log/jenkins。四 日志分析与实用技巧
sudo tail -f /var/log/jenkins/jenkins.log；sudo grep -i "error\|exception\|fail" /var/log/jenkins/jenkins.log；sudo less /var/log/jenkins/jenkins.log。五 高频特殊问题与修复
sudo update-alternatives --config java 切换；必要时创建软链 sudo ln -s /usr/lib/jvm/java-11-openjdk-amd64/bin/java /usr/bin/java。sudo timedatectl set-ntp true 或手动校准），再更新索引。--httpListenAddress=0.0.0.0 并重启。JENKINS_ARGS 中降低 -Xmx（如 512m），或增加服务器内存。