nacos-go-sdk 从 v2 升级到 v3

[AlexStocks]

apache/dubbo-go Nacos v2 to v3 升级方案

1. 背景

dubbo-go-samples 中的 Nacos v3 验证不应作为升级起点。Sample 只能证明某个示例链路是否跑通，无法定义 apache/dubbo-go 对 Nacos 3.x 的真实兼容边界。本次升级应从 apache/dubbo-go 主仓开始，先完成框架层的 Nacos 3.x 兼容性确认、必要改造和自动化验证，再使用 dubbo-go-samples 作为集成验收入口。

当前 apache/dubbo-go 已经依赖 github.com/nacos-group/nacos-sdk-go/v2 v2.2.5，并且已有 Nacos 注册中心、配置中心和元数据中心实现。升级的重点不是新增 Nacos 支持，而是确认现有实现能否在 Nacos 3.x 下稳定工作，并补齐鉴权、命名空间、数据库迁移、生命周期和回滚策略。

2. 升级目标

本次升级目标如下：

• 确认 apache/dubbo-go 对 Nacos 3.x 的支持范围和限制。
• 保证注册中心、配置中心、元数据中心三条 Nacos 链路在 Nacos 3.x 下行为可验证。
• 明确鉴权开启和关闭两种模式下的客户端配置方式。
• 明确 Nacos 服务端数据库 schema 变更和回滚策略。
• 建立可复现的自动化测试、集成测试和 samples 验收流程。
• 形成一条可以灰度发布、可以回滚、可以定位失败原因的升级路径。

本方案不以“只跑通 dubbo-go-samples/registry”为成功标准。最终成功标准必须落在 apache/dubbo-go 主仓能力上。

3. 当前主仓基线

3.1 依赖基线

主仓当前使用：

github.com/nacos-group/nacos-sdk-go/v2 v2.2.5

这说明当前代码已经处于 Nacos Go SDK v2 客户端体系内。根据 Nacos 官方升级文档，Nacos 3.x server 与 2.x client 兼容，因此第一阶段不应默认升级 SDK，而应先验证当前 SDK 在 dubbo-go 现有封装下的实际表现。

参考：

• https://nacos.io/en/docs/latest/manual/admin/upgrading/
• https://github.com/apache/dubbo-go/blob/main/go.mod

3.2 dubbo-go 中的 Nacos 入口

主仓至少存在三类 Nacos 能力入口：

• 注册中心：registry/nacos
• 配置中心：config_center/nacos
• 元数据中心：metadata/report/nacos

底层客户端构造逻辑集中在：

• remoting/nacos/builder.go

该文件负责从 common.URL 中解析 Nacos 服务地址、namespace、用户名、密码、AK/SK、timeout、endpoint、cache、log 等客户端配置。因此，本次升级需要重点验证 common.URL -> nacos ClientConfig/ServerConfig -> SDK client 的参数映射是否完整、明确、可诊断。

4. 升级原则

4.1 主仓优先

升级顺序必须是：

1. apache/dubbo-go 主仓完成兼容性确认和必要改造。
2. 主仓测试和集成环境验证通过。
3. dubbo-go-samples 更新配置和运行手册。
4. 使用 samples 作为最终验收和用户文档验证。

不能先在 samples 中绕过主仓问题，否则容易出现示例跑通但真实用户场景失败的情况。

4.2 不默认升级 SDK

第一阶段先基于当前 nacos-sdk-go/v2 v2.2.5 验证 Nacos 3.x。只有出现明确的 SDK 缺陷或官方文档要求时，才升级 SDK。

SDK 升级需要单独评审：

• 是否引入破坏性 API 变化。
• 是否改变默认超时、缓存、日志、鉴权行为。
• 是否影响现有 Nacos 2.x 用户。
• 是否需要同步更新 mock、单测和文档。

4.3 鉴权分层处理

Nacos 3.x 的鉴权必须拆成两条线：

• 控制台鉴权。
• 客户端访问鉴权。

官方文档中 nacos.core.auth.enabled 默认值为 false，用于客户端访问鉴权；nacos.core.auth.console.enabled 默认值为 true，用于控制台访问鉴权。Nacos 3.0 起控制台访问默认开启鉴权，但这不等价于客户端注册发现默认必须带用户名密码。

因此，升级方案中不能简单写“v3 默认开启鉴权，所以客户端必须配置用户名密码”。正确表达应为：

