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

目录

核心原理

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

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

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

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

2. 传输备份包并解压

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

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

方式 1：docker run 命令

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

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

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

2. 凭证丢失 / 无法解密

3. Agent 节点无法连接

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 种情况：

1. 未配置环境变量（默认）Tomcat 启动用户家目录：/usr/share/tomcat/.jenkins或/home/tomcat/.jenkins
2. 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 路径
3. 启动脚本指定 export JENKINS_HOME=/xxx

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

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

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

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

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

# 替换为你查到真实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（推荐长期使用）

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）在容器内不存在

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

六、可选迁移优化建议

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

七、回滚方案

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