Docker 容器化部署：镜像分层与 Compose 编排

先说人话。容器不是「一台迷你电脑」，而是一个被单独关进小房间的 Java 进程：它有自己的一套文件系统视图、自己的网卡、自己的内存额度，但和宿主机共用同一个 Linux 内核。正因为不虚拟硬件、不装操作系统，它才能秒级启动、几十 MB 起步。而「镜像」就是那套打包好的文件与配置——同一份镜像在任何一台装了 Docker 的机器上，展开出来的东西都一模一样，这就是它治「在我机器上能跑」的办法。

先把六个词一句话解释（全文都会用到）：

• 镜像（Image）：只读的文件层叠起来的模板，构建一次、到处复用；它是「交付物」，不是运行中的东西
• 容器（Container）：镜像跑起来的实例，等于在只读层顶上再盖一层可写的临时层；删掉容器，可写层就没了
• 分层（Layer）：Dockerfile 里每条 COPY / RUN 产生一层，层与层之间只认「我和我下面有没有变」
• 构建缓存（Cache）：某一层及其以下完全没变，这一层就不重跑，直接复用——这是 Dockerfile 写法的全部学问
• cgroup：Linux 内核的资源限额开关，docker run -m 512m 靠它限制内存；JVM 要「感知容器」就是去读它
• namespace：Linux 的视图隔离机制，让容器里的进程看不到宿主机的其他进程和网络

上图把整篇拆成四关：分清镜像与容器 → Dockerfile 怎么写才不吃缓存 → 跑起来之后 JVM 与容器的相处规则 → 编排与优雅停机。后面每一节都能在这张树上找到一个位置；卡壳时回来看一眼，就知道自己在第几关。

学完这一篇，你应该能回答三个问题：

• 为什么改一行业务代码，我的镜像构建要重跑一遍依赖下载？Dockerfile 到底该怎么排指令？
• 容器日志写着 Exit code (137)、Reason: OOMKilled，但 Java 日志里一行 OutOfMemoryError 都没有——到底谁杀了谁？
• 我明明配了优雅停机，为什么 docker stop 还是在切请求？信号在哪一步被吞掉了？

每个后端都听过这句话：「在我机器上能跑啊。」背后的本质是环境漂移——开发机是 JDK 21 加 MySQL 8.0，测试环境是 JDK 17 加 MySQL 5.7，生产又是另一套。容器化的第一步，就是把「应用 + 依赖 + 运行时」打包成一个不可变的交付物，让三个环境跑的是同一个东西。

容器之所以轻，是因为它不虚拟硬件、不装完整操作系统——所有容器共享宿主机的内核，只是用 namespace 做视图隔离、用 cgroup 做资源限制。这带来启动快、密度高的优点，代价是隔离性弱于虚拟机（内核漏洞可能被跨容器利用）。

先把四个最常混的概念分清：

镜像不是一整块，而是一层层叠加的只读层。每一条 COPY、RUN、ADD 指令都会产生新的一层。Docker 构建时会逐层比对缓存：某一层及其所有下层都没变，这一层就直接复用缓存，不再执行。

这就解释了一个经典优化：为什么要把 pom.xml 复制提前。

这条规则光看文字容易记反，亲手跑一次缓存判定就忘不了。下面这个实验用默认的 layer 参数把「每条指令产生哪一层」「缓存凭什么判定」「构建输出里的 CACHED 是什么意思」逐帧摊开——重点盯第 ③ 帧（为什么 COPY pom.xml 要提前）和第 ⑥ 帧（分层提取省下了多少）：

缓存判定光看图还不够，最容易忘的是「一层的指纹由谁组成」。下面这台单步台把 builder 段的五行构建拆成逐帧执行：每按一步，看它到底重算了哪个指纹——第 ③ 步是整段的灵魂：

记住这张指纹表再看 2.2 的 .dockerignore：如果 COPY src ./src 的输入被 target/ 这类垃圾污染，每一层都会变——缓存从此再没命中过。

上下文（context）是先整体打包传给守护进程的，所以 target/、.git/、node_modules/ 这些目录哪怕最终没进镜像，也照样要上传一遍。根目录建一个 .dockerignore：

先看一个能跑、但还不够生产级的基础版本：