• 如果只开启控制台鉴权，dubbo-go 客户端注册发现不一定需要用户名密码。
• 如果开启 nacos.core.auth.enabled=true，dubbo-go 客户端必须正确传递用户名密码或其他认证参数。
• 鉴权失败必须在启动或注册阶段有明确日志和错误信息。

参考：

• https://nacos.io/docs/v3.0/manual/admin/auth/

4.4 数据库不可被当成透明实现细节

Nacos 3.2.x 支持从 2.0.x ~ 3.1.x 升级，但官方文档明确说明数据库 schema 有变化，升级前需要对比并应用新的 mysql-schema.sql。Nacos 3.2.0 还新增 AI 相关表。

因此，回滚策略不能只写“切回 Nacos v2”。如果 v2 和 v3 共用同一数据库，schema 变化可能已经影响回滚边界。首次验证必须优先使用独立数据库或由备份恢复出的数据库副本。

5. 影响范围

5.1 注册中心

注册中心需要覆盖：

• Provider 注册。
• Provider 反注册。
• Consumer 订阅。
• Consumer 取消订阅。
• 全量服务查询。
• 实例列表变化监听。
• Nacos 重启后的恢复。
• 网络抖动后的恢复。
• 鉴权失败时的错误暴露。

重点代码区域：

• registry/nacos/registry.go
• registry/nacos/listener.go
• remoting/nacos/builder.go

重点风险：

• RegisterInstance 返回 false 但 error 为空时是否有明确错误。
• Subscribe 失败后的重试是否会退出过早或无限泄露 goroutine。
• Destroy 中关闭监听器、反注册、关闭 client 的顺序是否稳定。
• IsAvailable 使用 GetAllServicesInfo 探活时，在 Nacos 3.x 鉴权失败或异常返回下是否会误判。

5.2 配置中心

配置中心需要覆盖：

• 读取配置。
• 发布配置。
• 删除配置。
• 监听配置变更。
• 取消监听。
• 按 group 查询配置 key。
• 空 namespace 与 public namespace 的兼容。

重点代码区域：

• config_center/nacos/impl.go
• config_center/nacos/client.go
• config_center/nacos/facade.go
• remoting/nacos/builder.go

重点风险：

• Nacos 3.0 对 config namespace 做了迁移和兼容处理，namespaceId="" 与 namespaceId="public" 的行为需要显式验证。
• Destroy 直接关闭 done，需要确认重复调用或异常初始化失败时不会 panic。
• 配置不存在错误不能被误判为连接失败。

5.3 元数据中心

元数据中心需要覆盖：

• 应用元数据发布。
• 应用元数据读取。
• 服务到应用映射发布。
• 服务到应用映射读取。
• 映射监听。
• 映射取消监听。

重点代码区域：

• metadata/report/nacos/report.go
• remoting/nacos/builder.go

重点风险：

• 元数据中心复用 Nacos config client，容易被配置中心 namespace 迁移影响。
• 当前实现兼容 Java 元数据格式和 dubbo-go 旧格式，升级测试必须同时覆盖两种 dataId/group 组合。
• CreateMetadataReport 返回 nil 时上层是否能明确处理。

6. 目标版本与环境矩阵

6.1 Nacos 服务端版本

建议至少准备以下环境：

环境	Nacos 版本	用途
基线环境	当前生产或样例使用的 Nacos 2.x	对照组
目标环境	Nacos 3.2.x	本次主要升级目标
兼容环境	Nacos 3.0.x 或 3.1.x	如需声明泛 3.x 支持时使用

如果只计划支持 Nacos 3.2.x，不要在文档中承诺“支持所有 3.x”。可以写成“本次以 Nacos 3.2.x 为验收目标，其他 3.x 小版本仅做兼容参考”。

6.2 鉴权矩阵

必须验证两种模式：

模式	服务端配置	客户端期望
客户端鉴权关闭	nacos.core.auth.enabled=false	不配置用户名密码也能注册、发现、读写配置
客户端鉴权开启	nacos.core.auth.enabled=true	必须配置用户名密码，认证失败要有明确错误

控制台鉴权单独验证，不作为客户端兼容结论。

6.3 数据库矩阵

首次升级验证建议使用：

