跳转到内容
OpenClaw 不踩坑恶意 Skills ,企业需 Skills Registry:Nacos 3.2 发布点此了解

升级手册

1. 升级版本兼容性

当前文档所对应的版本为 3.2.x,所有 Nacos 版本升级到 3.2.x 的兼容性如下:

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

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 schema 文件和目标版本对应数据库的 schema 文件,确认表结构是否有变化。

若文件中表结构存在变化,请先进行数据库变更。以 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资源版本表';

如果使用 PostgreSQL,并且从 3.2.1 或更早版本升级到 3.2.2,请在升级前确认配置相关表的 tenant_id 字段是否已经是 NOT NULL DEFAULT ''。3.2.2 会在启动时校验 PostgreSQL schema;如果旧数据表中仍允许 tenant_id 为空,服务端可能会启动失败。相关讨论见 alibaba/nacos#15275

执行迁移前,建议先检查 config_info 中是否存在重复的逻辑配置。若同一 data_idgroup_id 下存在多条 tenant_id IS NULL 记录,请先清理冲突数据,再执行迁移 SQL。

SELECT data_id, group_id, COUNT(*)
FROM config_info
WHERE tenant_id IS NULL
GROUP BY data_id, group_id
HAVING COUNT(*) > 1;

确认没有冲突后,执行目标版本源码中的 pg-upgrade-null-tenant-id.sql。SQL 内容如下:

ALTER TABLE config_info ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_info SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_info ALTER COLUMN tenant_id SET NOT NULL;
ALTER TABLE config_info_gray ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_info_gray SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_info_gray ALTER COLUMN tenant_id SET NOT NULL;
ALTER TABLE config_tags_relation ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_tags_relation SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_tags_relation ALTER COLUMN tenant_id SET NOT NULL;
ALTER TABLE his_config_info ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE his_config_info SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE his_config_info ALTER COLUMN tenant_id SET NOT NULL;

2.1.2. 下载新版本

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

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

2.1.3. 替换二进制jar包

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

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

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

Terminal window
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.shbin/startup.cmd,确认是否有新增或修改的配置项,将这些配置项添加到旧的启动脚本件中,例如:

Terminal window
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.loglogs/nacos.log 观察到nacos启动成功的日志,如 Nacos started successfully in cluster mode. use xxx storage 说明程序已启动成功。

如果观察到[migrate] config_info namespace migrate insert failed 日志,则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在配置数据冲突的情况,即存在dataIdgroup相同,但是namespaceId分别为public的两份配置,请删除其中一份配置数据后再尝试启动节点。 如果观察到[migrate] config_info_gray namespace migrate insert failed日志,则说明数据库中namespaceId="public"的命名空间和namespaceId=""的命名空间下存在灰度配置数据冲突的情况,即存在dataIdgroupgrayName相同,但是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服务数据进行迁移。

Terminal window
# 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 compose所对应的文件中的Nacos版本,例如Nacos Docker项目下的standalone-mysql-8.yaml中的

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

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

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

2.3. Nacos 3.2.4 升级检查

Nacos 3.2.4 调整了废弃 API 的默认行为、Console MCP tools 导入的出站访问策略,并为 JRaft 原生 gRPC 增加了 Server identity 校验。下面内容对应 Nacos 3.2.4 Release Notes 中的 Breaking Change Notice,请在升级前完成检查。

2.3.1. 统一集群 Server identity

在开始逐节点升级前,为当前集群和待升级配置中的所有节点设置相同的非空 Server identity:

nacos.core.auth.server.identity.key=${自定义身份标识Key}
nacos.core.auth.server.identity.value=${自定义身份标识Value}

这两个值不会由 Nacos 在节点间同步。Nacos 3.2.4 的 JRaft 原生 gRPC 会独立使用它们校验服务端间请求,即使 nacos.core.auth.enabled=false 也不能省略。

