1. 为什么选 Docker 来跑 Jenkins1.1 传统安装方式的三座大山先说点实际感受。几年前我在一台 Windows 机器上直接装 Jenkins光环境准备就折腾了两天。第一座大山是 JDK 版本。Jenkins 本身是用 Java 写的对 JDK 版本特别敏感新版 Jenkins 要求 Java 11 或 17而项目里其他工具链可能还需要 JDK 8。一台机器上多版本 JDK 切换环境变量改来改去改完还要重启终端一个不小心启动脚本又报 Java 版本不兼容。第二座大山是升级与迁移。Jenkins 小版本更新频率不低直接安装的版本升级时要小心翼翼一旦插件和核心版本不匹配整个界面白屏配好的 Job 全部失联。更难受的是换机器JENKINS_HOME 目录整个拷过去路径、权限、服务配置全要调整。第三座大山是系统污染。Jenkins 默认跑在自带的 Jetty 上会拉一堆运行时依赖到系统目录。你要卸载它得手动清注册表、删残留文件稍不留神就把同机器上部署的其他 Java 应用影响了。1.2 Docker 方案到底解决了什么Docker 装 Jenkins 的核心价值就是一句话把 Jenkins 以及它的运行环境一起打包成一个独立容器与宿主机彻底隔离。这种隔离带来几个实实在在的好处。首先镜像自带 JDK 和运行时宿主机上有没有 Java、Java 版本是多少完全不影响 Jenkins。你机器上哪怕同时跑着 JDK 8 的老项目和 JDK 17 的新项目Jenkins 容器里依然按它自己的规矩办事。其次升级和迁移变成秒级操作。想换个 Jenkins 版本拉新镜像、停旧容器、起新容器JENKINS_HOME 挂载在外部数据全部保留。换机器更是简单把挂载目录拷过去一条 docker run 命令原地复活。最后是清理方便。不想要了docker stop 加 docker rm再删掉挂载目录干干净净宿主机上一个残留文件都不留。我自己的体会是用 Docker 部署 Jenkins 之后以前那些环境层面的麻烦基本与我无关了我可以把精力放在流水线和自动化本身上而不是陪它折腾 Java 环境和系统配置。1.3 镜像怎么选jenkins/jenkins 与 jenkinsci/blueocean官方推荐有两个镜像我分别用过说说差异。第一个是 jenkins/jenkins这是 Jenkins 官方长期维护的 LTS 镜像最正统文档最全社区踩坑记录最多。适合大多数人尤其是刚接触 Jenkins 的朋友。第二个是 jenkinsci/blueocean它在 jenkins/jenkins 基础上预装了 Blue Ocean 插件套装。Blue Ocean 是一套更现代的可视化流水线界面界面上能直接看到每个 Stage 的实时状态、日志、测试结果交互确实比经典界面漂亮。如果你的项目主要是 Pipeline 方式想追求更直观的界面体验可以选这个。还有一个选择是 jenkins/jenkins:lts-jdk17即 LTS 版本搭配 JDK 17。现在新装 Jenkins我建议直接上 JDK 17 的镜像因为新插件基本都在往 JDK 17 靠拢老镜像里的 JDK 11 慢慢会碰到兼容性问题。有个细节提醒一下别用 latest 标签生产环境。latest 指向的是每周发布的开发版功能更新快但稳定性没有 LTS 有保障。我一般固定用类似 jenkins/jenkins:2.452.1-lts-jdk17 这样的明确版本升级时自己控制节奏避免某天重启容器后发现版本突变导致插件全挂。2. 先把 Docker 环境打通2.1 Windows 和 macOSDocker Desktop 的几个关键设置Windows 上装 Docker 基本绕不开 Docker Desktop。这个软件目前做得比较成熟安装过程本身没什么难度但有几个设置不处理好后面会踩不少坑。第一个坑是 WSL 2 后端。Docker Desktop 默认用 WSL 2 跑 Linux 容器这就要求 Windows 系统开启 WSL 2 功能并且 BIOS 里必须开启虚拟化支持。很多用户反映启动时报错 virtualization support not detected就是虚拟化没开。解决办法很简单重启进 BIOS找到 Intel VT-x 或者 AMD SVM 的选项设为 Enabled保存重启。Win11 和 Win10 都可以在任务管理器-性能-CPU 里看到虚拟化是否已启用。第二个坑是 WSL 2 的 Linux 发行版需要预装。Docker Desktop 安装时一般会自动配置好一个默认发行版但如果你是精简装系统或者公司批量部署的机器可能缺少这一步。可以在命令行里执行 wsl --install 安装默认发行版再重开 Docker Desktop基本能解决。第三个坑是文件系统性能。Windows 上如果挂载目录选在 C 盘用户目录下Jenkins 的 IO 性能会受 NTFS 和 WSL 2 之间文件转换的影响构建多、日志多的时候性能下降明显。我的做法是尽量把 Docker 数据目录放到性能更好的磁盘Docker Desktop 的 Settings 里有 Resources 和 Disk image location 选项可以调整镜像存放位置这个设置平时容易被忽略但它对构建速度的影响很大。macOS 上情况类似Docker Desktop 也用虚拟机跑容器安装简单但注意 Apple Silicon 芯片的机器要选对架构的镜像。好在 Jenkins 官方镜像已经支持 arm64直接拉取即可。2.2 Linux命令行安装与国内源加速Linux 上装 Docker 走的是 apt 或 yum选择官方源有时候很慢我建议直接配国内镜像加速器这个后面细说。Ubuntu/Debian 系的安装步骤大概是先更新索引、安装依赖包然后添加 Docker 的 GPG 密钥和软件源最后装 docker-ce。CentOS/RHEL 系是用 yum 添加 docker-ce.repo。这些步骤网络上有大量教程我不展开抄一遍只说几个容易出现问题的细节。一个是 docker-ce 和 docker.io 的区别。Ubuntu 自带软件源里的 docker.io 是旧版本功能少坑多千万别图省事装这个一定要用 Docker 官方仓库的 docker-ce。另一个是安装完后用 systemctl enable --now docker 设置开机自启并立即启动这一步不做重启机器后 Docker 是停了的状态容易漏掉。Linux 下还有一个常见问题是权限。默认情况下Docker 命令需要 root 权限每次都要加 sudo 很麻烦。把当前用户加入 docker 组可以免 sudosudo usermod -aG docker $USER然后重新登录。但要注意加入 docker 组等同于授予该用户 root 级别的容器管理权限如果机器上有多个用户这点要慎重。2.3 Docker 权限问题的根源与解法再说几个高频报错。第一个是 permission denied while trying to connect to the Docker daemon socket。这个就是当前用户不在 docker 组或者 Docker 服务没启动。先 systemctl status docker 确认服务状态再检查用户组。第二个是 Failed to connect to the Docker API at npipe:////./pipe/docker_desktop_linux...这个主要出现在 Windows 的 Docker Desktop 上一般是 Docker Desktop 引擎没起来或者后端切换有问题。重启 Docker Desktop、确认 WSL 2 发行版正常多数能解决。第三个是 docker pull 时候的镜像下载慢。国内直连 Docker Hub 确实很吃力官方镜像经常拉一半就 timeout。解决办法是配置镜像加速器。在 Docker Desktop 的设置里找到 Docker Engine修改 registry-mirrorsLinux 则改 /etc/docker/daemon.json。我用过的加速地址有阿里云的容器镜像服务个人加速地址和网易的镜像源阿里云的地址每个用户不同需要登录阿里云容器镜像服务控制台获取专属地址。改完后重启 Docker拉取速度基本能达到可接受的水平。3. 创建 Jenkins 容器一条命令背后的细节3.1 目录规划与数据持久化Docker 容器本身是临时性的容器一删里面所有数据就没了。所以 Jenkins 的数据必须挂载到宿主机上。我习惯把 Jenkins 相关文件集中在 /opt/jenkins 或者 Windows 的 D:/docker/jenkins 下结构大概这样/opt/jenkins ├── jenkins_home # Jenkins 主目录JENKINS_HOME ├── docker.sock # 挂载的 Docker 套接字可选 └── backups # 手动备份目录jenkins_home 是重中之重的所有 Job 配置、插件、构建记录、用户账户信息都在里面。我一般会做两层保险容器数据卷挂载 定期把整个 jenkins_home 压缩备份到 backups。关于 Docker 数据卷还是 bind mount我的建议是 bind mount。数据卷volume更方便 Docker 化管理但你很难直接在宿主机上看到和使用文件而 bind mount 直接把宿主机目录映射进容器你把 jenkins_home 直接当作一个普通文件夹就可以操作备份、迁移都直观得多。3.2 端口认识与 8080 冲突处理Jenkins 默认监听 8080 端口这个端口太容易冲突了——Nginx、Spring Boot、各种开发服务都爱占 8080。所以映射到宿主机时我会换一个不太容易撞车的端口比如 8081 或者 9090。端口映射的格式是 -p 宿主机端口:容器端口。例如 -p 8081:8080意思是宿主机上用 8081 访问容器内部还是 8080。还有两个可选端口。一个是 50000这是 Jenkins 用于入站 TCP 代理的端口主要给 agent 节点连接用。如果你打算搞分布式构建、挂多个构建节点建议把 50000 也映射出来例如 -p 50001:50000。另一个是 8443HTTPS 访问用的一般用 Nginx 反代时并不需要除非直接暴露给用户浏览器。3.3 时区、JVM 参数与环境变量第一次跑 Jenkins 时我发现构建日志里的时间总是差 8 小时——容器默认时区是 UTC。如果你不处理时间显示会保持错误状态查看构建历史和定时任务安排都会混乱。解决办法是挂载宿主机的时区文件到容器里-v /etc/localtime:/etc/localtime:ro这样的挂载在 Linux 上很直接。macOS 和 Windows 因为文件系统差异我建议通过环境变量方式设置时区。在 docker run 时加上 TZ 环境变量容器内也需要先安装 tzdata 才能生效所以我的做法是直接把时区参数放到容器创建命令里配合镜像自身机制完成校准。JVM 参数也是必调的。Jenkins 容器默认的堆内存并不充裕如果你的流水线很多、构建并发大容易触发 OutOfMemoryError。用 JAVA_OPTS 环境变量指定堆大小例如-e JAVA_OPTS-Xms2048m -Xmx2048m -Duser.timezoneAsia/Shanghai另外还可以设置一些常规环境变量比如 JENKINS_OPTS 用来传额外的 Jenkins 参数JENKINS_HOME 指定数据目录。虽然默认值已经合理明确写出来能让后续排障时思路更清晰。3.4 docker run 完整命令与逐段解释我把最终版本的创建命令贴出来然后逐段拆解一下关键参数docker run -d \ --name jenkins \ --restartalways \ -u root \ -p 8081:8080 \ -p 50001:50000 \ -v /opt/jenkins/jenkins_home:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /usr/bin/docker:/usr/bin/docker \ -e TZAsia/Shanghai \ -e JAVA_OPTS-Xms2048m -Xmx2048m -Duser.timezoneAsia/Shanghai \ jenkins/jenkins:2.452.1-lts-jdk17-d 表示后台运行。--restartalways 是关键中的关键。没有它服务器重启后 Jenkins 容器就停留在 Exited 状态还需要手动 docker start。设置为 alwaysDocker 守护进程启动时会自动拉起容器服务自愈能力直接拉满。-u root 比较特殊。Jenkins 官方镜像默认用 jenkins 用户运行但这样没法在容器内执行 docker 命令去构建镜像、部署容器。为了能在 Pipeline 里调用 Docker CLI我直接用 root 用户跑容器。这个方式简单有效但安全上要注意如果你跑在多人共享的服务器上建议另加容器权限管理而不是盲目 root。-v /opt/jenkins/jenkins_home:/var/jenkins_home 是数据持久化的核心Jenkins 的全部数据落在这个目录。-v /var/run/docker.sock:/var/run/docker.sock 和 -v /usr/bin/docker:/usr/bin/docker 这两条是把宿主机上的 Docker CLI 和 Socket 映射进容器让 Jenkins 容器内可以像宿主机一样调用 docker 命令。很多人在这一步遇到 docker: command not found 就是因为宿主机上 docker 二进制不在 /usr/bin 下需要根据实际路径调整。我得提醒一下把 Docker Socket 挂给容器相当于把宿主机的 Docker 管理权限交给了 Jenkins这意味着只要 Jenkins 被入侵攻击者基本能控制宿主机上的所有容器生产环境一定要结合访问控制来权衡。启动后执行 docker ps 看容器状态如果发现 Exited用 docker logs jenkins 查看日志排障。常见原因是权限不足、端口被占或者目录无法访问。4. 初始化、插件加速与汉化4.1 解锁密码获取容器启动后浏览器访问 http://宿主机IP:8081第一次进入会看到“解锁 Jenkins”页面要求填管理员初始密码。这个密码存储在容器内的 /var/jenkins_home/secrets/initialAdminPassword 文件中。有两种方式获取。第一种是直接进容器看docker exec -it jenkins cat /var/jenkins_home/secrets/initialAdminPassword第二种是宿主机上直接看挂载目录里的文件cat /opt/jenkins/jenkins_home/secrets/initialAdminPassword输进去就能进入下一步。4.2 插件安装慢的解决方案初次进入后Jenkins 会询问安装建议插件还是自定义插件。我建议先选“安装推荐的插件”把常用的基础插件一次性装好之后再按需补装。但这里有一个几乎所有人都会遇到的问题插件下载特别慢甚至安装到一半直接失败。原因在于 Jenkins 默认从官方插件中心下载国内访问官方资源节点并不稳定。解决办法是替换插件更新中心为国内镜像。具体操作是进入 Jenkins 菜单的「Manage Jenkins」-「Plugins」-「Advanced settings」找到 Update Site 配置项把默认的 JSON 地址替换为可选镜像地址。替换后点击 Submit再点击立即检查通常下载速度会有质的提升。另外在容器创建时也可以直接用环境变量指定插件源-e PLUGIN_UPDATE_CENTER镜像地址 \ -e PLUGIN_DOWNLOAD_BASE_URL镜像下载地址这里要注意不同镜像站的 URL 格式并不完全相同配置前先确认一下具体规则避免配置错误导致插件列表加载不出来。4.3 汉化配置与界面体验插件装完后界面是英文的看着不习惯的话可以装一个 Locale 插件来实现汉化。在「Manage Jenkins」-「Plugins」-「Available plugins」搜索并安装 Locale 插件安装完成后在「Manage Jenkins」-「System」里找到 Default Language 选项填入 zh_US严格说 Jenkins 的中文语言代码是 zh_US 和 zh_CN一般填 zh_CN 也能生效然后勾选“强制使用默认语言”选项。重启 Jenkins界面就会切换成中文。另外还可以顺手装个主题插件调整一下界面色彩。这类插件纯粹是视觉层的不影响功能但日常盯着构建页面的时候体验会好一些。4.4 初始化过程常见问题初始化阶段我遇到过几个典型问题先说最常见的。一个是创建管理员账号后登录报 403 或页面一直转圈。一般是插件未完全安装或者重启不彻底导致的进入容器执行 docker restart jenkins 通常能解决。另一个是推荐的插件安装失败导致流程卡住。不用慌点右上角的跳过进入 Jenkins 后重新在插件管理里安装失败项即可。插件安装失败通常不影响 Jenkins 本身启动。还有一个是「Manage Jenkins」入口点了没反应。这可能是权限没配好导致的新装实例默认只有第一个管理员账号是超级管理员如果你后来创建了别的用户操作权限可能不够。排查时我一般都把当前用户角色调整回管理员再试。5. 从能跑到好用自动化部署配置实录5.1 容器内可用的环境变量Jenkins 里有很多内置环境变量写 Pipeline 脚本频繁用到。我贴几个高频变量实际配置时可以直接用。变量名含义典型用法BUILD_NUMBER当前构建序号用于生成构件名如 myapp-${BUILD_NUMBER}.jarBUILD_URL本次构建的完整 URL在钉钉/邮件通知中附带链接JOB_NAMEJob 名称区分不同应用WORKSPACE当前任务工作目录构建产物路径计算GIT_COMMITGit 提交哈希部署时打版本标签BRANCH_NAME分支名多分支流水线识别环境在「系统管理」-「系统信息」页面能看到全部环境变量需要什么查什么非常方便。5.2 JDK、Maven 与全局工具链容器内的 JDK 版本是镜像自带的但你的项目可能要求不同版本的 JDK 和 Maven。不要直接在宿主机上配工具链Jenkins 的「Global Tool Configuration」里可以配置多版本工具让 Jenkins 自己在构建节点上装。我以 Maven 为例。进入「Manage Jenkins」-「Tools」在 Maven 配置区域点击「Add Maven」可以指定 Name并选择 Automatic installation填上 Maven 版本保存即可。首次构建时 Jenkins 会自动下载对应版本并缓存到本机。JDK 类似只是还需要提供对应版本的下载地址Jenkins 可以从厂商下载你需要把校验信息一起配好否则安装会因校验失败中止。如果你在企业内网隔离环境手动指定工具包路径的方式更靠谱把 JDK 和 Maven 解压到宿主机某个目录挂载进容器再在工具配置里指定本地目录。5.3 前后端分离项目的部署流程前端 Vue/React 和后端 Spring Boot 项目是现阶段最常见的部署组合。我用一个典型的 Pipeline 脚本来展示在这套容器环境里部署流程如何跑通。pipeline { agent any stages { stage(Checkout) { steps { git url: https://github.com/example/myapp.git, branch: main } } stage(Backend Build) { steps { dir(backend) { sh mvn clean package -DskipTests } } } stage(Frontend Build) { steps { dir(frontend) { sh npm install npm run build } } } stage(Docker Build) { steps { sh docker build -t myapp:${BUILD_NUMBER} . } } stage(Deploy) { steps { sh docker stop myapp docker rm myapp || true docker run -d --name myapp -p 8082:80 myapp:${BUILD_NUMBER} } } } post { success { echo 构建成功 } failure { echo 构建失败 } } }这个脚本里比较关键的几个点npm 构建需要容器内有 Node.js 环境。我一般是在同一个 Jenkins 容器里挂载 Node 工具或者用构建节点的方式来隔离。相对省事的是在全局工具配置里加入 NodeJS 自动安装这样 Pipeline 里就能用 nodejs 工具块了。docker build 需要容器内能访问 Docker Socket需要提前确认 Socket 挂载正常。如果 Jenkins 容器内执行 docker ps 有输出就没问题。部署这一步用的是 docker stop 加 docker rm加 || true 是为了防止容器不存在时脚本报错中止。这套流程跑通的标志是push 代码后Pipeline 自动触发构建、打包、发布全部完成无需人工干预。5.4 构建历史清理与磁盘维护Jenkins 跑久了构建历史和旧产物会占大量磁盘空间。一个大型项目构建 200 次产物全留着磁盘直接报警。我的清理策略是双管齐下。第一是根据构建历史保留策略来清理。在 Job 配置里有个「Discard old builds」选项可以设置保留最多构建数或保留天数。比如保留最近 30 次构建或者保留最近 7 天。这会自动滚动清理旧记录。第二是手动清理 Docker 产生的悬空资源。每次构建生成的新镜像、中间镜像、旧容器都会积攒。定期执行以下命令或做成定时任务docker system prune -af这条命令会把所有停止的容器、未使用的网络、悬空镜像和构建缓存一并清掉释放出来的磁盘空间相当可观。但这个命令是全局清理生产环境执行前先确认没有重要的未引用资源。还有一招是 Jenkins 脚本命令行的清理进入「Manage Jenkins」-「Script Console」可以执行 Groovy 脚本批量删除特定 Job 的旧构建记录。这个属于高级操作新手建议还是先用好官方策略就足够了。6. 高频问题速查表问题现象可能原因解决思路Docker Desktop 启动报 virtualization support not detectedBIOS 中虚拟化未开启重启进入 BIOS开启 VT-x/AMD SVMdocker 命令报 permission denied当前用户不在 docker 组加入 docker 组并重新登录或使用 sudodocker pull 镜像超时、速度慢网络访问官方源不稳配置国内镜像加速器Jenkins 页面打不开端口映射不正确或防火墙拦截检查 docker ps 端口映射、宿主机防火墙规则插件安装/下载失败官方插件中心访问不稳定替换插件源为国内镜像容器内 docker: command not foundDocker CLI 未挂载到容器确认 -v /usr/bin/docker 路径正确构建日志时间相差 8 小时容器默认 UTC 时区设置 TZ 环境变量或挂载宿主机时区文件内存溢出 OutOfMemoryErrorJVM 堆内存不足增大 JAVA_OPTS 中 Xmx 数值8080 端口已被占用宿主机其他服务占用修改端口映射为其他可用端口容器启动后立即退出挂载目录权限不足或端口被占查看 docker logs 定位原因这些排查思路基本覆盖了从环境准备到日常使用的绝大多数问题。每一条都是我实际踩过的或者身边同事踩过的有共性的才整理出来个性问题参考意义不大就不列了。对我个人而言Docker 部署 Jenkins 最大的收益是省心。以前升级 Jenkins 像做一台手术提前备份、准备回滚方案、提心吊胆地等迁移完成现在就是拉一个新镜像、替换容器、等待数据目录自动复用分钟级完成。日常维护也从管理一台系统的繁琐工作中解放出来可以更专注在流水线设计和自动化能力建设上。如果你还在为 Jenkins 的环境问题头疼我建议直接照着这套流程走一遍体感会非常明显。