SpringBoot+Docker+Jenkins：从零搭建CI/CD自动化部署流水线

做了几年 Java 后端，最烦的就是“本地编译没问题，一上线就各种崩”这种事。反复打 jar 包、传服务器、手动重启，一两次还能忍，项目一多，每周都能烧掉大半天。后来我把 SpringBoot、Docker、Jenkins 串成一条自动化的构建、测试、部署流水线，代码一推到仓库，后面所有事都不用再管了。整个过程不复杂，但里面的坑是真不少。这篇文章把我从零搭到稳定运行的全过程记录下来，包括流水线怎么设计、Jenkinsfile 怎么写、部署脚本怎么处理，以及那些“照着文档做却死活跑不通”的诡异问题。适合正在搭 CI/CD 的小团队，也适合想把手动部署彻底解放出来的个人开发者。

1. 整套流水线的设计思路

1.1 为什么偏偏是 SpringBoot、Docker、Jenkins 这三个组合

先说清楚，这套方案没有什么玄学，就是各司其职。

SpringBoot 负责把业务跑起来。它的核心优势是“可执行 jar”和“内嵌 Web 容器”，这也决定了它的交付物天然适合容器化——一个 java -jar 就能启动的服务，扔进 Docker 镜像里几乎零成本。

Docker 负责把运行环境固定下来。SpringBoot 解决了“代码跑起来”的问题，但没解决“环境长什么样”的问题。同一个 jar 包，在 JDK 8 和 JDK 17 上行为可能完全不同，在 CentOS 和 Alpine 上也可能遇到 glibc 缺失的问题。Docker 把 JDK 版本、系统依赖、时区、编码方式全部打包进镜像，无论部署到哪台机器，运行环境都一模一样。

Jenkins 负责把前面两件事串成流水线。它其实就是一个自动化调度中心：监听代码变更、执行测试、跑构建、调 Docker 打镜像、推送到仓库、再触发远程服务器更新。可以把 Jenkins 想象成一个工厂的车间主任，SpringBoot 是产品，Docker 是包装线，Jenkins 就是那个喊着“下一个”的工头。

这三者组合起来，收益最直接的还不是“少打几次命令”，而是让每次发布都走同一条经过验证的路径。不会出现“上次是手动部署所以少传了一个配置文件”这种事，因为整条链路里没有手动操作了。

1.2 完整流水线是怎么串起来的

一条标准的流水线，从开发者的视角看只有一步：push 代码。但背后实际上走了六个环节：

1. 代码拉取：Jenkins 从 Git 仓库拉取最新代码，按分支区分。
2. 自动测试：执行 Maven 的单测、集成测试，测试失败直接中断，不许进入下一步。
3. 项目构建：mvn package 打出可执行 jar。
4. 镜像构建：用 Dockerfile 把 jar 包和运行环境打成 Docker 镜像。
5. 镜像推送：把镜像推到镜像仓库（可以是 Docker Hub，也可以是自建的 Harbor 或云厂商的镜像服务）。
6. 远程部署：目标服务器拉取新镜像，停掉旧容器，启动新容器。

这六个环节里，前三步跑在构建机上，后三步涉及产物流转。这里有一个关键设计理念：构建环境和部署环境必须隔离。测试、打 jar、打镜像这些重活全在 Jenkins 所在的构建机上完成，目标服务器只负责拉取和运行，保持轻量。

我见过不少团队图省事，直接在服务器上装 Jenkins，然后构建、部署全在一台机器上完成。短期内没问题，一旦项目多起来，磁盘被镜像占满、CPU 被构建任务打满、测试环境被搞挂，都是必然会发生的事。

1.3 部署方案的取舍

部署方式决定了流水线的复杂程度。我建议按团队规模分三档：

单机 Docker Compose：适合个人项目或小团队。镜像推到仓库后，目标机器上一条 docker compose pull && docker compose up -d 搞定。简单直观，出了问题也好排查。

多机 Docker 直连：适合已经有几台服务器的场景。通过 SSH 在远程机器上执行部署命令，或者在 Jenkins 里配置多个目标节点，用 sshPublisher 插件往不同机器分发容器启动指令。

Kubernetes 集群：适合业务量起来之后的阶段。这时候 Jenkins 的角色会偏重为“生成镜像 + 更新工作负载”，部署动作变成 kubectl set image 或者 helm upgrade，流水线的后端逻辑不变，只是最后一步的调用对象换了。

