企业官网建设流程全解析

如果你的工作里经常和 Java 服务打交道，那 Dockerfile 几乎是绕不开的一关。这玩意儿看着简单，不就是把 JAR 包塞进镜像里跑起来吗？可真到自己写的时候，你会发现里头全是讲究：基础镜像挑哪个、JVM 参数怎么传、时区怎么处理、镜像怎么越打越小、启动脚本写不好容器一重启就挂……每一个细节都能让人折腾半天。

这篇文章我就把自己反复踩坑、反复优化后沉淀下来的 Dockerfile 编写思路和打包流程完整梳理一遍。从最基础的镜像构建讲起，到多阶段构建、JVM 适配、健康检查、日志收集、常见问题排查，一路说到可以直接拿来用的生产级配置。内容适合刚接触 Docker 的 Java 开发者，也适合那些已经在用 Docker 但想优化镜像体积和稳定性的团队。

1. 先从整体想清楚：Java 应用镜像到底要解决哪些问题

写 Dockerfile 之前，我建议你先别急着打开编辑器。花几分钟想清楚一个问题：我到底想让这个镜像做到什么程度？

很多人第一次写 Dockerfile 就是“能跑就行”，把 JAR 包 COPY 进去，ENTRYPOINT 写个java -jar就完事了。这种镜像在本地跑 demo 一点问题没有，可一旦上了生产环境，问题就一件接一件冒出来。

1.1 一个 Java 镜像的“及格线”和“优秀线”

我自己的经验是，Java 镜像可以分成三个层次：

第一层：能跑。JAR 包放进去，java -jar能启动，端口能通。这是大多数教程停留在的地方。

第二层：能稳定跑。解决了时区问题、JVM 内存识别问题、优雅停机问题、日志持久化问题。容器重启不会莫名其妙挂掉，内存不会被宿主机器杀进程，日志不会丢。

第三层：能高效跑。镜像体积小、构建速度快、安全漏洞少、可观测性好，包含完整的健康检查、监控指标暴露、非 root 用户运行等。

这篇文章的目标就是带你走到第三层。每一层需要做的事情不同，所用的 Dockerfile 写法也完全不同。后文的配置基本是按第二层和第三层的标准来组织的，你可以在理解之后按需裁剪。

1.2 使用 Docker 跑 Java 服务，和传统部署到底差在哪

在写 Dockerfile 之前，得先理解 Java 程序放在容器里和放在虚拟机/物理机上有什么区别。核心差异其实就两个：

差异一是运行环境的隔离粒度。传统部署里，Java 进程直接跑在操作系统上，它能看到完整的 CPU、内存、磁盘信息。容器里则不同，Java 进程跑在 CGroup 限制的环境中，如果 JVM 不能正确感知到 CGroup 的限额，就会出现一种很头疼的情况：JVM 启动时按宿主机内存来分配堆内存，结果容器内存限制只有 512MB，JVM 实际可能申请 2GB 堆，一运行起来就被内核 OOM Killer 干掉。

差异二是进程的生命周期管理。容器编排平台（比如 K8s）是靠探针来管理容器生命周期的，容器里只能跑一个主进程。这意味着你的 Java 应用需要正确处理 SIGTERM 信号，做到优雅停机。传统部署里你可能从不关心进程退出信号，但在容器里这就是必须面对的事。

这两个差异直接决定了一个好的 Java Dockerfile 应该长什么样：不是简单“把 JAR 放进去”，而是要把 JVM 和容器环境之间的适配工作做完整。

2. 从零编写 Dockerfile：单阶段构建，先把地基打牢

学习阶段先从最直观的单阶段 Dockerfile 入手。虽然它构建出来的镜像很大，但它能帮你理解最基本的工作原理，后面再逐步优化。

2.1 第一个可运行的 Dockerfile 长什么样

假设你有一个 Spring Boot 项目，构建产物是app.jar，在target/目录下。最原始的 Dockerfile 大概是这样的：

FROM openjdk:8-jdk-alpine MAINTAINER yourname COPY target/app.jar /app.jar ENTRYPOINT ["java", "-jar", "/app.jar"]

