Jenkins+Docker实现SpringBoot自动化部署：从手动发布到一键流水线

刚接触 CI/CD 或者被手动打包、上传、重启、盯着日志这套流程折磨过的人这篇文章就是给你准备的。项目标题里的JenkinsDocker是当前 Java 后端部署最主流、也是上手成本最低的一套组合核心就一件事把代码从提交到运行整个链路自动化你只需要 push 代码剩下交给流水线。这篇我直接给出一套能在真实服务器上落地的最简流程不绕弯子不说废话先讲清楚为什么要这么搭再逐步拆解每一步的配置和实操最后把容易踩的坑和排查思路一起整理出来。很多人看到 Jenkins、Docker、Pipeline 这几个词就觉得复杂实际拆开看链路就这么短开发机 push 代码到代码仓库Jenkins 感知到变更后拉取源码在项目里用 Dockerfile 构建镜像跑容器启动完事。没有 K8s没有微服务编排纯粹的单机或少量服务器部署场景这套最省心。1. 整体思路拆解为什么选 JenkinsDocker 而不是手动部署先聊为什么不用传统的打包-上传-重启方式。我自己早期部署 SpringBoot 应用是这样的本地执行mvn clean package然后 scp 上传 jar 到服务器再登录服务器执行kill -9杀掉旧进程最后nohup java -jar启动。单机部署一个服务还好一旦有两个、三个服务需要发版这套流程的痛点会被迅速放大。痛点集中在几处一是操作链路长且无记录每次发版执行过哪些命令全凭记忆要么靠聊天记录要么靠终端滚动屏二是发布动作完全依赖人谁发布、发布哪一版代码、发布是否成功没有统一入口三是回滚成本高一旦发布的新版本有问题你得找到旧包、确认旧包还能用、重新上传启动整个过程手忙脚乱四是环境差异在开发机打包出来的东西到生产服务器上因为 JDK 版本、Tomcat 内嵌版本或操作系统差异可能起不来。这里最典型的例子就是你在本地用 JDK 17 编译的 class 文件放到 JDK 8 的服务器上直接报 UnsupportedClassVersionError。JenkinsDocker 这套组合把上面的问题一次解决。Jenkins 承担的是流水线中枢的角色它负责拉取代码、执行构建、调用 DockerDocker 承担的是运行时标准化角色把应用连同 JDK、环境变量、启动参数全部固化到镜像里保证任何一个装了 Docker 的服务器上构建出来的运行环境完全一致。用一个生活化的类比手动部署就像你每次搬家用纸箱零散打包每次搬到新家都要重新分类、拆箱、摆放出错了还不知道哪一箱的东西放错了地方JenkinsDocker 则是建立了一套标准集装箱方案代码、运行环境、启动命令全部封在镜像里Jenkins 是那个负责运输调度的人任何一个环节出错都能追溯到具体操作日志。这套方案的好处总结下来就是推送代码即触发发布构建和部署全程脚本化任何人操作结果都一致回滚时直接换镜像版本重启容器几秒钟完成服务器不需要安装 JDK 和 Maven只需要 Docker 运行环境因为 Jenkins 会自动在容器或内置环境里完成编译和镜像创建。这个无需在生产环境安装 JDK的效果很多人第一次体验时会觉得非常舒服因为生产机上的软件管理一下子从装一堆工具链变成了只跑容器。2. 服务器环境准备从零安装 Docker 与 Jenkins2.1 Docker 安装与基础配置不管 Jenkins 装在哪台机器上第一步都是准备 Docker。这里以 Linux 服务器为例操作系统普遍是 7.x 或 8.x 系列。安装方式很多常见的是通过官方脚本或直接配置 yum 源安装。我更推荐直接使用系统自带的包管理工具安装因为后续维护升级方便而且能自动处理依赖。安装过程我就不贴长串命令了只说几个关键点安装完成后必须把当前登录用户加入 docker 用户组这样后面执行 docker 命令时不需要每次都 sudo。这一步很多人会忽略然后后面配置 Jenkins pipeline 时发现权限问题排查老半天。简单执行sudo usermod -aG docker jenkins如果是普通用户操作 docker就改成自己的用户名。执行完需要重新登录会话才能生效这是第一个容易踩的坑。启动 Docker 服务并设置开机自启命令是sudo systemctl enable docker --now检查是否安装成功可以跑docker version看到 Client 和 Server 两段信息都正常就说明 Docker 引擎已经可用了。这里多说一句镜像加速的问题国内服务器拉取 Docker Hub 镜像经常超时如果遇到 pull 镜像特别慢或者直接失败需要去 Docker 守护进程配置文件里添加 registry-mirrors 配置。改完后执行sudo systemctl restart docker重启生效。具体地址实际使用中经常变化我之前用过的几个后面失效了这里重点是提醒你保留这个处理方式的认知遇到问题知道从哪里入手不要卡在这一步。2.2 Jenkins 的安装方式选择Jenkins 最早的安装方式是下载 war 包扔进 Tomcat 运行或者用官方 yum 源安装到系统里。现在已经不是最佳选择了我推荐直接用一个独立容器跑 Jenkins原因很现实Jenkins 本身依赖的 JDK 版本、插件兼容性、配置文件散落位置用传统方式装很容易污染宿主机环境。用容器装Jenkins 的运行环境是隔离的升级和迁移都简单。启动 Jenkins 容器的方式核心命令如下docker run -d \ --name jenkins \ -p 8080:8080 \ -p 50000:50000 \ -v /home/jenkins_home:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(which docker):/usr/bin/docker \ --restartalways \ jenkins/jenkins:lts-jdk17这条命令有几个地方值得细讲。-v /home/jenkins_home:/var/jenkins_home是把 Jenkins 的数据目录挂载到宿主机。Jenkins 的配置、插件、构建记录都在这如果不挂载容器一删数据全没。我见过有人在测试环境没挂载数据目录容器重启后整个 Jenkins 配置全丢教训深刻。-v /var/run/docker.sock:/var/run/docker.sock是让 Jenkins 容器可以通过 Docker 主机的套接字调用宿主机 Docker 进程。这句话是整个 JenkinsDocker 玩法里最核心的机制。简单解释容器里运行 docker 命令时虽然二进制文件是容器内的但实际执行动作用的还是宿主机 Docker 引擎的能力。-v $(which docker):/usr/bin/docker是把宿主机的 docker 命令挂载进 Jenkins 容器这样 Jenkins 容器内部才能执行 docker 相关命令。如果你不挂这个文件进入 Jenkins 容器执行docker version会直接提示 command not found。-p 50000:50000这个端口是 Jenkins 用于和 Agent 节点通信的单机使用不涉及构建代理的话可以不映射但建议保留后续如果增加构建节点会用到。启动完成后浏览器访问http://服务器IP:8080会看到 Jenkins 的解锁页面。初始管理员密码在容器日志里执行docker logs jenkins可以看到一段随机生成的 key或者在挂载目录的secrets/initialAdminPassword文件里查看。拿到密码解锁后选择安装推荐插件即可。插件安装会耗时几分钟耐心等一下。后续还需要在 Jenkins 插件管理里额外安装 Maven Integration、Pipeline、Docker Pipeline、Git Parameter 等插件推荐插件列表里不一定包含全部建议确认一下。2.3 全局工具与凭据配置Jenkins 核心管理配置里需要准备几样东西JDK、Maven、Git 凭据和 Docker Hub 或私有仓库凭据。JDK 和 Maven 可以在 Jenkins 的 Global Tool Configuration 里配置自动安装也可以用已存在的路径。如果 Jenkins 容器内部没有 JDK 和 Maven你可以在容器里执行apt-get install安装或者更省事的方式是使用 Jenkins 的自动安装功能。自动安装需要服务器能联网下载选择版本号后保存即可。实践中我更推荐容器方式跑一个含 JDK 和 Maven 的 Jenkins 镜像或者直接在 Global Tool Configuration 配置挂载到容器里的 JDK/Maven 路径这个路径是容器内部的路径不是宿主机路径这个区分经常让人混淆。凭据管理是自动化流程里永远绕不开的一环。你需要把代码仓库的账号密码或 SSH 密钥存进 Jenkins 凭据中心这样流水线里拉代码时不需要手动输入密码。同样的推送到镜像仓库的账号密码也要存进去。在 Manage Jenkins 的 Credentials 里添加 Username with password 类型的凭据即可。凭据就像一个保险柜流水线脚本里通过credentials(凭据ID)引用不会在日志里暴露明文密码。这一点非常重要不要把密码硬编码到 pipeline 脚本里否则 Jenkins 的日志会把密码打印出来等于把服务器钥匙贴在大门上。3. SpringBoot 项目的构建配置Dockerfile 与镜像仓库准备3.1 编写项目 Dockerfile环境准备好之后回到代码项目本身。SpringBoot 应用要 Docker 化关键是写一份合适的 Dockerfile。SpringBoot 项目打包产物就是一个可执行 jar所以 Dockerfile 的核心任务就是把 jar 放进去告诉容器怎么启动。一个最简的 Dockerfile 内容如下FROM openjdk:17-jdk-alpine MAINTAINER devopsexample.com WORKDIR /app COPY target/*.jar app.jar EXPOSE 8080 ENV JAVA_OPTS ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar app.jar]这里有几个点要展开讲。基础镜像选择openjdk:17-jdk-alpinealpine 版本体积小适合在生产环境使用。注意 SpringBoot 应用实际编译用的是 JDK 17如果你的代码是基于 JDK 8 写的就换成openjdk:8-jdk-alpine保持一致即可否则运行时会因为字节码版本问题直接崩溃。COPY target/*.jar app.jar这行依赖上一阶段 Maven 构建的输出。也就是说先跑 Maven 打包出 jar再构建 Docker 镜像。如果 Jenkins 里 Maven 构建失败后续镜像构建就不会执行。ENV JAVA_OPTS用环境变量预留调整 JVM 参数的入口。部署过程中需要调整堆内存、GC 参数时不用重新构建镜像通过docker run -e JAVA_OPTS-Xmx512m直接传参这种灵活性在调试阶段特别有用。如果你想让镜像更小可以用多阶段构建把 Maven 构建和运行时镜像分开。第一阶段用 maven 基础镜像编译项目第二阶段只从第一阶段拷贝 jar 文件。这样最终的运行镜像里没有 Maven 和编译残留体积能减掉不少。但要注意多阶段构建在 Jenkins 里的构建时间会变长因为每次都要重新下载 Maven 依赖具体取舍看你们团队的实际情况。Dockerfile 写好后本地可以先手动构建一次验证docker build -t demo-app:test .构建成功后跑一个容器测试接口是否正常响应。这一步在本地验证好能避免后面 Jenkins 链路出问题时分不清是代码问题还是流水线配置问题。3.2 镜像仓库选型与推送准备镜像构建完成后要推送到一个仓库Jenkins 部署时从仓库拉取。可选方案是 Docker Hub 私有仓库和自建 Registry。Docker Hub 的私有仓库对个人项目比较方便但国内服务器拉取时网络不稳定自建 Registry 适合内网环境部署速度快。如果选 Docker Hub在 Jenkins 里配置一个 docker 凭据即可。如果自建 Registry需要考虑配置 HTTP 访问或证书信任问题这个细节很多人会卡我后面在常见问题里细说。推到 Docker Hub 的流程是本地或管道内执行docker login然后docker tag 镜像名 用户名/仓库名:tag再docker push 用户名/仓库名:tag。Jenkins 流水线里会用到凭据引用避免明文密码withCredentials([usernamePassword(credentialsId: docker-hub, usernameVariable: DOCKER_USER, passwordVariable: DOCKER_PASS)]) { sh echo $DOCKER_PASS | docker login --username $DOCKER_USER --password-stdin }4. Jenkins Pipeline 核心实现一键自动化部署4.1 创建流水线任务现在到了最核心的部分。在 Jenkins 首页点击新建任务填写任务名选择类型为 Pipeline。不建议选 Freestyle projectFreestyle 的配置项虽然在界面里排列得很直观但很多配置无法代码化迁移和备份都不方便。Pipeline 的脚本即代码全流程写入 Jenkinsfile 可以直接跟着代码走版本可追溯换一台 Jenkins 服务立刻能把任务重建起来你只需维护代码仓库里的 Jenkinsfile 文件就行。在 Pipeline 配置页面的 Pipeline 区域Definition 选择 Pipeline script from SCMSCM 选择 Git填写仓库地址和凭据Branches to build 填*/main或*/master。Script Path 默认是Jenkinsfile。保存即可。这里有一个值得注意的点。很多人第一次配置时不知道 Jenkinsfile 是可以和代码一起版本管理的。Script Path 就是指代码仓库根目录下的 Jenkinsfile 文件。这意味着流水线的逻辑变更不需要去 Jenkins 界面里手工修改直接在代码仓库里改 Jenkinsfile提交后 Jenkins 执行的就是新逻辑。这份文件沉淀到项目仓库里团队任何人都能 review 部署逻辑这是 Freestyle 风格完全做不到的。4.2 Jenkinsfile 最小可用版本下面给一个真正可用的 Pipeline 脚本这是整套流程的骨架。代码里每一段都有它必须存在的理由我按阶段拆解。pipeline { agent any environment { DOCKER_REGISTRY your-registry-address IMAGE_REPO demo-app IMAGE_TAG ${BUILD_NUMBER} CONTAINER_NAME demo-app-container PORT_MAPPING 8080:8080 } stages { stage(拉取代码) { steps { checkout scm } } stage(Maven 构建) { steps { script { def jdkTool tool name: JDK17, type: jdk def mvnTool tool name: Maven3, type: maven sh export JAVA_HOME${jdkTool} export PATH${jdkTool}/bin:${mvnTool}/bin:\$PATH mvn clean package -DskipTests } } } stage(构建并推送镜像) { steps { script { sh docker build -t ${DOCKER_REGISTRY}/${IMAGE_REPO}:${IMAGE_TAG} . withCredentials([usernamePassword(credentialsId: docker-hub, usernameVariable: DOCKER_USER, passwordVariable: DOCKER_PASS)]) { sh echo $DOCKER_PASS | docker login --username $DOCKER_USER --password-stdin ${DOCKER_REGISTRY} sh docker push ${DOCKER_REGISTRY}/${IMAGE_REPO}:${IMAGE_TAG} } } } } stage(部署容器) { steps { script { sh docker stop ${CONTAINER_NAME} || true docker rm ${CONTAINER_NAME} || true docker run -d \ --name ${CONTAINER_NAME} \ -p ${PORT_MAPPING} \ -e JAVA_OPTS-Xmx512m \ ${DOCKER_REGISTRY}/${IMAGE_REPO}:${IMAGE_TAG} } } } } post { success { echo 部署成功应用已启动 } failure { echo Pipeline 执行失败请检查构建日志 } } }逐段说下设计意图。environment这块把镜像仓库地址、镜像名、tag、容器名等变量统一收拢。tag 用BUILD_NUMBER也就是 Jenkins 每次构建的递增序号这样每次部署的镜像版本都是唯一的很方便回滚时定位指向哪次构建。第一个阶段checkout scm是最基础的步骤从配置的 Git 仓库拉取当前分支代码。如果你的项目用分支策略区分环境比如 develop 分支对应测试环境、main 分支对应生产环境后续可以扩展成按分支参数化构建多分支 Pipeline 是另一个话题。第二个阶段 Maven 构建需要注意的事比较细腻。工具链选择这里我用tool关键字引用全局工具配置里已配置的 JDK 和 Maven然后显式设置JAVA_HOME和PATH。很多人第一次跑 Jenkins 流水线会遇到 Maven 构建时提示找不到 JAVA_HOME 或 mvn 命令不存在往往就是环境变量没有正确设置。每个 sh 步骤行尾的\是换行拼接\$PATH中反斜杠转义是为了让 Jenkins 在 Groovy 字符串插值之后由 shell 自己解析原来的 PATH 变量。-DskipTests跳过了测试如果你的工程已经配套了完善的自动化测试建议改成-Dmaven.test.failure.ignorefalse而不是直接跳过测试否则测试失败不会打断发布等于给你埋了个大雷。当然在最简流程里跳过测试是简化链路的一种方式实际项目大家按需调整。第三个阶段是最有 JenkinsDocker 风格的一段。构建镜像直接在工作空间执行docker build它会自动读取当前目录下的 Dockerfile。构建完成后用凭据中心保存的账号密码登录镜像仓库然后 push。这里的登录动作每次构建都会执行一次逻辑上是有些冗余但好处是简单可靠不会出现凭据因为时间过期导致的推送失败。第四个阶段是部署。这里的策略非常直接粗暴先停掉旧容器删除旧容器再用新镜像启动新容器。|| true的作用是如果当前没有运行的容器导致 docker stop 或 docker rm 报错脚本不会因为非零退出码直接终止而是继续往下走。这在首次部署和后续滚动升级两种场景下都适用。如果你对快速找回旧版本有要求可以在删容器之前把当前运行的镜像 tag 记下来例如执行docker inspect获取当前镜像信息回滚时直接指定旧 tag 再次部署即可。4.3 从提交到部署的完整时序Pipeline 配置好之后用户视角看整个流程是这样的。开发者在本地写完代码提交并 push 到 Git 仓库。Jenkins SCM 配置的轮询或 webhook 机制感知到有新提交触发流水线执行。流水线依次执行拉取代码、Maven 构建、镜像构建与推送、容器部署。最后 Jenkins 界面展示蓝绿状态条看到蓝色代表构建成功红色则代表失败并输出失败日志。触发方式默认是 Jenkins 定时轮询远端仓库默认最小间隔是 1 分钟。更快的方式是配置代码仓库的 Webhook提交代码后立即触发这需要代码仓库平台支持同时 Jenkins 可以被外部访问。对初学者来说轮询就够用了等流程跑顺了再上 Webhook。这条链路跑通之后你会发现发布这个动作的性质变了——之前发布是一个惊险操作现在发布是一个可重复的标准动作。同一份代码无论谁来触发无论哪一台配置好的机器来执行最终产物是一致的应用启动后的行为是一致的。5. 常见问题与排查技巧实录这部分内容全部来自实操中的踩坑记录整理了最常碰到的几类问题每一项我都告诉你问题长什么样以及怎么定位。首先是最常见的Jenkins 容器内 docker 命令不存在。现象是流水线执行到 docker build 阶段报错错误消息类似docker: command not found。原因基本就是启动 Jenkins 容器时没有挂载宿主机 docker 二进制。解决办法就是重新创建 Jenkins 容器把-v $(which docker):/usr/bin/docker加上。这里补充一个细节有些新版 docker 命令是动态链接容器里可能还缺少依赖库执行会报cannot execute binary file这种情况下需要挂载整个 docker 客户端相关的库目录或者换用挂载 Docker.sock 配合容器内附加 docker client 的方式。第二个高频问题是在 Jenkins 宿主机的端口冲突。容器启动时提示docker: Error response from daemon: driver failed programming external connectivity或者端口占用错误。因为 SpringBoot 默认监听 8080如果你同一台服务器上还有另一个服务也占用了 8080部署会直接失败。处理办法有两个方向要么改 PORT_MAPPING 把宿主机端口换成别的比如8081:8080要么把旧容器先停掉再启动新容器。推荐在早期就把端口规划好避免多个服务互相冲撞。第三个问题是镜像仓库是自建的 HTTPS 或 HTTP 信任。如果你用自建 Registry 且是 HTTP 协议Jenkins 推送镜像时会报http: server gave HTTP response to HTTPS client这是因为 Docker 默认要求 Registry 走 HTTPS。解决办法是在 Docker 守护进程配置文件里insecure-registries中把仓库地址加入白名单。注意这是配在宿主机 Docker 的/etc/docker/daemon.json中然后重启 docker 服务很多人在 Jenkins 界面里找配置项方向完全错了。第四个问题是时区不对。容器启动的 Java 应用打印日志时间总是比北京时间早 8 小时这是容器默认使用 UTC 时区。解决办法是在 docker run 时增加-e TZAsia/Shanghai或者在 Dockerfile 里设置时区。我通常两者都加确保万无一失。第五个问题是构建产物没有更新。改了代码重新构建启动后发现还是旧逻辑。这类问题极大概率出在 Maven 缓存上。回滚思路是看 Jenkins 控制台输出 Maven 阶段是否有 UP-TO-DATE 或 SKIPPED 字样如果依赖没变但代码变了要确认mvn clean package是否真的执行了 clean。另外就是确认 Dockerfile 的 COPY 路径里拿到的是不是这次构建的新 jar。我也踩过快照版本依赖不更新引发的伪旧包问题这属于业务侧依赖管理范畴建议发布前在测试环境做一次完整验证。第六个是 Jenkins 工作空间磁盘占满。SpringBoot 项目的 target 目录、Jenkins 的构建记录、Docker 的镜像层叠加时间久了容易把磁盘塞满。做好定期清理docker system prune -f或清理 Jenkins 旧构建记录这是运维习惯问题但会直接影响构建稳定性。第七个是docker build慢的问题。每次构建都要重新下载 Maven 依赖这个时间可能比代码编译还长。常见的方式是在本地 maven 仓库上做镜像或挂载共享存储也可以配置流水线缓存机制例如用-v /root/.m2:/root/.m2挂载 Maven 本地仓库到宿主机。这个方案最直接效果也最明显第二次构建的依赖下载时间会大幅缩短。我把上面几个高频问题和对应处理方案整理成速查表问题现象根因处理方式docker command not foundJenkins 容器未挂载 docker 命令重新创建容器并挂载 docker 二进制与 docker.sock端口占满导致容器启动失败宿主机端口冲突调整端口映射先停旧容器再启新容器推镜像报 HTTPS 错误自建仓库未配置信任在 Docker 守护进程配置 insecure-registries应用日志时间晚了 8 小时容器时区为 UTCdocker run 时加 TZAsia/Shanghai构建的镜像仍是旧代码Maven 缓存或 COPY 旧 jar确保执行 clean镜像构建前清理 target构建越来越慢依赖和镜像层缓存失效挂载 Maven 本地仓库清理无用镜像最后说一个从部署效率角度很有用的技巧部署阶段不要总是彻底删除容器再新建可以改成先拉镜像然后用docker-compose up -d或docker service update这类方式滚动更新。最简流程里用 stop/rm/run 这套是因为它直白、问题容易定位。我实际用久之后会倾向于在流水线里判断老容器镜像与当前要部署的镜像是否一致一致就直接跳过重启不一致才更新这样可以节省非常多的时间。另一个从安全性角度的建议确保 Jenkins 的权限控制合理。Jenkins 如果不做配置默认是任何登录用户都有管理权限。建议在系统管理中开启基于角色的授权策略普通开发人员只给 Job 执行与查看权限管理员才给系统配置权限。流水线里的凭据也按需最小化授权避免把生产服务器的 Docker 能力暴露给所有账号。这个问题在团队协作时尤其重要你给一个人开了登录权限就等于可能给了整个部署链路的核心控制权权限收得越紧容错空间越大。这条自动化的部署链路前前后后我帮不同团队搭过很多次也给几个内部项目从手动部署迁移过来。每次走完这套流程大家的普遍反馈都是以后发版不用再提心吊胆了。如果你正在经历手动部署的痛苦照着这篇文章的路径走一遍把 JenkinsDocker 这条链路在自己机器上跑通你会明显感觉到发版这件事开始变得省力和规范。第一次搭建的时候不用追求一步到位能满足代码提交后自动完成构建、镜像、部署就算成功后面的细节优化和更复杂的发布策略都是在跑通这条主线之后慢慢迭代的事。