Ubuntu 上部署 Jenkins 的排查与解决指南
一 快速自检清单
- 检查服务状态与日志
- 查看状态：sudo systemctl status jenkins
- 查看日志：sudo journalctl -u jenkins.service -f 或 tail -n 50 /var/log/jenkins/jenkins.log
- 确认 Java 可用
- 查看版本：java -version
- 安装 Java（Ubuntu 24.04 推荐）：sudo apt install fontconfig openjdk-17-jre
- 检查端口占用
- 查看端口：ss -ltnp | grep :8080 或 sudo lsof -i :8080
- 释放端口：sudo kill -9
- 防火墙放行
- UFW：sudo ufw allow 8080 && sudo ufw status
- 初始化密码
- 查看密码：sudo cat /var/lib/jenkins/secrets/initialAdminPassword
- 目录权限
- 修复目录：sudo chown -R jenkins:jenkins /var/lib/jenkins /var/cache/jenkins /var/log/jenkins
以上步骤覆盖了最常见的启动失败、访问异常与权限问题，可优先执行以快速定位故障点。
二 常见故障与修复
- 服务起不来或端口冲突
- 现象：systemctl 显示 failed；日志提示端口被占用。
- 处理：换端口或释放占用端口。
- 换端口（推荐用 systemd 覆盖）：systemctl edit jenkins，在 [Service] 下新增：Environment=“JENKINS_PORT=8081”，然后 sudo systemctl daemon-reload && sudo systemctl restart jenkins
- 或编辑：/etc/default/jenkins，将 HTTP_PORT=8080 改为 8081，再重启
- Java 未找到或版本不兼容
- 现象：日志出现 “ERROR: No Java executable found in current PATH”
- 处理：
- 安装合适版本：sudo apt install openjdk-17-jre（或 openjdk-11-jdk）
- 建立软链：sudo ln -s /usr/lib/jvm/java-17-openjdk-amd64/bin/java /usr/bin/java
- 选择默认 Java：sudo update-alternatives --config java
- APT 源与证书错误
- 现象：apt update 报 GPG 或证书校验失败
- 处理：
- 导入新密钥并写入 keyring（Debian 系推荐方式）：
- wget -O /usr/share/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
- echo “deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/” | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
- sudo apt update
- 若仍报证书错误，先更新 CA 证书：sudo apt install --reinstall ca-certificates
- 时间与证书校验失败
- 现象：apt 报 “server certificate verification failed”
- 处理：校准系统时间（如 sudo timedatectl set-ntp true 或手动校正），再 apt update
- 插件下载慢或失败
- 现象：插件安装卡顿或超时
- 处理：在 Manage Jenkins > Manage Plugins > Advanced 将更新站点改为国内镜像，例如：https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json
以上修复覆盖了端口、Java、证书、源与插件等高频问题，按序处理通常可恢复安装与启动。
三 标准安装步骤 Ubuntu 24.04
- 安装 Java
- sudo apt update && sudo apt install -y fontconfig openjdk-17-jre
- 验证：java -version
- 添加 Jenkins 官方仓库（使用签名 keyring）
- wget -O /usr/share/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
- echo “deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/” | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
- 安装并启动
- sudo apt update && sudo apt install -y jenkins
- sudo systemctl enable --now jenkins
- 检查：sudo systemctl status jenkins
- 防火墙放行
- sudo ufw allow 8080 && sudo ufw status
- 初始化
- 获取密码：sudo cat /var/lib/jenkins/secrets/initialAdminPassword
- 访问：http://<服务器IP>:8080，按向导安装推荐插件并创建管理员
以上流程适用于 Ubuntu 24.04，兼顾安全与可维护性（签名源、systemd 管理、默认端口 8080）。
四 Docker 部署方案
- 准备数据目录与权限
- sudo mkdir -p /opt/jenkins_home
- sudo chown -R 1000:1000 /opt/jenkins_home（容器内默认 jenkins 用户 UID/GID 为 1000）
- 启动容器（示例）
- 使用 LTS + JDK 17 镜像，映射 8080/50000，挂载数据卷与 Docker 套接字（如需在容器内执行宿主 Docker 命令）
- 示例 compose（可按需精简）：
- version: ‘3’
- services:
- jenkins:
- image: jenkins/jenkins:lts-jdk17
- container_name: jenkins
- restart: always
- ports:
- “8080:8080”
- “50000:50000”
- volumes:
- /opt/jenkins_home:/var/jenkins_home
- /var/run/docker.sock:/var/run/docker.sock
- 初始化
- 获取密码：sudo docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
- 访问：http://<服务器IP>:8080
该方式隔离环境、便于备份与迁移，注意挂载 /var/run/docker.sock 的安全风险与权限设置。
五 任务执行与权限要点
- Shell 命令找不到或环境不一致
- 现象：Execute shell 中 ll 等命令不可用
- 处理：在命令前加 #!/bin/sh -l 以登录方式执行，或在脚本中显式加载环境（如 source /etc/profile）
- 容器内执行宿主命令
- 如需在容器内使用宿主 Docker，挂载 /var/run/docker.sock 并确保目录权限与用户映射正确（常见为 1000:1000）
- 远程部署
- 安装 Publish Over SSH 插件，在系统配置中添加目标主机与凭据，使用 SSH 执行远程脚本或传输文件
这些要点可显著降低“命令不可用”“权限被拒”等流水线常见问题。