这段配置就能跑，但问题也是肉眼可见的。openjdk:8-jdk-alpine镜像里包含完整 JDK，不仅有运行环境，还有编译器、调试器这些运行时用不到的东西，最终镜像体积动辄两三百兆。另外它默认时区是 UTC，中国用户跑起来日志时间差 8 个小时。再有就是没有暴露端口，没有配置 JVM 参数，没有健康检查机制。

2.2 关键指令逐一拆解：不要只照着抄

要把 Dockerfile 写明白，几个核心指令的语义必须掌握扎实。

FROM 指令是每一层的基础。选择基础镜像时要想清楚你是要 JDK 还是 JRE。运行时只需要 JRE，体积能小很多。编译时才需要 JDK，这一点正是后面多阶段构建的核心逻辑。

COPY 和 ADD 的区别值得认真理解。COPY 只做本地文件到镜像的拷贝，ADD 则在拷贝之外额外支持从 URL 下载和解压 tar 包。这种额外的能力带来了两个问题：一是行为不容易预测，二是镜像层会变大。所以官方推荐能用 COPY 就别用 ADD。

ENTRYPOINT 和 CMD 的区别是面试常客，也是实际写 Dockerfile 最容易搞混的地方。简单说，ENTRYPOINT 定义的是容器启动后执行的程序，docker run 后面的参数会作为参数传给 ENTRYPOINT；CMD 则提供默认参数，可以被 docker run 传入的命令覆盖。一个常见套路是：ENTRYPOINT 用 exec 形式写脚本，脚本里做环境变量预处理，最后用exec启动 Java 进程，这样能保证信号正确传递。

2.3 给 JVM 设置内存参数的正确姿势

容器里跑 Java，JVM 参数必须显式声明。我见过不少人直接在 Dockerfile 里写死-Xmx512m，其实更好的做法是借助环境变量动态配置。在 Dockerfile 里做一个默认值，运行时再覆盖：

ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 -XX:InitialRAMPercentage=50.0" ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar /app.jar"]

用-XX:MaxRAMPercentage=75.0而不是-Xmx指定固定值，好处在于容器内存调大调小时 JVM 会自动跟随。比如容器限制 2GB，JVM 堆就约 1.5GB；改成 1GB，JVM 堆就约 768MB，不用改任何配置重新发布。

如果你非要用固定值，也强烈建议通过环境变量而非 Dockerfile 写死：

ENV JAVA_OPTS="-Xmx512m -Xms256m"

然后运行时这样覆盖：

docker run -e JAVA_OPTS="-Xmx1g" ...

这种做法在需要临时调优时特别实用，不用重新构建镜像，改个环境变量就能重启验证。

3. 镜像瘦身的关键手段：多阶段构建

单阶段构建最大的问题，是把编译和运行环境混在一起。你想想，编译一个 Java 项目需要 Maven、JDK、全部依赖下载；但运行时真的只需要 JRE 和一个 JAR 包。把两者分开，就是多阶段构建的核心思路。

3.1 多阶段构建的结构与原理

多阶段构建允许一个 Dockerfile 里出现多个 FROM。每段 FROM 是一个独立的构建阶段，前面的阶段可以拥有完整的开发工具链，最后那个阶段只保留运行所需的最小环境。中间阶段的文件可以通过 COPY --from 指令拷贝到最终镜像。

比如这样：

# 第一阶段：编译 FROM maven:3.8-openjdk-11 AS builder WORKDIR /build COPY pom.xml . RUN mvn dependency:go-offline COPY src/ ./src/ RUN mvn clean package -DskipTests # 第二阶段：运行 FROM openjdk:11-jre-slim WORKDIR /app COPY --from=builder /build/target/app.jar ./app.jar EXPOSE 8080

第一阶段用 Maven 镜像完成代码编译和打包，第二阶段只把 JAR 文件拷过去，运行时镜像里完全没有 Maven 和 JDK 源码相关的无用文件。单阶段镜像可能 400MB，多阶段构建往往能压到 200MB 以下。

3.2 利用构建缓存加速打包

很多人写多阶段 Dockerfile 碰到一个问题：每次改一行 Java 代码，Maven 都要重新下载全部依赖，构建慢到怀疑人生。其实这是没有正确利用层缓存导致的。

Docker 构建时，每一行指令如果前后没有变化，就会复用本地缓存。依赖下载逻辑和源码打包逻辑如果写在同一行，那源码一变，依赖也得重新下。正确做法是把两件事分离：

