【quarkus系列】构建可执行文件native image

序言

为什么选择 Quarkus Native Image？

性能优势

• 快速启动时间
  传统的 Java 应用运行在 JVM（Java Virtual Machine）上，启动时需要进行类加载、字节码解释和 JIT（Just-In-Time）编译等一系列过程，这些过程会导致启动时间较长。而 Quarkus 的 Native Image 使用 GraalVM 进行本地编译，直接将 Java 应用编译成机器码。这样，在应用启动时，几乎不需要任何额外的初始化步骤，启动时间可以快一个数量级。
  例如，传统的 Java 应用可能需要几秒钟甚至更长时间才能完全启动，而使用 Quarkus Native Image 的应用通常在几十毫秒内即可启动。这对于需要快速响应和弹性扩展的场景（如微服务架构和无服务器架构）尤为重要。
• 低内存占用
  由于 Quarkus Native Image 在编译时进行了一系列优化，包括去除未使用的代码和优化内存布局，生成的本地二进制文件的内存占用显著减少。这种优化不仅减少了运行时的内存消耗，还降低了垃圾回收的频率和开销。
  对于在云环境中运行的应用，这种内存占用的减少意味着可以在相同的硬件资源上运行更多的实例，提升了资源利用率和性价比。

便捷的云原生部署

• 轻量级容器
  传统的 Java 应用在容器化部署时，需要包含完整的 JVM 环境，这会增加容器镜像的大小。而 Quarkus Native Image 生成的二进制文件不依赖 JVM，可以显著减小容器镜像的体积。例如，一个传统的 Java 应用的容器镜像可能有几百 MB，而使用 Quarkus Native Image 的镜像可能只有几十 MB。

这种轻量级容器的优势在于：
1、更快的镜像拉取：在部署和扩展应用时，镜像的拉取速度更快，减少了启动时间。
2、更低的存储成本：减小了存储镜像所需的空间，节省了存储成本。

• Kubernetes 集成
  Quarkus 天生为 Kubernetes 设计，提供了很多开箱即用的特性，简化了在 Kubernetes 环境中的部署和管理。例如：
  1、自动生成 Kubernetes 资源配置：通过 Quarkus 的扩展，可以自动生成 Deployment、Service 等 Kubernetes 资源配置，减少了手动配置的工作量。
  2、与 Kubernetes 原生工具集成：Quarkus 提供了与 Kubernetes 原生工具（如 Helm 和 OpenShift）的集成，方便应用的打包、部署和管理。
  3、健康检查和监控：Quarkus 提供了内置的健康检查、指标收集和分布式跟踪支持，方便在 Kubernetes 环境中进行应用的监控和管理。

搭建项目

之前的文章，按照官网指南构建第一个quarkus项目，并启动运行。
【quarkus系列】创建quarkus第一个应用程序

这篇文章，我们开始学习如何本地构建quarkus可执行文件。

官网指南中，本地开发环境需要满足以下条件：

1、按照JDK17+版本；

2、本地有docker环境；

接着上篇文章中的开发代码继续开发：

关于构建成native本地文件核心配置pom.xml

<profiles><profile><id>native</id><activation><property><name>native</name></property></activation><properties><skipITs>false</skipITs><quarkus.native.enabled>true</quarkus.native.enabled></properties></profile>
</profiles>

默认构建会执行native文件；

其次或者使用命令行 -Dquarkus.native.enabled=true 作为属性传递

构建可执行文件

官网指南给出多种构建方式，优先介绍常用的方式：

方式一：配置GraalVM

方式一：（推荐使用方式二）

安装并配置GraalVM,官网链接https://quarkus.io/guides/building-native-image#configuring-graalvm

如图：

• 运行命令

./mvnw install -Dnative

如果使用该命令，没有配置GraalVM,执行报错如下：

