升级手册

1. 升级版本兼容性

当前文档所对应的版本为 3.3.x，所有 Nacos 版本升级到 3.3.x 的兼容性如下：

1.1 客户端兼容性

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

升级服务端前，请确认客户端已配置正确的身份信息；使用 A2A 的部署还需完成第 2.7 节的迁移准备。

2. 升级步骤

2.1. 升级前检查

升级生产集群前，请完成以下准备：

1. 确认源集群版本受支持，且数据库 schema 已满足目标 3.3.x 版本要求；具体数据库检查和变更见第 2.2 节。
2. 备份数据库、各节点的 data、conf、cluster.conf，以及自定义插件和配置。
3. 在预发环境使用生产数据副本演练升级和回滚。
4. 按第 2.1.2 节盘点 Client API 调用方并完成鉴权迁移；不要等到首个 3.3 节点启动后才开始补客户端凭据。
5. 按第 2.1.3 节核对全部节点的 Server identity，并确认第 2.8.1 节的回滚限制。

2.1.1. 确认从 2.x 升级的路径

Nacos 3.3 已移除配置中心兼容迁移逻辑，不再支持从 2.x 直接平滑升级。升级前应盘点两类历史数据：

• 默认 namespace 中仍以空 tenant 保存的配置，需要完成到 public 的存储迁移。
• 旧 config_info_beta、config_info_tag 表中的灰度配置，需要迁移到 config_info_gray 当前灰度模型。

若使用过以上任一类数据或无法确认，请先升级到支持相应迁移的 3.0.x～3.2.x 版本，完成迁移并验证默认 namespace 的配置查询、灰度规则和灰度客户端获取结果，再升级到 3.3.x。直接跳过迁移会导致历史配置无法查询或灰度行为不符合预期。即使当前已运行 3.x，也应确认曾经需要的迁移已完成；不要只以版本号作为完成依据。

本次移除不改变当前默认 namespace 或 beta/tag 灰度 API 的语义；空或省略 namespace 的请求仍归一为 public。更多说明见兼容与废弃。

2.1.2. 准备客户端鉴权

Nacos 3.3 默认开启客户端鉴权（nacos.core.auth.enabled=true）。如果客户端没有配置正确的身份信息或访问权限，升级后配置读取、服务注册与发现等请求可能被拒绝，影响业务运行。

升级前请根据客户端准备情况选择：

• 已具备鉴权条件：确认服务端鉴权配置和客户端身份配置正确，并验证配置读取、服务注册与发现等业务操作后再升级。
• 暂时无法完成客户端改造：在所有节点显式关闭客户端鉴权，保持原有访问方式；完成客户端身份和权限配置后再统一开启。

临时关闭期间，应限制 Nacos 只能从可信网络访问，并在客户端改造完成后恢复鉴权。以上开关只影响客户端鉴权，Admin API 和 Console API 的鉴权行为不变。

2.1.3. 确认 JRaft 节点间鉴权配置

Nacos 3.3 新增 JRaft 节点间鉴权。滚动升级期间会兼容旧节点，所有节点升级完成并确认支持后自动启用，无需手动开启。

升级前，请确认所有节点的 nacos.core.auth.server.identity.key 和 nacos.core.auth.server.identity.value 均非空且一致。配置错误可能在升级完成后导致节点间通信失败，影响集群读写；应在继续升级前修正。即使临时关闭客户端鉴权，也必须保持这两项配置正确。

升级完成后的回滚限制见第 2.8.1 节。

2.1.4. 从 3.3 预发布客户端升级

如果应用使用过 3.3.0-BETA 或 3.3.0-RC 的新 Agent SDK，请重新编译并调整 RAD 订阅代码。正式版的两个 subscribeAgent 重载返回 void，初始状态和后续更新都通过 Listener 接收。调用前先初始化监听器状态，不再从返回值获取初始快照。旧 A2A 方法签名及 HTTP/gRPC 协议不受此变更影响。参见 Agent 订阅和 RAD 发现。

2.2. 应用数据库变更

在启动任何 3.3.x 节点前，先按 3.2.x 升级手册 完成从当前源版本到 3.2.x schema 所需的前置数据库操作；这一步不要求启动 3.2.x 服务端。然后比较完成前置操作后的实际 schema 与目标 3.3.x 发行包中对应数据库的完整 schema，并把剩余差异转换为经过评审的增量 DDL。不要在已有数据库上直接执行包含 CREATE TABLE 或 DROP TABLE 的完整初始化文件。

