编辑
2026-11-19
学习记录
0

目录

Spring Boot 4 编译 GraalVM Native Image:Docker 构建实录
Native Image 换来什么,付出什么
环境准备
项目侧准备
Dockerfile:两阶段构建
国内构建命令
坑一:三方 jar 自带的 Feature 引用了不存在的类
坑二:record 序列化没有反射元数据
坑三:Spring 7 的 hints API 和旧文档不一样
验证
什么时候值得做

Spring Boot 4 编译 GraalVM Native Image:Docker 构建实录

把一个 Spring Boot 4 + Spring AI 的 RAG 服务编译成了原生可执行文件,装进 Docker 镜像。镜像 131MB,空库启动 0.5 秒,挂着 48MB 向量库启动 3.1 秒。

整个过程不顺利:失效的镜像源、GraalVM Feature 报错、反射元数据缺失,三个坑各挡了一次路。这篇把环境准备、构建命令和每个坑的修法都记下来,命令全部实测过。

Native Image 换来什么,付出什么

JVM 版启动要几秒,原生版 0.5 秒;常驻内存也明显更低,适合内存紧张的小机器。代价有三条:

  1. 构建吃内存。native-image 阶段要 6–10GB,构建机内存不够会直接 OOM。
  2. 构建慢。本次 14 线程编译了 4 分 25 秒,单核机器会更久。
  3. 反射要提前登记。JVM 上随手就用的反射、动态代理、record 序列化,native 里没登记就运行时报错。第三条是绝大多数失败的原因。

产物体积供参考:可执行文件约 328MB(代码段 138.6MB、镜像堆 172.2MB、其他 17.3MB),压缩进镜像后 131MB。Tika 这类解析库会把所有解析器编进去,别指望镜像比 JVM 版小太多,换的是启动速度和内存。

环境准备

需要 Docker(或兼容引擎)和一台内存足够的构建机。在 WSL2 里构建的话,先确认分到的内存:

bash
free -h

WSL2 默认只拿宿主机一半内存。total 不到 10GB 就在 Windows 侧建 C:\Users\<用户名>\.wslconfig:

ini
[wsl2] memory=10GB

然后 PowerShell 里 wsl --shutdown 重启生效。

网络上还有一个坑在拉镜像这一步:Docker Hub 直连超时。 国内直连基本不通,要走镜像源。2026 年 11 月实测还活着的:docker.m.daocloud.io、docker.1panel.live;不少教程里的 hub.rat.dev、dockerproxy.cn、dockerpull.org 已经失效。镜像源寿命短,用之前先拉个小镜像试:

bash
docker pull docker.m.daocloud.io/library/alpine:latest

项目侧准备

pom.xml 声明 native-maven-plugin,版本交给 spring-boot-starter-parent 管:

xml
<plugin> <groupId>org.graalvm.buildtools</groupId> <artifactId>native-maven-plugin</artifactId> <extensions>false</extensions> <configuration> <imageName>rag-agent</imageName> </configuration> </plugin>

extensions=false 有讲究:父 POM 默认把它当 build extension,一打开就会在普通构建里提前解析,离线构建 mvn -o test 直接失败。

-Pnative 不用自己写 profile,starter-parent 已经提供,会接上 process-aot(生成 AOT 代码)和 add-reachability-metadata(自动补 Tomcat、Reactor、Jackson 等三方库的反射元数据)。

Dockerfile:两阶段构建

编译阶段用 GraalVM 官方镜像,运行阶段只要 debian slim。关键约束:native-image 必须和 Maven 用的 JDK 同源同版本,所以从 Maven 镜像里只借 Maven 发行版,JDK 用 GraalVM 自带的:

