Nacos 3.3.0 升级笔记：Client API 鉴权默认开启，插件配置 key 集体改名
项目地址：https://github.com/alibaba/nacos
发布公告：https://nacos-group.github.io/blog/release-330/
Nacos 3.3.0 已正式发布。这个版本的重心在 AI Registry：协议无关的 Agent 注册发现、统一的 ARD 资源检索、MCP 与 Skill 生命周期管理。同时新增 DNS 服务发现，增强实验性分布式锁，并继续调整配置管理、服务发现和安全相关的实现。
对准备升级的集群来说，真正需要逐项核对的是兼容性变更，新功能可以稍后再看。
AI Registry 相关的用途可以概括为：ARD 负责“按任务找资源”，应用围绕当前任务搜索 Agent、Skill、Prompt、MCP 等资源，再读取说明和内容，不需要把全部资源描述塞进模型上下文；它默认关闭，通过 nacos.ai.ard.enabled=true 开启，使用 AI Registry 适配器的独立端口，默认 9080，向量检索需要另外配置服务。RAD（Remote Agent Discovery）负责发现 Agent 运行端点、协商传输协议并订阅端点变化，配套 Java SDK 和控制台。
下面按升级时容易踩到的顺序整理。
Client API 鉴权默认开启
从 3.3.0 开始，未配置 nacos.core.auth.enabled 时，其默认值变为 true。此前依赖默认配置、未提供凭据的客户端，升级后会遇到鉴权失败。
升级前要检查三类位置：
- 服务端配置；
- 业务应用使用的凭据；
- 脚本和运维工具使用的凭据。
已有显式 nacos.core.auth.enabled=false 配置仍然生效。Admin API 和 Console API 的鉴权默认值没有变化，不要混在一起判断。
需要分阶段启用鉴权的集群，可以先保留原有显式配置，完成客户端凭据配置和验证后，再统一开启。直接删掉配置让默认值生效，等同于一次性打开鉴权。
插件配置 key 调整
插件实现参数统一为 nacos.plugin.{pluginType}.{pluginName}.{itemKey} 的命名方式。原公告给出的主要对应关系如下：
| 配置范围 | 原配置 key | 新配置 key |
|---|---|---|
| 鉴权插件选择 | nacos.core.auth.system.type | nacos.plugin.auth.type |
| 默认鉴权插件的 Token 参数 | nacos.core.auth.plugin.nacos.token.* | nacos.plugin.auth.nacos.token.* |
| 鉴权信息缓存 | nacos.core.auth.caching.enabled | nacos.plugin.auth.nacos.caching.enabled |
| AI 匿名访问 | nacos.core.auth.nacos.anonymous.ai.enabled | nacos.plugin.auth.nacos.anonymous.ai.enabled |
| LDAP 参数 | nacos.core.auth.ldap.* | nacos.plugin.auth.ldap.{itemKey}，部分字段名同步调整 |
| OIDC 参数 | nacos.core.auth.plugin.oidc.* | nacos.plugin.auth.oidc.* |
| 数据库方言选择 | spring.sql.init.platform | nacos.plugin.datasource-dialect.type |
| 数据库连接与连接池参数 | db.* | nacos.plugin.datasource.db.*，连接池字段使用标准连字符命名 |
| 数据库查询超时 | JVM 参数 QUERYTIMEOUT | nacos.plugin.datasource.db.query-timeout |
| 流控插件选择 | nacos.plugin.control.manager.type | nacos.plugin.control.type |
| 配置变更插件启用状态 | nacos.core.config.plugin.{pluginName}.enabled | nacos.plugin.config-change.{pluginName}.enabled |
| 可见性插件选择 | nacos.plugin.visibility.type | nacos.plugin.visibility.{pluginName}.enabled，按实现管理启用状态 |
| AI Pipeline 启动链 | nacos.plugin.ai-pipeline.type | nacos.plugin.ai-pipeline.{pluginName}.enabled，按实现管理启用状态 |
| AI 资源导入总开关 | nacos.ai.resource.import.enabled | nacos.plugin.ai-resource-import.enabled |
| 内置资源导入插件启用状态 | nacos.plugin.ai.importer.*.enabled | nacos.plugin.ai-resource-import.{pluginName}.enabled |
除了前缀变化，部分字段也改了名称：
- LDAP：
basedc→base-dn，userDn→user-dn； - 连接池：
maximumPoolSize→maximum-pool-size； - AI Pipeline 中 Skill Scanner：
useLlm→use-llm，llmApiKey→llm-api-key。
已有配置可以通过保留的历史别名继续读取，服务端会输出迁移提示。新部署和更新后的部署模板应使用新的标准 key。
四条规则
- 新 key 优先于旧 key，空值同样生效。 如果新模板已经包含某个标准 key，即使其值为空，也不会回退读取旧 key。实际配置值要迁移到新 key，避免新模板中的空值或默认值覆盖已有配置。这是最容易出问题的一条。
- 是否需要重启，由配置项的生效模式决定。 鉴权插件选择、数据库连接参数、Token 密钥及 LDAP/OIDC 参数等仍需重启生效；只有支持运行时更新的配置项才能通过插件管理接口动态修改。
- 静态启用配置只用于确定插件的初始状态。 如果已经通过插件管理接口保存了运行时配置或启停状态，这些值可能优先于配置文件。排查配置未生效时，要同时查看插件当前状态和配置来源。
- 部分旧导入配置需要重新整理。 旧
nacos.ai.resource.import.sources[N].*来源模型已移除，不提供自动迁移，需要按受管导入插件重新配置来源；旧nacos.plugin.ai.importer.*中保留的等价参数也要逐项迁移。对尚未接入统一配置定义的第三方配置变更插件，其参数仍通过旧的nacos.core.config.plugin.{pluginName}.{propertyKey}兼容路径传入。
nacos.core.auth.enabled、Admin/Console 鉴权开关和服务端身份配置等核心配置保持原有名称。迁移应按配置项核对，不要对所有 nacos.core.* 参数直接替换前缀。
历史 A2A 数据要设 AUTO 才会迁移
3.3.0 保留了原有 A2A 接口，并提供历史数据兼容迁移流程。已有历史 A2A 数据的集群，需要按升级指南启用：
nacos.ai.a2a.compatibility.mode=AUTO
默认的 CANONICAL 模式不会扫描和迁移历史 A2A 数据，只更换安装包不会触发迁移。
滚动升级期间，历史 A2A 数据继续作为读写依据；待集群成员能力、数据同步和校验条件满足后，Nacos 自动协调迁移与切换，把已有 Agent 纳入新的 Agent 模型和 RAD 体系。切换完成后，不要再让仅支持旧逻辑的服务端节点重新加入。
MCP 后台对账后切换生命周期
3.3.0 把 MCP 纳入统一生命周期，同时保留已有客户端和网关使用的服务数据。升级后 Nacos 会在后台核对历史 MCP 数据，建立对应的资源和版本记录；在数据一致、所有成员具备相应能力后，再切换到新的管理流程。
迁移期间原有 MCP 管理路径继续工作，新的生命周期写操作需要等待切换完成。历史 Config、Naming 数据及其服务方式保持兼容。控制台出现新资源记录后，底层历史数据先别清理；切换完成后不要再让旧节点承接 MCP 管理写入。
其他兼容变化
- 已废弃接口：部分旧 Pipeline 和 MCP 导入接口默认返回 HTTP 410，仍在使用这些接口的应用应迁移到新接口。
nacos.core.api.compatibility.enabled=true可作为临时过渡配置。 - 更早版本的数据：从 3.0 之前的版本升级，需要先经过较早的 3.x 版本，完成历史配置数据迁移。保留了旧版无类型标记 Raft 日志的集群，也需要先处理对应数据，单纯更换运行版本不会转换已有日志。
- BETA / RC Agent SDK：新增的 RAD
subscribeAgent方法返回值调整为void，初始状态和后续变化统一通过 Listener 接收。使用这些接口的应用需要适配并重新编译。 - 客户端监控：
nacos-client不再强制依赖 Prometheus 客户端。需要采集客户端指标时，由应用向 Micrometer 的Metrics.globalRegistry注册具体的MeterRegistry，并配置相应的指标导出。
运行环境
Nacos Server 和 Console 需要 Java 17 及以上；Nacos Client 和 Maintainer Client 继续支持 Java 8 及以上。服务端升级至 Spring Boot 4.0.6，并完善了 Jackson 2 / Jackson 3 适配。
DNS 服务发现与分布式锁
DNS 服务发现支持通过 UDP、TCP 查询 A、AAAA 和 SRV 记录，给不方便引入 SDK 的应用提供接入方式。DNS 默认关闭，启用后默认只监听本机地址，需要远程访问时要配置监听地址。
分布式锁仍是实验性能力，提供 Java SDK，支持可重入、看门狗续约和 FIFO 等待。
同期发布的 Nacos 2.5.5
继续使用 2.x 的团队有 2.5.5 可选。该版本以问题修复和稳定性改进为主，增强了服务端文件路径及 HTTP 健康检查校验，修复集群整体重启时服务实例丢失、gRPC 报文异常、HTTP 请求处理和集群成员一致性问题。服务端和客户端保持 Java 8 基线。升级前建议结合发布说明检查已有的路径配置和自定义 HTTP 健康检查配置。