对于 PostgreSQL 部署，如果从 3.0.x、3.1.x、3.2.0 或 3.2.1 直接升级，或者曾跳过 3.2.2 的 schema 规范化，请先完成 3.2.x 升级手册 中的 tenant_id 非空迁移。

目标发行包在 conf 目录提供 mysql-schema.sql、pg-schema.sql、oracle-schema.sql 和 derby-schema.sql。完成 3.2.x schema 前置操作后，还需要重点处理以下 3.3.x 变化：

2.3. 迁移配置与插件

3.3 对服务端插件配置进行了统一管理。大部分旧版本配置 key 在 3.3 中仍可继续使用，但未来版本可能移除。升级时无需一次性替换所有旧 key，建议对照目标发行包的 conf/application.properties 逐步迁移到新 key，也不建议直接用源版本配置文件覆盖目标文件。常用参数见系统参数，插件迁移规则见插件迁移指南。

2.3.1. 默认鉴权插件

默认鉴权实现仍然是 nacos，但在统一插件体系中的身份为 auth:nacos，实现选择与私有配置迁移到了标准 nacos.plugin.auth.* 命名空间。

nacos.core.auth.enabled、nacos.core.auth.admin.enabled、nacos.core.auth.console.enabled 和 nacos.core.auth.server.identity.* 仍是核心鉴权开关或节点身份配置，不要迁移到插件私有命名空间。

标准 key 与旧 key 同时存在时，标准 key 优先；即使标准值为空，也会屏蔽旧 key。大部分旧 key 在 3.3 中仍可兼容读取，但目标发行包可能已经提供对应的新 key 默认值，合并配置时应避免实际值被默认值覆盖。启动脚本只会自动处理 application.properties 中有效的旧 token secret，其他旧 key 不会被自动改写，可根据日志提示逐步迁移。LDAP、OIDC 和自定义鉴权插件还应按照鉴权插件文档逐项核对。

开启 AI 匿名访问时，显式携带但为空或无效的 Authorization、accessToken、用户名或密码不再降级为匿名访问，而会被拒绝。匿名调用方应完全不携带凭据，鉴权调用方则必须提供有效凭据。

2.3.2. 其他插件配置

历史 key 在兼容窗口内仍可能作为 alias 被读取并输出迁移 WARN，但新 key 只要存在就具有更高优先级。持久化实现状态也会覆盖静态 .enabled 初始值。方言、互斥实现选择和标记为 RESTART 的字段必须通过静态配置修改并重启，不能通过插件配置 API 动态切换。

AI Resource Import 在新旧模块开关均未配置时默认开启；如果升级后仍需关闭，必须在发布前显式设置：

nacos.plugin.ai-resource-import.enabled=false

旧 Importer/Source SPI、可复制 Source/preset 和通过配置复制同一 importer 到多个 endpoint 的模型已经移除，外部实现必须迁移到新的 AiResourceImportServiceBuilder。详细映射及内置来源见 AI Resource Import 迁移说明。

2.3.3. 自研与第三方插件

• 按稳定的 pluginType:pluginName 记录每个实现，消除重复身份，并确认目标版本能够发现预期 JAR。重复身份现在按 first-wins 确定实际实现。
• 旧版零配置插件通常仍能加载，但只有实现 PluginConfigSpec definitions、当前配置快照和 apply 回调后才会显示为可配置。
• 旧 Config Change 二进制插件在兼容窗口内仍可加载，但会显示 configurable=false；应尽快迁移到新的 definitions 和 callbacks。
• AI Pipeline 不再加载 PublishPipelineServiceBuilder。第三方 Pipeline 插件需要重新编译，以 public 无参构造直接注册 PublishPipelineService，并实现统一配置契约。
• 实现或注册了已移除 ConfigInfoBetaMapper、ConfigInfoTagMapper、ConfigMigrateMapper SPI 的第三方数据源插件必须移除这些接口并重新编译；3.0 之前的数据迁移应在升级前完成。
• 旧 AI Resource Import SPI 没有兼容适配器，必须重新编译并同步修改配置与调用方，不能与新模型混跑。
• auth、datasource-dialect、ai-storage 等关键插件在选中的实现缺失、被禁用或初始化失败时可能阻止服务启动，应在预发环境验证选择、状态和初始化过程。
• 先在单节点核对插件列表、详情、effective source、脱敏结果和 RESTART 提示；滚动升级期间不要下发只有 3.3 节点才能理解的运行时配置。