滚动升级期间,3.2.4 节点会暂时兼容无法携带凭据的旧节点。当完整成员列表中的所有节点都支持 JRaft 鉴权后,每个 3.2.4 进程会自动进入不可逆的强制校验状态,并将状态写入 ${nacos.home}/data/jraft-auth-enforced.state。可以通过日志 All Nacos servers support JRaft authentication; enforcement is enabled 确认该状态。

2.3.2. 迁移默认关闭的废弃 v3 API

以下废弃 API 从 Nacos 3.2.4 起默认返回 HTTP 410 GoneAPI_DEPRECATED,请迁移到标准 API:

废弃 API标准替代 API
GET /v3/admin/ai/pipelinesGET /v3/admin/ai/pipelines/list
GET /v3/admin/ai/pipelines/{pipelineId}GET /v3/admin/ai/pipelines/detail?pipelineId={pipelineId}
GET /v3/console/ai/pipelinesGET /v3/console/ai/pipelines/list
GET /v3/console/ai/pipelines/{pipelineId}GET /v3/console/ai/pipelines/detail?pipelineId={pipelineId}
POST /v3/console/ai/mcp/import/validatePOST /v3/console/ai/import/validate
POST /v3/console/ai/mcp/import/executePOST /v3/console/ai/import/execute

如果无法在升级前完成迁移,可以在迁移窗口内临时设置:

nacos.core.api.compatibility.enabled=true

该开关只重新开启显式接入兼容门禁的废弃 v3 API,原有认证和鉴权仍然生效;它不会恢复已从主发行包移除的 v1/v2 API。旧参数 nacos.ai.resource.import.legacy-mcp-api-enabled 从 3.2.4 起不再识别。若旧 MCP 直接 URL 导入仍需临时抓取用户提供的 URL,还必须同时设置 nacos.ai.resource.import.allow-user-url=true。迁移完成后应关闭共享兼容开关。

2.3.3. 配置 Console MCP tools 导入策略

Console 专用接口 GET /v3/console/ai/mcp/importToolsFromMcp 默认允许访问公网 MCP 目标,但会拒绝私网或本地目标。需要访问受信任私网目标时,在每个承载 Console API 的实例上配置白名单并重启实例:

# 默认值为 true;设为 false 可关闭全部出站 MCP tools 导入
nacos.console.ai.mcp.import.enabled=true
# 只接受逗号分隔的 IPv4/IPv6 地址或 CIDR,不接受域名
nacos.console.ai.mcp.import.allowed-private-addresses=192.168.0.0/16,10.0.0.8

目标域名解析出的每一个私网或本地地址都必须命中白名单;任一非法白名单条目都会阻止请求。baseUrl 必须是 HTTP 或 HTTPS URL,endpoint 必须保持为相对 URI,且请求不会跟随重定向。若部署不需要此功能,建议设置 nacos.console.ai.mcp.import.enabled=false 关闭 Console 出站访问。

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和客户端 (推荐)

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

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

3.3 安装旧版API适配器

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

方式 A: 从 Release 下载

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

方式 B: 从源码构建

Terminal window
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 部署:

  1. 将 JAR 文件放入 Nacos plugins 目录:
Terminal window
cp nacos-api-legacy-adapter-${version}.jar ${NACOS_HOME}/plugins/
  1. 重启 Nacos server:
Terminal window
sh ${NACOS_HOME}/bin/shutdown.sh
sh ${NACOS_HOME}/bin/startup.sh -m standalone # 单机模式
# 或
sh ${NACOS_HOME}/bin/startup.sh # 集群模式
  1. 当 JAR 文件在 classpath 中时,适配器将自动加载。

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

添加 Maven 依赖:

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

步骤 3: 验证安装

检查 Nacos server 日志以确认:

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

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

步骤 4: 测试旧版API

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

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

3.4 版本兼容性

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

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

3.5 规划您的迁移

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

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

3.6 获取帮助