COPY pom.xml . RUN mvn dependency:go-offline COPY src/ ./src/ RUN mvn clean package -DskipTests

第一行的COPY pom.xml .只拷贝 POM 文件，然后单独执行依赖下载。只要 POM 不变，这一层就不会失效，后面三层直接复用缓存。我实测过，项目几百个依赖，有缓存的情况下构建只要十几秒，没缓存要拉好几分钟。

这里有个小细节，mvn dependency:go-offline并不是所有插件都能覆盖，有的插件在后续打包阶段还会在线下载。稳妥起见可以加一个-Dmaven.repo.local指定本地仓库路径，或者使用mvn package后直接保留~/.m2目录作为缓存挂载。生产环境如果用 CI 平台（比如某公司的流水线），也可以设置 Docker BuildKit 的 cache mount：

RUN --mount=type=cache,target=/root/.m2 mvn clean package -DskipTests

这种方式比单独分层更高效，因为它不把依赖打进镜像层，而是直接复用宿主机的缓存目录，速度更快。

3.3 选择基础镜像的思路

Java 相关的基础镜像，市面上主要见这几类：

• openjdk:8-jdk-alpine：基于 Alpine Linux，体积小，但 Alpine 使用的 musl libc 在某些极端情况下会有兼容问题（比如一些原生库）。
• openjdk:11-jre-slim：基于 Debian Slim，体积适中，兼容性比 Alpine 好。
• eclipse-temurin：提供了 OpenJDK 的多种构建版本，社区活跃，也是目前很多新项目的首选。
• amazoncorretto：某云厂商维护的 OpenJDK 发行版，长期支持，性能调优到位。
• 自定义基础镜像：公司内部统一维护基础 JDK 镜像，预置了证书、时区、监控 agent 等，适合规模化团队。

我的建议是：追求最小体积可用 Alpine，追求兼容性和稳定性用 Slim 系列。JDK 版本建议跟本地开发环境保持一致，或者略高于生产要求的版本，避免本地编译出来的 class 在运行时因版本过低而报UnsupportedClassVersionError。

4. Java 应用容器化适配：JVM 参数、时区、健康检查

这一部分是最容易被忽略、但影响最大的环节。很多人镜像能跑，但运行一段时间就出各种奇奇怪怪的问题，多数都出在这几个点上。

4.1 JVM 与 CGroup 内存限制

Java 8 及以前版本默认不会自动识别 CGroup 限制，JVM 按宿主机的内存来设置堆大小，一超过容器内存限制就会被内核杀进程。这个问题在高版本 JDK 中已有改善，但低版本依然存在。

JVM 参数里推荐使用百分比配置：

为什么不直接写-Xmx？因为-Xmx是绝对值。容器内存从 2GB 扩容到 4GB，JVM 堆不会跟着变。虽然 Kubernetes 可以重启容器生效，但每次配置变更都要走一次发布流程，远不如百分比灵活。

还有一点值得注意：堆内存不是 JVM 的全部内存。JVM 还包含元空间、线程栈、直接内存、JIT 编译器、GC 相关结构等。即使设了MaxRAMPercentage=75.0，实际进程占用也可能超过容器限制，所以这个比例不宜设得太高。我习惯用 75% 作为大值，但如果你有较多堆外内存使用（比如 Netty 的 direct buffer），建议下调到 50%-60%。

4.2 时区问题：为什么你看到的日志时间总差 8 小时

Java 默认时区跟随系统。很多基础镜像的默认时区是 UTC，这在部署到国内服务器时非常折磨人：应用日志时间全是 UTC，和运维平台、监控告警、数据库记录的时间对不上。

最稳妥的办法是在 Dockerfile 里直接设置系统时区：

ENV TZ=Asia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

Alpine 镜像需要先安装 tzdata 才能设置时区：

RUN apk add --no-cache tzdata \ && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo "Asia/Shanghai" > /etc/timezone

构建时写好时区，运行时容器内 Java 进程的TimeZone.getDefault()就会正确返回东八区。也可以在启动时通过-Duser.timezone=Asia/Shanghai强制指定 JVM 时区，这个方法不依赖系统时区设置，在调试时特别有效。

4.3 容器健康检查：别等流量打到坏实例上才发现

