Tomcat 部署 Jenkins → Docker Jenkins 完整迁移方案

核心原理

[一、第一步：找到 Tomcat 上 Jenkins 的 JENKINS_HOME（最容易踩坑）](#一、第一步：找到 Tomcat 上 Jenkins 的 JENKINS_HOME（最容易踩坑）)

[二、旧服务器：停止服务 + 完整备份](#二、旧服务器：停止服务 + 完整备份)

[三、新服务器：准备 Docker Jenkins 挂载目录](#三、新服务器：准备 Docker Jenkins 挂载目录)

[1. 创建宿主机持久化目录](#1. 创建宿主机持久化目录)

[2. 传输备份包并解压](#2. 传输备份包并解压)

[🔥重中之重：权限修复（Docker 迁移头号坑）](#🔥重中之重：权限修复（Docker 迁移头号坑）)

[四、启动 Docker Jenkins（两种方式任选）](#四、启动 Docker Jenkins（两种方式任选）)

[方式 1：docker run 命令](#方式 1：docker run 命令)

[方式 2：docker-compose.yml（推荐长期使用）](#方式 2：docker-compose.yml（推荐长期使用）)

[五、启动后关键校验 & 常见问题修复](#五、启动后关键校验 & 常见问题修复)

[1. 访问地址注意上下文路径！](#1. 访问地址注意上下文路径！)

[2. 凭证丢失 / 无法解密](#2. 凭证丢失 / 无法解密)

[3. Agent 节点无法连接](#3. Agent 节点无法连接)

[4. 构建脚本内绝对路径失效](#4. 构建脚本内绝对路径失效)

六、可选迁移优化建议

七、回滚方案

核心原理

Jenkins 所有配置、任务、凭证、构建记录全部保存在 JENKINS_HOME 目录。

Tomcat 部署 war 包形式的 Jenkins 和 Docker Jenkins 本质是同一套程序，直接迁移完整JENKINS_HOME即可 ，不需要单独导出任务。 ⚠️ 关键前提：新旧 Jenkins 大版本尽量保持一致（例如旧是 2.401，新镜像也选用 2.401-lts；跨大版本极易插件报错）

一、第一步：找到 Tomcat 上 Jenkins 的 JENKINS_HOME（最容易踩坑）

Jenkins.war 丢进 Tomcat，JENKINS_HOME位置分 3 种情况：

未配置环境变量（默认） Tomcat 启动用户家目录：/usr/share/tomcat/.jenkins 或 /home/tomcat/.jenkins
tomcat context.xml 配置了 JENKINS_HOME（生产最常见）
复制代码
```
<Environment name="JENKINS_HOME" value="/data/jenkins_home" type="java.lang.String"/>
```
去${CATALINA_HOME}/conf/Catalina/localhost/jenkins.xml查找 value 路径
启动脚本指定 export JENKINS_HOME=/xxx

快速验证：登录 Jenkins → 系统管理 → 系统信息 ，找到 JENKINS_HOME 字段，复制路径！

二、旧服务器：停止服务 + 完整备份

进入 Jenkins 页面：http://ip:8080/jenkins/exit 优雅关闭
停止 Tomcat

bash 复制代码

systemctl stop tomcat
# 确认进程全部关闭

打包完整JENKINS_HOME（必须停止服务再打包，防止文件损坏）

bash 复制代码

# 替换为你查到真实JENKINS_HOME路径
JENKINS_OLD=/data/jenkins_home
tar -zcvf jenkins_full_backup.tar.gz ${JENKINS_OLD}

不要只备份 jobs 目录！secrets/、credentials.xml、secret.key 存放所有凭证，丢了凭证全部失效。

三、新服务器：准备 Docker Jenkins 挂载目录

1. 创建宿主机持久化目录

复制代码

mkdir -p /opt/jenkins_home

2. 传输备份包并解压

复制代码

# 旧机器推送
scp jenkins_full_backup.tar.gz root@新机器IP:/opt/
# 新机器解压
cd /opt
tar -zxvf jenkins_full_backup.tar.gz -C /opt/jenkins_home --strip-components=1

--strip-components=1：去掉压缩包外层文件夹，保证文件直接落在/opt/jenkins_home/下

🔥重中之重：权限修复（Docker 迁移头号坑）

官方镜像 jenkins/jenkins:lts 容器内运行用户 UID=1000，GID=1000 宿主机解压出来的文件属主一般是 root/tomcat，容器会报 Permission denied！

复制代码

chown -R 1000:1000 /opt/jenkins_home

CentOS/RHEL 开启 SELinux 环境，启动挂载增加:z标签解决权限拦截

四、启动 Docker Jenkins（两种方式任选）

方式 1：docker run 命令

复制代码

docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /opt/jenkins_home:/var/jenkins_home:z \
  jenkins/jenkins:lts

/var/jenkins_home 是容器内部固定 JENKINS_HOME 路径，不要修改！

方式 2：docker-compose.yml（推荐长期使用）

bash 复制代码

services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - /opt/jenkins_home:/var/jenkins_home:z
    restart: always

启动：docker compose up -d

五、启动后关键校验 & 常见问题修复

1. 访问地址注意上下文路径！

Tomcat 部署默认访问路径：http://xxx:8080/jenkins（带 /jenkins 上下文） Docker 默认根路径：http://xxx:8080

两种处理方案： 方案 A（推荐，修改 Jenkins 系统 URL）登录 Jenkins → 系统管理 → 系统找到 Jenkins URL ，把旧地址 http://ip:8080/jenkins/ 改成新地址 http://新IP:8080/，保存重启。

方案 B：让 Docker Jenkins 也使用 /jenkins 上下文启动参数增加环境变量：

复制代码

-e JENKINS_OPTS="--prefix=/jenkins"

访问地址：http://ip:8080/jenkins

2. 凭证丢失 / 无法解密

现象：所有凭据显示【无法解密】原因：备份不完整，缺少 secrets/secret.key ✅ 解决方案：重新用停止服务后的完整 JENKINS_HOME 打包迁移，不要只拷贝 jobs

3. Agent 节点无法连接

旧 Agent 配置里写的是旧 Jenkins 地址，需要：

修改 Agent 配置中的 Jenkins URL
或者重启 Agent 重新建立连接

4. 构建脚本内绝对路径失效

重点排查：

脚本中硬编码旧服务器路径（/opt/maven、/data/workspace）
工具（JDK/Maven/Git）在容器内不存在

建议：容器内安装对应工具，或者使用工具自动安装插件

六、可选迁移优化建议

不要直接使用 latest 标签 ，锁定和旧环境一致的版本，例如 jenkins/jenkins:2.401.3-lts
迁移前在旧 Jenkins 升级全部插件到最新，减少启动报错
先并行运行新旧 Jenkins 测试，确认任务正常执行，再关停 Tomcat 旧实例
大量构建历史占用磁盘：可迁移完成后选择性清理旧 build 记录

七、回滚方案

迁移出现重大问题：停止 docker jenkins，重新启动 tomcat 旧 Jenkins，数据完全不受影响。