升级手册

1. 升级版本兼容性

当前文档所对应的版本为3.2.0，所有Nacos版本可升级到该版本的兼容性如下：

Nacos版本	是否支持升级到当前版本	备注
0.X ～ 1.X	不支持	0.X ~ 1.X 版本需要先升级到2.0以上的版本，请参考Nacos2.0升级文档先升级到2.0或2.1版本后再进行升级
2.0.X ~ 3.1.X	支持	3.2.X版本支持从 2.0.X ~ 3.1.X 升级到 3.2.X，但数据库表结构有发生变化，请升级前对比mysql-schema.sql文件，并应用新的表结构后进行升级

1.1 客户端兼容性

Nacos 3.x 服务端与各版本客户端的兼容性如下：

客户端版本	是否兼容	备注
0.x	不兼容	-
1.x	不兼容	若需继续使用 1.x 客户端，请自行集成 nacos-api-legacy-adapter
2.x	兼容	-
3.x	兼容	-

2. 升级步骤

2.1. 发行版升级

2.1.1 确认表结构

先对比部署的旧版本Nacos版本的mysql-schema.sql文件和将升级版本的mysql-schema.sql文件，确认表结构是否有变化。

若文件中表结构存在变化，请先进行数据库变更（以MySQL为例）：

-- 从 2.0.X 升级时需要执行下列所有SQL, 从2.1.X之后版本升级仅需执行最后三行。
ALTER TABLE `config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `config_info_gray` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `config_info_beta` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `his_config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT '密钥';
ALTER TABLE `his_config_info` ADD COLUMN `publish_type` varchar(50)  DEFAULT 'formal' COMMENT 'publish type gray or formal';
ALTER TABLE `his_config_info` ADD COLUMN `gray_name` varchar(50)  DEFAULT NULL COMMENT 'gray name';
ALTER TABLE `his_config_info` ADD COLUMN `ext_info`  longtext DEFAULT NULL COMMENT 'ext info';

3.2.0 版本新增了AI相关的表，所有版本升级到 3.2.X 均需创建以下表：

