0%

Jenkins 升级最佳实践

📋 目录

  1. 升级前准备
  2. 升级 Jenkins 核心
  3. 升级插件
  4. 升级后验证
  5. 常见问题与解决方案
  6. 回滚方案

🚨 升级前准备

1. 检查当前状态

1
2
3
4
5
6
7
8
# 查看 Jenkins 版本
curl -s http://localhost:8080/login | grep -o 'Jenkins [0-9.]*'

# 查看 Java 版本
java -version

# 查看插件列表
ls -la /var/jenkins_home/plugins/*.hpi | wc -l

2. 备份（必须！）

1
2
3
4
5
6
7
8
9
10
11
# 备份 Jenkins 主目录
cp -r /var/jenkins_home /var/jenkins_home.backup.$(date +%Y%m%d)

# 备份 jenkins.war
cp /usr/share/java/jenkins.war /usr/share/java/jenkins.war.backup.$(date +%Y%m%d)

# 备份插件目录
cp -r /var/jenkins_home/plugins /var/jenkins_home/plugins.backup.$(date +%Y%m%d)

# 备份任务配置
cp -r /var/jenkins_home/jobs /var/jenkins_home/jobs.backup.$(date +%Y%m%d)

3. 检查系统要求

Jenkins 2.551+ 要求：

  • ✅ Java 21 或 Java 25
  • ✅ 内存：至少 2GB
  • ✅ 磁盘：至少 10GB 可用空间

检查 Java 版本：

1
2
java -version
# 如果低于 Java 21，需要升级

升级 Java：

1
2
3
4
5
cd /home
wget https://download.java.net/java/GA/jdk21.0.2/f2283984656d49d69e91c558476027ac/13/GPL/openjdk-21.0.2_linux-x64_bin.tar.gz
tar -xzf openjdk-21.0.2_linux-x64_bin.tar.gz
export JAVA_HOME=/home/jdk-21.0.2
export PATH=$JAVA_HOME/bin:$PATH

4. 通知团队

  • 📧 发送升级通知邮件
  • 📅 选择低峰时段（如周末或深夜）
  • ⏸️ 暂停正在进行的构建

🚀 升级 Jenkins 核心

方法 1：Jenkins UI 升级（推荐）

Jenkins 管理 → 插件管理 → Updates：

  1. 点击 Check now (立即检查)
  2. 找到 Jenkins 核心更新
  3. 勾选 Jenkins
  4. 点击 Download now and install after restart
  5. 勾选 Restart Jenkins when installation is complete and no jobs are running
  6. 点击 Install
  7. 等待重启（约 5-10 分钟）

优点：

  • ✅ 自动处理依赖
  • ✅ 安全回滚
  • ✅ 图形化界面

方法 2：手动替换 jenkins.war

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 备份
cp /usr/share/java/jenkins.war /usr/share/java/jenkins.war.backup

# 3. 下载新版本
cd /usr/share/java
wget https://updates.jenkins.io/download/war/2.553/jenkins.war

# 4. 设置权限
chown jenkins:jenkins jenkins.war
chmod 644 jenkins.war

# 5. 启动 Jenkins
systemctl start jenkins

# 6. 查看日志
tail -f /var/log/jenkins/jenkins.log

方法 3：Docker 升级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 备份数据卷
docker run --rm -v jenkins_home:/data -v $(pwd):/backup alpine tar czf /backup/jenkins-backup.tar.gz -C /data .

# 2. 停止并删除容器
docker stop jenkins
docker rm jenkins

# 3. 拉取最新镜像
docker pull jenkins/jenkins:lts

# 4. 启动新容器
docker run -d -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  --name jenkins \
  jenkins/jenkins:lts

# 5. 查看日志
docker logs -f jenkins

🔧 升级插件

1. 批量升级所有插件（推荐）

Jenkins 管理 → 插件管理 → Updates：

  1. 点击 Check now
  2. 点击 Select all (全选)
  3. 点击 Download now and install after restart
  4. 勾选 Restart Jenkins when installation is complete
  5. 等待重启

优点：

  • ✅ 自动解决依赖关系
  • ✅ 避免版本冲突
  • ✅ 最安全的方式

2. 升级单个插件

Jenkins 管理 → 插件管理 → Installed：

  1. 点击 Updates available
  2. 找到目标插件
  3. 勾选并安装
  4. 重启 Jenkins

3. 手动安装插件

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 下载插件
cd /var/jenkins_home/plugins
wget https://updates.jenkins.io/download/plugins/git-client/6.4.3/git-client.hpi

# 2. 停止 Jenkins
systemctl stop jenkins

# 3. 安装插件
# 直接放入 plugins 目录即可

# 4. 启动 Jenkins
systemctl start jenkins

4. 处理依赖冲突

如果遇到依赖错误：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 删除冲突插件
cd /var/jenkins_home/plugins
rm -f git*.hpi git*.jpi git-client*.hpi git-client*.jpi gitlab*.hpi gitlab*.jpi
rm -rf git git-client gitlab-plugin

# 3. 启动 Jenkins
systemctl start jenkins

# 4. 重新安装插件（按顺序）
# Jenkins UI → 插件管理 → Available plugins
# 1. 先安装 Git Client
# 2. 再安装 Git Plugin
# 3. 最后安装 GitLab Plugin

✅ 升级后验证

1. 检查版本

1
2
3
4
# 访问 Jenkins Web UI
curl -s http://localhost:8080/login | grep -o 'Jenkins [0-9.]*'

# 应该显示新版本号

2. 检查插件状态

Jenkins 管理 → 插件管理 → Installed：

  • ✅ 所有插件状态为 “已启用”
  • ✅ 无依赖错误
  • ✅ 无警告信息

3. 检查任务配置

1
2
3
4
5
# 遍历所有任务
for job in /var/jenkins_home/jobs/*/config.xml; do
  echo "检查：$job"
  grep -i "error" "$job" || echo "✅ 正常"