上面那个 Dockerfile 有个前提：宿主机得先 mvn package 打出 jar。但 CI 机器未必装了 Maven，就算装了，也不该把构建环境和运行环境混在一起。解法是多阶段构建——一个 Dockerfile 里写两段 FROM，前一段负责构建，后一段只拿产物。

多阶段构建解决了体积，但还有一个缓存问题：每次改一行业务代码，整个 app.jar 变了，COPY app.jar 这一层就失效，依赖层跟着重来。Spring Boot 提供了分层提取，把 fat jar 拆成独立的层分别 COPY：

前面四节讲的其实是一条流水线上的三段：先打出能跑的 jar，再把 jar 切成层搬进镜像，最后起容器发布端口。新手最容易断在「jar 和镜像到底谁装了谁」这一环，所以把整条路按顺序走一遍：

第六步特别说明一下：-p 8080:8080 和 /actuator/health/readiness 属于两个不同的责任——前者是 Docker 干的（把宿主端口映射进容器），后者是应用自己得答对（回答「我现在能不能接流量」）。这一篇先把 Docker 这半边做扎实，探针那半边见第 42 篇。

而第一、二步的前提是：你确实知道自己打进镜像的那个 jar 长什么样。上一篇文章拆开过可执行 jar 的内部结构——Main-Class 是 JarLauncher 而不是你的启动类，依赖躺在 BOOT-INF/lib 里由自定义类加载器读取。做容器化之前先用这个实验把这层确认一遍，尤其是 war 那一档：等你换成 war 部署外部 Tomcat 时，COPY target/*.jar 这条指令会直接找不到文件。

容器默认跑在 bridge 网络里，每个容器有独立 IP，容器内的 localhost 指容器自己，不是宿主机。同一自定义网络内，容器可以直接用服务名互相访问：

手敲一堆 docker run 很快就会失控。Compose 用一份声明式 YAML 描述整套环境，docker compose up 一键拉起：

逐段解读：

• 服务依赖与启动顺序：depends_on 默认只保证"启动顺序"，不保证"就绪顺序"。加上 condition: service_healthy，才会等健康检查通过——这是避免"应用先起来、数据库还没准备好"的关键
• 健康检查：healthcheck.test 是探活命令，MySQL 用 mysqladmin ping、Redis 用 redis-cli ping。depends_on 的 service_healthy 依赖它的结果
• 环境变量注入数据库配置：应用不写死连接串，而是读 DB_HOST / DB_NAME，由 Compose 注入。${MYSQL_ROOT_PASSWORD:-root} 表示"取环境变量，缺省用 root"
• 数据卷：mysql-data、redis-data 是命名卷，声明在顶层 volumes: 下，容器重建数据不丢
• 构建与镜像：build: . 让 Compose 现场构建，image: 给它起名字便于复用

Compose 的 healthcheck 让编排系统知道容器「能不能接活」，而容器里跑的 Spring Boot 应用也得自己回答这个问题。第 42 篇讲过 Actuator 的健康端点，这里补上它在容器视角的样子——健康检查不是一次探活，而是多个检查项投票之后的最坏结果：

• 数据库通、Redis 通 → UP；任何一项不通 → 整条链路 DOWN，K8s 的 readiness 据此把你摘出负载均衡
• 所以健康检查里别挂业务查询：一个偶发的慢 SQL 会把「进程活着」误报成「实例不可用」
• 想知道容器里到底是哪一项在拉低状态，打开 management.endpoint.health.show-details=always 逐项看

容器化不只是写 Dockerfile，应用本身也要做两处配合。

不要在 application.yml 里写死 localhost，用带默认值的占位符：

容器哲学里有一条：进程只写标准输出，日志的去向交给平台。所以生产配置应该只往控制台打，而不是写文件：

这是容器化里最容易「平时不出事、一扩容就炸」的一处。JVM 判断该开多大堆时，默认看的是整台机器的物理内存，而不是分给它的那份配额。一个跑在 512m 容器里的进程如果按宿主 32GB 去算默认堆，就会一路冲到 cgroup 上限被内核直接抹掉。Java 8u191 之后 UseContainerSupport 默认打开，JVM 会去读 cgroup 的限额文件（v1 是 memory.limit_in_bytes，v2 是 memory.max），但它读的是限额，不是「你的堆」。

正确写法是按百分比声明，而不是写死 -Xmx：

两种失败模式必须分清，因为它们的排查方向完全相反：

两种失败的分界，其实就落在「给堆留多少百分比」这一个数字上。512MB 的容器里把 -XX:MaxRAMPercentage 从 25 拖到 100，每一步都能看到堆、非堆、总账三者怎么分摊——注意右端那一档，它等价于写死 -Xmx512m：

左边那一列解释了为什么「加大内存限额就好了」经常只是掩盖问题：根因可能在 Netty 的直接内存没释放，而堆外压根不受 -Xmx 管辖。这个实验把「JVM 读到多少 → 默认堆怎么算出来 → 两种失败各自长什么样」一次走完：

清单读完了，把它变成你家项目的行为——下面这台生成器把「生产级 Dockerfile 该有哪些块」做成勾选项。先只勾「多阶段 + 分层提取」看最小骨架，再逐项叠加非 root、内存比例、健康检查与停机信号，对照上面表格里各自的收益：

最常见的误解：以为容器里 localhost:3306 能连到宿主机的 MySQL。错——容器的网络 namespace 是独立的，localhost 指容器自己。要么用宿主机 IP（Linux 上是 172.17.0.1），要么干脆把数据库也放进 Compose，用服务名互访（推荐后者）。

EXPOSE 8080 只是声明，不会让外部访问到。真正发布端口的是 docker run -p 8080:8080（或 Compose 的 ports）。少写 -p，容器跑得好好的，浏览器却死活连不上。

容器默认 UTC，日志时间戳和数据库时间都会比北京时间少 8 小时。解决方案：Dockerfile 里加 ENV TZ=Asia/Shanghai，或运行时 -e TZ=Asia/Shanghai，并在连接串里带 serverTimezone=Asia/Shanghai。

某些镜像（尤其精简版）熵池小，SecureRandom 初始化时阻塞读 /dev/random，表现为应用卡在启动、Tomcat 迟迟不监听端口。Linux 内核 5.6+ 后 /dev/random 不再阻塞，老内核可挂载 /dev/urandom 或加 -Djava.security.egd=file:/dev/./urandom 绕过。

在 Apple Silicon（M 系列）Mac 上跑一个只为 x86 构建的镜像，或者把本地构建的 arm64 镜像推到 amd64 服务器上，就会看到这条：

它跟 Java 一点关系都没有——是 Docker 在尝试执行 ENTRYPOINT 那个二进制时失败了：镜像里打包的是 linux/arm64 的 java，宿主内核是 linux/amd64，指令集不同，加载器直接拒绝。三条自救路径：

• 构建时显式声明平台：docker buildx build --platform linux/amd64 -t bee-app:1.0 .
• 运行时声明（仅在有 qemu 模拟的机器上有效，慢且不稳）：docker run --platform linux/amd64 bee-app:1.0
• CI 里一次产出两种架构：docker buildx bake 或多条 --platform linux/amd64,linux/arm64 配合 manifest 推送

排查只有一条命令就够，看镜像自己的架构而不是你的机器的：

第 36 篇讲过优雅停机的六个动作，前提是JVM 真的收到了那个信号。容器里最容易断的就是这一环。

关键在第 ②③ 两帧的分岔：

• exec（JSON 数组）形式：ENTRYPOINT ["java","-jar","app.jar"] —— java 自己就是 PID 1，SIGTERM 直达 JVM，关闭钩子照常跑
• shell 形式：ENTRYPOINT java -jar app.jar —— 容器实际启动的是 /bin/sh -c "java -jar app.jar"，站在 1 号位上的是 shell；/bin/sh 默认不转发收到的信号，于是你所有优雅停机配置一句都没执行，10 秒后被 SIGKILL 硬杀

症状非常固定：日志里一行 shutdown 相关的话都没有，但容器确实被正常停了。修法三选一——改用 exec 形式；或保留 shell 形式但写成 ENTRYPOINT exec java -jar app.jar；或用 tini / dumb-init 当 1 号进程代管信号与僵尸回收。

还要两边对齐：Spring 侧的 server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase 若配了 30 秒，而 Docker 侧 docker stop 默认宽限期只有 10 秒，那后 20 秒的请求照样是被硬切的。

验证方法很土但最有效：一边 docker stop -t 30 bee-app，一边 docker logs -f bee-app，看得见 Closing org.springframework... 才算通。这个实验把信号链路完整走一遍，重点看第 ②③ 两帧的分岔：

容器环境变量和应用里的条件装配，本质是同一件事：同一份代码，在不同环境装配出不同结果。这个演示把 IoC 容器的条件开关跑一遍——就像切换容器环境变量一样。

• 拨动 @ConditionalOnProperty 这类开关，观察容器里注册的 Bean 如何变化
• 容器环境变量（如 DB_HOST）通过 Spring 的 @ConfigurationProperties 绑定，最终影响装配
• 理解这一点，就理解了"一个镜像跑多环境"的底层机制

不过这一篇的主角不是应用内部装配，而是镜像本身。第二节那条「上层变化不影响下层」的规则，只有亲手看一次缓存判定才记得住——上面第 2.1 节已经用 layer 参数走过一遍，这里补一个视角：同一份代码，环境不同、装配结果不同。下面这个实验把条件注解的求值过程摊开，它对应的就是「容器里注入什么环境变量，应用就长成什么样子」：

再切到 build 参数看构建阶段的卫生问题（.dockerignore、builder 层的 ~/.m2、基础镜像选型），它对应第四节的取舍：

镜像、容器与应用三件事讲完了，验证手段还剩最后一层：命令行。下面这台控制台连着浏览器里的同一个 Java 内核——先 whoami 看当前进程，再逐条 lab 把本节的四个实验敲一遍，回显全部由内核真实执行：

上面所有功夫最后都要落在一次真实的滚动发布上：新容器顶上、老容器退场，而用户不该感觉到中间那次抖动。老容器退场的完整动作不是「杀掉进程」，而是三件事按顺序发生——先被摘掉流量、再把在途请求处理完、最后才退出。这三步里 Docker 只负责第一步的一半，剩下的都在应用和编排层。

第 42 篇讲过 Actuator 的两个探针端点，语义完全不同，混用会造成「数据库抖一下，全体实例被重启」：

• /actuator/health/liveness 回答「这个进程还有救吗」——只该判断进程自身，配错了会导致反复重启
• /actuator/health/readiness 回答「现在能不能给我流量」——依赖不健康时应该由它摘流量，而不是杀进程

• 宽限期要对齐：K8s 的 terminationGracePeriodSeconds（默认 30 秒）必须大于 Spring 侧 spring.lifecycle.timeout-per-shutdown-phase，否则你等到一半就被 SIGKILL
• preStop 那个 sleep 不是玄学：Endpoint 更新有传播延迟，收到 SIGTERM 的一瞬间旧实例仍可能被打进新请求，所以惯例是先 sleep 2~5 再开始收尾
• docker stop -t 同理：本地或 Compose 环境下没有 preStop，唯一能调的就是 -t；第五节那条坑说的就是这件事

下面每一行的「报错原文」都能整段复制去搜索，别意译、别缩写。新手在这三处最容易卡住：内存被外部处决、端口连不上、构建每次都重来。

上面那张速查表里，java.lang.OutOfMemoryError: Java heap space 和第一行的 137 长得很像，现场却完全不同。下面这段是真实堆栈，先别看答案——点出你认为的凶手行，再对照两种失败的分界：

先来一道热身题，考的是第二节的缓存规则：

再来一道综合题，把 8.3、10.6 和第十三节串起来：

「把限额调大就好了」是容器排障里最贵的一句安慰——它让症状消失，却让你永远不知道是谁在吃内存。下面这个沙盘把堆比例和容器限额做成两个开关，切一档就能同屏看到默认堆算出多大、总用量落在哪、以及最终以什么姿势失败：

目标：从空目录起，做出「多阶段构建 + 分层 COPY + 感知限额 + exec 形式入口」的镜像，并用 Compose 把它和 MySQL 一起拉起来。每一步都给预期输出，对不上就停下检查。

第一步，建工程骨架（只需要三个文件）：

第二步，pom.xml（开启分层提取，这是后面 COPY 四层的前提）：

第三步，.dockerignore（少这一行，构建上下文会白白上传几十秒）：

第四步，最小应用 LabApplication.java：

第五步，Dockerfile（多阶段 + 分层 + exec 入口 + 按比例设堆）：

第六步，构建并观察缓存：

预期输出（关键看 CACHED 出现的层数）：

第七步，带限额起容器，回头对照 8.3 节那张对照图验算比例：

预期响应：

384 正好是 512 的 75%，说明 MaxRAMPercentage 生效了。若这里读到的是宿主物理内存的一个很大比例，说明你的基础镜像 JDK 太老、UseContainerSupport 没开。

第八步，改一行业务代码再构建一次，确认依赖层仍是 CACHED：

预期：构建阶段那条 RUN mvn -B dependency:go-offline 依然打印 CACHED，只有 COPY src 之后的层重跑。如果你看到的是依赖重新下载，回头检查 2.1 节的指令顺序。

第九步，验证优雅停机真的走到了 JVM：

预期能看到一行类似 Closing org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext...。看不到就回到本篇 10.6 节检查 ENTRYPOINT 的形式。

第十步，落成 Compose（docker-compose.yml，放在 Dockerfile 旁边）：

预期 app 状态为 running，mysql 为 healthy；docker compose ps 里 app 的 PORTS 列必须有 0.0.0.0:8080->8080/tcp——没有就是第七节少了 ports。

验收清单：① 说得出第八步为什么依赖层还能命中缓存（对应第二节规则）；② curl 到的 384MB 是怎么算出来的；③ docker inspect lab --format '{{.State.ExitCode}} {{.State.OOMKilled}}' 在你手动 docker stop 后返回什么、为什么不是 137 True。

只改一处，观察结论翻转：

1. 把 ENTRYPOINT 改成 shell 形式 ENTRYPOINT java -jar app.jar（去掉 JSON 数组）。你会观察到：docker stop -t 30 lab 仍然在约 10 秒后就结束，日志里一句 Closing ... 都没有——这就是 10.6 节讲的信号被 shell 吞掉。再用 docker exec lab ps -ef 看 1 号位是谁，答案会是 sh。
2. 把 .dockerignore 里那行 target/ 删掉，先本地跑一次 mvn package 再 docker build。你会观察到：构建开头的 transferring context 从几百 KB 涨到几十 MB，耗时明显变长；而且 COPY src ./src 之外的内容变化会让上层缓存失效。这就是「上下文也是成本」。
3. 把 -m 512m 改成 -m 256m 而不动 JAVA_TOOL_OPTIONS。你会观察到：curl 变成连接被拒，docker inspect 给出 OOMKilled true、Exit Code 137，而 docker logs 最后一行还是正常的启动完成日志——完美的「外部处决、不留现场」样本。此时把比例降到 50 再试，症状会从 137 变成能被日志记录的堆内错误。
4. 把基础镜像换成 eclipse-temurin:21-jre-alpine。你会观察到：镜像体积确实小了约 20MB，但如果连的是服务名而不是 IP，可能开始出现偶发的解析失败——对照第九节提示条与上方 build 实验的第 ④ 帧。

做完第 1 条回头看第十六节沙盘：把 policy 切成 fixed-xmx、limit 切成 512m，两处的结论应该能互相对上。

给自己做一个「一键可复现环境 + 上线体检脚本」，要求别人拿到仓库后不需要问你任何问题就能跑起来。

需求：

• 一份 compose.yaml：包含 mysql（带 healthcheck 与初始化 SQL）、redis（命名卷持久化）、app（depends_on: condition: service_healthy）三个服务，全部显式声明内存限额
• app 的 Dockerfile 必须同时满足：多阶段、.dockerignore、layertools 四层 COPY、exec 形式入口、MaxRAMPercentage 而非 -Xmx、非 root 用户（USER app）
• 一个 Makefile，至少四个目标：make build（构建）、make up（拉起整套）、make smoke（curl 健康端点 + /hello，任一失败即退出码非 0）、make graceful-test（后台 docker stop -t 30，同时 docker logs -f 抓取关闭日志，断言里必须出现 Closing，否则报「信号没走到 JVM」并以非 0 退出）
• 一段 README 里的「内存预算表」：写出你选的百分比、堆大小、Metaspace、线程数 × -Xss、直接内存估算，以及它们相加为什么不超过限额

验收清单：① 全新机器上 make up && make smoke 全绿；② 故意把一个 Bean 的构造写成抛异常，make smoke 必须失败而不是挂住；③ make graceful-test 在 exec 形式下通过、把入口改成 shell 形式后必须失败（证明脚本真的能抓到回归）；④ docker images 里最终镜像不超过 300MB，且 docker inspect --format '{{.Os}}/{{.Architecture}}' 与部署目标一致；⑤ 说清「为什么 docker stop 之后 ExitCode 是 143 而不是 137」。