数据库	策略
v2 基线库	保持不变，只读对照
v3 验证库	从 v2 备份恢复后执行 schema 升级
回滚验证库	从升级前备份恢复，验证回滚步骤

禁止在没有备份和回滚演练的情况下让 v3 首次验证直接连接生产 v2 数据库。

7. 实施阶段

7.1 阶段一：事实盘点

输出一份影响清单，包含：

• 当前 dubbo-go 依赖的 nacos-sdk-go 版本。
• 所有 Nacos 相关 package。
• 所有 Nacos 配置项。
• 注册中心、配置中心、元数据中心是否都在目标业务中启用。
• samples 中实际依赖 Nacos 的 demo 清单。

建议命令：

go list -m github.com/nacos-group/nacos-sdk-go/v2
grep -R "nacos" -n registry config_center metadata remoting config common

Windows 环境可使用 PowerShell：

Get-ChildItem -Recurse -File | Select-String -Pattern "nacos"

阶段退出标准：

• 影响范围明确。
• 不存在“只知道 registry，遗漏 config center 或 metadata report”的情况。

7.2 阶段二：本地兼容性验证

启动两套 Nacos：

• Nacos 2.x：基线。
• Nacos 3.2.x：目标。

每套环境都跑同一批 dubbo-go 测试和最小集成链路。

验证内容：

• 当前 nacos-sdk-go/v2 v2.2.5 是否能连接 Nacos 3.2.x。
• remoting/nacos/builder.go 生成的 ServerConfig 和 ClientConfig 是否正确。
• 地址、context path、namespace、group、username、password、timeout 是否按预期传入 SDK。

阶段退出标准：

• Nacos 3.2.x 下注册中心最小链路可运行。
• 鉴权关闭和开启模式各有明确结论。
• 如果失败，能定位到服务端配置、dubbo-go 参数映射、SDK 行为或样例配置中的某一类。

7.3 阶段三：主仓改造

根据阶段二结果决定是否需要改代码。

优先改造项：

• 补齐 Nacos 3.x 鉴权配置文档和示例。
• 增强 Nacos client 初始化错误信息，避免把认证失败、地址错误、namespace 错误全部包装成模糊错误。
• 补充 remoting/nacos/builder.go 的单元测试，覆盖 Nacos 3.x 关键参数。
• 补充 registry/config center/metadata report 在鉴权失败、连接失败、配置不存在下的错误路径测试。
• 如发现生命周期问题，修复 Destroy、listener、retry、client close 顺序。

SDK 升级不是默认动作。只有满足以下条件之一时才升级：

• Nacos 3.x 目标功能要求新版 SDK。
• 当前 SDK 在 Nacos 3.x 下存在已确认缺陷。
• 官方文档或 issue 明确建议升级。
• 新版 SDK 修复了本次升级阻塞问题，且对 Nacos 2.x 用户无破坏性影响。

阶段退出标准：

• 主仓单测通过。
• Nacos 相关新增测试覆盖关键分支。
• 不引入对 Nacos 2.x 的兼容性回退。

7.4 阶段四：集成测试

集成测试需要覆盖三条链路。

注册中心：

• Provider 启动并注册成功。
• Consumer 发现 provider。
• RPC 调用成功。
• Provider 停止后 Nacos 实例下线。
• Provider 重启后 Consumer 能恢复调用。
• Nacos 重启后实例和订阅最终恢复。

配置中心：

• 发布配置成功。
• 读取配置成功。
• 监听配置变更成功。
• 删除配置后读取行为符合预期。
• namespaceId="" 和 namespaceId="public" 场景有明确结论。

元数据中心：

• 应用元数据发布成功。
• 应用元数据读取成功。
• 服务应用映射发布成功。
• 映射监听能收到变更。
• Java 兼容格式和 dubbo-go 旧格式都能覆盖。

阶段退出标准：

• 三条链路在 Nacos 3.2.x 下全部通过。
• 失败路径有日志，有错误，有归因。

7.5 阶段五：samples 验收

主仓通过后，才进入 samples。

samples 的职责：

• 验证用户可理解的配置方式。
• 验证 README 和命令是否可复现。
• 验证 registry、config center、metadata 场景是否能作为用户示例。

samples 不负责定义主仓兼容策略。

需要输出：

• Nacos 2.x 运行结果。
• Nacos 3.2.x 运行结果。
• 鉴权关闭运行结果。
• 鉴权开启运行结果。
• 失败样例和原因列表。