CREATE TABLE IF NOT EXISTS `pipeline_execution` (
    `execution_id`  varchar(64)  NOT NULL COMMENT '执行ID',
    `resource_type` varchar(32)  NOT NULL COMMENT '资源类型',
    `resource_name` varchar(256) NOT NULL COMMENT '资源名称',
    `namespace_id`  varchar(128) DEFAULT NULL COMMENT '命名空间ID',
    `version`       varchar(64)  DEFAULT NULL COMMENT '版本',
    `status`        varchar(32)  NOT NULL COMMENT '执行状态',
    `pipeline`      longtext     NOT NULL COMMENT 'pipeline节点结果JSON',
    `create_time`   bigint(20)   NOT NULL COMMENT '创建时间',
    `update_time`   bigint(20)   NOT NULL COMMENT '修改时间',
    PRIMARY KEY (`execution_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源发布审核Pipeline执行记录';

CREATE TABLE IF NOT EXISTS `ai_resource` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '修改时间',
    `name` varchar(256) NOT NULL COMMENT '资源名称',
    `type` varchar(32) NOT NULL COMMENT '资源类型',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT '资源描述',
    `status` varchar(32) DEFAULT NULL COMMENT '资源状态',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT '命名空间ID',
    `biz_tags` varchar(1024) DEFAULT NULL COMMENT '业务标签',
    `ext` longtext DEFAULT NULL COMMENT '扩展信息(JSON)',
    `c_from` varchar(256) NOT NULL DEFAULT 'local' COMMENT '来源标识(导入/同步来源)',
    `version_info` longtext DEFAULT NULL COMMENT '版本信息(JSON)',
    `meta_version` bigint(20) NOT NULL DEFAULT 1 COMMENT '元数据版本(乐观锁)',
    `scope` varchar(16) NOT NULL DEFAULT 'PRIVATE' COMMENT '可见性: PUBLIC/PRIVATE',
    `owner` varchar(128) NOT NULL DEFAULT '' COMMENT '创建者用户名',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT '下载次数',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ns_name_type` (`namespace_id`,`name`,`type`,`c_from`),
    KEY `idx_ai_resource_name` (`name`),
    KEY `idx_ai_resource_type` (`type`),
    KEY `idx_ai_resource_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源元数据表';

CREATE TABLE IF NOT EXISTS `ai_resource_version` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '修改时间',
    `type` varchar(32) NOT NULL COMMENT '资源类型',
    `author` varchar(128) DEFAULT NULL COMMENT '作者',
    `name` varchar(256) NOT NULL COMMENT '资源名称',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT '版本描述',
    `status` varchar(32) NOT NULL COMMENT '版本状态',
    `version` varchar(64) NOT NULL COMMENT '版本号',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT '命名空间ID',
    `storage` longtext DEFAULT NULL COMMENT '存储信息(JSON)',
    `publish_pipeline_info` longtext DEFAULT NULL COMMENT '发布流水线信息(JSON)',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT '下载次数',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ver_ns_name_type_ver` (`namespace_id`,`name`,`type`,`version`),
    KEY `idx_ai_resource_ver_name` (`name`),
    KEY `idx_ai_resource_ver_status` (`status`),
    KEY `idx_ai_resource_ver_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI资源版本表';

进入Nacos官网版本下载页面，选择稳定版本，然后点击二进制包下载列中的${nacos.version}.zip进行下载。

注意：有时大量用户同时进行下载时，可能会遇到下载限流失败的情况，若出现下载限流失败，请稍等后重试，或采用从 Github 下载方式。

进入Nacos Github 的最新稳定版本，选择需要下载的Nacos版本，在Assets中点击下载 nacos-server-$version.zip 包。

2.1.3. 替换二进制jar包

解压新下载的发行版压缩包

  unzip nacos-server-$version.zip
  # 或者 tar -xvf nacos-server-$version.tar.gz

然后找到nacos/target/nacos-server.jar 将该jar包替换到旧的发行版中，例如：

cp nacos/target/nacos-server.jar ${old.nacos.home}/target/

2.1.4. 修改配置文件

Nacos 3.0.X 版本相比Nacos 2.X版本有较大的配置文件内容改动，除了新增大量关于server和console的相关配置，还对参数的顺序进行了改动，因此请务必仔细对比新版本和旧版本的配置文件，并重新设置Nacos的配置文件。

主要的参数改动如下：

server.port —> nacos.server.main.port

server.servlet.contextPath —> nacos.server.contextPath

2.1.5. 修改启动参数（可选）

对比部署的旧版本的启动脚本和新版本的启动脚本bin/startup.sh或bin/startup.cmd，确认是否有新增或修改的配置项，将这些配置项添加到旧的启动脚本件中，例如：

diff nacos/bin/startup.sh ${old.nacos.home}/bin/startup.sh

2.1.6. 重启Nacos Server

均替换完成后，重启Nacos Server:

# 以集群模式为例
## Linux
${nacos.home}/bin/shutdown.sh
${nacos.home}/bin/startup.sh

## Windows
${nacos.home}/bin/shutdown.cmd
${nacos.home}/bin/startup.cmd

2.1.7. 配置中心命名空间迁移

Nacos 3.0 中对于配置中心的空命名空间和public命名空间进行了统一，将namespaceId="public"的命名空间作为默认命名空间，并将原先namespaceId=""的命名空间的配置数据全部统一到namespaceId="public"的命名空间中。相关ISSUE。

为了能够完成平滑升降级，Nacos 3.0 将会开启配置中心命名空间兼容模式，将namespaceId="public"的命名空间和namespaceId=""的命名空间的配置数据进行双向同步，因此会对性能有一定影响。当集群升级并稳定运行后，可以关闭配置中心命名空间兼容模式，关闭兼容模式后将会失去平滑降级的功能。

命名空间的兼容模式默认为开启状态，可以通过nacos.config.namespace.compatible.mode配置项关闭。

2.1.7.1. 如何确认配置命名空间迁移已经完成

首先查看nacos目录下 logs/startup.log或logs/nacos.log 观察到nacos启动成功的日志，如 Nacos started successfully in cluster mode. use xxx storage 说明程序已启动成功。

如果观察到[migrate] config_info namespace migrate insert failed 日志，则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在配置数据冲突的情况，即存在dataId、group相同，但是namespaceId分别为空和public的两份配置，请删除其中一份配置数据后再尝试启动节点。如果观察到[migrate] config_info_gray namespace migrate insert failed日志，则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在灰度配置数据冲突的情况，即存在dataId、group、grayName相同，但是namespaceId分别为空和public的两份配置，请删除其中一份灰度配置数据后再尝试启动节点。

如果没有观察到上述两个错误信息，而是[migrate] finish migrate config namespacetotal time taken: xxx ms 那么说明此时配置命名空间迁移已经完成，再进行业务配置使用验证无误后，可以关闭命名空间兼容模式。

2.1.7.2. 配置命名空间迁移导致首次启动较慢

在升级过程中，Nacos 3.0会对配置中的namespaceId=""的命名空间下存在配置进行全量迁移，因此升级过程中，首次启动Nacos 3.0版本时，可能会存在较长的启动时间，具体时间由配置数据量决定。

迁移过程中，您可以从logs/nacos.log日志中观察到如下日志[migrate] migrating config namespace from empty to public, finished:xxx.

根据测试配置namespaceId=""的命名空间下若存在 20000个左右配置时，迁移过程会在2分钟左右结束，这依赖于如下配置及数据库的处理能力大小：

# 迁移时，每批迁移的配置数量，默认100，增加此值可提高迁移速度，但也会随之增加对数据库的压力。
nacos.namespace.migrate.batch.size=100

2.1.8. 迁移MCP服务（可选）

若您是从3.0.0版本进行升级，且您的集群中存在MCP服务，由于官方社区MCP Registry API标准的改动， MCP Server定义的元数据存在一定的变化，这部分变化将会导致一定的数据结构不兼容，从3.0.0版本升级到3.0.1及以上版本之后会导致控制台无法读取到旧版本MCP Server数据，因此需要使用MCP迁移工具对3.0.0版本的存量MCP服务数据进行迁移。

# java -jar ./mcp-migration-tool.jar ${nacos-server-host}:${nacos-server-port} ${username} ${password}
# 示例
java -jar ./mcp-migration-tool.jar localhost:8848 nacos ${your_password}

2.2. Docker/Kubernetes升级

2.2.1 确认表结构

请参考 2.1.1 确认表结构，对比并应用数据库表结构变更。

2.2.2. 确认环境变量

可以对比当前部署版本的环境变量与系统参数-镜像环境变量中的环境变量是否有变化，如有，需要修改Docker的环境变量文件或Kubernetes的regcenter中的环境变量。

例如, 添加如下环境变量：

NACOS_AUTH_TOKEN=${长度32位以上的自定义字符串，进行base64编码后的token}
NACOS_AUTH_IDENTITY_KEY=${任意字符串}
NACOS_AUTH_IDENTITY_VALUE=${任意字符串}

2.2.3. 修改镜像版本

Docker
Kubernetes

首先修改docker compose所对应的文件中的Nacos版本，例如Nacos Docker项目下的standalone-mysql-8.yaml中的

services:
    nacos:
        image:
            nacos/nacos-server:${target_version}

然后执行如下命令进行升级

  docker-compose pull
  docker-compose up -d --remove-orphans

通过kubectl set image 命令更新版本，如：

    kubectl set image deployment/nacos-deployment ${container_name}=nacos/nacos-server:${target_version}

3. 旧版HTTP API移除说明 (Nacos 3.2.0+)

3.1 API移除通知

旧版的 v1 和 v2 HTTP API 不再包含在默认的 Nacos server 发行版中。这些 API 已迁移到单独的旧版适配器模块中。

受影响的API:

所有 v1 REST APIs (例如: /nacos/v1/ns/instance, /nacos/v1/cs/configs)
所有 v2 REST APIs

3.2 迁移选项

您有两个选择:

选项 1: 迁移到新API和客户端 (推荐)

使用新的 v3 API
- v3 Admin API 文档
- v3 Console API 文档
升级到最新的 Nacos 客户端 SDK
- Nacos 客户端文档

选项 2: 使用旧版API适配器 (临时方案)

如果您需要时间进行迁移,可以临时使用旧版适配器恢复旧API。

3.3 安装旧版API适配器

步骤 1: 构建或下载适配器

方式 A: 从 Release 下载

# 从 GitHub releases 下载
wget https://github.com/nacos-group/nacos-api-legacy-adapter/releases/download/v${version}/nacos-api-legacy-adapter-${version}.jar

方式 B: 从源码构建

git clone https://github.com/nacos-group/nacos-api-legacy-adapter.git
cd nacos-api-legacy-adapter
mvn clean install
# 输出: target/nacos-api-legacy-adapter-${version}.jar

环境要求:

JDK 17+
Maven 3.6+
nacos.version 必须与目标 Nacos server 版本匹配

步骤 2: 安装适配器

对于 Nacos Server 部署:

将 JAR 文件放入 Nacos plugins 目录:

cp nacos-api-legacy-adapter-${version}.jar ${NACOS_HOME}/plugins/

重启 Nacos server:

sh ${NACOS_HOME}/bin/shutdown.sh
sh ${NACOS_HOME}/bin/startup.sh -m standalone  # 单机模式
# 或
sh ${NACOS_HOME}/bin/startup.sh                # 集群模式

当 JAR 文件在 classpath 中时,适配器将自动加载。

对于嵌入式/自定义应用:

添加 Maven 依赖:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-api-legacy-adapter</artifactId>
    <version>${nacos.version}</version>
</dependency>

步骤 3: 验证安装

检查 Nacos server 日志以确认:

tail -f ${NACOS_HOME}/logs/nacos.log

查找表明旧版适配器已加载的日志消息。

步骤 4: 测试旧版API

测试您的旧 v1/v2 API 调用是否再次工作:

curl -X GET "http://localhost:8848/nacos/v1/ns/instance/list?serviceName=test"

3.4 版本兼容性

Nacos版本	适配器版本	兼容性
3.2.0	3.2.0	✅ 兼容
3.3.0+	匹配Nacos版本	⚠️ 请检查兼容性

重要提示: 适配器版本必须与您的 Nacos server 版本匹配。

3.5 规划您的迁移

在使用旧版适配器的同时,请规划您的迁移:

审计您的API使用 - 识别所有 v1/v2 API 调用
查看新的 v3 API - 了解新的 API 结构
更新客户端 - 升级到最新的 Nacos 客户端 SDK
充分测试 - 在预发环境中测试
逐步迁移 - 使用功能开关或金丝雀部署
移除适配器 - 迁移完成后,移除适配器 JAR

3.6 获取帮助

旧版适配器仓库: https://github.com/nacos-group/nacos-api-legacy-adapter
Nacos 主仓库: https://github.com/alibaba/nacos
社区支持: Nacos 社区