我见过太多团队，Java服务已经在 Docker 里跑得好好的，结果一提到“发新版本”，第一反应还是：把 jar 包拷上服务器，用一个什么命令覆盖进去，然后docker restart。真要这么干，你迟早有一天会在半夜盯着日志发呆——新代码一点没生效，或者更惨，容器起不来了，数据库、上传文件全找不到了。
这篇东西要解决的，就是“已经容器化部署（docker部署java服务）的情况下，如何进行重新部署（发新版本）”这个看起来简单、实际上门道不少的问题。我会从最基础的概念讲起，把一次标准发版的完整链路拆给你看，再把你最容易踩的那几个坑单独拎出来，最后给到回滚思路和零停机更新的进阶玩法。适合所有刚上手容器化部署、又被发版搞得头疼的人。
1. 先扭转一个观念：容器部署的更新从来不是“重启”
我见过不少人的理解是：Docker 就是个轻量虚拟机，我的服务跑在里头，更新版本嘛，就是把进程重新拉起来一次。这个理解是死穴。容器和虚拟机有本质区别，做发版规划之前，得先把这件事想明白。
1.1 容器是一次性产物，不是可维护的“老员工”
你可以把镜像理解成一套“出厂模具”，容器就是根据模具冲压出来的成品。Java 服务在容器里跑起来之后，这个容器就是一个已经定型、随时可以被销毁的实例。你想升级服务，正确的做法是：用新代码做一套新模具（新镜像），再冲一个新成品（新容器），然后把旧的扔掉。而不是在旧容器上打补丁、改文件、装软件，折腾半天还指望它变成一个新版本。
这也是容器设计和传统服务器运维最大的不同。传统服务器像雇了个老员工，干得久了，身上的经验和配置越来越值钱，你不能随便把他辞了换个新人。容器则像一个流水线上的标准件，它的“经验”全部存在镜像定义里，实例本身不承担任何状态，随时换一个一模一样的。一旦你想跟旧容器里敲命令“续命”，其实你已经退回到传统运维的老路上，容器化部署的红利就一点都没吃到。
1.2 镜像、容器、数据卷：三个角色各管一摊
聊 Docker 发版，绕不开这三个词。用一个类比帮你理清：
- 镜像：菜谱。写清楚菜怎么做，是静态的、只读的。
- 容器：按菜谱做出来的一盘菜，是动态的、能吃的，但吃完就没了。
- 数据卷：冰箱。你往冰箱里放的东西，做菜、吃饭、洗碗都不受影响，下次做新菜还能接着用。
对 Java 服务来说，有两个东西天生应该进“冰箱”：一个是配置，一个是产生的数据。配置比如application.yml、环境变量；数据比如日志文件、上传的附件、写入数据库的文件。如果你发新版时，新容器没接上原来的“冰箱”，那它就是一个从零开始的全新服务，啥记忆也没有，日志从空的开始写，上传文件也找不到了。
所以你在规划发版流程时，第一步不是敲命令，而是先回答一个问题：哪些数据必须在容器销毁后继续存活？答案决定了docker run的-v参数、compose 文件里的volumes该怎么写。
1.3 停止、删除、创建：三件事必须成套出现
很多新人发版失败，是因为只执行了docker restart。restart的意思是：把当前这个容器里的进程停掉，再让它重新跑起来。注意，它用的还是同一个容器、同一套文件系统，所以你的新代码根本没进去——因为新代码只存在于新镜像里，旧容器不可能凭空获得它。
正确的容器更新逻辑永远是三步走：
- 用新镜像创建新容器（
docker run或 compose 的up -d）； - 停掉旧容器（
docker stop）； - 删除旧容器（
docker rm）。
顺序上有个讲究：如果你先把旧容器删了，新容器又因为某个原因启动失败，那你就把自己逼进了“无服务可用”的绝境。所以我个人习惯的顺序是，新镜像先构建好、检查一遍确认没问题，再停旧的；停掉瞬间就把新的拉起来，中间空窗期越短越好。这也是后面所有自动化脚本的基本逻辑。
2. 一次标准发版的完整链路：新代码到新容器的四步
讲完概念，我们直接走一遍完整流程。假设你有个 Java 微服务，叫模拟项目A，已经用 Docker 部署在服务器上跑了几个版本。现在要发 V1.3.0。一个规范的发版，由下面四步组成。
2.1 镜像从哪来：本地构建与流水线构建的取舍
Java 项目打成镜像，通常有两种路径。
第一种：本地打包镜像，推到仓库，再到服务器拉取。
# 本地先构建出新的 jar 包 mvn clean package -DskipTests # 再构建镜像，tag 里带版本号 docker build -t registry.example.com/demo/project-a:1.3.0 . # 推送镜像到私有仓库 docker push registry.example.com/demo/project-a:1.3.0第二种：代码提交之后，由某种持续集成系统自动完成上面的动作。我倾向于推荐第二种，因为本地构建最怕一个问题：构建环境跟别人不一样。你在自己电脑上装了一堆环境变量、私服配置，打出来的包换了台机器可能就行为诡异。流水线构建的好处是环境固定，镜像可复现，谁提交的代码都一样处理，不会出现“我本地是好的，上了服务器就不行”的经典甩锅场景。
当然，小团队、个人项目、或者内网开发环境，你完全可以先本地构建。这里我给你一个必须守住的底线：永远不要让服务器去改镜像内部的代码。不要觉得镜像启动慢了就docker exec进去调参数，也不要为了省事就直接把 jar 包挂进容器覆盖原有的。任何手工覆盖，都会让镜像个黑盒，发多少次版都发不明白。
2.2 镜像 tag 怎么打，直接决定回滚难度
构建镜像时，docker build都会带一个-t参数。tag 既可以是latest，也可以是1.3.0。我强烈建议你养成带语义化版本号的习惯。
理由很简单：镜像 tag 是回滚的路标。万一 1.3.0 上了之后线上崩了，你只要重新拉registry.example.com/demo/project-a:1.2.0就能稳妥回到上个版本。如果所有人都只打latest，旧版本镜像会被覆盖，那回滚就变成“找一台测试机重新构建一个旧分支镜像”，时间成本和风险都上去了。
给 tag 起名，我的建议是下面这种格式：
- 正式环境：
<项目名>:<主版本>.<次版本>.<修订号>，例如project-a:1.3.0 - 预发布环境：
<项目名>:<主版本>.<次版本>.<修订号>-rc，比如project-a:1.3.0-rc - 快照包：
<项目名>:<分支名>-<构建时间>，比如project-a:feature-login-202506071200
需要注意，latest不是不能用，但它只能当“默认快捷方式”用，不能当唯一的标识。我见过有人拿latest同时又想发多个版本，结果几个环境之间互相覆盖，排查起来相当痛苦。另一个常见问题是构建脚本里每次 tag 都写死同一个名字，推上去之后发现本地缓存没失效，拉下来的还是旧镜像——这个坑我后面会细说。
2.3 用 docker 命令手动发布：每个命令到底在干什么
假设镜像已经推到仓库了，服务器上开始手动发版。典型操作如下：
# 第一步：拉取新版本镜像 docker pull registry.example.com/demo/project-a:1.3.0 # 第二步：把服务先停下来 docker stop project-a # 第三步：删掉旧容器 docker rm project-a # 第四步：用新镜像创建新容器并启动 docker run -d \ --name project-a \ --restart unless-stopped \ -p 8080:8080 \ -v /data/project-a/logs:/app/logs \ -v /data/project-a/uploads:/app/uploads \ -e SPRING_PROFILES_ACTIVE=prod \ -e DB_HOST=10.0.0.8 \ registry.example.com/demo/project-a:1.3.0这里每一句都不能省略。docker stop给 Java 进程留出做清理工作的时间，docker rm把旧的文件系统层、容器状态全部释放掉，最后docker run才是真正把新代码跑起来。
有几点需要解释：
--restart unless-stopped：让容器在意外退出或服务器重启时自动拉起，但如果运维主动stop，它就乖乖保持停止状态。这个参数对保持服务可用性非常重要。-p 8080:8080：宿主机 8080 映射到容器 8080。如果旧容器没有先rm，新容器想绑定同一个宿主端口是做不到的，因为端口还占着。这也是为什么要严格按“停旧 + 删旧 + 起新”的顺序来。-v /data/project-a/logs:/app/logs：把日志目录挂到宿主机的固定路径。否则新版容器启动就是全新空目录，旧日志直接“蒸发”。-e环境变量：把连接数据库、开启哪个 profile 这类配置从镜像里摘出来，镜像本身不携带环境相关信息，换个环境不需要重新构建。
2.4 发布之后，拿什么判断“真的成功了”
我发现很多人发布会有一个习惯：看到docker ps的 STATUS 是 Up，就放心地在群里发一句“已发布”。其实这个判断是不够的。容器 Up 只能说明进程没挂，不代表 Spring Boot 已经完成初始化、更不代表业务接口正常。
我自己的检查顺序是：
docker ps看容器状态，排除启动即退出这种简单错误；docker logs --tail 50 project-a看启动日志，确认没有异常堆栈，看到 “Started Application in 5.8 seconds” 这类字样才算真正起来；- 如果服务有健康检查接口，直接
curl -s http://localhost:8080/actuator/health，确认返回{"status":"UP"}； - 至少真实调用一个核心业务接口，别只看健康检查，因为健康检查通常不覆盖数据库连接等外部依赖。
这套流程在 make 一个小脚本固化下来，省得每次手忙脚乱。它本质上是在回答“新版是否达到了可上线状态”这个核心问题，而不是流于形式。
3. 发新版最容易翻车的三个点：数据、配置和残留容器
现在来聊实战里最容易踩的坑。我看了太多团队发的版本，十次里有八次出问题，都集中在下面三件事上。
3.1 日志和上传文件在发版后消失的真相
有一次，某开发者组里的一个 Java 服务在做例行升级，升级完了之后，用户反馈“历史上传的附件全部打不到”。一查，原来旧容器启动时用的是容器内部路径/app/uploads，而 Dockerfile 里也声明了VOLUME /app/uploads。但问题在于：当时这个卷由 Docker 自动创建，对应的宿主机目录是一串随机 hash，比如/var/lib/docker/volumes/2a2f4c3e.../_data。新容器重新创建时，又生成了一个全新的匿名卷，数据就完全断了。
解决方案非常简单：显式挂载宿主目录或命名卷。你可以在docker run里写-v /data/project-a/uploads:/app/uploads，或者用 compose 里的 named volume：
volumes: uploads-data:然后把服务里的上传路径配置成挂载目标。记住，匿名卷只适合测试环境的临时容器，生产环境的发版流程里，任何你想在容器升级后保留的数据，都必须显式声明挂载关系。
日志也是同一个道理。容器本身就是短命的，你不想排查问题的时候只看到当天日志，就得把日志持久化挂出来。很多人升级完一看日志目录是空的，第一反应是“代码没生效”，其实只是挂载写漏了。
3.2 配置用环境变量还是挂配置文件，别混着来
Java 服务的配置来源很多：application.yml里的默认值、环境变量、启动参数、外部配置中心。容器化之后，我见过最混乱的做法是：一部分配置写在application-docker.yml里打进镜像，一部分用-e传，还有一部分偷偷改容器内部的文件。等发版时想改个数据库地址，都不知道该动哪里。
我的建议是，把配置分成两类处理：
- 不随环境变化的代码级配置，留在镜像内部文件里，比如框架默认参数；
- 随环境变化的运行时配置，统一走环境变量或外部挂载文件。
用环境变量的方式，一条命令就把不同环境的差异覆盖掉了：
docker run -d --name project-a \ -e SPRING_PROFILES_ACTIVE=prod \ -e DB_HOST=10.0.0.8 \ -e DB_PORT=3306 \ -e DB_USER=app_user \ -e DB_PASSWORD='这里放你自己的密码' \ -p 8080:8080 \ registry.example.com/demo/project-a:1.3.0如果环境变量太多，也可以用--env-file：
docker run -d --name project-a \ --env-file /data/project-a/.env \ -p 8080:8080 \ registry.example.com/demo/project-a:1.3.0这比在命令行里堆上百个-e干净多了。注意，.env文件本身属于敏感信息，权限要收紧，别随手chmod 777。
还有一类配置既不适合塞进环境变量，也不适合打进镜像，比如那种格式复杂的规则文件、证书文件。这种情况我建议挂只读文件卷：
-v /data/project-a/config:/app/config:ro镜像里不要放任何真实密钥，所有密钥都通过外部挂载注入。发版时换配置只需换挂载源，根本不用重新构建镜像。
3.3 旧容器和悬空镜像，留多久、怎么清
发版发多了，服务器上会堆很多历史容器和悬空镜像。它们的危害是：占用磁盘，混淆排查。尤其是你docker run新容器时没注意名字已经存在，会直接报Conflict. The container name "/project-a" is already in use，这就是旧容器没清干净的表现。
标准清理命令我列一下：
# 看当前有哪些容器活着 docker ps # 看所有容器，含停止的 docker ps -a # 清理所有已停止的容器 docker container prune # 清理悬空镜像（没有 tag 且没有被任何容器引用的） docker image prune这里我特别提醒一下：docker image prune只删悬空镜像，手滑的概率不高。但如果加了-a，它会尝试删除所有未被使用的镜像，这个要谨慎，因为有些镜像你可能暂时没跑容器，但回滚时还指望着它。
清理时机也很重要。不要刚发完版就立刻prune，我自己的习惯是：旧容器确认新版本稳定运行一天之后再清理；旧版本镜像保留最近两三个版本，超过的再删。这样手一抖发坏了，还能快速回滚，不用重新去仓库拉历史版本。
还有一个容易被人忽略的细节：docker restart不会帮你换镜像，docker stop也不会。想让容器名字不变、端口不变、配置不变，但代码换掉，就得先rm再run。如果你为了方便用的是 compose 文件，这个操作差异会小一些，因为 compose 本身就帮你封装好了。
4. 快速回滚的实操路线：新版翻了车，别慌
既然发了新版，就一定要想好“怎么退回来”。很多人平时不发版没事，一出问题就开始慌，在服务器上翻 Docker 历史记录，越翻越乱。这里给你两条清楚的路线。
4.1 有版本号镜像：一条 run 命令回旧版
这是最理想的情况，前提是你当初没有偷懒只打latest。假设当前新版本是 1.3.0，现在要回退到 1.2.0：
# 拉旧版镜像 docker pull registry.example.com/demo/project-a:1.2.0 # 停掉并删除当前容器 docker stop project-a && docker rm project-a # 用旧镜像重新启动 docker run -d \ --name project-a \ --restart unless-stopped \ -p 8080:8080 \ -v /data/project-a/logs:/app/logs \ -v /data/project-a/uploads:/app/uploads \ -e SPRING_PROFILES_ACTIVE=prod \ registry.example.com/demo/project-a:1.2.0命令跟发新版几乎一模一样，只有镜像 tag 不一样。这也是我反复强调“tag 必须带版本号”的原因——回滚实操简单、时间短，全公司都能执行，而不是只能依赖某一个人。
需要注意的是，回滚并不是把容器换回旧版就完事了。如果新版在数据库做了一个不可逆变更，比如加了字段、改了数据格式，那么旧版代码可能根本跑不通。所以回滚前要评估“数据的兼容性”，但这属于另外一个大话题，这里只提醒你别天真地以为回滚=换镜像。
4.2 没有 tag 怎么办：两个应急恢复手段
有的项目会手忙脚乱，急着发版，镜像 tag 胡乱打，或者干脆用localhost:5000/project-a这种没有区分度的名字。真到回滚时刻，仓库里根本找不到旧版本。这时还有两个应急手段，但应急归应急，不要当常规操作。
手段一：看当前运行容器的镜像 hash。
docker inspect --format '{{.Image}}' project-a docker images如果你足够走运，旧镜像虽然没打 tag，但镜像 ID 还在本地镜像列表里，你就能用镜像 ID 回滚：
docker tag <镜像ID> registry.example.com/demo/project-a:rollback-1.2.0 docker run -d --name project-a-rollback ... registry.example.com/demo/project-a:rollback-1.2.0手段二：把还在运行的旧容器 commit 成镜像。
如果你发完新版之后立刻发现不对，而且已经把旧容器stop了但没有rm，那你还能抢救：
docker commit project-a-old registry.example.com/demo/project-a:emergency-backupdocker commit会把一个容器的当前文件系统状态固化成镜像。听起来很方便，但它同时会把容器里的临时文件、进程残留、当时的网络状态一股脑打进去，用它恢复出的镜像既不干净也不可复现。我只能说，这是最后一根救命稻草，用完之后赶紧去把真正的可重复构建流程搭起来，别指望下次还能这么走运。
4.3 回滚之后先别急着下班：三个验证点
我见过最典型的翻车场景是：回滚命令敲完，容器状态 Up，大家以为搞定了，结果用户仍然说服务不可用。为什么？因为回滚不只是换一个镜像，你还要确认以下三点：
- 配置是否一致。新版本环境变量、挂载配置如果已经变了，那旧版本启动后可能读不到它想要的配置。比如数据库地址指向了一个新库，但旧代码不认。
- 数据是否兼容。新版本跑过的数据，旧版本能不能照常处理，这个在回滚前就要想好，不是回滚后靠监控能救回来的。
- 依赖服务是否就绪。如果新版把 API 的某个接口路径改了，下游调用方还按新版调，旧版顶上之后接口不存在，调用方也会报错。回滚往往是多服务协同的动作，不是单独一个容器的事。
所以，回滚动作本身几分钟就完了，真正的功夫在回滚前后的验证上。别省这一步。
5. 让发版更稳的进阶经验：优雅停机与零停机更新
到这里，你已经掌握了一套完整的容器发版流程。接下来我说的进阶经验，能让你在“直接把旧容器停掉再启动新容器”的基础上更进一步，尤其是 Java 服务这种启动可能要花个几十秒的应用，体验差别会很大。
5.1 Spring Boot 优雅停机：别让请求被硬生生掐断
默认情况下，docker stop会在等一个宽限期（默认 10 秒）后，对容器主进程发送 SIGKILL，直接把进程杀掉。对 Java 应用来说，这会导致正在处理的请求被打断，可能留下半截数据或者脏状态。你可以在 Spring Boot 2.3+ 中启用优雅停机：
server: shutdown: graceful如果用的是 Spring Boot 3.x，同样支持。为了给“收拾手尾”留时间，可以再加这个：
spring: lifecycle: timeout-per-shutdown-phase: 20s配置之后，当 Docker 停止容器时，Spring Boot 会先停止接收新请求，然后给正在处理的请求留出时间完成，最后才退出。这个配置虽然简单，但对用户体验和系统稳定性影响巨大。
5.2 单机环境下的零停机切换思路
如果你只有一个节点，想要“旧容器停掉瞬间新容器立即接手，中间请求无感知”，单靠手敲命令很难做到。比较现实的方案有几种：
方案一：临时多端口并发。
把旧容器先保留，新容器用另一个宿主端口（比如 8081）启动，等新容器健康检查通过之后，再反向代理或负载均衡层切换流量，最后停掉旧容器。这个方案最灵活，但要求你用 nginx 或者 gateway 之类做流量入口，而不是让用户直连 8080 端口。
方案二：用编排工具做滚动更新。
如果在单机上装了 Docker Compose，可以用docker compose up -d --scale配合负载均衡实现多副本滚动更新。但这个对 Java 应用的门槛不低，需要服务本身无状态、能平滑扩容缩容，也要做好会话共享。如果只是几十个人的内部系统，且停机几分钟可以接受，其实完全不必为了“零停机”三个字引入巨大的复杂度。
我的态度是：先把基本的发版流程做扎实，零停机属于锦上添花。很多团队连版本号 tag 都没打好，就急着上蓝绿发布，最后给自己挖了大坑。
5.3 一张发版自检清单，贴在电脑前
这些年做下来，我把发版流程收敛成一张清单，每次发布前逐条确认。你完全可以按自己的情况调整：
| 阶段 | 检查项 | 说明 |
|---|---|---|
| 构建 | 新代码已经合并到目标分支并打了标签 | 知道发的是哪一版 |
| 构建 | 镜像已构建并推送到仓库 | 服务器能拉得到 |
| 构建 | tag 是语义化版本号，不是只有 latest | 回滚有路标 |
| 发布前 | 数据卷挂载路径正确 | 日志、上传文件不会丢 |
| 发布前 | 环境变量、配置文件已完成备份 | 出问题能还原 |
| 发布中 | 先拉新镜像，再停旧容器，删除并重新创建 | 顺序不能乱 |
| 发布中 | 端口未被占用 | 容器起不来的头号原因 |
| 发布后 | 容器状态 Up 并且启动日志正常 | 不只是看进程状态 |
| 发布后 | 健康检查通过，核心接口抽测一次 | 确认业务真实可用 |
| 发布后 | 旧镜像保留至少一个版本 | 出问题能快速回滚 |
我记得有一次发版，所有命令都没错，唯独漏了一个-v参数，结果就是用户上传的文件访问不了。那次之后，我把这张表打出来贴在工位上，每次发布都对着检查一遍。别觉得这是多此一举，容器化部署最怕的就是“好像哪里都对，但又哪里不对”。
真正把这一套流程跑顺之后，发版就不再是“惊心动魄”的事。它变成了一件可以标准化、可以重复执行、甚至可以被脚本自动化的日常操作。而这一切的前提，就是你理解了镜像、容器、数据卷三者各司其职的关系，并且愿意在每一个细节上多问一句“为什么”。