阶段退出标准：

• samples 文档能指导用户启动 Nacos 3.x。
• 用户不需要读主仓源码即可配置用户名、密码、namespace、group。
• 失败场景有明确排查入口。

8. 数据库升级方案

8.1 首次验证

首次验证不得直接改生产或共享 v2 数据库。

推荐步骤：

1. 备份 v2 Nacos 数据库。
2. 恢复到独立 v3 验证库。
3. 对比当前版本和目标版本的 mysql-schema.sql。
4. 执行 Nacos 官方要求的 schema 变更。
5. 启动 Nacos 3.2.x。
6. 查看 logs/startup.log 和 logs/nacos.log。
7. 通过 dubbo-go 注册、配置、元数据链路验证数据可用。

8.2 回滚边界

如果 v3 使用独立数据库，回滚方式是切回 v2 Nacos 地址和 v2 数据库。

如果 v2 和 v3 共用数据库，回滚必须满足：

• 升级前有完整数据库备份。
• 已演练从备份恢复到 v2。
• 明确 schema 变更是否可逆。
• 明确 v3 运行期间写入的新数据是否需要迁回 v2。

不能在共库方案里承诺“配置切换即可回滚”。

8.3 Config Namespace 迁移

Nacos 3.0 将配置中心的空 namespace 与 public namespace 做了统一和兼容处理。官方文档说明，兼容模式默认开启，可通过 nacos.config.namespace.compatible.mode 关闭；关闭后将不再具备平滑降级能力。

因此：

• 升级初期保持兼容模式开启。
• 验证配置中心读写和监听后，再评估是否关闭兼容模式。
• 关闭兼容模式前必须确认不再需要平滑回退到旧行为。
• 如果日志中出现 namespace 迁移冲突，需要先清理冲突配置，再继续验证。

9. 鉴权升级方案

9.1 服务端配置

如果开启客户端鉴权，Nacos 服务端至少需要配置：

nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true
nacos.core.auth.plugin.nacos.token.secret.key=${custom_base64_token_secret_key}
nacos.core.auth.server.identity.key=${custom_server_identity_key}
nacos.core.auth.server.identity.value=${custom_server_identity_value}

Docker 环境至少需要：

NACOS_AUTH_ENABLE=true
NACOS_AUTH_TOKEN=${custom_base64_token_secret_key}
NACOS_AUTH_IDENTITY_KEY=${custom_server_identity_key}
NACOS_AUTH_IDENTITY_VALUE=${custom_server_identity_value}

9.2 dubbo-go 客户端配置

dubbo-go 侧应通过现有配置字段传递认证信息：

dubbo:
  registries:
    nacos:
      protocol: nacos
      address: 127.0.0.1:8848
      username: nacos
      password: ${NACOS_PASSWORD}
      namespace: public
      group: DEFAULT_GROUP

配置中心和元数据中心也需要分别验证用户名、密码、namespace、group 是否正确透传。不能只验证 registry。

9.3 失败行为

必须覆盖以下失败场景：

• 未配置用户名密码但服务端开启客户端鉴权。
• 用户名错误。
• 密码错误。
• namespace 不存在。
• group 配置错误。
• token secret 或 server identity 配置不一致。

验收要求：

• 错误不能被吞掉。
• 日志必须能区分认证失败和网络失败。
• Provider 不应在注册失败后表现为“启动成功但不可发现”。

10. 测试方案

10.1 单元测试

建议补充或确认以下测试：

• remoting/nacos/builder.go：URL 到 Nacos config 的映射。
• registry/nacos：注册、反注册、订阅、取消订阅参数构造。
• config_center/nacos：配置不存在、发布失败、删除失败、监听失败。
• metadata/report/nacos：metadata dataId/group 兼容格式。

10.2 集成测试

建议通过 Docker Compose 或 CI service 启动 Nacos 2.x 和 3.2.x。

测试矩阵：

链路	Nacos 2.x	Nacos 3.2.x 鉴权关	Nacos 3.2.x 鉴权开
Registry register/unregister	必测	必测	必测
Registry subscribe/unsubscribe	必测	必测	必测
RPC provider/consumer	必测	必测	必测
Config get/publish/delete/listen	如当前支持	必测	必测
Metadata publish/read/listen	如当前支持	必测	必测

10.3 稳定性测试

