Nacos Native 快速开始

这个快速开始手册是帮忙您快速在您的电脑上，下载、安装并使用 Nacos。

Nacos 从 3.3.0 开始支持本文介绍的 Native 构建与运行方式。本文以 Linux/macOS 上的单机、Server 与 Console 合并部署、外置 MySQL为例，从源码生成适用于目标平台的可执行程序。

普通 JDK 部署请参考标准快速开始。

1. 准备构建环境

• 使用 Nacos 3.3.0 源码，在源码根目录执行下文命令。
• 安装 Maven；将 JAVA_HOME 指向包含 native-image 的 GraalVM 25+，以满足 Spring Boot 4 Native 工具链要求。
• 安装本机 C/C++ 编译工具及系统库。Ubuntu 可安装 build-essential、zlib1g-dev；macOS 使用 Xcode Command Line Tools。其他平台依赖见 GraalVM Native Image 环境要求。
• Native 编译进程的堆上限默认为 8g，可通过 nacos.native.build.heap 调整。

export JAVA_HOME='/path/to/graalvm-25'
export PATH="$JAVA_HOME/bin:$PATH"
java -version
native-image --version
mvn -version

请在与运行环境匹配的操作系统、CPU 架构和系统库环境中构建。本文使用 Linux/macOS 启动脚本。

2. 构建 Native 发行包

2.1. 选择构建参数和插件

构建时需要选定数据库类型，以纳入对应组件；数据库连接、账号密码及鉴权配置在第 3 节部署时填写。

在源码目录旁创建工作目录，保存构建参数、额外插件和 reachability metadata，避免被 Maven clean 删除：

export NACOS_VERSION='3.3.0'
export NACOS_NATIVE_WORK="$(cd .. && pwd)/nacos-native-work"
mkdir -p "$NACOS_NATIVE_WORK/plugins" "$NACOS_NATIVE_WORK/metadata"
printf '%s\n' 'nacos.plugin.datasource-dialect.type=mysql' > "$NACOS_NATIVE_WORK/build.properties"

native profile 会引入默认插件。需要自定义 SPI 插件、额外 JDBC 驱动时，将其 JAR 及全部依赖放到 $NACOS_NATIVE_WORK/plugins；Maven runtime 依赖也可以提供这些实现。使用外置 MySQL、PostgreSQL 或自定义插件时，还需准备对应的 Native 元数据。

插件自带的 META-INF/native-image 元数据会参与编译；额外准备的元数据放入 $NACOS_NATIVE_WORK/metadata。构建前确认元数据覆盖所选插件和驱动。若需要补充反射、JNI 或资源等元数据，先按附录采集，再执行下面的构建命令。

2.2. 执行构建

在源码根目录执行：

mvn -B '-Pnative,release-native,!dev' -pl distribution -am clean package \
  -DskipTests \
  -Dnacos.native.config="$NACOS_NATIVE_WORK/build.properties" \
  -Dnacos.native.metadata="$NACOS_NATIVE_WORK/metadata" \
  -Dnacos.native.plugins="$NACOS_NATIVE_WORK/plugins" \
  -Dnacos.native.deployment=merged \
  -Dnacos.native.standalone=true

同时启用 native 和 release-native，完成 Native 编译和发行包打包。示例中的 -DskipTests 用于跳过单元测试。

构建完成后可以找到：

• 可执行程序：bootstrap/target/native/nacos-server（Windows 为 .exe）。
• 发行包：distribution/target/nacos-server-<version>-native-<os>-<arch>.tar.gz，同时生成 ZIP 包。例如 macOS ARM64 的后缀为 native-macos-aarch64。

发行包包含程序、配套本机库、配置模板、启动脚本和 AOT 结构配置记录。

3. 准备数据库和运行配置

解压实际生成的发行包。例如，在 macOS ARM64 上：

mkdir -p "$NACOS_NATIVE_WORK/run"
tar -xzf "distribution/target/nacos-server-${NACOS_VERSION}-native-macos-aarch64.tar.gz" \
  -C "$NACOS_NATIVE_WORK/run"
cd "$NACOS_NATIVE_WORK/run/nacos"

Linux 用户将文件名后缀换为实际构建的 native-linux-<arch>。以下配置均修改解压目录中的 conf/application.properties。

3.1. 准备 MySQL

按数据源插件指南创建 MySQL 数据库并导入对应版本的 schema。填写数据库连接信息，将示例中的地址、账号和密码替换为实际值：

nacos.plugin.datasource-dialect.type=mysql
nacos.plugin.datasource.db.num=1
nacos.plugin.datasource.db.url.0=jdbc:mysql://127.0.0.1:3306/nacos_native_test?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
nacos.plugin.datasource.db.user=nacos_native_test
nacos.plugin.datasource.db.password=<test-database-password>

数据库类型应与构建时选择的 MySQL 一致；其他需要保持一致的配置见第 5 节。

3.2. 配置鉴权

nacos.core.auth.server.identity.key=native-test
nacos.core.auth.server.identity.value=<test-server-identity>
nacos.plugin.auth.nacos.token.secret.key=<base64-token-secret>

Nacos 3.3 默认开启鉴权，使用默认鉴权插件时，请填写上面的节点身份和 token 签名密钥：

