复古 护眼 海天 深邃 暗黑 默认

构建 GraalVM Native Image(Alpha)

背景信息

本节主要介绍如何通过 GraalVMnative-image 组件构建 ShardingSphere-Proxy 的 Native Image 和对应的 Docker Image

注意事项

version: "3.8"

services:
  apache-shardingsphere-proxy-native:
    image: ghcr.io/apache/shardingsphere-proxy-native:latest
    volumes:
      - ./custom/conf:/opt/shardingsphere-proxy-native/conf
    ports:
      - "3307:3307"
  • 本节假定处于 Linux(amd64,aarch64),MacOS(amd64,aarch64/M1)或 Windows(amd64)环境。

  • 本节依然受到 ShardingSphere JDBC 一侧的 GraalVM Native Image 的已记录内容的限制。

前提条件

  1. 根据 https://www.graalvm.org/downloads/ 要求安装和配置 JDK 21 对应的 GraalVM Community EditionGraalVM Community Edition 的下游发行版。若使用 SDKMAN!
sdk install java 21.0.2-graalce
  1. 根据 https://www.graalvm.org/jdk21/reference-manual/native-image/#prerequisites 的要求安装本地工具链。

  2. 如果需要构建 Docker Image, 确保 docker-ce 已安装。

操作步骤

  1. 获取 Apache ShardingSphere Git Source
  1. 在命令行构建产物, 分两种情形。
  • 情形一:不需要使用存在 SPI 实现的 JAR 或第三方依赖的 JAR

  • 在 Git Source 同级目录下执行如下命令, 直接完成 Native Image 的构建。

./mvnw -am -pl distribution/proxy-native -B -T1C -Prelease.native -DskipTests clean package
  • 情形二:需要使用存在 SPI 实现的 JAR 或 GPL V2 等 LICENSE 的第三方依赖的 JAR。

  • distribution/proxy-native/pom.xmldependencies 加入存在 SPI 实现的 JAR 或第三方依赖的 JAR。示例如下


<dependencies>
  <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.1.0</version>
  </dependency>
</dependencies>
  • 通过命令行构建 GraalVM Native Image。
./mvnw -am -pl distribution/proxy-native -T1C -Prelease.native -DskipTests clean package
  1. 通过命令行启动 Native Image, 需要带上 4 个参数。 第一个参数为 ShardingSphere Proxy 使用的端口,第二个参数为你编写的包含 global.yaml/conf 文件夹, 第三个参数为绑定端口的 Address,第四个参数为 Force Start,如果为 true 则保证 ShardingSphere Proxy Native 无论能否连接都能正常启动。 假设已存在文件夹./custom/conf,示例为
./apache-shardingsphere-proxy-native 3307 ./custom/conf "0.0.0.0" false
  1. 如果需要构建 Docker Image, 在添加存在 SPI 实现的依赖或第三方依赖后, 在命令行执行如下命令。
./mvnw -am -pl distribution/proxy-native -T1C -Prelease.native,docker.native -DskipTests clean package
  • 假设存在包含global.yamlconf 文件夹为 ./custom/conf,可通过如下的 docker-compose.yml 文件启动 GraalVM Native Image 对应的 Docker Image。
version: "3.8"

services:
  apache-shardingsphere-proxy-native:
    image: apache/shardingsphere-proxy-native:latest
    volumes:
      - ./custom/conf:/opt/shardingsphere-proxy-native/conf
    ports:
      - "3307:3307"
  • 如果你不对 Git Source 做任何更改, 上文提及的命令将使用 oraclelinux:9-slim 作为 Base Docker Image。 但如果你希望使用 busybox:glicgcr.io/distroless/basescratch 等更小体积的 Docker Image 作为 Base Docker Image,你需要根据 https://www.graalvm.org/jdk21/reference-manual/native-image/guides/build-static-executables/ 的要求, 做为 pom.xmlnative profile 添加 -H:+StaticExecutableWithDynamicLibCjvmArgs 等操作。 另请注意,某些第三方依赖将需要在 Dockerfile 安装更多系统库,例如 libdl。 因此请确保根据你的使用情况调整 distribution/proxy-native 下的 pom.xmlDockerfile 的内容。

可观察性

针对 GraalVM Native Image 形态的 ShardingSphere Proxy,其提供的可观察性的能力与 https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/observability/ 并不一致。

你可以使用 https://www.graalvm.org/jdk21/tools/ 提供的一系列命令行工具或可视化工具观察 GraalVM Native Image 的内部行为, 并根据其要求使用 VSCode 完成调试工作。如果你正在使用 IntelliJ IDEA 并且希望调试生成的 GraalVM Native Image,你可以关注 https://blog.jetbrains.com/idea/2022/06/intellij-idea-2022-2-eap-5/#Experimental_GraalVM_Native_Debugger_for_Java 及其后继。如果你使用的不是 Linux,则无法对 GraalVM Native Image 进行 Debug,请关注尚未关闭的 https://github.com/oracle/graal/issues/5648

对于使用 ShardingSphere Agent 等 Java Agent 的情形, GraalVM 的 native-image 组件尚未完全支持在构建 Native Image 时使用 javaagent,你需要关注尚未关闭的 https://github.com/oracle/graal/issues/1065

若用户期望在 ShardingSphere Proxy Native 下使用这类 Java Agent,则需要关注 https://github.com/oracle/graal/pull/8077 涉及的变动。