2.3.4. 迁移默认关闭的旧 AI API

以下废弃的 v3 API 默认关闭，迁移调用方时应使用对应的标准入口：

关闭时返回 HTTP 410 Gone 和 API_DEPRECATED 结果码，并提示替代 API。确需保留迁移窗口时，可在提供这些端点的节点临时设置 nacos.core.api.compatibility.enabled=true，完成调用方迁移后恢复为默认 false。该共享开关会同时开放表中端点，原有鉴权仍然生效；它不恢复 v1/v2 HTTP API，也不控制第 2.7 节的旧 A2A 兼容链路。

旧 nacos.ai.resource.import.legacy-mcp-api-enabled 已不再识别。旧 MCP 直接 URL 导入还要求显式设置 nacos.ai.resource.import.allow-user-url=true；优先迁移到受管来源及新请求模型，不能只替换 URL 而沿用全部旧参数。详见 AI Resource Import 迁移说明。

2.4. 发行版升级

2.4.1. 下载目标版本

以下发行包和容器示例使用 3.3.0 正式版。先完成前述升级检查，再部署目标版本。

2.4.2. 准备新的安装目录

解压目标发行包到新的目录：

unzip nacos-server-3.3.0.zip -d ${INSTALL_PARENT}
# 或 tar -xvf nacos-server-3.3.0.tar.gz -C ${INSTALL_PARENT}

3.3 的发行包同时包含新的服务端 JAR、默认插件、schema、启动脚本和配置模板。不要只替换 target/nacos-server.jar，也不要用源版本的 bin、conf 或整个 plugins 目录覆盖新发行包。

请按以下原则迁移部署数据：

• 以新 application.properties 为基础，逐项迁移第 2.3 节确认的配置。
• 对比后重新设置 cluster.conf、JVM 参数、日志目录、证书和其他部署专属文件。
• 只复制已经完成 3.3 兼容验证的自研或第三方插件 JAR。
• 所有部署都要迁移或恢复该节点原有的 data/plugin，以保留 plugin-states.json 和 plugin-configs.json。Derby 或嵌入式存储还必须在停机和完整备份后迁移整个 data。外置数据库集群不要在节点间盲目复制仍活跃的 Raft 数据，应复用该节点自己的持久卷或遵循已演练的节点恢复方案；任何新旧进程都不能同时使用同一数据目录。

2.4.3. 重启或滚动升级

单机部署先停止旧实例，再使用新发行包的启动脚本启动：

${OLD_NACOS_HOME}/bin/shutdown.sh
${NEW_NACOS_HOME}/bin/startup.sh -m standalone

集群部署建议逐节点升级。每次只停止一个源版本节点，使用该节点对应的 3.3 配置和新发行包启动，确认节点重新加入集群且核心功能正常后再处理下一个节点。全部节点升级完成前，不要修改统一插件运行时状态或配置。

Windows 部署使用新发行包中的 shutdown.cmd 和 startup.cmd，不要复用旧版脚本。

2.5. Docker/Kubernetes 升级

容器部署同样需要先完成第 2.1～2.3 节的数据库、历史配置和插件检查。对比目标镜像的环境变量转换规则与挂载的 application.properties，不要假设旧环境变量一定能够映射到新的标准插件 key。常用参数见系统参数 - 启动脚本和镜像变量。

services:
  nacos:
    image: nacos/nacos-server:v3.3.0

docker compose pull
docker compose up -d --no-deps nacos

kubectl set image deployment/nacos-deployment \
  ${container_name}=nacos/nacos-server:v3.3.0
kubectl rollout status deployment/nacos-deployment

2.6. 等待 MCP 历史数据自动迁移完成

从 Nacos 3.0.x～3.2.x 升级且已有 MCP Server 数据时，无需手工迁移。完成服务端升级后，等待后台迁移完成即可；已有 MCP 服务地址和客户端调用方式不变。

2.6.1. 升级期间的正常现象

• 原有 MCP 管理接口继续可用；新版管理接口可能暂时返回 409 / RESOURCE_CONFLICT，此时先使用原有接口，并等待迁移完成。
• 全部节点完成升级、历史数据检查通过且已启用的检索索引准备好后，迁移才会完成。任务默认约每 5 分钟重试，可能需要等待多个周期。
• 通常保持 nacos.ai.mcp.resource.reconciliation.enabled=true，无需调整其他迁移参数，详见系统参数。

