1. 先写一条能跑的Dockerfile逐行拆给你看大概一年前帮一个朋友排查容器启动失败的问题。他的项目是常规的Spring Boot应用Dockerfile也照着网上的模板写了但容器就是起来以后立刻退出日志里只有一句话Unable to access jarfile app.jar。后来发现他把COPY target/demo.jar app.jar写在了WORKDIR /app之前而java -jar app.jar用的是相对路径JVM在工作目录里根本找不到那个jar包。这个问题很小却暴露了一个现实——很多Java开发者写Dockerfile靠的是复制粘贴而不是真正理解每一行在干什么。所以这篇文章我打算把Java程序打包成Docker镜像这件事从最简单的一条Dockerfile开始一路讲到多阶段构建、分层缓存、容器里的JVM参数、时区时区权限健康检查这些容易翻车的地方。每一条指令我都会说明为什么这么写而不是只给你一个能跑的模板。1.1 一条最小可用的Java镜像Dockerfile先看一条最基础、也最完整的写法这是所有Java项目镜像的起点FROM eclipse-temurin:17-jre WORKDIR /app COPY target/demo-0.0.1-SNAPSHOT.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]先解释一下这条Dockerfile的每一行。FROM eclipse-temurin:17-jre是基础镜像。为什么不用老的openjdk系列因为openjdk官方镜像在Java 17之后基本不再更新维护大家现在普遍使用Eclipse Temurin源自Adoptium项目的镜像。eclipse-temurin:17-jre只包含JRE运行环境体积比包含完整JDK的镜像小不少。如果你的程序是JDK 11就把17改成11如果是JDK 8可以找eclipse-temurin:8-jre这类标签不同基础镜像厂商的标签规则略有差异建议先去镜像仓库确认一下。WORKDIR /app是设置工作目录。它有两个作用一是后续的COPY、RUN、ENTRYPOINT都会默认在这个目录下执行二是容器启动后进程的工作目录也会是这里。建议每个项目都设置别省这一行否则你后面写路径时很容易出现文件在但就是找不到的问题。COPY target/demo-0.0.1-SNAPSHOT.jar app.jar是把构建好的jar包从宿主机复制到镜像的/app目录下并重命名为app.jar。注意源路径target/demo-0.0.1-SNAPSHOT.jar是相对于构建上下文context的不是相对于Dockerfile所在目录的——这个区别很多人会踩坑后面我会单独讲。EXPOSE 8080只是声明容器内的应用监听8080端口它不做什么实际操作纯粹是文档性质的。真正把端口映射到宿主机需要在docker run时加-p参数。ENTRYPOINT [java, -jar, app.jar]是容器启动时执行的命令。这里是exec form也就是JSON数组写法它不会额外启动一个shell进程而是直接以java进程作为容器的主进程PID 1。1.2 ENTRYPOINT与CMD的区别以及为什么让你用数组写法网上很多旧教程会写CMD java -jar app.jar或者ENTRYPOINT java -jar app.jar这两种写法是shell formDocker会把它包装成/bin/sh -c java -jar app.jar来执行。问题在于容器的主进程变成/bin/sh而你实际的Java程序变成了它的子进程。这在日常跑起来似乎没什么区别但当你执行docker stop时Docker会向PID 1发送SIGTERM信号。如果PID 1是shell它不一定会把这个信号转发给Java子进程结果就是Java进程收不到停止信号不能优雅停机只能等超时后被SIGKILL强杀。对于Spring Boot这类依赖优雅停机来释放数据库连接池、完成请求收尾的应用这个差异是致命的。另外还有一个很实际的原因shell form在执行时会做变量替换所以当你写ENTRYPOINT java $JAVA_OPTS -jar app.jar时$JAVA_OPTS会被shell解析但如果你写成ENTRYPOINT [java, $JAVA_OPTS, -jar, app.jar]$JAVA_OPTS不会被解析Docker会试图找一个名叫$JAVA_OPTS的文件直接报错。所以我的建议是固定不变的命令用exec form数组写法需要运行时注入环境变量的场景用ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar app.jar]这种显式shell包装既保留了变量替换又明确了意图。下表是这两种写法的对比写法示例是否启动shell能否做变量替换信号传递exec form[java, -jar, app.jar]否否直接PID 1是Javashell formjava -jar app.jar是是可能丢失PID 1是shell混合写法[sh, -c, java $JAVA_OPTS -jar app.jar]是是shell需自行保证2. 多阶段构建把编译环境和运行环境彻底分开很多人第一次写Java的Dockerfile会在镜像里装Maven或者Gradle然后RUN mvn package再CMD java -jar。这条链路本身没问题但它会带来两个实际问题镜像体积惊人以及构建产物、依赖、源码全部塞在一个镜像里安全性和可维护性都很差。2.1 为什么推荐多阶段构建多阶段构建的核心思想用一句话说就是编译阶段用一个包含完整工具链的镜像运行阶段只把编译好的jar包拷贝到一个小镜像里最终交付的镜像只包含运行所需的最小环境。# 第一阶段构建 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests # 第二阶段运行 FROM eclipse-temurin:17-jre WORKDIR /app COPY --frombuilder /build/target/demo-0.0.1-SNAPSHOT.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]第一阶段做了三件事先拷贝pom.xml然后执行mvn dependency:go-offline把依赖提前下载好最后拷贝源码并打包。注意mvn dependency:go-offline这一步的关键作用是为了配合Docker的层缓存机制我下一节细说。第二阶段从第一个阶段构建出的镜像中只把jar包拷贝过来然后以纯JRE镜像作为最终镜像。COPY --frombuilder就是从名为builder的构建阶段取文件。用这种方式最终镜像里只包含JRE和你的jar包不会带着一整套Maven仓库和源码。我实测过一个普通的Spring Boot项目如果不加多阶段构建镜像体积轻松超过500MB用多阶段构建通常在180MB左右。2.2 进一步裁剪用jlink生成最小运行时如果你的项目对镜像体积有执念或者需要部署到带宽受限、启动频繁的边缘环境可以考虑用jlink来裁剪JRE。jlink是JDK 9开始提供的工具它可以根据你实际用到的模块生成一个最小的自定义运行时镜像。FROM eclipse-temurin:17 AS jre-build WORKDIR /build COPY target/demo-0.0.1-SNAPSHOT.jar app.jar # 用jdeps分析jar包实际依赖的JDK模块 RUN jdeps --ignore-missing-deps --print-module-deps app.jar /tmp/modules.txt # 用jlink裁剪最小运行时 RUN jlink \ --add-modules $(cat /tmp/modules.txt) \ --strip-debug \ --no-man-pages \ --no-header-files \ --compress2 \ --output /custom-jre FROM debian:bookworm-slim WORKDIR /app COPY --fromjre-build /custom-jre /custom-jre COPY --fromjre-build /build/app.jar app.jar ENV PATH/custom-jre/bin:${PATH} EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]这里有几个细节值得注意。jdeps --print-module-deps会扫描jar包的字节码找出它真正依赖的JDK内置模块输出结果像java.base,java.logging,java.sql这样的模块列表。理论上如果程序只用到了一小部分JDK功能裁剪后的运行时体积可以降到40~60MB左右但前提是你的项目没有用到反射加载类、SPI等动态特性——这些场景下模块依赖分析可能不准运行时你就会收到ClassNotFoundException。另外我把自定义jre放到debian:bookworm-slim上而不是直接用temurin的jre镜像。这么做的好处是底包更干净、体积更小坏处是你需要自己维护时区数据和CA证书。对于大多数团队来说用temurin的jre镜像作为运行阶段就够了jlink裁剪属于进阶玩法不必一上来就追求极致。3. 镜像分层缓存先拷贝pom.xml而不是源码如果只是日常构建多阶段构建的写法已经够用了。但当你开始每天频繁出包、反复执行docker build时构建速度会成为一个真实的痛点。Docker的构建过程是分层的每一层都会尝试复用之前的缓存而缓存命中的关键在于你对COPY指令顺序的安排。3.1 Docker镜像分层的原理Docker镜像由一系列只读层堆叠而成。每一条RUN、COPY指令都会生成一个新的层。当你再次执行docker build时Docker会逐条检查指令如果指令本身没变且它依赖的上层也没有变化就会直接复用上次构建生成的层缓存而不是重新执行。这个机制很像代码版本管理里的增量编译唯一变化的那一层需要重做其他层全部复用。问题来了如果我把Dockerfile写成COPY src ./src RUN mvn package那么只要src目录下有任何文件发生变化COPY src这一层的缓存就会失效。紧接着RUN mvn package的输入变了缓存也失效于是Maven要把整个项目重新编译打包。哪怕你只是改了一个变量的值也要重新下载依赖虽然本地仓库可能还在但Docker层重建会带来额外开销、重新执行编译器。3.2 正确的依赖缓存姿势正确的思路是把变化的频率作为COPY顺序的排序依据最不容易变化的东西放在最前面最频繁变化的东西放在最后面。FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build # 最稳定的pom.xml COPY pom.xml . # 先拉取所有依赖这一层几乎不会失效 RUN mvn dependency:go-offline # 变化最频繁的源码 COPY src ./src RUN mvn package -DskipTestsmvn dependency:go-offline会把项目所需的外部依赖全部下载到本地仓库。只要你的pom.xml没有变化这一层缓存就会一直命中。之后你改Java代码、改配置文件都只需要重跑COPY src和RUN mvn package这两层免去了反复解析依赖、下载依赖的时间。我实际用下来一个中等规模的Spring Boot项目缓存命中后的增量构建只需要十几秒而完全重新构建可能要三分钟以上差距非常明显。注意mvn dependency:go-offline并不是Maven官方提供的标准生命周期目标而是maven-dependency-plugin插件提供的能力。它会把项目声明的依赖以及插件依赖都拉取到本地仓库。如果遇到个别插件无法通过这个命令完整拉取可以在构建镜像时额外执行一次RUN mvn package -DskipTests来补全但通常go-offline已经够用。3.3 别忘了.dockerignore还有一个和构建速度直接相关的文件.dockerignore。它的作用类似于.gitignore告诉Docker在构建时不要把某些文件发送到构建上下文。默认情况下docker build .会把当前目录下的所有文件除了被.dockerignore排除的都打包发送给Docker守护进程。如果你不做排除target/目录、node_modules/、.git/这些动辄几百MB的目录都会被上传严重拖慢构建。如果构建上下文里包含大量无关文件还可能因为体积膨胀导致构建超时。一份典型的Java项目.dockerignore长这样target/ .git/ .idea/ *.iml *.log Dockerfile .dockerignore注意如果Dockerfile本身对你最终的构建没有影响是可以排除的但如果你的Dockerfile里有用到COPY Dockerfile .这种操作就不要排除。.dockerignore里写的规则也支持*和**通配符需要更复杂的排除规则时可以参考官方文档。4. 容器里的JVM别再写死-Xmx512m了这个问题是我见过最多、也最容易被忽视的。很多Java开发者写Dockerfile习惯性地把JVM参数固化在启动命令里比如ENTRYPOINT [java, -Xmx512m, -jar, app.jar]。在物理机上这么做没什么问题但在容器环境里这可能导致严重的资源浪费甚至OOM。4.1 为什么-Xmx在容器里不安全容器的核心资源限制是cgroup提供的。docker run -m 2g给容器设定了2GB的内存上限但这并不意味着JVM能感知到。旧版本的JVM只读取宿主机的物理内存它按照宿主机内存来设置默认堆大小。举个例子你的宿主机有64GB内存容器限了2GB。如果不在启动时显式指定堆大小JVM默认会把堆大小设置成宿主机的四分之一也就是16GB。这已经超出了容器的2GB上限。当应用运行到内存峰值时进程会触发OOM而这个OOM可能不一定是Java堆OOM而是容器级别的OOM Killer直接把容器杀掉。反过来如果写死-Xmx512m在容器内存调整到4GB时JVM最多也只能用512MB造成了大量资源闲置。写死参数的另一个问题是你没办法在不重新构建镜像的情况下对不同环境做差异化调优。4.2 使用容器感知参数从JDK 8u131开始JVM对容器有了初步感知能力JDK 8u191之后-XX:UseContainerSupport默认开启JDK 10及以上版本默认就支持cgroup内存限制。所以如果你用的是现代JDK正确的做法是让JVM根据容器限制自动计算堆大小。推荐的做法是使用百分比参数ENV JAVA_OPTS-XX:MaxRAMPercentage75.0 -XX:InitialRAMPercentage50.0 -XX:MinRAMPercentage25.0 ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar app.jar]MaxRAMPercentage75.0表示JVM最多使用容器内存上限的75%。为什么要留25%因为堆之外还有元空间、线程栈、直接内存DirectByteBuffer、JVM自身开销以及可能的系统缓存。如果你的Spring Boot应用大量使用ByteBuffer或Netty还需要进一步降低这个比例。InitialRAMPercentage50.0和MinRAMPercentage25.0可以避免JVM启动时一次性申请过多内存也让堆可以根据负载动态扩展。当然如果你明确知道应用需要1GB堆也可以直接-Xmx1g——关键区别在于百分比参数让同一个镜像在不同规格的容器下都能自适应。4.3 别忘了保留诊断现场容器里的Java应用挂掉了最痛苦的事情是连日志都没留下。所以我建议在JAVA_OPTS里固定加这两个参数-XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/tmp/heapdump.hprof这样当Java抛出OOM时会自动把堆快照写到/tmp/heapdump.hprof方便事后用MAT或VisualVM分析。同时还可以加上-XX:ExitOnOutOfMemoryError让JVM在OOM时直接退出而不是继续半死不活地运行方便编排系统自动重启容器。这里补充一个排查技巧当容器还在运行但表现异常时用docker exec -it 容器名 jstat -gcutil 1 10可以直接在容器内查看GC情况不需要进入容器再安装东西。如果容器里没有jstatJRE镜像通常不带可以用jcmd或者直接看Spring Boot Actuator暴露的/actuator/metrics数据前提是你在应用里开启了对应端点。5. 三个容易翻车的细节时区、用户权限、健康检查前几节讲的是怎么把镜像构建出来这一节讲的是构建出来的镜像在真实生产环境里能不能站稳。我见过不少镜像在本地跑得欢一到服务器上就出各种幺蛾子问题往往都出在这些不容易注意的小细节上。5.1 时区问题日志时间少了8小时镜像里的默认时区通常是UTC而国内服务器的业务日志、定时任务都期望使用北京时间。如果你不在镜像里设置时区接到的第一个反馈必然是xx系统的日志时间不对差了8个小时。在Debian系的镜像temurin的jre镜像大多基于Ubuntu或Debian里可以这样设置ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone但如果你用的是Alpine系的基础镜像/usr/share/zoneinfo默认不存在需要先安装tzdataRUN apk add --no-cache tzdata \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ echo Asia/Shanghai /etc/timezone \ apk del tzdata注意最后把tzdata卸载掉是为了减小镜像体积但如果你后续还需要zoneinfo文件就别卸载否则时区又变回UTC。也可以在启动命令里通过-e TZAsia/Shanghai传入环境变量省去镜像内配置。但这样做的缺点是你的运行环境必须记住要带这个参数容易遗漏。我更建议直接在镜像里固化时区配置毕竟每个环境都加-e并不现实。5.2 别用root用户跑Java进程默认情况下容器内的进程是以root身份运行的。这带来两个问题镜像里任何一个漏洞被利用攻击者直接获得容器内的最高权限而容器内的root其实和宿主机root有剪不断理还乱的关系一旦发生挂载卷的权限问题宿主机上的文件权限也会被污染。你应该创建一个普通用户用它来运行应用FROM eclipse-temurin:17-jre RUN useradd -r -s /sbin/nologin -u 1001 appuser WORKDIR /app COPY --frombuilder /build/target/demo-0.0.1-SNAPSHOT.jar app.jar # 让appuser拥有应用目录 RUN chown -R appuser:appuser /app USER appuser EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]这里有两个细节。第一chown -R appuser:appuser /app不能省。因为COPY进来的文件默认所有者是root切换到appuser后如果应用需要写日志、写临时文件就会遇到权限不足。如果你的应用根本不写文件可以不chown但为了保险起见建议统一处理。第二EXPOSE 8080写在USER appuser之后没有影响因为EXPOSE不涉及文件操作。但如果你后续还需要安装依赖、修改文件这些操作必须在USER appuser之前完成因为非root用户对系统目录没有写权限。还有一个相关的点是不要在容器里用spring-boot-maven-plugin自动生成的可执行jar包跑java -jar时依赖/tmp做解压。Spring Boot可执行jar在启动时会把内部jar解压到临时目录而/tmp通常任何人都可写所以问题不大但如果你的基础镜像设置了严格的tmpfs挂载策略就要格外留意。5.3 HEALTHCHECK与容器生命周期容器编排系统比如Docker Swarm或Kubernetes需要一种方式来判断容器里的应用是不是真的活着。进程活着不代表应用可用——JVM进程还在但端口无响应、线程池打满这种情况并不罕见。Dockerfile里可以用HEALTHCHECK指令定义健康检查HEALTHCHECK --interval30s --timeout3s --start-period20s --retries3 \ CMD wget -q -O - http://localhost:8080/actuator/health || exit 1这个检查会每30秒执行一次启动后20秒才开始探活连续3次失败才判定为不健康。它调用的是Spring Boot Actuator的/actuator/health端点所以你的应用需要引入spring-boot-starter-actuator依赖。注意镜像里不一定有wget如果用的是裁剪过的小镜像可能只有curl或者两个都没有。我在实际使用中更倾向于用Java本身来做这个健康检查比如在JRE镜像里写一个很小的HealthCheck类不依赖外部命令。但你也可以接受镜像里自带一个wget或curl作为折中方案毕竟它们本身也是合法工具。还有一个常被忽略的问题优雅停机。docker stop会先发SIGTERMSpring Boot默认注册了shutdown hook会等待正在处理的请求完成后再退出。但如果你在Dockerfile里写了类似ENTRYPOINT java -jar app.jar 这种后台启动方式Docker的PID 1就不是Java而是shellstop信号会被shell吞掉导致容器只能等超时被强杀。所以请坚持用前文推荐的ENTRYPOINT风格不存在后台启动这个需求。6. 从构建到发布一条命令跑通完整流程前面讲的都是Dockerfile本身的内容这一节把视角拉高一点从构建命令、运行参数到常见报错串起一个完整的操作闭环。6.1 docker build与docker run的完整操作假设你的项目根目录下已经有了Dockerfile那么一次完整的构建和运行过程如下# 构建镜像 docker build -t demo-app:1.0 . # 查看镜像信息 docker images demo-app # 运行容器把宿主机8080映射到容器8080后台运行并设置JVM参数 docker run -d \ --name demo-app \ -p 8080:8080 \ -e JAVA_OPTS-XX:MaxRAMPercentage75.0 \ --memory1g \ demo-app:1.0 # 查看启动日志 docker logs -f demo-app # 进入容器检查运行状态 docker exec -it demo-app bash--memory1g给容器设内存上限配合MaxRAMPercentageJVM就能自动计算出合理的堆大小。如果你有多个环境需要不同的堆设置用-e JAVA_OPTS传入即可不需要为每个环境单独构建镜像。如果你在构建时需要指定平台比如在Apple Silicon上构建amd64的镜像加上平台参数docker build --platform linux/amd64 -t demo-app:1.0 .6.2 常见报错排查表我把实际中见过的高频报错整理成一份速查表报错现象常见原因解决办法COPY failed: no such file or directoryjar包路径不在构建上下文内或尚未执行Maven打包检查target/下有没有jar包把mvn package放到Dockerfile里或先在本机执行调整.dockerignoreexec: java: executable file not found in $PATH基础镜像里没有JRE或使用了非标准路径检查FROM是否选对了镜像标签不要在运行时去PATH里找不存在的命令容器启动即退出Unable to access jarfile拷贝路径和工作目录不匹配确认COPY的目标路径与ENTRYPOINT里的路径一致尽量使用绝对路径或统一依赖WORKDIR/bin/sh: 1: java: not found基础镜像缺少Java运行时确保运行阶段选用了jre镜像而不是纯操作系统镜像以appuser启动后报Permission denied应用需要写文件但目录属主为root在USER appuser之前chown应用目录或者把需要写的文件目录单独挂载并授权容器反复重启docker inspect显示OOMKilled为true内存上限设置过低或MaxRAMPercentage过高调大--memory或降低MaxRAMPercentage检查是否有堆外内存使用6.3 构建产物与镜像管理的小技巧构建完成之后还有几个日常运维经常用到的小操作。悬空镜像dangling image会随着多次构建越积越多它们是没有被任何容器引用、也没有被打标签的镜像层可以用下面命令清理docker image prune -f如果你想临时把某个镜像导出成tar包带走可以docker save demo-app:1.0 | gzip demo-app.tar.gz在另一台机器上导入docker load demo-app.tar.gz如果是推到私有仓库先打标签再推送docker tag demo-app:1.0 registry.example.com/demo-app:1.0 docker push registry.example.com/demo-app:1.07. 如果时间紧Jib和Buildpacks是备选方案最后说点个人经验。Dockerfile虽然很灵活但对于一个“只想把Spring Boot应用跑起来”的团队来说写Dockerfile本身还是有一定学习成本。如果你或者你的团队时间紧张有两条替代路径可以参考。一个是Google的Jib。它不需要Dockerfile也不需要你本地装Docker直接用Maven或Gradle插件把Java应用构建成镜像并推送到仓库。它的优势是构建过程与你已有的构建工具深度集成把“镜像构建”变成了“打包”这个动作的一部分。缺点是它不生成Dockerfile你失去了对镜像内容的精细控制——比如想在镜像里安装特定的调试工具用Jib就不太方便。另一个是Cloud Native Buildpacks。用pack build demo-app:1.0一条命令就能根据你的代码自动检测出这是一个Java项目生成一个包含完整运行环境的镜像。Buildpacks自动帮你处理了JVM参数、安全补丁、用户权限等大量细节适合标准化程度高、不希望维护Dockerfile的团队。但我的态度是这些工具可以救急不能成为你不学Dockerfile的理由。生产环境中总有一些场景需要你手动调整镜像——比如往里面加一个自定义的证书、改时区、处理特殊的启动参数。到时候你连Dockerfile都看不懂调试成本会非常高。就我个人而言现在写Java的Dockerfile已经形成了一套固定套路多阶段构建加temurin基础镜像pom.xml单独拷贝再go-offline运行阶段用jre镜像、非root用户、固定时区JVM参数走JAVA_OPTS并配合MaxRAMPercentage最后加一个健康检查。这套组合拳用下来无论是本地开发还是生产部署都很少再被容器问题绊住。