把一个 Spring Boot 4 + Spring AI 的 RAG 服务编译成了原生可执行文件,装进 Docker 镜像。镜像 131MB,空库启动 0.5 秒,挂着 48MB 向量库启动 3.1 秒。
整个过程不顺利:失效的镜像源、GraalVM Feature 报错、反射元数据缺失,三个坑各挡了一次路。这篇把环境准备、构建命令和每个坑的修法都记下来,命令全部实测过。
JVM 版启动要几秒,原生版 0.5 秒;常驻内存也明显更低,适合内存紧张的小机器。代价有三条:
产物体积供参考:可执行文件约 328MB(代码段 138.6MB、镜像堆 172.2MB、其他 17.3MB),压缩进镜像后 131MB。Tika 这类解析库会把所有解析器编进去,别指望镜像比 JVM 版小太多,换的是启动速度和内存。
需要 Docker(或兼容引擎)和一台内存足够的构建机。在 WSL2 里构建的话,先确认分到的内存:
bashfree -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 已经失效。镜像源寿命短,用之前先拉个小镜像试:
bashdocker 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 等三方库的反射元数据)。
编译阶段用 GraalVM 官方镜像,运行阶段只要 debian slim。关键约束:native-image 必须和 Maven 用的 JDK 同源同版本,所以从 Maven 镜像里只借 Maven 发行版,JDK 用 GraalVM 自带的:
dockerfileARG 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 参数覆盖:
bashdocker pull docker.m.daocloud.io/moby/buildkit:buildx-stable-1
bashdocker tag docker.m.daocloud.io/moby/buildkit:buildx-stable-1 moby/buildkit:buildx-stable-1
bashdocker 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 跨架构。
第一次编译在 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 源码,多数留了开关;没有开关的考虑排除依赖。
编译过了,启动 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 管不到,必须手写注册器:
javapublic 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 字面量,按名字注册:
javahints.reflection().registerType(SimpleVectorStore.class, categories);
hints.reflection().registerTypeIfPresent(classLoader,
"org.springframework.ai.vectorstore.SimpleVectorStoreContent", categories);
照着旧教程写会编译不过,两处已变(用 javap 对着 spring-core 7.0.9 核实):
ImportRuntimeHints 在 org.springframework.context.annotation,不再是 org.springframework.aot.hint.annotation。TypeHint.Builder 没有 onField(...),字段访问直接靠 MemberCategory.DECLARED_FIELDS。写 hints 前先 javap 本地依赖 jar 核 API,比信搜索引擎快照可靠。
镜像跑起来后按这个顺序冒烟,全部通过才算数:
/healthz 返回 UP。本次结果:空库启动 0.525 秒,挂 48MB 向量库 3.1 秒,登录、后台总览、会话列表、挂件匿名 token、检索、反射读分片全通。构建全程约 5 分钟一轮(依赖有缓存时),报错迭代成本不高,可以连着修。
启动速度和常驻内存是真实收益,小内存机器上尤其明显。但反射 hints 是按项目逐个补的,依赖越多清单越长,每次升级 Spring 或换库都可能要重新核对。服务长期跑、重启不频繁的话,JVM 版省心得多;需要频繁冷启动、或者内存只有几百 MB 的部署环境,native 才划算。
本文作者:Weee
本文链接:
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!