dockerfile
ARG NATIVE_IMAGE=ghcr.io/graalvm/native-image-community:25 ARG MAVEN_IMAGE=maven:3.9-eclipse-temurin-25 ARG RUNTIME_IMAGE=debian:12-slim FROM ${MAVEN_IMAGE} AS maven FROM ${NATIVE_IMAGE} AS build COPY --from=maven /usr/share/maven /opt/maven ENV PATH=/opt/maven/bin:$PATH MAVEN_OPTS="-Xmx1g" WORKDIR /build COPY pom.xml ./ RUN mvn -B org.apache.maven.plugins:maven-dependency-plugin:3.8.1:go-offline || true COPY src ./src RUN mvn -B -Pnative -Dmaven.test.skip=true native:compile FROM ${RUNTIME_IMAGE} WORKDIR /app RUN apt-get update && apt-get install -y --no-install-recommends \ ca-certificates tzdata bash zlib1g passwd \ && rm -rf /var/lib/apt/lists/* COPY --from=build /build/target/rag-agent /app/rag-agent EXPOSE 8080 ENTRYPOINT ["/app/rag-agent"] CMD ["-Xmx256m"]

三个基础镜像地址都留成 ARG,国内构建时整体换前缀,不用改文件。依赖下载那步建议配阿里云 Maven 镜像(settings.xml 的 mirror 指到 maven.aliyun.com/repository/public),本次 95 秒下完全部依赖。

运行层有个和 JVM 镜像不同的点:native 二进制不读 JAVA_TOOL_OPTIONS,堆上限只能当启动参数传,所以写在 CMD 里,docker run 时可以覆盖。

国内构建命令

buildx 启动要先拉 moby/buildkit,Dockerfile 头部的 # syntax=docker/dockerfile:1 也要拉一个前端镜像,这两个都走 Docker Hub。前者先拉下来改回原名,后者用 BUILDKIT_SYNTAX 参数覆盖:

bash
docker pull docker.m.daocloud.io/moby/buildkit:buildx-stable-1
bash
docker tag docker.m.daocloud.io/moby/buildkit:buildx-stable-1 moby/buildkit:buildx-stable-1
bash
docker build -f Dockerfile.native -t rag-agent:native --progress=plain \ --build-arg BUILDKIT_SYNTAX=docker.m.daocloud.io/docker/dockerfile:1 \ --build-arg NATIVE_IMAGE=ghcr.m.daocloud.io/graalvm/native-image-community:25 \ --build-arg MAVEN_IMAGE=docker.m.daocloud.io/library/maven:3.9-eclipse-temurin-25 \ --build-arg RUNTIME_IMAGE=docker.m.daocloud.io/library/debian:12-slim .

ghcr.io 的前缀是 ghcr.m.daocloud.io,和 Docker Hub 的不是同一个。只能在本机架构上编,不要用 buildx + QEMU 跨架构。

坑一:三方 jar 自带的 Feature 引用了不存在的类

第一次编译在 35 秒处中止:

Error: Feature defined by org.eclipse.angus.activation.nativeimage.AngusActivationFeature unexpectedly failed with a(n) java.lang.NoClassDefFoundError. Caused by: java.lang.NoClassDefFoundError: jakarta/mail/Part

依赖链是 Tika → jaxb-runtime → jaxb-core → angus-activation。最后这个 jar 在 META-INF/native-image/ 里注册了一个 Feature,编译时读 mailcap 文件登记的邮件处理类。项目不解析邮件,classpath 上没有 jakarta.mail,Feature 一跑就崩。

读它的源码发现留了官方开关,在 pom 的 buildArgs 里加一条(-J 把系统属性传给 native-image 构建器进程):

xml
<buildArgs> <buildArg>-J-Dangus.activation.native-image.enable=false</buildArg> </buildArgs>

这类问题的通用思路:报错点名哪个 Feature,就去那个 jar 里找 META-INF/native-image/*.properties 和 Feature 源码,多数留了开关;没有开关的考虑排除依赖。

坑二:record 序列化没有反射元数据

编译过了,启动 0.5 秒也正常,第一次落盘就崩:

No serializer found for class ...UserStore$Account and no properties discovered to create BeanSerializer ... This appears to be a native image, in which case you may need to configure reflection for the class that is to be serialized

JVM 上 Jackson 靠运行时反射发现 record 组件;native 是封闭世界,编译期没登记的反射不存在。Spring AOT 会给自己管理的 Jackson bean 推导 hints,但这个项目各处用的是 new ObjectMapper(),AOT 管不到,必须手写注册器:

java
public class NativeHints implements RuntimeHintsRegistrar { @Override public void registerHints(RuntimeHints hints, ClassLoader classLoader) { MemberCategory[] categories = { MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS, MemberCategory.INVOKE_PUBLIC_METHODS, MemberCategory.INVOKE_DECLARED_CONSTRUCTORS, MemberCategory.DECLARED_FIELDS }; hints.reflection().registerType(UserStore.Account.class, categories); // 每个被 Jackson 读写的 record 都要一行 } }

再挂到任意 @Configuration 上:

java
@Configuration @ImportRuntimeHints(NativeHints.class) public class RagConfig { ... }

清单要覆盖三类:HTTP 请求/响应 DTO、落盘读写的 record、controller 内嵌的响应 record。第三类最容易漏——本次补完 DTO 后登录接口又报 Record components not available for record class ...LoginResponse,就是 controller 里定义的 record 没进清单。

还有一处特殊反射:项目用 getDeclaredField("store") 读 Spring AI SimpleVectorStore 的内部表,字段和包级私有的值类型都要登记,后者拿不到 Class 字面量,按名字注册:

java
hints.reflection().registerType(SimpleVectorStore.class, categories); hints.reflection().registerTypeIfPresent(classLoader, "org.springframework.ai.vectorstore.SimpleVectorStoreContent", categories);

坑三:Spring 7 的 hints API 和旧文档不一样

照着旧教程写会编译不过,两处已变(用 javap 对着 spring-core 7.0.9 核实):

  1. ImportRuntimeHints 在 org.springframework.context.annotation,不再是 org.springframework.aot.hint.annotation。
  2. TypeHint.Builder 没有 onField(...),字段访问直接靠 MemberCategory.DECLARED_FIELDS。

写 hints 前先 javap 本地依赖 jar 核 API,比信搜索引擎快照可靠。

验证

镜像跑起来后按这个顺序冒烟,全部通过才算数:

  1. /healthz 返回 UP。
  2. 登录拿 token,带 token 打一个需要鉴权的接口。
  3. 挂载真实数据重启,确认加载计数正确(本次 326 来源 / 3361 分片)。
  4. 走一条用到反射的读路径(本次是后台查看分片)。
  5. 最后才是真实模型调用和写入落盘——反射问题大多藏在写路径里,只读冒烟不够。

本次结果:空库启动 0.525 秒,挂 48MB 向量库 3.1 秒,登录、后台总览、会话列表、挂件匿名 token、检索、反射读分片全通。构建全程约 5 分钟一轮(依赖有缓存时),报错迭代成本不高,可以连着修。

什么时候值得做

启动速度和常驻内存是真实收益,小内存机器上尤其明显。但反射 hints 是按项目逐个补的,依赖越多清单越长,每次升级 Spring 或换库都可能要重新核对。服务长期跑、重启不频繁的话,JVM 版省心得多;需要频繁冷启动、或者内存只有几百 MB 的部署环境,native 才划算。

本文作者:Weee

本文链接:

版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!