我个人强烈建议从单机方案起步，但从第一天起就要把镜像推到私有仓库。哪怕只有一台服务器，也养成“先推送、再拉取”的习惯。因为一旦后面加了第二台服务器，你不需要回头改流程。

2. 前置环境与项目基础准备

2.1 Docker 环境安装与镜像加速

构建机上必须先有 Docker。Linux 上安装很简单，官方脚本一条命令：

curl -fsSL https://get.docker.com | sh systemctl enable --now docker

Windows 上一般用 Docker Desktop，但有个极其常见的坑：安装完启动报Docker Desktop failed to start because virtualisation support wasn't detected。这不是 Docker 的问题，是 hypervisor 没开。需要进 BIOS 把 CPU 虚拟化（Intel VT-x / AMD SVM）打开，同时确认 Windows 的 Hyper-V 功能或 WSL2 已启用。装完执行 docker info 确认没问题再往下走。

国内环境还有个绕不开的点：镜像加速。 Docker 默认从 Docker Hub 拉镜像，在国内网络环境下经常超时。需要改 /etc/docker/daemon.json，配置国内镜像源：

{ "registry-mirrors": ["https://docker.m.daocloud.io"] }

改完执行 systemctl daemon-reload && systemctl restart docker。注意，这个配置影响的是拉取镜像的速度，不影响已配置的镜像仓库地址。后续 Jenkins 构建时如果在同一台机器上，也会自动享受加速。

2.2 SpringBoot 工程改造

SpringBoot 项目本身的改造点不多，但有几个直接影响流水线成败的细节：

第一个是版本。网上常有人问“SpringBoot 版本太高怎么办”，其实就是兼容性问题。比如 SpringBoot 3.x 强制要求 JDK 17+，某些老版本的 Maven 插件、动态代理库不兼容。做流水线时要先确认项目用的 JDK 版本、Maven 版本，然后在 Dockerfile 和 Jenkins 里锁死同一个版本，避免出现“本地 JDK 17 能编，Jenkins 容器里 JDK 8 报错”的镜像。

第二个是健康检查。容器编排和部署脚本需要知道应用是否真的启动成功，SpringBoot 的 Actuator 就是为这个准备的。pom.xml 加依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>

然后在 application.yml 里暴露健康端点：

management: endpoints: web: exposure: include: health,info

部署脚本里就可以通过 curl http://localhost:8080/actuator/health 判断服务是否就绪，而不是傻等几秒。

第三个是端口配置。容器化的 SpringBoot 建议直接用环境变量覆盖配置，比如：

server: port: ${SERVER_PORT:8080}

这样部署时通过 -e SERVER_PORT=9090 就能灵活调整端口，不用改代码重新打包。

2.3 Jenkins 环境安装与基础配置

Jenkins 本身也推荐用 Docker 安装，一来干净，二来后续升级简单。一个可以落地的启动命令如下：

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 \ -e TZ=Asia/Shanghai \ jenkins/jenkins:lts-jdk17

这里有两个细节要解释一下。挂载 /var/run/docker.sock 是为了让 Jenkins 容器内可以直接执行 docker 命令，这解决了“Jenkins 容器内使用 Docker 命令”的经典问题。时区设置为 Asia/Shanghai 是为了让构建日志时间显示正常，否则默认 UTC，排查问题时会差 8 小时，非常难受。

首次启动后，浏览器访问 http://服务器IP:8080，用初始密码解锁。初始密码在容器日志里，可以这样拿：

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

插件安装时建议选“自定义安装”，不推荐装全套推荐插件。你真正需要的只有这些：

• Git Parameter：构建时选择分支或标签
• Pipeline：核心流水线插件
• Docker Pipeline：构建和推送镜像的增强支持
• SSH Agent / Publish Over SSH：远程部署
• Blue Ocean：查看流水线可视化界面，会舒服很多

装完插件后可以顺手汉化一下，安装 Locale 插件，把语言设为 zh_CN。这不是必须的，但团队里有英语不太熟练的同事时，汉化能减少很多基础沟通成本。

2.4 编写一个可复用的 Dockerfile

SpringBoot 项目的 Dockerfile 推荐用多阶段构建，把“编译环境”和“运行环境”分开，最终镜像只保留运行所需的最小内容。

一个比较稳妥的模板是这样：

# 第一阶段：编译 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /workspace COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn clean package -DskipTests # 第二阶段：运行 FROM eclipse-temurin:17-jre WORKDIR /app COPY --from=builder /workspace/target/*.jar app.jar EXPOSE 8080 ENV TZ=Asia/Shanghai ENTRYPOINT ["java", "-jar", "/app.jar"]

