目录

一、环境前置

方式 1：docker run 快速启动

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

2. 启动命令

方式 2：docker-compose.yml（推荐生产使用）

二、首次访问初始化

重点：Docker 环境下 升级 Jenkins

重点：Docker Jenkins 跨服务器迁移

高频踩坑清单

坑 1：目录权限报错（最常见）

坑 2：容器内无法执行 docker 命令（想要宿主机 docker 构建镜像）

坑 3：Java 版本不匹配

坑 4：升级启动失败如何回滚

可选优化建议

---

官方镜像：jenkins/jenkins（不要用 jenkinsci/jenkins 旧镜像） 推荐 LTS 长期支持版 + JDK17，生产首选。

核心原理：容器本身只是运行环境，所有数据保存在宿主机挂载目录 /var/jenkins_home 👉 升级、迁移只需要换镜像，数据卷不动。

一、环境前置

1. 已装好 docker & docker-compose（推荐使用 compose 管理）
2. 开放端口：
   • 8080：Web 访问端口
   • 50000：Jenkins Agent 通信端口

方式 1：docker run 快速启动

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

mkdir -p /data/jenkins_home
# 设置权限！重中之重，容器内jenkins用户UID=1000
chown -R 1000:1000 /data/jenkins_home

2. 启动命令

docker run -d \
  --name jenkins \
  --restart always \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /data/jenkins_home:/var/jenkins_home \
  -v /etc/localtime:/etc/localtime:ro \
  jenkins/jenkins:2.462.3-lts-jdk17

方式 2：docker-compose.yml（推荐生产使用）

新建 docker-compose.yml

services:
  jenkins:
    image: jenkins/jenkins:2.462.3-lts-jdk17
    container_name: jenkins
    restart: always
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      # 持久化数据目录
      - /data/jenkins_home:/var/jenkins_home
      # 同步宿主机时间
      - /etc/localtime:/etc/localtime:ro
    environment:
      TZ: Asia/Shanghai

启动：

# 首次启动前务必授权目录
chown -R 1000:1000 /data/jenkins_home
docker compose up -d

二、首次访问初始化

1. 浏览器访问 http://服务器IP:8080
2. 获取初始管理员密码

# 方式1：容器内读取
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
# 方式2：直接读取宿主机挂载目录
cat /data/jenkins_home/secrets/initialAdminPassword

1. 填入密码 → 推荐选择 安装推荐插件
2. 创建管理员账号，完成初始化

重点：Docker 环境下 升级 Jenkins

无需拷贝配置，数据目录不变，只更换镜像

1. 停止容器

docker compose down
# 或者 docker stop jenkins && docker rm jenkins

1. 更新 compose 文件内 image 版本号为目标新版本
2. 拉取新镜像

docker compose pull

1. 启动

docker compose up -d

✅ 原理：/data/jenkins_home 完整保留所有任务、凭据、构建记录，启动时 jenkins 自动完成版本数据升级。

⚠️ 升级前备份！

tar -zcvf jenkins_back_$(date +%Y%m%d).tar.gz /data/jenkins_home

重点：Docker Jenkins 跨服务器迁移

流程极简：

1. 旧服务器操作

# 停止jenkins
docker-compose down
# 打包整个数据目录
tar -zcvf jenkins_data.tar.gz /data/jenkins_home

1. 将 jenkins_data.tar.gz 传到新服务器
2. 新服务器操作

# 解压
tar -zxvf jenkins_data.tar.gz -C /
# 修复权限
chown -R 1000:1000 /data/jenkins_home

1. 在新服务器执行 docker-compose up -d（使用相同或更高版本镜像）

高频踩坑清单

坑 1：目录权限报错（最常见）

日志出现 Permission denied

# 永久修复命令
chown -R 1000:1000 /data/jenkins_home

容器内 jenkins 用户 uid=1000，不要使用 root 运行 jenkins！

坑 2：容器内无法执行 docker 命令（想要宿主机 docker 构建镜像）

如需 Jenkins 内调用 docker 打包镜像，挂载宿主机 docker.sock：

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

安全提醒：拥有极高权限，内网环境适用。

坑 3：Java 版本不匹配

• 2.357+：最低 JDK11
• 2.401+ 官方推荐 JDK17 镜像名称区分： jenkins/jenkins:xxx-lts-jdk17 → jdk17 jenkins/jenkins:xxx-lts-jdk11 → jdk11

坑 4：升级启动失败如何回滚

1. stop 容器
2. 把镜像版本改回旧版本
3. 使用备份包还原 /data/jenkins_home
4. 重新启动

可选优化建议

1. 配置 Nginx 反向代理 80 端口，开启 HTTPS
2. 修改 Jenkins 系统设置，调整工作空间、构建保留策略，防止磁盘爆满
3. 插件不要一次性全部更新，分批更新避免插件兼容性崩溃
4. 定期定时备份 /data/jenkins_home