平滑升级 Jenkins 的核心在于保留 JENKINS_HOME 数据目录并在升级前进入静默模式，确保正在运行的构建任务完成后再重启服务。适用场景包括 WAR 包替换、Docker 镜像更新或插件生态迁移，主要风险边界是插件兼容性和数据卷备份完整性，正在运行的构建任务在服务重启时会中断，需提前排队或完成。

命令速用版

以下命令用于快速备份数据、进入静默模式及重启服务，根据部署方式选择对应操作。

# 1. 备份数据目录 (Docker 环境)
docker cp your_jenkins_container:/var/jenkins_home /backup/jenkins_home_backup

# 2. 进入静默模式 (阻止新构建，等待现有任务完成)
curl -X POST http://admin:token@jenkins-url/quietDown

# 3. 检查静默状态
curl http://admin:token@jenkins-url/quietDown

# 4. 取消静默模式 (升级完成后)
curl -X POST http://admin:token@jenkins-url/quietDown

# 5. 传统 WAR 包部署重启
service jenkins stop
# 替换 war 包后
service jenkins start

为什么会这样

Jenkins 的配置与构建历史存储在独立目录，与核心 WAR 包分离，因此升级核心程序不会丢失数据。

Jenkins 运行时将任务配置、插件、构建历史等数据存储在 JENKINS_HOME 目录（默认位于 /root/.jenkins 或容器内的 /var/jenkins_home），而核心逻辑位于 WAR 包或容器镜像中。升级操作仅替换核心程序文件，只要不修改或丢失数据目录，原有 Job 配置和构建记录即可保留。但需注意，插件与新版本核心的兼容性可能导致升级后功能异常，且服务重启必然中断当前正在运行的构建进程。

分步处理

按顺序执行备份、静默、替换和验证步骤，确保升级过程可控且可回滚。

第一步：全量备份数据目录
在操作前必须备份持久化数据。对于 Docker 环境，需找到宿主机上挂载的实际目录进行备份，因为容器本身是无状态的，删除或重建容器后内部数据会丢失。对于 WAR 包部署，默认初始化目录在 /root/.jenkins 下面，直接打包备份该目录即可。

第二步：进入静默模式（Quiet Mode）
通过 Web 界面或 API 触发静默模式，阻止新构建任务进入队列，同时等待正在运行的任务完成。注意某些备份插件（如 ThinBackup）可能会意外触发静默模式导致构建队列冻结，需区分是人为操作还是插件故障。

第三步：停止服务并替换核心
确认无运行中任务后停止服务。Docker 环境需拉取目标版本镜像并重新创建容器，确保挂载卷路径不变；WAR 包部署则直接替换 WAR 文件。建议参考官方长期支持版发布页选择稳定版本，避免插件兼容性问题。

第四步：启动服务并取消静默
启动新版本服务，登录后台检查系统状态，手动取消静默模式以恢复构建队列。若发现插件报错，需在外网环境模拟完整插件生态后再迁移至内网，避免依赖缺失。

怎么验证是否生效

通过版本检查、任务列表和日志确认升级结果，确保无数据丢失。

登录 Jenkins 管理界面，查看底部版本号是否已更新为目标版本。进入“新建任务”页面，确认原有 Job 列表存在且配置未丢失。查看“系统日志”或“构建历史”，确认升级前的构建记录可正常访问。若使用 Docker，执行 docker ps 确认容器状态正常，且数据卷挂载路径与升级前一致。

常见坑

升级过程中容易因插件依赖、数据卷映射或静默模式陷阱导致服务不可用。

• 插件依赖地狱：新插件可能依赖多个底层插件，手动下载容易缺失依赖项。建议在外网环境培育完整插件生态后再整体迁移至内网。
• Docker 数据卷丢失：升级时若未正确映射 /var/jenkins_home，重建容器后所有数据将丢失。务必检查 docker inspect 中的 Mounts 信息。
• 静默模式误触发：若发现构建队列不再增长且提示“Preparing for shutdown”，检查是否被备份插件意外触发静默模式，需手动取消。
• 运行中任务中断：服务重启会导致正在运行的 Shell 或 Maven 进程被杀死，可能破坏工作区一致性。务必在静默模式下等待任务自然结束。

常见问题

升级过程中正在运行的构建任务会怎样？

服务重启会导致正在运行的构建任务中断，无法自动恢复。

Jenkins 核心进程停止时，其启动的子进程（如 Shell 脚本、Maven 编译）通常会收到终止信号。若未正确处理信号，任务将强制退出，可能导致工作区不一致或数据库迁移回滚不完整。建议在升级前通过静默模式等待任务自然完成。

升级后插件失效怎么办？

插件失效通常是因为新版本核心不兼容旧插件，需升级插件至匹配版本。

插件和 Jenkins 版本有严格的兼容性要求，强行安装轻则功能异常，重则服务崩溃。若内网无法直接更新，可在外网模拟目标版本环境解析依赖，下载完整插件包后迁移至内网替换。

如何快速回滚到旧版本？

使用升级前备份的数据目录和旧版本 WAR 包或镜像即可回滚。

回滚的关键是数据目录的完整性。只要备份了升级前的 JENKINS_HOME 目录，将其还原并启动旧版本核心程序，即可恢复至升级前状态。切勿仅备份容器内部路径，必须备份宿主机上的实际挂载目录。

参考来源

• 内网 Jenkins 插件生态一键迁移与版本平滑升级实战【避坑指南】
• Jenkins 平滑升级指南-CSDN 博客
• Jenkins 升级踩坑实录：从 2.346 到 2.375 的完整操作指南 (含 Docker 环境解决方案)
• jenkins 停工程
• Jenkins 构建突然中断？ThinBackup 插件可能是罪魁祸首 (附详细修复步骤)