Kubernetes 提供了 liveness 和 readiness 探针，但在没有 K8s 的环境里（比如 docker-compose 或裸 Docker），Docker 自身的 HEALTHCHECK 指令也能提供类似能力。

Spring Boot 自带 Actuator 模块，暴露了/actuator/health端点，这是最现成的健康检查依据。Dockerfile 里可以这样写：

HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \ CMD wget -q -O - http://localhost:8080/actuator/health || exit 1

各参数的含义：

• --interval=30s：每 30 秒检查一次。
• --timeout=5s：单次检查超过 5 秒视为失败。
• --start-period=60s：容器启动后 60 秒内不检查，给应用足够的时间完成启动。
• --retries=3：连续 3 次失败后，容器被标记为 unhealthy。

注意 Alpine 镜像里没有 wget，要改用 BusyBox 自带的 wget 命令或者安装 curl。Slim 系镜像则要看是否预置了相关工具。

HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \ CMD curl -fs http://localhost:8080/actuator/health || exit 1

如果走了网关链路，健康检查端点务必要绕过登录鉴权，否则探针返回 401，容器永远不健康。这类问题排查起来很隐蔽，我踩过一次，最后看容器日志才发现是鉴权拦截了 actuator 路径。

4.4 优雅停机与信号处理

Java 应用收到 SIGTERM 信号时会触发 Shutdown Hook，但这个行为依赖两个前提：信号是 SIGTERM 而不是 SIGKILL，且 JVM 进程是容器主进程。

如果用ENTRYPOINT ["java", "-jar", "/app.jar"]这种方式启动，Java 本身就是 PID 1，信号能被正确接收。但如果用了sh -c "java -jar app.jar"这种写法，sh 是 PID 1，Java 是子进程，信号到了 sh 这儿可能不会转发给 Java，导致 JVM 收不到停机信号，无法触发优雅停机。

正确写法是使用exec：

ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app.jar"]

同理，如果写启动脚本，脚本里一定要以exec形式启动 Java。这个细节我之前栽过跟头：Spring Boot 的优雅停机已经配置好了，但容器 kill 时应用还是直接退出，根本没走 Shutdown Hook，最后排查到根因就是启动脚本少了exec。

Spring Boot 还支持优雅停机配置，在application.yml里加上：

server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 20s

这样应用收到停机信号后，会等待正在处理的请求完成或超时后再退出，不会直接掐断连接。

5. 让镜像更实用：日志处理、安全加固与运维友好

镜像能跑、能稳定跑之后，就该考虑让它“更好用”了。这个阶段做的事情虽然不直接影响功能，但对日常运维和故障排查帮助极大。

5.1 日志处理：别让容器日志撑爆磁盘

容器里 Java 应用写日志的方式，直接决定了磁盘的使用情况。如果不做任何处理，应用的日志默认写到容器可写层，一旦容器被删除，日志全部丢失；如果应用的日志框架配置成按文件输出，不加以归档清理，长时间运行会占满磁盘。

容器化场景下最推荐的方式：日志走 stdout/stderr，交给 Docker 的日志驱动统一收集。Spring Boot 默认就是输出到 stdout 的，所以基本不用改什么。

Docker 默认的日志驱动是 json-file，会保留所有日志在本地。需要配置轮转限制，在 docker-compose 或 daemon.json 里设置：

logging: driver: json-file options: max-size: "100m" max-file: "3"

max-size设置单个日志文件的最大大小，超过则轮转；max-file设置保留的日志文件数。有了这两个配置，日志永远不会无限增长撑爆磁盘。

如果应用必须写日志文件，那就要挂载卷持久化，并在应用层面配置好 logback/log4j2 的滚动策略。日志文件和 stdout 双写，排查问题时确实方便，但日志量大了对性能有影响，自己要权衡。

5.2 非 root 用户运行容器

默认情况容器内以 root 身份运行 Java 进程。这是一个安全风险：万一应用被攻破，攻击者拿到的是 root 权限，宿主机如果挂载了目录，风险更大。

在 Docker 官方的最佳实践里，明确建议容器运行非 root 用户。具体做法是：

RUN groupadd -r app && useradd -r -g app app USER app

或者用镜像里自带的低权限用户，比如很多发行版自带nobody。我个人习惯创建专门的应用用户，这样日志目录、配置目录的权限控制更清晰。

