兼容与废弃
Nacos 会在版本演进中保留一部分兼容能力，帮助用户完成升级和迁移。这些能力不是推荐的新模型。新接入和新开发应优先使用当前文档中的标准能力。
状态怎么理解
| 状态 | 含义 | 用户建议 |
|---|---|---|
| 标准能力 | 当前推荐使用的 API、SDK、配置或资源模型。 | 新系统直接使用。 |
| 仅兼容 | 为了避免破坏已有用户而保留。 | 只在迁移期使用，不要继续扩展依赖。 |
| 已废弃 | 仍可用，但后续可能移除。 | 尽快迁移到替代方案。 |
| 待移除 | 已废弃，且移除条件或方向已经明确。 | 制定迁移计划，不建议继续上线新用法。 |
| 实验性 | 尚未承诺稳定行为。 | 先小范围验证，接受后续不兼容调整。 |
常见兼容入口
| 场景 | 当前建议 | 继续阅读 |
|---|---|---|
| v1/v2 HTTP API | 迁移到 v3 OpenAPI 或当前 SDK。确有迁移窗口需求时，临时使用 legacy adapter。 | 升级手册、OpenAPI 概览 |
| 兼容开关 | 只在升级或迁移窗口期打开。稳定后关闭。 | 系统参数 |
| 废弃 v3 AI API | 旧 Pipeline 查询与 MCP 导入端点默认返回 410 Gone / API_DEPRECATED；迁移到标准入口，共享兼容开关只用于临时恢复。 | 受影响 API 与替代入口 |
| JRaft 节点间鉴权 | 配置一致的 Server identity，升级完成后自动启用；启用后不要直接滚动降级到不支持该鉴权的旧版本。 | 鉴权准备、回滚注意事项 |
| A2A 到 Agent/RAD | 保留旧 A2A 协议兼容；外部 RAD 在历史迁移完成前拒绝业务请求。先完成服务端迁移，再升级依赖 RAD 的客户端。 | 升级手册 |
| Beta/Tag 灰度配置兼容 | Nacos 3.3 起不再自动迁移旧 config_info_beta、config_info_tag 表，升级前需迁移到 config_info_gray 当前灰度模型。当前 beta/tag API 仍由 config_info_gray 和 GrayRule 支撑。 | 升级手册、配置灰度发布 |
| 默认命名空间迁移 | Nacos 3.3 起不再自动在空 tenant 与 public 之间做存储迁移或双写。空或省略 namespace 请求仍会归一为默认 namespace public。 | 升级手册、Java SDK 使用手册 |
| 插件管理重构 | 迁移到 pluginType:pluginName、标准 definition key 和统一状态。AI Resource Import 的旧双层 SPI/Source/preset 模型已移除。 | 插件迁移、AI 资源导入插件 |
| 旧控制台 | 仅用于兼容存量使用习惯。新部署使用新控制台。 | 控制台手册 |
| Java SDK 已废弃配置项 | 不在新系统中继续使用。 | Java SDK 属性配置 |
| CLI 已废弃命令 | 使用显式生命周期命令替代快捷 publish 命令。 | Nacos CLI 使用指南 |
| 实验性功能 | 只在明确接受变更风险后使用。 | 实验性功能概览 |
Nacos 3.3 配置兼容迁移移除
Nacos 3.3 移除了 Config 3.0 之前的运行时兼容迁移逻辑，包括默认 namespace 在 legacy 空 tenant 与 public 之间的存储迁移、旧 config_info_beta/config_info_tag 到 config_info_gray 的迁移，以及相关双写和混部同步逻辑。
从 2.x 升级仍属于有限支持，不应仅根据当前版本号判断历史数据已经迁移。若使用过默认 namespace 或旧 beta/tag 灰度表，应先在支持迁移的 3.0.x～3.2.x 完成空 tenant 到 public、旧灰度表到 config_info_gray 的迁移，并验证查询与灰度行为。若未使用这些数据，则不受这一项移除影响，但仍需满足其他升级条件。具体路径见升级手册。
这不是移除当前默认 namespace 语义，也不是移除当前 beta/tag 灰度 API。空或省略 namespace 请求仍归一为 public；当前 beta/tag 灰度行为仍由 config_info_gray 和 GrayRule 支撑。
插件管理与 AI Resource Import breaking change
next 版本插件使用统一身份、状态、配置来源和生命周期。历史实现如果未实现 PluginConfigSpec 仍可加载，但自动显示为 configurable=false。Config Change 的 ConfigChangeConfigs 已废弃但仍处于兼容周期。
AI Resource Import 是不兼容迁移：AiResourceImportSource、Source Provider SPI、preset、nacos.ai.resource.import.sources[N].* 以及通过配置复制同一实现到多个 endpoint 的模型均已移除。一个 pluginName 现在对应一个确定来源，sourceId 等于 managed pluginName；旧 API 的 pluginName 字段继续表示 importerType。新部署使用 nacos.plugin.ai-resource-import.*，迁移清单见插件迁移。
使用兼容能力时要确认什么
- 它是否只是为了升级或迁移临时使用。
- 是否有明确的替代 API、SDK、配置或资源模型。
- 是否会改变鉴权、可见性、响应格式、性能或数据一致性。
- 是否需要额外安装插件、adapter 或独立组件。
- 迁移完成后如何关闭兼容开关或移除兼容组件。
不建议的做法
- 在新业务中主动依赖旧 API 或已废弃 SDK 方法。
- 把兼容字段当作新的资源语义。
- 长期打开短期兼容开关而不做迁移。
- 用 Console API 作为自动化系统的长期稳定接口。
- 把实验性功能当作稳定生产能力。