done

4. 测试构建

  1. 选择一个简单任务
  2. 点击 立即构建
  3. 查看构建日志
  4. 确认成功完成

5. 检查日志

1
2
3
4
5
6
7
8
# 查看 Jenkins 日志
tail -100 /var/log/jenkins/jenkins.log

# 查看系统日志
journalctl -u jenkins -n 50

# 查找错误
grep -i "error\|exception\|failed" /var/log/jenkins/jenkins.log | tail -20

🔧 常见问题与解决方案

问题 1：Java 版本太低

错误信息：

1
Running with Java 17, which is older than the minimum required version (Java 21)

解决方案：

1
2
3
4
5
6
7
8
# 升级 Java 到 21
wget https://download.java.net/java/GA/jdk21.0.2/.../openjdk-21.0.2_linux-x64_bin.tar.gz
tar -xzf openjdk-21.0.2_linux-x64_bin.tar.gz
export JAVA_HOME=/home/jdk-21.0.2
export PATH=$JAVA_HOME/bin:$PATH

# 重启 Jenkins
systemctl restart jenkins

问题 2：插件依赖缺失

错误信息：

1
Plugin is missing: jersey3-api (3.1.11-2.v4a_b_db_cf4557b_)

解决方案：

  1. Jenkins UI → 插件管理 → Available plugins
  2. 搜索 jersey3-api
  3. 安装并重启

问题 3：类加载冲突

错误信息：

1
java.lang.ClassNotFoundException: org.eclipse.jgit.errors.MissingObjectException

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 删除冲突插件
cd /var/jenkins_home/plugins
rm -f git*.hpi git-client*.hpi gitlab*.hpi
rm -rf git git-client gitlab-plugin

# 3. 重启 Jenkins
systemctl start jenkins

# 4. 重新安装插件（按顺序）
# Git Client → Git Plugin → GitLab Plugin

问题 4：任务配置保存失败

错误信息：

1
Error while serving .../configSubmit

解决方案：

  1. 重启 Jenkins（清除缓存）
  2. 如果不行，清理插件缓存：
    1
    rm -rf /var/jenkins_home/plugins/.cache
  3. 重新安装相关插件

问题 5：Webhook 不触发

问题：GitLab 推送后 Jenkins 无反应

解决方案：

  1. 检查 GitLab Server 配置

    1
    2
    3
    Jenkins 管理 → 系统配置 → GitLab
    - Server URL: 正确
    - Credentials: 有效

  2. 检查任务触发器

    1
    2
    任务配置 → 构建触发器
    ✅ Build when a change is pushed to GitLab

  3. 检查 GitLab Webhook

    1
    2
    3
    GitLab → 项目 → 设置 → Webhooks
    - URL: 正确
    - 触发器：Push events

  4. 测试 Webhook

    1
    GitLab → Webhooks → Test → Push events

🔙 回滚方案

回滚 Jenkins 核心

1
2
3
4
5
6
7
8
9
10
11
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 恢复备份
cp /usr/share/java/jenkins.war.backup /usr/share/java/jenkins.war

# 3. 启动 Jenkins
systemctl start jenkins

# 4. 验证
curl -s http://localhost:8080/login | grep -o 'Jenkins [0-9.]*'

回滚插件

1
2
3
4
5
6
7
8
9
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 恢复插件备份
rm -rf /var/jenkins_home/plugins
cp -r /var/jenkins_home/plugins.backup /var/jenkins_home/plugins

# 3. 启动 Jenkins
systemctl start jenkins

完全回滚

1
2
3
4
5
6
7
8
9
# 1. 停止 Jenkins
systemctl stop jenkins

# 2. 恢复完整备份
rm -rf /var/jenkins_home
cp -r /var/jenkins_home.backup.YYYYMMDD /var/jenkins_home

# 3. 启动 Jenkins
systemctl start jenkins

📋 升级检查清单

升级前

  • 备份 Jenkins 主目录
  • 备份 jenkins.war
  • 备份插件目录
  • 备份任务配置
  • 检查 Java 版本（≥ 21）
  • 通知团队
  • 选择低峰时段

升级中

  • 升级 Jenkins 核心
  • 等待重启完成
  • 升级所有插件
  • 等待插件安装完成

升级后

  • 检查 Jenkins 版本
  • 检查插件状态
  • 检查任务配置
  • 测试构建
  • 检查日志
  • 验证 Webhook
  • 通知团队升级完成

📖 参考链接

📝 升级记录模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
## Jenkins 升级记录

**升级日期**: YYYY-MM-DD
**升级人员**: [姓名]

### 升级前
- Jenkins 版本：x.x.x
- Java 版本：x.x.x
- 插件数量：xxx

### 升级后
- Jenkins 版本：x.x.x
- Java 版本：x.x.x
- 插件数量：xxx

### 问题与解决
1. [问题描述] - [解决方案]
2. [问题描述] - [解决方案]

### 验证结果
- [ ] Jenkins 启动正常
- [ ] 所有插件正常
- [ ] 任务配置正常
- [ ] 构建测试通过
- [ ] Webhook 测试通过

### 备注
[其他需要记录的信息]

升级前务必备份！升级时按顺序操作！升级后全面验证！🔥