稳定性测试至少包含：

• 长稳运行 24 小时。
• Provider 每 30 秒重启一次，持续 30 分钟。
• Nacos 单节点重启。
• Nacos 全集群滚动重启。
• Consumer 持续调用，观察错误率和恢复时间。
• 注册实例数量放大到至少 100 个。
• 订阅服务数量放大到至少 100 个。

10.4 资源泄露测试

重点观察：

• goroutine 数量。
• Nacos SDK client 数量。
• listener cache 大小。
• 连接数。
• 日志错误频率。
• 进程内存。

特别关注订阅失败重试、Nacos 重启、Consumer 销毁、配置监听取消这些路径。

11. 发布方案

11.1 发布阶段

建议按以下顺序推进：

1. 本地验证：开发者本地运行 Nacos 3.2.x。
2. CI 验证：新增 Nacos 3.2.x 集成测试。
3. 测试环境：业务应用连接 Nacos 3.2.x 验证。
4. 预发环境：开启与生产一致的鉴权、namespace、group、数据库配置。
5. 生产灰度：少量 Provider 和 Consumer 切到 Nacos 3.2.x。
6. 全量切换：观察稳定后全量切换。

11.2 灰度策略

优先采用双环境灰度：

• Nacos 2.x 保持原链路。
• Nacos 3.2.x 使用独立地址和数据库。
• dubbo-go 应用通过配置切换 registry/config/metadata 地址。

如果业务允许，可评估双注册：

• Provider 同时注册到 v2 和 v3。
• Consumer 分批切到 v3。
• 灰度期间对比 v2/v3 实例数、健康状态和调用成功率。

双注册需要单独评审，不应默认纳入第一阶段。

11.3 观测指标

发布期间必须观察：

• 注册成功率。
• 反注册成功率。
• 订阅成功率。
• RPC 成功率。
• RPC P99 延迟。
• Consumer 实例列表为空次数。
• Provider 频繁上下线次数。
• Nacos 登录或鉴权失败次数。
• Nacos server CPU、内存、连接数、数据库 QPS。
• dubbo-go 进程 goroutine、内存、日志错误数。

12. 回滚方案

12.1 可快速回滚的前提

只有满足以下条件时，才能承诺快速回滚：

• v2 Nacos 环境保持运行。
• v2 数据库未被 v3 schema 或 v3 写入破坏。
• 应用配置可以快速切回 v2 地址。
• 没有关闭 Nacos 3.x config namespace 兼容模式。
• 业务没有只写入 v3 而未同步回 v2 的关键配置或元数据。

12.2 回滚步骤

推荐步骤：

1. 停止继续扩大 v3 灰度。
2. 将 Consumer 配置切回 v2 Nacos。
3. 将 Provider 配置切回 v2 Nacos。
4. 确认 Provider 在 v2 控制台可见。
5. 确认 Consumer 能发现实例。
6. 确认 RPC 调用恢复。
7. 保留 v3 环境现场日志和数据库，不立即清理。
8. 汇总失败原因后再决定是否重试升级。

12.3 不可快速回滚场景

以下情况不能写作快速回滚：

• v2 和 v3 共用数据库且无恢复演练。
• 关闭了 namespace 兼容模式。
• 业务配置只在 v3 修改，v2 不具备同等数据。
• 应用代码已经依赖只在 Nacos 3.x 存在的行为。

13. 验收标准

本次升级完成必须满足：

• apache/dubbo-go 主仓明确声明支持的 Nacos 3.x 版本。
• registry、config center、metadata report 三条链路均有验证结论。
• 鉴权开启和关闭两种模式均有测试结果。
• 数据库升级和回滚策略可执行。
• Nacos 2.x 回归通过，不破坏存量用户。
• dubbo-go-samples 能作为用户示例跑通 Nacos 3.x。
• 文档中说明 username、password、namespace、group、auth 开关和数据库 schema 注意事项。
• 所有 P0/P1 问题关闭后才能进入生产灰度。

14. 待办清单

P0

• 确认目标 Nacos 3.x 小版本，禁止泛化承诺所有 3.x。
• 使用独立数据库完成 v3 schema 升级验证。
• 验证 registry/config center/metadata report 三条链路。
• 验证客户端鉴权开启时 username/password 透传。
• 验证回滚流程，不能只写配置切回。

P1