Spring Boot 3 的 Fat Jar 在只读文件系统中也能运行（因为它把内部 JAR 解压到了临时目录），这也是它适合容器化的一个原因。非 root 用户需要注意临时目录的写权限，必要时挂载指定临时目录并设置-Djava.io.tmpdir=/tmp为该用户可写。

5.3 镜像元信息与暴露端口

Dockerfile 中 LABEL 可以为镜像添加元信息，比如版本、文档地址、维护者信息。这在镜像多了之后尤其有用，一看标签就知道这个镜像是谁打的、什么版本、对应什么服务。

LABEL org.opencontainers.image.title="订单服务" LABEL org.opencontainers.image.version="1.0.0" LABEL org.opencontainers.image.source="https://example.com/order-service"

EXPOSE 指令本身不发布端口，它只是声明容器内服务监听哪些端口，作为镜像使用者查看端口的文档依据。实际端口映射还是靠 docker run 的-p或 compose 里的 ports 配置。但写清楚 EXPOSE 是良好习惯，别人拿到镜像能快速知道该映射什么端口。

5.4 镜像体积再优化：JRE 精简与层合并

多阶段构建已经把镜身体积降了很多，但如果你的服务很多、存储和带宽成本敏感，还有几个手段可以再压缩。

手段一：使用 JRE 而不是完整 JDK。openjdk:11-jre-slim比openjdk:11-jdk-slim小很多。多阶段构建中的构建阶段用 JDK，运行阶段用 JRE 即可。注意某些需要动态编译或工具链支持的框架（比如 Java Agent、Groovy 动态编译）可能依赖 JDK 的某些类，这种情况只能继续用 JDK 镜像，要自己做验证。

手段二：合并 RUN 指令减少层数。每一条 RUN 指令都会生成一个新的镜像层，层数多了会浪费空间。把一系列操作合成一条 RUN 并清理临时文件：

