Docker 安装 Jenkins 实战：从环境部署到自动化构建与部署全流程

最近这段时间一直在折腾持续集成这套东西起因也很简单某次发布新版本的时候我手动打包、传服务器、重启服务一步接一步结果到了最后才发现漏了一个配置文件整个流程又得从头来一遍。那天晚上我就在想这活儿要是能自动化提交完代码就自动构建、自动部署、出问题还能自动收到提醒那该省多少事。后来就把 Docker 和 Jenkins 这套组合搭了起来项目从构建到部署再到监控基本能做到一条流水线走完。这篇文章就围绕基于 Docker 安装 Jenkins 这件事讲清楚我走过的完整路径包括为什么这么选、关键的配置参数怎么写、流水线脚本怎么组织以及踩过的那些坑。如果你也对自动化构建和部署感兴趣想搭一套自己的发布系统这篇文章应该能让你少走不少弯路。1. 核心设计思路为什么非要用 Docker 装 Jenkins1.1 宿主机直接安装的痛点最原始的方案当然是直接在服务器上装一个 JenkinsJava 环境配好插件装好就能用了。但实际用下来这个方式有几个让人头疼的地方。首先就是环境冲突Jenkins 本身依赖 Java而项目可能也需要 Java但版本要求不一致一台机器上多套 JDK 来回切换配置环境变量非常容易出错。其次是隔离性差插件装多了之后整个 Jenkins 的配置散落在系统的各个目录里升级一次可能就把之前的设置搞乱了想迁到另外一台机器几乎等于重新搭一遍。再有就是团队协作的时候每个人本地的环境其实都不完全一致同一套操作在这个人机器上成功换个人可能就失败。这种“在我机器上是好的”的尴尬在 CI 场景里一样存在。1.2 容器化带来的主要收益Docker 对这个问题解决得相当彻底。用容器跑 Jenkins就是把整个运行环境连同配置一起打包成一个镜像只要有 Docker 引擎的地方启动方式和结果完全一致。这样做的好处有三个层面一是环境隔离Jenkins 以及它构建项目所需的工具链都关在容器里不会污染宿主机二是迁移方便数据目录通过挂载卷管理备份和还原就是打包一个目录的事三是团队协作更顺畅新人拿到镜像和启动脚本几分钟就能起一套一模一样的构建环境。用大白话讲以前搭 Jenkins 是给机器“装系统”现在更像是“搬家”所有家当装进集装箱到哪都能直接落地使用。1.3 方案选型时的几个关键考量在确定用 Docker 跑 Jenkins 之后我反复权衡了几个问题。第一个是用官方镜像还是第三方镜像我的结论是优先用官方镜像因为第三方镜像可能集成了多余的插件或定制的配置出了问题不好排查官方镜像干净稳定。第二个是容器内执行任务的方式默认情况下 Jenkins 容器内的jenkins用户其实已经内置了常用工具但如果你的项目需要调用宿主机上的 Docker 命令就需要考虑挂载/var/run/docker.sock这也是后文重点要讲的部分。第三个是持久化Jenkins 的所有配置都在/var/jenkins_home目录里如果不做挂载容器一删就全都丢了这个从一开始就要规划好。这几个问题想明白了后面的操作就顺畅很多。2. 环境准备与基于 Docker 的 Jenkins 部署2.1 基础环境与镜像加速在正式拉取镜像之前先把 Docker 环境准备好。Linux 服务器上安装 Docker 之后建议立刻配置镜像加速器否则拉取 Jenkins 这种几百兆的镜像会非常痛苦。常见的做法是修改 Docker 的守护进程配置文件比如/etc/docker/daemon.json填入可用的加速地址然后重启 Docker 服务让配置生效。配置完成后可以执行docker info查看镜像加速是否生效。确认 Docker 正常之后拉取 Jenkins LTS 镜像。为什么不选最新版因为 Jenkins 的插件生态有一个特点新版本往往伴随着插件兼容性的问题而 LTS 版本经过了更充分的社区验证长期维护稳定性更高。对于生产环境我一般只使用 LTS 版本。docker pull jenkins/jenkins:lts镜像拉取完成后可以用docker images | grep jenkins确认镜像已经存在。2.2 启动 Jenkins 容器的核心参数接下来是启动容器。这一步是全文最关键的部分参数没写对后面大概率出问题。先给出我实际使用的命令然后再逐条解释为什么这么写。docker run -d \ --name jenkins \ -p 8080:8080 \ -p 50000:50000 \ -v /data/jenkins_home:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ -e TZAsia/Shanghai \ --restartalways \ jenkins/jenkins:lts逐条说。-p 8080:8080是 Jenkins 的 Web 访问端口映射宿主机上用 8080 访问内部还是 Jenkins 默认的 8080。-p 50000:50000是 Jenkins 与代理节点Agent通信的端口如果你打算用 Jenkins 的 master-agent 分布式构建模式这个端口必须保留暂时用不上也不想影响也可以保留省得以后要用还得重建容器。-v /data/jenkins_home:/var/jenkins_home是容器数据的持久化目录所有任务配置、构建记录、插件都放在这里挂载到宿主机上容器重建不影响数据。-v /var/run/docker.sock:/var/run/docker.sock这一步是关键中的关键它把宿主机的 Docker 套接字挂载进了容器里让容器内的 Jenkins 可以直接调用宿主机的 Docker 服务从而实现容器内再构建镜像、再启动容器的效果。-e TZAsia/Shanghai是设置时区不设置的话容器默认是 UTC 时间构建日志里的时间会比本地慢 8 小时排查问题的时候非常容易产生误导。--restartalways表示 Docker 服务重启后容器自动拉起相当于给 Jenkins 加了一道保命锁服务器意外重启后不用手动再启动容器。2.3 数据卷的权限陷阱挂载数据卷的时候有一个很容易踩的坑权限。Jenkins 官方镜像内运行的用户是jenkins它的 UID 是 1000。宿主机上新建的/data/jenkins_home目录默认 owner 是 root这个目录被挂载进容器之后容器内的jenkins用户可能没有权限写入。表现就是你访问 Jenkins 页面时后台日志疯狂报 permission denied或者插件安装失败。解决办法是在启动容器前先把目录权限调整好mkdir -p /data/jenkins_home chown -R 1000:1000 /data/jenkins_home这里直接把目录的属主改成 UID 1000和容器内用户保持一致。如果你已经开始启动容器了可以用docker exec -it jenkins bash进入容器执行ls -ld /var/jenkins_home查看属主然后回到宿主机用chown修正。这个细节看起来小但能卡你好几个小时。3. 初始化配置与插件体系搭建3.1 首次访问与解锁密码容器起来之后访问http://服务器IP:8080会看到 Jenkins 的解锁页面要求输一段初始管理员密码。这个密码是容器自动生成的可以从两个地方拿。一个是容器日志docker logs jenkins | tail -30日志里会有一段类似Jenkins initial setup is required. An admin user has been created and a password generated.的提示后面跟着一串密码。另一个是直接从文件读取默认初始密码存在容器的/var/jenkins_home/secrets/initialAdminPassword里由于我们已经挂载了宿主机目录它实际上也在宿主机的/data/jenkins_home/secrets/initialAdminPassword里直接cat就行。拿到密码以后进入解锁界面创建一个管理员账号。注意这里的账号密码用于日常登录一定要记好。创建完成后进入插件安装页面。3.2 插件安装的取舍思路初始化页面会推荐安装“建议插件”列表刚上手的时候直接按默认来问题不大但如果你对项目需求有比较清楚的认识我建议不要全装因为插件装多了会拖慢 Jenkins 的启动速度而且很多用不上反而增加维护成本。我的建议是分两类一类是基础必备型包括Git client、Pipeline、Docker Pipeline、Credentials Binding、Build Timeout、Timestamper、Email Extension这些基本覆盖了从拉取代码到流水线执行再到通知的核心场景。另一类是场景增强型比如你要做远程服务器发布就装Publish Over SSH你希望有可视化看板就装Build Monitor View和Blue Ocean你想接收 Webhook 消息就装一个通用通知插件。插件的选择原则很简单围绕你真正会用的功能来选而不是把社区里口碑好的都装一遍。插件安装的入口在“系统管理 - 插件管理 - 可用插件”搜索到之后勾选点击安装即可。安装过程可能需要一段时间耐心等着就行。如果碰到网络下载慢或者失败的情况下面第 7 章有专门的解决方案。3.3 全局工具链配置插件装完之后先别急着建任务要到“系统管理 - Tools”里把构建项目要用的工具链配好包括 JDK、Maven、Git。如果 Jenkins 容器内直接安装了这些工具就填容器内的路径如果没有可以用 Jenkins 的自动安装功能勾选“Install automatically”Jenkins 会去下载对应版本的工具。自动安装的好处是省事版本可控坏处是初次构建时等待下载时间较长。我平时用 Docker 跑项目构建时倾向于在宿主机上预留好 JDK 和 Maven 的安装目录再通过-v参数挂载进容器这样容器里就可以直接引用实际路径。虽然自动安装也足够但考虑到公司内的网络环境可能不稳定手动管理工具链更稳一点。另外Maven 的本地仓库目录建议也挂载到宿主机上否则每次构建都要重新下载依赖非常浪费时间。还有一个容易忽略的点是 Git 的全局配置。进入容器执行下面两条命令避免构建过程中出现 “Please tell me who you are” 的报错docker exec -it jenkins bash git config --global user.email ciexample.com git config --global user.name CI Bot exit这块配置好了整个构建环境的基础就算打牢了。4. 自动化构建的实现从任务创建到流水线脚本4.1 自由风格任务 vs 流水线任务Jenkins 支持两种主流的任务类型自由风格任务Freestyle Job和流水线任务Pipeline Job。自由风格任务的界面比较友好通过下拉选项和文本框配置适合简单的构建步骤。流水线任务则是用代码来描述整个构建过程配置文件可以放在项目仓库里通常叫 Jenkinsfile随代码版本管理这样团队的构建逻辑可以 review、可以追溯而且更容易实现复杂的多阶段流程。我的建议是如果只是小团队、简单项目先上手用自由风格任务完全没问题但如果项目会持续演进或者你想让构建逻辑像代码一样被管理起来那就一步到位用流水线。我这里两种方式都会讲先讲自由风格任务怎么配再给一段可以直接用的流水线脚本。4.2 自由风格任务的核心配置项新建任务之后需要配置的内容主要有几块。一是“源码管理”选择 Git填写仓库地址然后添加凭据。这里的凭据推荐使用 SSH Key 而不是账号密码因为 SSH Key 更安全而且不用经常轮换。在服务器上生成一对密钥把公钥加到代码仓库的部署公钥里然后在 Jenkins 的凭据管理中添加私钥这样 Jenkins 拉代码就不用每次输密码。操作路径是“凭据 - 全局 - 添加凭据”类型选 “SSH Username with private key”把私钥粘进去。二是“构建触发器”常见选项包括轮询 SCM 和 Webhook 触发。轮询 SCM 是指每隔一段时间自动检查代码仓库有没有新提交有的话就触发构建。这个方式的缺点是存在延迟而且频繁轮询会给代码仓库服务器带来额外压力。更推荐的做法是配置 Webhook 触发代码仓库在每次 push 的时候就向 Jenkins 发送一个请求实现真正的“代码一变立刻构建”。具体地址是http://Jenkins地址:8080/github-webhook/如果你的仓库不是同一类就把这个词换成对应平台的接入路径在仓库后台的 Webhook 设置中填好这个地址即可。三是“构建步骤”选择“调用顶层 Maven 目标”填写clean package。这里可以添加参数构建比如-DskipTests跳过单元测试或者用-P指定不同的构建 profile。构建产物会比较常出现在项目的target目录下可以顺便配一个归档步骤把**/target/*.jar归档起来方便后续从构建产物页面直接下载查看。4.3 流水线脚本的骨架与解析流水线任务的核心是 Pipeline 脚本。我把自己常用的 Jenkinsfile 骨架贴出来并解释每一段的作用。pipeline { agent any environment { PROJECT_NAME my-demo DOCKER_REGISTRY registry.example.com } stages { stage(检查) { steps { echo 开始构建 ${PROJECT_NAME} } } stage(下载依赖并打包) { steps { sh mvn clean package -DskipTests } } stage(构建Docker镜像) { steps { sh docker build -t ${DOCKER_REGISTRY}/${PROJECT_NAME}:${BUILD_NUMBER} . } } stage(推送镜像) { steps { sh docker push ${DOCKER_REGISTRY}/${PROJECT_NAME}:${BUILD_NUMBER} } } } post { success { echo 构建成功 } failure { echo 构建失败 // 这里可以加通知动作后面监控章节再说 } } }这个例子里的BUILD_NUMBER是 Jenkins 内置的环境变量表示当前构建的编号每个任务从 1 开始递增天然适合做镜像的版本标签。stage的命名要尽量清晰因为流水线的视图界面会直接把每个阶段渲染成可视化步骤方便一眼看出卡在哪一步。post块则负责在构建结束后处理后续动作失败的时候发通知、成功的时候打标签都可以放在这里。这里给大家一个经验流水线脚本尽量短小精悍把复杂的构建逻辑抽到项目里的脚本文件比如build.sh中Jenkinsfile 只负责串联和编排。这样开发人员可以在本地直接用脚本复现构建过程不需要依赖 Jenkins 环境遇到问题也好排查。5. 自动化部署体系把构建产物送上线5.1 基于 SSH 的远程部署方案构建完成后下一步就是把产物部署到目标服务器上。最稳妥的方案之一是用Publish Over SSH插件通过 SSH 协议把构建好的 jar 包或镜像推送到目标服务器并在远端执行启动或更新的命令。插件装好后到“系统管理 - 系统配置 - Publish over SSH”里填目标服务器的连接信息包括 IP、端口、SSH 凭据和远程目录。配置完成后构建步骤里就可以添加“Send files or execute commands over SSH”步骤配置好传输文件和执行命令。例如把target/app.jar传到服务器的/opt/app目录下然后执行systemctl restart app或者写好的部署脚本。这里有几个细节要提醒。一是建议用专用部署账号而不是 root 登录权限控制得更精准也避免误操作。二是 SSH 认证尽量用密钥而不要用密码密码容易过期密钥可以有效降低维护成本。三是远程执行的命令不能依赖交互式输入因为自动化场景下没人会在终端里给你敲确认所有命令都要能非交互执行。Publish Over SSH比较适合部署到多台服务器或者没有容器化改造的纯 Java 项目。如果你的项目本身已经容器化了那思路可以换一换往下看。5.2 挂载 Docker 套接字后的容器内部署我们之前启动 Jenkins 容器时挂载了宿主机 Docker 套接字目的就是为了这个场景Jenkins 容器内部直接调用宿主机 Docker 完成“构建镜像 - 推到私有仓库 - 在目标机拉取并启动容器”的全流程。这样可以不用 SSH 逐台机器去操作而是把部署逻辑统一在流水线里描述环境越多越显优势。一个典型的部署流水线是流水线里docker build构建新镜像然后docker push推到私有镜像仓库最后通过 SSH 登录目标服务器执行docker pull和docker-compose up -d完成应用更新。这里要注意目标服务器上是需要预装 Docker 和 Docker Compose 的而且 Jenkins 的 SSH 用户需要有操作 Docker 的权限否则远端命令执行不下来。关于私有镜像仓库我强烈建议有条件的团队起一个自己的 Registry 服务无论是本机装也好还是用云服务也好。默认的 Docker Hub 无论从速度还是管理角度都不适合做内部项目的发布渠道私有仓库存镜像、打标签、回滚都更可控。5.3 版本管理与回滚策略自动化部署最怕什么最怕发布了坏版本。虽然自动化的目标是加快发布速度但引入版本回滚能力是必备的否则自动化反而变成了“故障放大器”。我在流水线里有一个不成文的规定每次构建的镜像都以唯一的构建编号打 tag同时在部署前同步更新一个latest标签。这样既保留了历史版本也方便快速回退。一旦线上出现异常运维只需要登录服务器把容器镜像指向上一个构建编号的 tag 再重启即可。在脚本层面我会在部署阶段保留最近 5 个版本的镜像多余的历史镜像定期清理避免服务器磁盘被撑爆。磁盘被镜像撑满这个问题很多团队都遇到过后面也会作为常见问题单独讲。回滚说起来简单做起来需要提前想好。启动容器的脚本里镜像的版本尽量用环境变量传入不写死在命令里这样回滚时只需要改环境变量不需要改完整的部署脚本。6. 监控与通知让构建状态自己“说”出来6.1 构建状态的可视化看板构建自动化做起来之后每个人都会关心构建到底成没成功。虽然 Jenkins 的界面上能看到每次构建的结果但团队成员不可能每个人都盯着 Jenkins 页面看。这时候搭建一个可视化看板就很有必要。第一个方案是安装Build Monitor View插件它是一个大屏幕视图可以把所有任务的状态用色块展示出来绿色代表成功、红色代表失败、黄色代表不稳定。这个视图特别适合放在团队公共区域的大屏幕上谁提交的代码把构建搞挂了一眼就能认出来。第二个方案是安装Blue Ocean插件它能提供更现代的流水线可视化界面每一个 stage 的执行时间、失败点都能很直观地看到。日常排查问题的时候我也会借助 Blue Ocean 的界面因为它的日志展示方式比传统页面舒服很多而且能按阶段折叠日志定位问题效率比翻整页日志高不少。6.2 邮件通知最低成本的告警方式通知模块里邮件是最基础也最常用的一种。Jenkins 自带的邮件通知和Email Extension插件都能实现构建结果的通知区别在于后者功能更强支持按不同事件成功、失败、不稳定配置不同的邮件内容模板还能附带构建日志。配置的时候有几个容易踩坑的地方。第一是 SMTP 服务地址这里要注意不能用默认的localhost要填你自己的邮件服务地址并且把端口、账号、密码填正确。第二是默认发件人地址Jenkins 会用它作为邮件的发件人很多企业邮箱对发件人地址有校验填写时尽量使用真实的邮箱地址。第三是“默认收件人”也就是不额外指定收件人时的默认邮件接收者至少要填上你们团队的邮箱。配好之后建议在邮件通知模块里先点一下“测试邮件”确认能收到邮件再配置流水线里的通知。这样能快速排除配置层面的问题。邮件虽然传统但在公司内部依然是通知告警的可靠手段特别是夜间构建失败的情况第二天一早到工位看到邮件就心里有数了。6.3 通过 Webhook 机器人把消息推给团队更实时的通知方式是走群机器人的 Webhook。很多团队协作工具都支持自定义机器人你把机器人的 Webhook 地址配到流水线里构建结果就会直接推送到群里大家打开手机就能看到比邮件触达得快。配置思路很简单。先在群管理里添加一个自定义机器人拿到 Webhook 地址。然后写一个小脚本用 curl 就行把构建状态、任务名、构建编号、日志地址包装成一个 JSON通过 POST 请求发给 Webhook。curl -X POST $WEBHOOK_URL \ -H Content-Type: application/json \ -d {\msg_type\:\text\,\content\:{\text\:\构建失败: $PROJECT_NAME 第 $BUILD_NUMBER 次构建日志: $LOG_URL\}}我把这段逻辑封装成一个notify.sh在流水线的post阶段按需调用失败时把完整信息推到群里。这样团队成员不用主动盯着 Jenkins 页面出问题就会被第一时间“喊到”。配合上面提到的 Build Monitor 看板一个是主动推送一个是被动展示两条路都走监控体系才算完整。6.4 服务存活状态的基础监控构建和部署都自动化之后还要考虑一个层面的监控目标服务器上的服务到底活着没有。这一点和 Jenkins 本身不是很直接相关但作为自动化部署的一部分我习惯在部署完成之后加一个“健康检查”阶段。最简单的方式是在流水线的部署步骤后调用一下服务的健康检查接口比如curl http://目标IP:端口/actuator/health看返回的状态码是不是 200。用sh步骤就能实现。也可以把这个检查变成一个定时任务放在 Jenkins 里定期扫描服务的健康状态如果连续多次失败就发送告警。这样做的好处是服务的存活状态不需要外部监控系统就能得到基本的保障。如果公司有更专业的监控平台也可以导出构建 metrics 过去但对于中小团队来说先用 Jenkins 把基础的自动检查和通知跑起来成本最低、见效最快。7. 实际踩坑记录与排查技巧7.1 插件下载慢或者直接失败这是刚接触的时候最让人崩溃的问题之一。现象是插件管理页面的安装进度一直不动或者在某个插件上卡了很久最后报错。原因主要是默认插件源在国外网络不稳定。解决办法是把插件源换成国内的镜像源。进入“系统管理 - 插件管理 - 高级”在底部找到“升级站点”把 URL 改成国内的 Jenkins 镜像地址。改完之后点击提交再回去安装插件就会发现速度快不少。还有一个办法是直接去关掉不需要的插件自动更新减少不必要的下载。7.2 构建时报错找不到 JDK 或 Maven这个问题的根源通常是工具链路径配置不对。如果用了容器自带的环境工具链的路径不一定是默认的/usr/bin/java建议先进入容器执行which java、which mvn找到实际路径然后在全局工具配置里填完整路径。如果使用自动安装也可能是下载工具的过程中网络失败重试一次基本都能解决。一个非常容易忽略的点是自由风格任务里如果指定了 JDK 版本但全局配置里没有这个版本对应的安装项构建就会直接失败。所以全局工具配置和任务里的引用要保持一致。7.3 重启容器后数据全丢或配置丢失这个问题的原因基本可以确定是数据卷没挂对。如果启动容器时没有-v /data/jenkins_home:/var/jenkins_home这个参数容器一旦删除所有配置、任务、构建记录都会不见。还有另一种情况是-v挂载了目录但权限不对容器启动时无法写数据表面上容器起来了实际上配置没有真正落盘。排查方式很简单用docker inspect jenkins | grep -A5 Mounts查看挂载信息确认宿主机路径正确。再看看宿主机目录下有没有config.xml、jobs这些关键文件夹没有就说明持久化没生效。7.4 构建任务一直卡在某个阶段最初我遇到过一次构建卡在Pull代码阶段的情况原因是代码仓库凭据失效了Jenkins 尝试拉取时一直在等待认证任务就挂在那。排查思路是先去任务的控制台输出看最后几行日志如果发现了认证失败或连接超时的字样就去凭证管理里把对应的 SSH Key 或账号密码更新一遍。还有一种可能是流水线的某个脚本写了一个交互式等待比如在构建里用了read命令但没有标准输入任务就会一直等在那里。检查流水线脚本把非交互模式打打开比如mvn就加上-B参数避免让它进入交互状态。7.5 磁盘被镜像和构建产物占满部署系统跑起来之后最容易忽视的就是磁盘空间。镜像仓库堆积、Jenkins 数据目录里积压了海量的历史构建产物、日志文件越滚越大最后磁盘 100% 导致构建失败。我的做法是在系统管理里设置“丢弃旧的构建”只保留最近 20 次构建同时把构建产物上限设成 30 个。对于 Docker 镜像写一个定时清理脚本用docker image prune和条件删除命令把老版本的镜像清掉。有一个原则想分享构建系统本身也需要定期的“卫生打扫”。自动化并不意味着放任自流定期清理、定期备份、定期检查插件版本都是日常维护的一部分。7.6 常见问题速查表为了方便大家快速定位问题我把高频故障整理成一张对照表。现象常见原因快速处理方式端口访问不了防火墙没放行或端口映射错误检查防火墙规则docker ps确认端口映射解锁页不知道密码没看日志或没找到初始密码文件查看initialAdminPassword文件拉取代码失败凭据失效或仓库地址错误更新凭据检查仓库 URLMaven 构建巨慢本地仓库为空或镜像源不稳定配置本地仓库缓存改用国内镜像源远程部署失败SSH 秘钥不对或目标目录无权限检查密钥认证和远端目录属主容器重启数据丢失没挂载数据卷或挂载路径错误检查 Mounts 信息补挂载卷构建卡住超时脚本有交互等待或网络阻塞加 Build Timeout检查脚本交互最后分享一点我的实际操作体会这套 Docker Jenkins 的自动化方案搭好之后最直观的感受就是发布这个动作变得非常轻。以前发一个版本从打包到确认上线怎么也得折腾半小时现在只要代码合并进主分支剩下的事情都是自动的我只需要在监控面板上看着状态变为绿色就行。但我也必须强调自动化不是银弹它只是把重复性的流程固定下来想让它稳定可靠前期的基础配置和定期的维护一样都不能省。比如插件不是越多越好流水线脚本不是越复杂越好磁盘空间也不是无限使用的。这些“脏活累活”做在前面后面的自动化才真正靠得住。如果你也正准备搭一套持续集成环境建议先从小项目开始把构建、部署、通知这三个环节跑通再去扩展更复杂的场景。每一步都踩实了这套系统就会变成你团队里最省心的那个成员。