• 补充 remoting/nacos/builder.go 参数映射测试。
• 补充 Nacos 鉴权失败、namespace 错误、连接失败的错误路径测试。
• 补充 samples 的 Nacos 3.x 配置示例。
• 补充 Nacos 3.x 运行手册，包括 Docker 环境变量和管理员密码初始化。
• 补充长稳和资源泄露测试记录。

15. 最终结论

Nacos v2 到 v3 的升级应从 apache/dubbo-go 主仓开始，而不是从 dubbo-go-samples 开始。主仓需要先证明自身 Nacos 适配层在 Nacos 3.x 下的行为稳定、可诊断、可回滚，再让 samples 作为用户侧验收。

本次升级的核心风险不在“能不能连接 Nacos 3.x”，而在：

• 鉴权是否被正确理解和配置。
• 数据库 schema 变更是否破坏回滚边界。
• config namespace 迁移是否影响配置中心和元数据中心。
• 注册、订阅、监听、销毁生命周期是否在异常场景下稳定。
• Nacos 2.x 存量用户是否被兼容性改造影响。

只有这些风险都有明确结论后，才能认为 dubbo-go 对 Nacos 3.x 的升级方案完成。

[AlexStocks]

补充：

从 apache/dubbo-go 主仓开始升级，再用 dubbo-go-samples 做验证层”的思路，从零写一版完整方案。

先给结论：这不是 sample 的升级文档，而是 dubbo-go 对 Nacos 3.x 的兼容改造与验证方案。样例只负责证明主仓改造后的行为是对的，不应该反过来主导方案。

升级目标
把 apache/dubbo-go 当前基于 nacos-sdk-go/v2 的注册中心、配置中心、元数据报告能力，升级成一套能稳定对接 Nacos 3.x 的实现，并给出可回滚、可验证、可分阶段发布的落地路径。

当前基线
仓库里现在已经在用 github.com/nacos-group/nacos-sdk-go/v2 v2.2.5，而且 RegistryConfig 已经具备 username/password/namespace/accessKey/secretKey 这些透传字段，registry/nacos/registry.go 也已经把这些参数映射进 Nacos 客户端初始化流程。所以这次升级的重点不是“从零接入 Nacos”，而是“把现有接入改造成可稳定支持 Nacos 3.x 的形态”。
参考：go.mod，config/registry_config.go，registry/nacos/registry.go

推荐路径
我建议走下面这条主线：

1. 先锁定兼容边界，不先动 sample。
2. 在 apache/dubbo-go 中梳理所有 Nacos 入口，明确 registry、config center、metadata report 三条链路各自是否受影响。
3. 补齐 Nacos 3.x 的环境约束、鉴权约束、数据库约束和回滚约束。
4. 先做兼容性改造和自动化测试，再让 samples 做集成验收。
5. 最后再决定是否需要单独升级 SDK 版本。

为什么不是先从 samples 开始
因为 samples 只能暴露“现象”，不能定义“能力边界”。真正的升级风险在主库里：

• 注册/订阅的生命周期管理
• 鉴权参数透传
• 命名空间和分组兼容
• 监听器和重试逻辑
• 元数据和配置中心是否一起受影响

这些都在 apache/dubbo-go 里，不在 samples 里。

方案正文

1. 升级目标版本与范围

先明确目标不是“所有 3.x 都一次性覆盖”，而是“以业务实际准备上线的 Nacos 3.x 小版本为目标，先完成主干兼容，再做版本回归”。

范围建议分三层：

• 第一层：注册中心 nacos 兼容
• 第二层：配置中心 nacos 兼容
• 第三层：元数据上报/发现链路兼容

如果你们当前只用了注册中心，第二层和第三层可以作为后续波次，但必须在方案里显式写明，不要默认跳过。

2. 前置调研与风险确认

这一阶段只做事实确认，不改代码。

要确认四件事：

• Nacos 3.x 目标版本号
• 是否启用鉴权
• 是否共用数据库
• 是否启用配置中心和 metadata center

官方文档明确说明：Nacos 3.x server 与 2.x client 是兼容的；同时 Nacos 3.x 的客户端鉴权开关默认是 false，但控制台鉴权默认是开启的。也就是说，升级方案不能把“控制台能登录”和“客户端能注册”混为一谈。
参考：Nacos 升级手册，Nacos 权限校验

3. 主仓改造项

