Jenkins 迁移 + 版本升级 完整实操方案

目录一、先确认关键信息1找到 JENKINS_HOME2版本兼容性提醒场景 1本机 Jenkins 版本升级不迁移机器步骤场景 2跨服务器迁移旧机器 → 新机器可顺便升级方案 A完整迁移推荐任务、构建历史、凭证全部保留操作流程⚠️迁移后常见问题方案 B只迁移配置丢弃历史构建记录轻量迁移场景 3Docker Jenkins 迁移 / 升级高危避坑清单故障回滚标准流程可选进阶方案配置导出导入适合少量 Job不推荐大规模迁移先区分两个场景同服务器只升级 Jenkins 版本跨服务器迁移可顺带升级版本核心原则所有配置、任务、构建记录、凭证、插件都存在JENKINS_HOME程序包 war/jar 只是运行程序⚠️ 重要前置升级不要跨太大版本跳跃大版本间存在兼容性断层例如 2.249 → 2.401 尽量分步旧 LTS 升级新 LTS 优先一、先确认关键信息1找到 JENKINS_HOMELinux yum/apt 默认/var/lib/jenkinsDocker/var/jenkins_homeWindowsC:\Program Files (x86)\Jenkins页面查看Jenkins 首页 → 系统 → 系统信息 →JENKINS_HOME2版本兼容性提醒Jenkins 分为LTS 长期支持版推荐生产和 Weekly 周更版禁止从非常老旧版本直接跳到最新版例2.222.x → 不要直接升到 2.460中间分段升级避免插件数据结构变更导致启动失败Java 版本强绑定大坑Jenkins ≥2.357最低 Java 11Jenkins ≥2.401推荐 Java 17升级前新服务器 / 新环境 Java 版本必须匹配目标 Jenkins 版本场景 1本机 Jenkins 版本升级不迁移机器步骤停止 Jenkins 服务# systemd systemctl stop jenkins # docker docker stop jenkins备份【必做】# 备份整个家目录 cp -r /var/lib/jenkins /var/lib/jenkins.bak.$(date %Y%m%d) # 可选单独备份插件、凭证替换程序包rpm/yum更新软件包yum update jenkinsaptapt upgrade jenkinswar 包部署下载新版本 jenkins.war覆盖旧 war启动服务systemctl start jenkins访问页面 首次启动会执行数据迁移脚本等待初始化完成 进入后系统 → 插件管理升级所有兼容插件。回滚方案启动异常 → stop 服务删除新 war换回旧 warJENKINS_HOME 使用备份恢复。场景 2跨服务器迁移旧机器 → 新机器可顺便升级两种方案方案 A完整迁移推荐任务、构建历史、凭证全部保留新旧机器可以Jenkins 版本相同也可以在新机器直接部署高版本实现「迁移 升级一步到位」操作流程旧节点操作① 停止旧 Jenkinssystemctl stop jenkins② 打包整个 JENKINS_HOMEtar -zcvf jenkins_home_backup.tar.gz /var/lib/jenkins新节点准备① 安装 Jenkins目标版本可以比旧版本高注意 Java 版本匹配 ②不要启动 Jenkins极其关键 ③ 删除新安装生成的空家目录rm -rf /var/lib/jenkins④ 上传压缩包解压还原tar -zxvf jenkins_home_backup.tar.gz -C / # 修正权限jenkins运行用户必须拥有目录权限 chown -R jenkins:jenkins /var/lib/jenkins新节点启动 Jenkinssystemctl start jenkins访问验证全部流水线、凭据、节点配置保留如果新旧版本不一致启动时自动升级数据库结构进入插件管理更新插件⚠️迁移后常见问题agent 节点配置旧机器 IP 写死的 agent需要修改地址路径硬编码构建脚本里写死旧服务器路径需要全局替换ssh 凭据一般无需重配密钥保存在目录内端口、nginx 反向代理按需重新配置。方案 B只迁移配置丢弃历史构建记录轻量迁移不复制builds/目录适合构建日志巨大、不想迁移几十 G 数据 打包时排除 buildstar --exclude/var/lib/jenkins/builds --exclude/var/lib/jenkins/workspace -zcvf jenkins_cfg.tar.gz /var/lib/jenkins缺点所有历史构建记录丢失场景 3Docker Jenkins 迁移 / 升级逻辑完全一致容器重点在于持久卷停止旧容器备份挂载目录宿主机映射的/var/jenkins_home拉取新版本 jenkins/jenkins 镜像使用同一个持久卷启动新容器docker run -d \ -p 8080:8080 -p 50000:50000 \ -v /宿主机jenkins目录:/var/jenkins_home \ -v /etc/localtime:/etc/localtime \ jenkins/jenkins:2.440.3-lts-jdk17不要直接删除卷卷就是你的 JENKINS_HOME高危避坑清单❌Java 版本不匹配直接启动→ 进程崩溃❌ 新机器先启动 Jenkins 生成目录再覆盖数据 → 权限冲突、文件锁异常❌ 大跨度版本跳跃无备份直接升级 → 数据库结构无法降级❌ 迁移后忘记修改目录属主jenkins 用户无读写权限页面 500❌ agent 连接使用旧 IP、旧密钥❌ Windows ↔ Linux 迁移注意文件换行、路径分隔符差异故障回滚标准流程启动异常、页面报错、任务打不开停止 jenkins删除当前 JENKINS_HOME解压之前的备份包换回原来可正常运行的 jenkins.war/ 旧版本程序可选进阶方案配置导出导入适合少量 Job不推荐大规模迁移使用插件Configuration Slicing、Job Import Plugin缺点凭据、全局工具、系统配置无法完整导出只适合少量任务迁移企业正式迁移优先用【完整拷贝 JENKINS_HOME】方案。