• token 签名密钥用于签发和校验登录 token，必须是有效的 Base64 字符串，解码后不少于 32 字节。可用 openssl rand -base64 32 随机生成，也可自行生成符合要求的密钥，填入 <base64-token-secret>。
• 节点身份用于服务端之间的通信，nacos.core.auth.server.identity.key 和 nacos.core.auth.server.identity.value 均需为自定义的非空字符串。示例 key 为 native-test；<test-server-identity> 可自行设置，也可用 openssl rand -hex 16 随机生成。

同一集群各节点使用相同的密钥和节点身份，不同部署独立生成。

更多配置说明见鉴权手册。

4. 启动、验证和停止

4.1. 启动 Native

在解压后的 Nacos 目录执行：

NACOS_NATIVE_OPTS='-Xmx1g' bash bin/startup-native.sh
tail -f logs/startup.log

startup-native.sh 直接运行 Native 程序，无需 JAVA_HOME；启动前请完成第 3.2 节的鉴权配置。NACOS_NATIVE_OPTS 用于传入以空格分隔的 Native VM 参数。脚本默认采用构建时的部署和功能模式。

启动输出位于安装目录的 logs/startup.log，其他日志也位于该目录的 logs/ 下。

4.2. 初始化管理员并验证

确认 Native 启动成功后，访问 http://127.0.0.1:8080，首次使用时按页面提示初始化管理员密码。随后按标准快速开始的验证步骤登录获取 accessToken，验证配置发布与读取、服务注册与发现。若数据库中已有管理员账号，直接使用该账号登录。

4.3. 停止 Native

在本机只运行一个 Nacos 测试进程时，可使用发行包的停止脚本：

bash bin/shutdown.sh

该脚本按 Nacos 进程标记查找进程；同一主机运行多个实例时，应由进程管理工具向目标实例发送 SIGTERM，避免停止其他实例。

5. 哪些配置需要重新构建

更改配置时，按下表决定是否需要重新构建：

6. 使用嵌入式 Derby

在 Native Server 中使用 Derby，需要 GraalVM 的实验性 RuntimeClassLoading 能力。使用支持该能力的 GraalVM，在第 2.2 节构建命令中增加 -Dnacos.native.derby.experimental=true，并将构建和运行配置中的 nacos.plugin.datasource-dialect.type 设为 derby。

已在 macOS ARM64、GraalVM CE 25.4.4.1.1、单机合并部署的环境中验证可用。

7. 自行构建 Docker 镜像

Nacos 暂不提供官方 Native Docker 镜像。Native 的插件组合在构建时确定，新增或升级插件需要重新构建 Native 程序和镜像。

可将所需默认插件、自定义插件、JDBC 驱动及依赖纳入上述构建，再用生成的可执行程序和配套文件制作适合目标平台的 Docker 镜像。

制作镜像时保留配套本机库、配置和 AOT 结构配置记录，基础镜像需提供匹配的系统库；配置及凭据在部署时注入。startup-native.sh 会后台启动进程，在容器中应使用能保持前台进程并正确转发终止信号的入口。

8. 常见问题

附录：补充 Native 元数据

所选插件或驱动需要补充元数据时，使用 GraalVM tracing agent 临时运行 JVM 程序，记录 Native 编译所需的反射、JNI 和资源访问。采集完成后停止 JVM，再返回第 2.2 节构建 Native。

完成第 1、2.1 节的构建环境、工作目录和插件准备后，在源码根目录生成用于采集的 JVM 包：

mvn -B '-Prelease-nacos,!dev' clean install -DskipTests
mkdir -p "$NACOS_NATIVE_WORK/jvm"
tar -xzf "distribution/target/nacos-server-${NACOS_VERSION}.tar.gz" -C "$NACOS_NATIVE_WORK/jvm"

采集过程需要实际运行 Nacos。按第 3.1、3.2 节准备独立的测试数据库和鉴权凭据，填写到 $NACOS_NATIVE_WORK/jvm/nacos/conf/application.properties，并保持数据库类型、插件和功能开关与目标 Native 构建一致。随后启动采集：

"$JAVA_HOME/bin/java" \
  "-agentlib:native-image-agent=config-output-dir=$NACOS_NATIVE_WORK/metadata" \
  -Dnacos.standalone=true -Dnacos.deployment.type=merged \
  "-Dnacos.home=$NACOS_NATIVE_WORK/jvm/nacos" \
  "-Dloader.path=$NACOS_NATIVE_WORK/jvm/nacos/plugins,$NACOS_NATIVE_WORK/plugins" \
  -jar "$NACOS_NATIVE_WORK/jvm/nacos/target/nacos-server.jar" \
  "--spring.config.additional-location=file:$NACOS_NATIVE_WORK/jvm/nacos/conf/" \
  "--logging.config=$NACOS_NATIVE_WORK/jvm/nacos/conf/nacos-logback.xml"

测试 JVM 启动后，在另一个终端按标准快速开始的验证步骤初始化测试账号并执行登录、配置和服务操作，通过 SDK 执行所需的 gRPC 调用；启用 AI 或自定义插件时也要执行对应功能。这些操作用于让采集覆盖实际使用路径。

完成后用 Ctrl+C 正常停止采集进程。将命令中的 config-output-dir 改为 config-merge-dir，保留测试数据再次启动并验证读取，合并重启后的路径；再次停止进程后，检查生成的元数据，再返回第 2.2 节。

工具用法见 GraalVM tracing agent 文档；JVM AOT 采集步骤见源码中的 bootstrap/README-AOT.md。