GitHub user AlexStocks created a discussion: nacos-go-sdk 从 v2 升级到 v3
从 `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](D:\test\github\dubbo-go\go.mod:38)，[config/registry_config.go](D:\test\github\dubbo-go\config\registry_config.go:43)，[registry/nacos/registry.go](D:\test\github\dubbo-go\registry\nacos\registry.go:141) **推荐路径** 我建议走下面这条主线： 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 升级手册](https://nacos.io/en/docs/latest/manual/admin/upgrading/)，[Nacos 权限校验](https://nacos.io/docs/v3.0/manual/admin/auth/) ### 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 升级手册](https://nacos.io/en/docs/next/manual/admin/upgrading/) ### 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 只能放在最后做“验收场”，不能当成升级起点。真正要把方案写实，就要把“兼容边界、数据库策略、鉴权策略、生命周期、回滚”这五件事写死。 GitHub link: https://github.com/apache/dubbo-go/discussions/3318 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