这里的关键点是mvn dependency:go-offline。它在 COPY src 之前先把所有依赖下载好，这样源码改动后重新构建时，能充分利用 Docker 的层缓存——只要 pom.xml 没变，这一层就不会重新执行，镜像构建速度会快很多。

注意运行阶段用的是eclipse-temurin:17-jre，比默认的 openjdk 镜像更省空间，也是目前社区推荐的 Java 运行镜像。另外，我把时区在镜像里显式设好了，这样容器内 Java 进程取到的时间就是北京时间，配合 Jenkins 上的时区设置，日志时间线完全对齐。

3. 核心流水线脚本与落地实操

3.1 Jenkinsfile 基础框架

流水线的核心是 Jenkinsfile，它用代码描述整条构建流程。我建议用声明式语法，它对新人友好，结构一眼能看懂，而且 Blue Ocean 的可视化兼容性最好。

一个可以直接用的最小框架如下：

pipeline { agent any tools { maven 'maven-3.9' jdk 'jdk-17' } environment { REGISTRY = 'registry.cn-hangzhou.aliyuncs.com/demo' IMAGE_NAME = 'order-service' IMAGE_TAG = "${BUILD_NUMBER}" } stages { stage('检出代码') { steps { checkout scm } } stage('单元测试') { steps { sh 'mvn test' } } stage('打包构建') { steps { sh 'mvn clean package -DskipTests' } } stage('构建镜像') { steps { script { sh "docker build -t ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} ." } } } stage('推送镜像') { steps { script { withCredentials([usernamePassword( credentialsId: 'docker-registry', usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASS' )]) { sh """ echo "${REGISTRY_PASS}" | docker login ${REGISTRY} -u ${REGISTRY_USER} --password-stdin docker push ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} """ } } } } } }

注意几个地方。Maven 和 JDK 的配置要在“全局工具配置”里提前配好，环境中定义的 tools 会保证每个 stage 使用统一的编译工具版本。IMG_TAG 用构建号（BUILD_NUMBER），好处是每次构建产物的标识唯一，回滚时直接指定上一个构建号对应的镜像即可。

3.2 参数化构建与多分支策略

实际使用中，你不可能只构建 master 分支。功能分支、预发分支、打标签发布，这些都是常见场景。用参数化构建可以让你在点击“立即构建”时选择分支和动作。

在 Jenkinsfile 顶部增加参数定义：

pipeline { agent any parameters { string(name: 'BRANCH', defaultValue: 'main', description: '要构建的分支') choice(name: 'ACTION', choices: ['build', 'deploy', 'build-deploy'], description: '执行动作') } stages { stage('检出代码') { steps { checkout([$class: 'GitSCM', branches: [[name: "${params.BRANCH}"]], userRemoteConfigs: [[url: 'https://git.example.com/demo/order-service.git']]]) } } ... } }

如果想要更自动化的体验，可以装 Git Parameter 插件，构建时以下拉列表的方式展示所有远程分支和标签，选一个点构建就行，不用手输。

多分支流水线是另一套思路：Jenkins 会自动扫描仓库的所有分支，为每个分支生成一条流水线，你可以为不同分支单独配置是否“自动构建”、“自动部署”。适合做大项目时区分开发环境、测试环境、生产环境。

3.3 测试、构建、推送环节的细节打磨

单测阶段不要只跑mvn test就完事，一定要让流水线在测试失败时“红掉”。Maven 默认行为就是测试失败会导致构建失败，所以这个 stage 的核心价值是尽早阻断——与其等镜像推上去了再发现代码有问题，不如在第一步就拦住。

我还会在测试阶段加一个干净的环境执行，防止本地 target 目录里的瞬时产物干扰测试结果：

stage('单元测试') { steps { sh 'mvn clean test' } post { always { junit 'target/surefire-reports/*.xml' } } }

这句 junit 指令会把单测报告收集到 Jenkins，Blue Ocean 界面里可以直接看到哪些用例挂了、报错内容是什么。之后版本迭代多了，还能看到测试趋势图，这个积累对团队质量建设很有价值。

构建镜像环节有一个容易被忽略的问题：构建缓存导致的“假构建”。如果你的 Dockerfile 里 COPY src 这层缓存生效了，但构建上下文里有旧 target 目录，则可能把老 jar 打进去。所以我通常在 mvn clean package 之后才执行 docker build，并且如果用了多阶段构建，则依赖层面的缓存没问题，问题只可能出在业务代码那几层，那层缓存本来就是按需失效的，不用太过担心。

推送镜像时，前面提到用 withCredentials 取用户名密码做 docker login。更安全的做法是做一层封装，使用 Docker Pipeline 插件的 docker.withRegistry：

stage('推送镜像') { steps { script { docker.withRegistry("https://${REGISTRY}", 'docker-registry-creds') { docker.image("${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}").push() } } } }

这样 Jenkins 会在执行期间自动完成登录，凭证也不会出现在构建日志里，比手动拼 shell 的方式干净很多。

3.4 自动化部署与容器生命周期管理

走到部署这一步，我推荐用 Docker Compose 做容器编排。哪怕只有一个容器也建议用 Compose，因为部署参数（端口、挂载卷、环境变量、重启策略）都固化在 docker-compose.yml 里，可审查、可版本化。

docker-compose.yml 一个示例：

services: order-service: image: registry.cn-hangzhou.aliyuncs.com/demo/order-service:${TAG} container_name: order-service ports: - "8080:8080" environment: - TZ=Asia/Shanghai - SPRING_PROFILES_ACTIVE=prod restart: unless-stopped

这里用环境变量 TAG 来控制部署的镜像版本。Jenkins 部署 stage 可以这样写：

stage('部署服务') { steps { sh """ export TAG=${IMAGE_TAG} docker compose -f /opt/deploy/docker-compose.yml up -d sleep 15 curl -sf http://localhost:8080/actuator/health || exit 1 """ } }

注意，我用的是 /opt/deploy/docker-compose.yml 这个固定路径，而不是项目仓库里的 compose 文件。原因是部署用的 compose 文件往往会包含生产环境的特殊配置（比如某些内网地址、流量控制参数），不该和测试环境共用一份。部署文件由运维统一维护，流水线只管把 TAG 传过去。

curl -sf探测健康检查端点这个动作，是对“容器起来了”这个状态做二次确认。有时候容器起来了但应用没起来，比如数据库连接不上，这时候 health 接口会返回非 2xx，流水线就会失败，不会出现“明明部署失败你还以为成功”的情况。

3.5 触发方式与通知机制

流水线准备好之后，最后一步是让构建“自动发生”。两种常见触发方式：

Webhook：在代码仓库（GitLab/Gitea/GitHub）配置 Webhook，推送代码时请求 Jenkins 接口触发构建。这种方式时效性最高，但要保证 Jenkins 能被仓库服务器访问到，且需要配置 token。

轮询：Jenkins 每隔一段时间检查仓库有没有新提交。配置简单，但有时差，而且会浪费不必要的请求。

我推荐 Webhook。如果用的是 GitLab，在 Jenkins 里安装 GitLab 插件，然后配置令牌即可。如果你用的是 Gitea 或 Gitee，也都支持类似方式。

通知方面，不一定要接邮件。我在实际项目里用企业微信或者钉钉机器人 Webhook，构建失败时往群里推一条消息，包括分支、构建号、失败阶段和日志链接。因为大家看群消息的频率远高于看邮件。实现方式就是在流水线末尾加一个 post 块：

post { success { sh "curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx' -H 'Content-Type: application/json' -d '{\"msgtype\":\"text\",\"text\":{\"content\":\"构建成功：order-service #${BUILD_NUMBER}\"}}'" } failure { sh "curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx' -H 'Content-Type: application/json' -d '{\"msgtype\":\"text\",\"text\":{\"content\":\"构建失败：order-service #${BUILD_NUMBER}\"}}'" } }

4. 真实环境里的问题排查实录

4.1 Jenkins 容器里用不了 Docker 命令

这个问题的经典报错是：Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?或者docker: command not found。

有两个层次的原因。一是容器里根本没有 docker 命令，这需要在镜像里装 Docker CLI，或者在启动容器时把宿主机的 docker CLI 挂载进去。二是有命令但连不上守护进程，这就是 socket 没挂对。

最直接的解决方案就是启动 Jenkins 容器时加一行：

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

这样 Jenkins 容器内执行 docker 命令时，其实是和宿主机上的 Docker daemon 通信。注意，这种方式有个安全代价：Jenkins 容器拥有了宿主机 Docker 的全部权限，相当于能执行任意容器命令。如果是生产环境，建议使用更严格的安全控制，比如在 Jenkins agent 容器上做限制，或者独立出一台专门做构建的机器，不要和企业核心服务器混用。

4.2 时区、编码与镜像源那些事

时区问题在构建日志里非常隐蔽。表现为 Jenkins 页面时间正常，但应用日志时间全是 UTC，差 8 小时。排查半天才发现不是代码问题，是容器时区没设。解决方案是三层同步：

• Jenkins 容器启动时设置-e TZ=Asia/Shanghai
• Dockerfile 运行镜像内设置ENV TZ=Asia/Shanghai
• docker-compose.yml 里同样设置TZ=Asia/Shanghai

编码问题也很常见。Windows 上写的代码、配置的 Jenkins，跑出来的日志可能是乱码，典型场景是 Maven 编译时控制台输出中文测试名变成问号。解决思路是保证三处编码统一：构建机系统编码为 UTF-8、Jenkins 里设置系统属性-Dfile.encoding=UTF-8、pom.xml 里设置project.build.sourceEncoding为 UTF-8。

另外，Jenkins 默认插件安装源在国外，第一次装插件经常卡死或者超时。同样可以改成国内镜像，在“插件管理→高级”里替换更新站点地址为国内源，不然光是装基础插件就能耗掉一下午。

4.3 测试通过但镜像却没更新

这是一个“看起来成功实际上失败”的经典场景。现象是：流水线全绿，新代码也推送了，但部署后功能还是旧的。

排查方向有两个。

第一个方向：代码根本没进镜像。检查流水线的“检出代码”阶段是不是真的拉到了最新分支。特别是手动触发构建时，如果没选对分支，就会用旧代码完成整条流水线，而旧代码当然能通过测试。这也是我后来坚持在参数化构建里把“当前分支”做成默认值的原因，尽可能避免人为选错。

第二个方向：镜像缓存导致的旧 jar 包。如果你没有用多阶段构建，而是直接在一个带 Maven 的镜像里 COPY 源码然后构建，那么 Docker 会按层缓存，只要 Dockerfile 里前面的指令没有变化，后续层也不会重新执行，最终打进去的可能是历史 jar。用多阶段构建能大幅缓解这个问题，只要 COPY src 那层的校验值变了，后续就会被重新执行。

4.4 一个踩坑速查表

我把这几年被问得最多的几个问题做成一张表，方便遇到问题时快速定位：

4.5 权限与安全配置建议

安全这块容易被忽略，但真出事的时候代价很大。我的建议是按下面几条做基础防护：

• Jenkins 开启全局安全配置，创建普通用户账号，不要所有人共用 admin。
• 用于镜像仓库登录的凭证，尽量用一个权限受限的机器人账号，避免使用管理员令牌。
• Jenkins 容器和部署服务器之间如果走 SSH，建议用专门的部署密钥，而不是开发者的个人密钥。
• 不要把镜像仓库凭证、服务器密码直接写在 Jenkinsfile 或 docker-compose.yml 里，一律通过 Jenkins 的凭据管理机制注入。
• 定期清理构建机上的旧镜像和 Docker 悬空数据，执行docker system prune -f，避免磁盘被占满后触发莫名奇妙的构建失败。

5. 后续可以继续扩展的方向

这套流水线跑稳之后，其实已经能满足大多数中小团队的日常发布需求了。但如果团队质量和规模化在往前走，下面几个方向是我建议考虑接入的：

代码质量门槛：在测试阶段后加一个 SonarQube 扫描，如果代码质量指标不达标（比如代码覆盖率低于设定阈值），则流水线直接失败。这听起来有点严格，但确实能逼着团队把单测质量做上去。

自动化接口测试：SpringBoot 服务部署到测试环境后，自动跑一轮 Postman/Newman 或基于 Testcontainers 的集成测试，把部署后的活体验证也纳入流水线。

Kubernetes 部署：当服务数量多了，单机 Compose 管理起来会越来越困难。可以考虑把最后一步换成更新 Deployment 镜像或 Helm Chart，流水线前面的部分几乎可以原封不动地保留。

制品版本管理：镜像 tag 目前用的是构建号，但发布到生产时更适合用语义化版本号。可以让打标签的发布走独立分支，触发流水线时读取 pom.xml 里的版本号作为镜像 tag，这样制品标识和代码版本就形成了可追溯的对应关系。

在我实际使用的过程中感受最深的，还不是省了多少时间，而是开发、测试、部署之间的沟通成本真的降下来了。以前“这个东西我本地是好的”是团队里最有杀伤力的一句话，有了统一流水线之后，这句话的含金量被彻底消解了——每个人都用同一套路径验证代码，所有环境跑的都是同一个产物的不同版本。如果你也在被手动部署反复折磨，不要犹豫，挑一个空闲的周末把这一整套搭起来，后续收益会远超你的预期。