RUN apt-get update \ && apt-get install -y --no-install-recommends curl \ && rm -rf /var/lib/apt/lists/*

注意 Docker 镜像层的机制：层与层之间是叠加关系，删除某个文件只是在上一层做一个 whiteout 标记，底层文件可能依然占用空间。所以在同一个 RUN 里安装再删除是最有效的，例如：

RUN apt-get update && apt-get install -y curl \ && curl -o app.jar https://... \ && apt-get purge -y curl \ && apt-get autoremove -y \ && rm -rf /var/lib/apt/lists/*

手段三：使用更小的基础镜像。Alpine 的镜像体积优势非常明显，但 musl libc 偶尔带来兼容性问题。使用前最好在本地完整跑一遍应用的测试用例，确认没有隐性问题。

5.5 给 JVM 开启监控与诊断能力

这部分是关于可观测性的建议。容器环境里看不到 jstack、jmap 的图形界面，调试问题全靠命令和监控数据。

生产环境建议至少做两件事：

第一，通过 JMX 暴露 JVM 指标。注意 JMX 远程连接不建议直接暴露公网，可以配合容器网络或者在 K8s 里通过 Sidecar 方式抓取指标。

ENV JAVA_TOOL_OPTIONS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9090 -Dcom.sun.management.jmxremote.rmi.port=9090 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"

第二，应用侧暴露监控端点。Spring Boot Actuator 的/actuator/prometheus配合 Prometheus 抓取，能把 JVM 内存、GC、线程数等指标全部接入监控体系，比 JMX 更便捷。这个端点也需要注意鉴权，防止敏感信息泄露。

如果应用发生 OutOfMemoryError，在 Dockerfile 里配置参数，让 JVM 在 OOM 时自动 dump 堆：

ENV JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/heap-dumps/"

然后给容器挂载一个卷存放 dump 文件，出问题时就能拿到完整的堆现场进行离线分析。这个参数我强烈建议保留，代价几乎为零，但在关键时刻能救整个团队于水火。

6. 一个完整的生产级 Dockerfile 模板

前面讲了那么多原理和注意事项，是时候给出一个可以直接复用的完整模板了。以 Spring Boot 2.7.x + JDK 11 为例。

6.1 全量模板与逐行解读

# 语法版本，建议显式声明，防止未来默认语法变化 # syntax=docker/dockerfile:1.4 # ========== 第一阶段：编译打包 ========== FROM maven:3.8-openjdk-11 AS builder WORKDIR /build # 先拷贝 pom.xml，利用 Docker 缓存加速依赖下载 COPY pom.xml . RUN --mount=type=cache,target=/root/.m2 mvn dependency:go-offline # 再拷贝源代码并打包 COPY src/ ./src/ RUN --mount=type=cache,target=/root/.m2 mvn clean package -DskipTests # ========== 第二阶段：最小运行环境 ========== FROM openjdk:11-jre-slim # 创建应用用户，避免 root 运行 RUN groupadd -r app && useradd -r -g app app # 设置时区 RUN ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo "Asia/Shanghai" > /etc/timezone WORKDIR /app # 从构建阶段拷贝 JAR 包 COPY --from=builder /build/target/app.jar ./app.jar # 如果还需要其他文件（比如配置文件、证书、字体等） # COPY --from=builder /build/target/classes/*.yml ./config/ # 暴露端口 EXPOSE 8080 # 健康检查 HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \ CMD curl -fs http://localhost:8080/actuator/health || exit 1 # JVM 参数通过环境变量注入，默认按容器内存百分比分配 ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 -XX:InitialRAMPercentage=40.0 -XX:+UseContainerSupport -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/heap-dumps/" # 切换用户 USER app # 启动命令，注意 exec + 环境变量展开 ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app.jar"]

这个模板里我把注释写得很细，你实际使用时把app.jar替换成你的打包产物名称，端口改成自己的服务端口，健康检查路径根据项目实际情况调整即可。

6.2 不同基线版本的适配要点

JDK 8 场景：基础镜像建议openjdk:8-jre-alpine或加入-XX:+UseCGroupMemoryLimitForHeap参数（JDK 8u191+ 可用），让 JVM 感知 CGroup 限制。再老一些的 8u131 前版本，只能手动指定-Xmx。JDK 8 移到eclipse-temurin:8-jre也是可行方案，维护更活跃。

JDK 11 场景：openjdk:11-jre-slim或eclipse-temurin:11-jre均可。JDK 11 默认启用容器感知，但建议显式添加-XX:+UseContainerSupport以保持行为明确。

JDK 17 场景：可以使用eclipse-temurin:17-jre或更小的17-jre-alpine。JDK 17 是当前很多新项目的选择，启动性能、GC 表现、容器适配都比之前版本好不少。

Spring Boot Fat Jar vs 解压 Jar：Fat Jar 的java -jar方式用起来简单，但启动时要把 JAR 里的所有内嵌包解压到临时目录，速度稍慢。如果对启动时间敏感，可以在构建阶段先解压：

RUN cd /build/target && java -Djarmode=layertools -jar app.jar extract COPY --from=builder /build/target/app/ /app/

Spring Boot 官方文档里把这种镜像称为分层镜像（Layered Jar），它的另一个好处是每一层可以独立利用 Docker 缓存，依赖层不变的话，镜像构建能省不少时间。

6.3 实战构建与运行验证

Dockerfile 写完后，构建镜像和运行容器验证的基本流程如下：

# 构建镜像，注意最后的上下文路径 docker build -t order-service:1.0.0 . # 运行容器，映射端口、设置内存限制、挂载日志目录 docker run -d --name order-service \ -p 8080:8080 \ -m 1024m \ -e JAVA_OPTS="-XX:MaxRAMPercentage=75.0" \ -v /data/logs:/logs \ order-service:1.0.0

进入容器里验证进程和环境：

docker exec -it order-service /bin/bash ps -ef java -version cat /etc/timezone jcmd <pid> VM.flags

jcmd是 JDK 自带的诊断工具，比jstack、jmap更全面。容器里如果只有 JRE 而没 JDK，部分诊断工具会缺失。生产环境镜像可以考虑加入较小的 JDK 构建，或者通过独立的方式连接 JMX 获取指标。

7. 常见问题与排查技巧实录

这一节专门用来记录那些你会反复遇到、且网上资料分散的坑。每一个都是我用真金白银的线上事故换来的经验，看到就是赚到。

7.1 镜像构建阶段的问题

问题 1：Maven 依赖反复下载，构建极慢

现象：每次构建都重新拉几万个小文件，几分钟起步。排查发现 pom.xml 和源码分开后仍然慢，查看构建缓存发现 COPY src/ 这一步基础镜像已变化，导致依赖缓存失效。解决办法是上--mount=type=cache,target=/root/.m2，对 Maven 依赖做宿主机级缓存，实测几百个依赖的项目全量构建从 8 分钟降到 40 秒。

问题 2：本地能打包，Docker 里打包却失败

常见原因有三：构建上下文里把 target/ 或 .git 目录也传进去了，体积大且可能包含敏感文件；网络不通导致依赖无法下载；容器里 Maven 版本和本地不一致导致某些插件行为不同。建议在项目根目录写一个.dockerignore：

target/ .git/ .gitignore *.iml .idea/

这个文件不仅加速构建上下文传输，也避免本地编译产物污染构建环境。

问题 3：docker build 时 COPY 找不到文件

排查思路：确认文件在构建上下文中（不是在 .dockerignore 里被排除），确认路径是相对于 Dockerfile 所在目录的，而不是相对于系统根目录。如果用了多阶段构建，确认 source 阶段的路径拼写是否正确。最有效的调试方式是在对应阶段临时加一行RUN ls -la看目录结构。

7.2 容器运行阶段的问题

问题 4：容器启动了但马上退出，看不到任何日志

先用docker logs <container>查看输出。如果是Error: Unable to access jarfile，多半是 COPY 路径不对。如果日志里没有内容，检查是不是启动脚本里用了后台启动方式（比如nohup ... &），Docker 要求前台进程占据主进程，后台方式会导致容器立即退出。

问题 5：应用莫名被 kill 掉，exit code 为 137

137 表示容器被 SIGKILL，通常是内存超限。检查方法：docker inspect <container>看OomKilled字段是否为 true，docker stats看内存趋势。解决办法：调整容器内存上限，下调堆比例，降低线程数，或者给 JVM 加上-XX:+ExitOnOutOfMemoryError让问题明确暴露而不是被直接杀进程。

问题 6：容器启动很慢，卡在某个阶段很久

大概率是 JVM 启动时熵不足，-Djava.security.egd=file:/dev/./urandom能加快 SecureRandom 初始化。我在容器化部署的时候固定会把这个参数加进 JAVA_OPTS，实测启动时间可以明显缩短。

问题 7：时区不对，日志时间差 8 小时

解决方案在前面已经讲过了，Dockerfile 里设置 TZ 环境变量或者/etc/localtime软链。还有一种更隐蔽的情况：宿主机的 /etc/localtime 是 UTC，容器挂载了宿主机时区文件，也会继承错误时区。所以设置时区时尽量在容器内独立设置，而不要依赖宿主机。

问题 8：健康检查总是不通过

关键排查链：确认健康端点路径正确，确认端口暴露正确，确认容器内能访问 localhost 端口（有些应用监听在 0.0.0.0 没问题，但监听在 127.0.0.1 可能导致容器外访问不到），确认没有鉴权拦截。最后用docker inspect的Health字段查看检查日志，比盲猜快得多。

7.3 安全与稳定性检查清单

这部分是给要上生产环境的团队的清单，我每发布一个 Java 服务镜像都会过一遍：

7.4 优化镜像体积的实测收益

用一个中等规模的 Spring Boot 项目做对照，结果很直观：

体积从 460MB 降到 150MB，传输和部署成本的下降非常明显。启动时间的差距主要来自 Fat Jar 的解压逻辑，Spring Boot 3 和分层技术的组合还能进一步优化。

8. 更进一步：面向 K8s 环境的镜像设计思路

如果你的服务最终是部署在 Kubernetes 集群里的，那 Dockerfile 的写法和裸 Docker 环境会有一些差异，这里单独讲几个关键点。

8.1 探针策略与健康检查的取舍

K8s 环境里可以使用 livenessProbe 和 readinessProbe，它们和 Docker HEALTHCHECK 的作用不同：

• readinessProbe：决定流量是否进入 Pod，失败时会从 Service 的 Endpoint 中摘除。
• livenessProbe：决定容器是否需要重启，失败时会杀掉容器重新拉起。

两者不能混为一谈。readinessProbe 应该用业务相关的就绪指标（比如数据库连接池初始化完成、缓存预热完成），livenessProbe 则用最基础的 JVM 存活判断（比如/actuator/health）。在 K8s 里一般不需要再写 Docker HEALTHCHECK，否则两个机制叠加可能产生非预期行为，比如容器状态 unhealthy 影响排查问题的直观性。

Spring Boot Actuator 的/actuator/health会汇总所有健康指标（DB、Redis、磁盘等），如果某个下游依赖不可用，这个端点就返回 DOWN，导致 readinessProbe 把 Pod 摘掉。有时候服务本身还能处理流量（比如缓存失效但能降级），却被探针判定为不健康，这就需要自定义健康指标分组，用单独的端点做探针判定。

8.2 镜像 tag 策略

生产环境不要使用latest作为部署 tag，这是所有容器化实践文档里反复强调的一点。镜像 tag 应该与版本号对应，推荐形如order-service:1.2.3或者带构建号的order-service:1.2.3-b12。在 CI/CD 流水线里，用 Git commit 的短 SHA 作为 tag 也是一种常见做法，优点是能精确对到代码版本。

多环境部署时，我习惯构建一次、到处运行：同一个镜像 tag 部署到测试、预发、生产，避免环境差异导致行为不一致。如果不同环境需要不同的配置，通过环境变量或配置中心注入，而不是重新构建镜像。

8.3 Init 容器与前置依赖处理

Java 服务经常有前置依赖（比如数据库、配置中心、注册中心）。如果这些依赖还没就绪，应用启动会报错退出。K8s 下可以用 Init 容器做依赖等待：

initContainers: - name: wait-for-db image: busybox:1.36 command: - sh - -c - |- until nc -z db-service 5432; do echo "waiting for db..." sleep 2 done

但要注意：这个方案等待的是 TCP 端口连通，不保证数据库真的完成了初始化。如果应用自身具备重连机制，其实不用 Init 容器，把等待逻辑放在应用启动阶段更健壮。Spring Boot 的spring.datasource.hikari.connection-timeout和initialization-fail-timeout可以配成超时重试，这就够了。

8.4 ConfigMap 与 Secret 注入配置

容器的配置注入，推荐用 K8s 的 ConfigMap 和 Secret 挂载到容器内，而不是把配置文件写进镜像。这样镜像本身是可复用的，配置差异由编排层管理。

apiVersion: v1 kind: ConfigMap metadata: name: order-service-config data: application.yml: | server: port: 8080 spring: profiles: active: prod --- apiVersion: apps/v1 kind: Deployment metadata: name: order-service spec: template: spec: containers: - name: order-service image: order-service:1.2.3 volumeMounts: - name: config mountPath: /app/config

应用启动时自动加载/app/config/application.yml（Spring Boot 默认会扫描/config目录），直接和本地开发保持一致的加载规则。

9. 回看一遍：几个让我少走弯路的经验

也许文章太长你已经忘了细节，最后再拎几个我觉得最值得记住的经验。

第一个是：容器里跑 Java，内存参数永远要比你以为的更严格。不管你是不是在云上，不管你设置了多大的容器内存，只要没有正确配置 JVM 的容器感知参数，总有一个深夜会让你从睡梦中被叫醒。

第二个是：启动命令一定要用 exec 形式。那个sh -c里漏掉的exec，就是容器优雅停机失效的直接原因。写 Dockerfile 的时候，ENTRYPOINT永远考虑用 exec 形式，需要环境变量展开时再用sh -c "exec ..."。

第三个是：镜像越小不只是省磁盘，更是省每次发布的时间。多阶段构建带来的好处不仅是体积，还有构建速度和可维护性。把编译和运行环境分离，思路简单，收益巨大。

第四个是：时区这个问题，应该在 Dockerfile 里解决，而不是在应用代码里写死。应用代码里加TimeZone.setDefault()属于打补丁，治标不治本。容器里设置好系统时区，应用不做任何时区特殊处理，行为才统一。

最后再分享一个小技巧：调试 Dockerfile 时，用docker build --progress=plain可以看到每一层执行的完整输出，比默认的交互式进度视图好用得多。遇到构建失败，直接定位到失败的那一行，配合临时加 RUN 命令查看环境状态，排查效率能翻倍。

这些经验是我断断续续踩了大半年坑才攒起来的。前面讲的那些模板和参数，建议你拿到真实项目里试试，多跑几个环境验证一下。等你自己把整套流程跑顺了，再来回看这篇文章，相信会有更深的理解。