这部分才是方案核心。

3.1 配置透传与初始化校验

检查并补强 RegistryConfig 到 Nacos 客户端的映射，至少覆盖：

• namespace
• username/password
• accessKey/secretKey
• timeout
• group
• registry type

目标不是简单“能传进去”，而是：

• 参数缺失时有明确报错
• 参数冲突时能在启动期失败
• 不要把认证失败包装成模糊的注册失败

3.2 注册与订阅生命周期

重点核查 registry/nacos/registry.go 里的几个行为：

• 注册后是否有完整注销路径
• 订阅失败后的重试是否会泄露 goroutine
• Destroy() 是否会正确关闭监听器、关闭 client、等待退出
• IsAvailable() 的缓存逻辑在 Nacos 3.x 下是否会导致假阳性或假阴性

这部分不一定要改接口，但必须做针对性回归，因为 Nacos 3.x 的连接、心跳、鉴权失败表现，往往会直接暴露在这里。

3.3 命名空间和分组语义

如果升级涉及 config center，就必须补一段关于 namespace 迁移的说明。Nacos 3.0 对 config namespace 做过兼容和迁移处理，默认存在兼容模式，且关闭后无法再平滑降级。
这意味着方案里要写清楚：

• 是否允许 public 和空 namespace 并存
• 是否要先做 namespace 数据迁移
• 是否允许关闭兼容模式
• 如何验证迁移完成

参考：Nacos 升级手册

4. 数据库与环境准备

这是原方案最容易写虚的地方，我建议写得硬一点。

4.1 数据库策略

不要把 v2 和 v3 放在同一个数据库实例里做首次验证。建议：

• v2 保持原库，冻结不动
• v3 使用独立数据库或独立备份恢复出来的库
• 首次升级前先做 schema diff
• 先验证升级脚本，再验证业务数据迁移

如果必须共库，那就必须写清楚：

• 回滚点
• 备份策略
• 恢复步骤
• 哪些表可以回退，哪些不能回退

4.2 鉴权策略

分成两条线写：

• 控制台鉴权
• 客户端鉴权

验证时要明确：

• 是否开启客户端鉴权
• username/password 是否必须配置
• 未配置时是否应当启动失败
• 密钥和 token secret 是否由谁管理

不要把“能打开控制台”当成“客户端可用”。

5. 测试矩阵

这部分建议写成验收清单，不要只写“跑 demo”。

5.1 必测项

• Provider 注册成功
• Consumer 能发现实例
• RPC 调用成功
• 实例心跳稳定
• Nacos 重启后可恢复
• 服务重启后可恢复
• 网络抖动后可恢复
• 鉴权开启时可正常注册/发现
• 鉴权关闭时行为符合预期
• 订阅和反订阅不会泄露资源

5.2 稳定性项

• 长稳运行至少 24h
• 高并发注册/发现/调用
• 频繁上下线场景
• 重试风暴场景
• 客户端短暂不可达恢复场景

5.3 回归项

• dubbo-go-samples 中所有受 Nacos 影响的 demo
• registry demo
• config center demo
• metadata 相关 demo
• 你们实际业务依赖的最小链路 demo

6. 发布与回滚

这是必须单独成节的内容。

发布策略

建议分三步：

1. 开发环境验证
2. 测试环境双跑 v2/v3
3. 预发灰度
4. 生产切换

回滚策略

回滚不能只写“切回 v2”。
要明确：

• 数据库是否可回滚
• 业务配置是否可回滚
• 客户端是否支持双注册
• 配置切换是否只改一个入口
• 回滚后是否要清理 v3 侧数据

如果数据库已经做了不可逆迁移，那就不能写“秒级回滚”，这会误导评审。

7. 验收标准

这版方案的验收标准我建议直接写成硬条件：

• 主仓中 Nacos 相关链路在 Nacos 3.x 下通过自动化测试
• 注册、发现、调用、订阅、反注册都稳定
• 鉴权配置明确，失败路径可解释
• 数据库迁移步骤可复现
• 回滚路径可执行
• samples 验证结果与主仓结论一致

我对这版方案的建议结论
这次升级的主战场应当是 apache/dubbo-go，不是 samples。samples 只能放在最后做“验收场”，不能当成升级起点。真正要把方案写实，就要把“兼容边界、数据库策略、鉴权策略、生命周期、回滚”这五件事写死。