2.6.2. 升级后检查

确认所有节点健康、服务端日志记录迁移完成，并验证 MCP 列表、详情和新版管理接口可用。

2.6.3. 迁移未完成时如何排查

2.6.4. 回滚注意事项

MCP 迁移完成后，降级不会自动撤销新版管理数据。使用 MCP 的部署应在回滚前确认目标版本能否正确处理这些数据。

2.7. A2A 历史数据自动迁移

本节适用于从 Nacos 3.1.x～3.2.x 升级，且已使用 A2A Agent 管理或旧 A2A SDK 注册服务的部署。升级前，在所有目标版本节点配置：

nacos.ai.a2a.compatibility.mode=AUTO
nacos.ai.a2a.migration.legacy-naming-shadow-enabled=false

默认 CANONICAL 不会迁移历史 A2A 数据，已有 A2A 业务必须显式使用 AUTO。各节点应使用一致的 Agent Storage 和迁移配置，迁移开始后不要改变这些设置。

普通 A2A API/SDK 调用方保持 legacy-naming-shadow-enabled=false 即可。只有直接通过 Naming Gateway 读取旧 <legacyEncodedAgentName>::<exactVersion> 服务名的业务，才需要在迁移前设为 true，否则迁移完成后可能无法再通过这些旧服务名发现实例。其他迁移参数通常保持默认值，详见系统参数。

2.7.1. 升级期间的正常现象

历史迁移完成前，外部 RAD 的搜索、发现、发布、Endpoint 注册和订阅请求会返回 409 / AGENT_MIGRATION_IN_PROGRESS (50105)；gRPC 返回相同业务错误码。应等待迁移完成后重新发起请求或订阅。已有合法 Endpoint 的心跳、完整注销和本地取消订阅仍可执行。

先完成服务端升级和迁移，再升级依赖 RAD 的客户端。 新版 SDK 即使调用 A2A 方法，也可能使用 RAD 并受到上述限制，不会自动退回旧协议。

2.7.2. 升级后检查

确认全部节点已升级且健康，服务端日志记录迁移完成；检查已有 Agent 的名称、版本、内容和服务地址，并验证旧 A2A 调用和 RAD 发现均正常。

2.7.3. 迁移未完成时如何排查

2.7.4. 回滚注意事项

迁移完成前，可在当前版本将全部节点统一配置为 LEGACY 并滚动重启，以停止自动迁移。这不会回退服务端版本。

迁移完成后，不支持回到只能识别旧 A2A 数据的版本。确需回滚时，应先确认目标版本兼容性，并同时遵循第 2.8.1 节的限制。

2.8. 升级后验证与回滚准备

升级完成后至少验证：

1. 所有节点已升级并保持健康，日志中没有持续的节点通信、鉴权、数据库或插件加载错误。
2. 配置发布/查询、服务注册/发现和控制台登录正常；已开启鉴权的客户端能够正常访问。临时关闭鉴权的，确认后续开启时间。
3. 从 2.x 升级的部署，确认默认 namespace 配置和原有灰度规则生效。
4. 自定义插件已正确加载，配置和启用状态符合预期。
5. 使用 AI 资源检索或向量检索的，确认索引初始化完成且查询正常。
6. 使用 MCP 或 A2A 的，按第 2.6、2.7 节确认迁移完成，已有业务调用及新管理功能正常；直接使用旧 Naming Gateway 服务名的，还需验证服务发现。
7. 确认第 2.3.4 节中的旧 AI API 调用方已迁移，或已配置临时兼容开关。

保留升级前的发行包、配置、插件和数据备份直到观察期结束。

2.8.1. 回滚注意事项

升级过程中出现异常时，先暂停后续节点升级，检查节点身份、数据库变更和插件配置；能够通过修正配置恢复的，优先修复并验证。

升级完成、JRaft 鉴权自动启用后，不应直接滚动降级到不支持该鉴权的旧版本，否则可能导致节点间通信失败、集群不可用。关闭客户端鉴权不能解除这一限制。

如需回滚，应在升级前确认目标版本的兼容性并完成演练。尚未验证的回滚操作，请保留现场与日志，联系维护者确认处理方案。