[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.quarkus.platform:quarkus-maven-plugin:2.13.3.Final:build (default) on project getting-started: Failed to build quarkus application: io.quarkus.builder.BuildException: Build failure: Build failed due to errors
[ERROR]         [error]: Build step io.quarkus.deployment.pkg.steps.NativeImageBuildStep#build threw an exception: java.lang.RuntimeException: Cannot find the `native-image` in the GRAALVM_HOME, JAVA_HOME and System PATH. Install it using `gu install native-image`
[ERROR]         at io.quarkus.deployment.pkg.steps.NativeImageBuildStep.getNativeImageBuildRunner(NativeImageBuildStep.java:314)
[ERROR]         at io.quarkus.deployment.pkg.steps.NativeImageBuildStep.build(NativeImageBuildStep.java:212)
[ERROR]         at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
[ERROR]         at java.base/java.lang.reflect.Method.invoke(Method.java:580)
[ERROR]         at io.quarkus.deployment.ExtensionLoader$3.execute(ExtensionLoader.java:909)
[ERROR]         at io.quarkus.builder.BuildContext.run(BuildContext.java:281)
[ERROR]         at org.jboss.threads.ContextHandler$1.runWith(ContextHandler.java:18)
[ERROR]         at org.jboss.threads.EnhancedQueueExecutor$Task.run(EnhancedQueueExecutor.java:2449)
[ERROR]         at org.jboss.threads.EnhancedQueueExecutor$ThreadBody.run(EnhancedQueueExecutor.java:1478)
[ERROR]         at java.base/java.lang.Thread.run(Thread.java:1583)

方式二：容器运行

相对于方式一，更推荐使用方式二开发，无需配置以上环境变量，直接启动docker即可；

必要条件，确保有一个有效的容器运行时（Docker、podman）环境

首先将本地服务器docker启动；

• 构建可执行命令：

./mvnw install -Dnative -DskipTests -Dquarkus.native.container-build=true

• 显示选择运行时容器

官方也可以显式选择容器运行，命令如下：

此处我们仍然选择使用docker

./mvnw install -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=docker

• 优化构建命令
  使用命令构建不方便，也可以将其设置在application.properties
  quarkus.native.container-build=true

运行命令：./mvnw install -Dnative -DskipTests即可

错误示例

如果docker未启动，则报错如图：

日志中很明显，提示需要运行docker

构建过程分析

• docker启动之后，开始pull image ,如图：
  
• docker同时会启动构建native镜像的容器，如图：
  
• 构建完成之后，本地项目会生成可执行文件，如图：
  

创建docker镜像

基于可执行文件命令式构建

构建命令

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.container-image.build=true

控制台日志：

Finished generating 'getting-started-1.0.0-SNAPSHOT-runner' in 3m 14s.
[INFO] [io.quarkus.deployment.pkg.steps.NativeImageBuildRunner] docker run --env LANG=C --rm -v /quarkus-projects/getting-started/target/getting-started-1.0.0-SNAPSHOT-native-image-source-jar:/project:z --entrypoint /bin/bash quay.io/quarkus/ubi-quarkus-native-image:22.2-java17 -c objcopy --strip-debug getting-started-1.0.0-SNAPSHOT-runner
[INFO] [io.quarkus.deployment.QuarkusAugmentor] Quarkus augmentation completed in 218135ms
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  03:43 min
[INFO] Finished at: 2024-05-13T18:47:06+08:00
[INFO] ------------------------------------------------------------------------

从控制台中可以看到，已经完成docker镜像的创建以及镜像标签：22.2-java17

输入docker images查看镜像是否生成

基于dockerfile构建

方式一：构建micro base image

Micro base image 通常是指极度精简的基础镜像，这类镜像仅包含运行应用所需的最基本的依赖和工具，去除了所有不必要的部分。
特点:
1、极小的体积：micro base image 的目标是将镜像体积降到最低，以便快速传输和启动。
2、最小依赖：只包含运行应用所需的最基本的库和工具，通常没有包管理器、shell 等组件。
3、安全性：由于镜像内的组件极少，减少了攻击面，提高了安全性。
4、性能：更小的镜像体积和更少的组件有助于快速启动和高效运行。

路径src/main/docker，文件名Dockerfile.native-micro

内容如下：

FROM quay.io/quarkus/quarkus-micro-image:2.0
WORKDIR /work/
COPY target/*-runner /work/application
RUN chmod 775 /work
EXPOSE 8080
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

与命令同理，一样需要依赖本机的可执行文件，故不能删除可执行文件

可以使用以下命令生成 docker 映像：

docker build -f src/main/docker/Dockerfile.native-micro -t quarkus-quickstart/getting-started .

运行镜像命令

docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started

方式二：构建minimal base image

Minimal base image 通常指的是精简但仍保留了一些基础工具和库的镜像，这类镜像比 micro base image 体积稍大，但更易用。

特点
1、较小的体积：相比完整的操作系统镜像，minimal base image 体积较小，但比 micro base image 略大。
2、基本工具和库：包含一些常用的工具和库，如包管理器、shell、调试工具等，方便开发和调试。
3、较高的灵活性：在保持精简的同时，提供了一定的灵活性和便利性，适合大多数应用场景。
4、易用性：提供了更多的基础设施支持，易于使用和配置。
路径：src/main/docker，文件名Dockerfile.native

内容如下：

FROM registry.access.redhat.com/ubi8/ubi-minimal:8.9
WORKDIR /work/
RUN chown 1001 /work \&& chmod "g+rwX" /work \&& chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/applicationEXPOSE 8080
USER 1001CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

以上两种方式，均需要本地生成native可执行文件，故如果本地可执行文件删除，则需要先执行命令:./mvnw install -Dnative -DskipTests

方式三：使用dockerfile多阶段构建

使用dockerfile直接在容器中生成本机可执行文件，同时完成镜像的构建;

第一阶段使用 Maven 或 Gradle 构建本机可执行文件;

第二阶段是复制生成的本机可执行文件的最小映像;

Dockerfile

## Stage 1 : build with maven builder image with native capabilities
FROM quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 AS build
COPY --chown=quarkus:quarkus mvnw /code/mvnw
COPY --chown=quarkus:quarkus .mvn /code/.mvn
COPY --chown=quarkus:quarkus pom.xml /code/
USER quarkus
WORKDIR /code
RUN ./mvnw -B org.apache.maven.plugins:maven-dependency-plugin:3.1.2:go-offline
COPY src /code/src
RUN ./mvnw package -Dnative## Stage 2 : create the docker final image
FROM quay.io/quarkus/quarkus-micro-image:2.0
WORKDIR /work/
COPY --from=build /code/target/*-runner /work/application# set up permissions for user `1001`
RUN chmod 775 /work /work/application \&& chown -R 1001 /work \&& chmod -R "g+rwX" /work \&& chown -R 1001:root /workEXPOSE 8080
USER 1001CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

同理将dockerfile文件，路径src/main/docker/Dockerfile.multistage.

构建镜像命令

docker build -f src/main/docker/Dockerfile.multistage -t quarkus-quickstart/getting-started .

运行命令

docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started