Dubbo + Nacos：先核对注册名、group/version，再做真实 smoke test

结论优先：Dubbo + Nacos 排障不能只看“注册中心里有实例”。先核对接口级 service name providers:{interface}:{version}:{group}、Nacos group、provider URL metadata 和 consumer 的 version/group 订阅条件，再判断是否需要应用级发现。默认 register-mode=all 可能同时产生应用名服务与接口级服务；只有真实 Nacos provider/consumer smoke test 才能证明端到端 RPC。

版本与范围

本页依据 Apache Dubbo dubbo-3.3.6 固定提交 f1585880bee4ca7776f44380c47c994217721ffe 与官方 Nacos registry 文档整理。文档目标是 Nacos 2.x，示例推荐 Dubbo 3.3.0 + Nacos 2.3.0；这不是对所有 Dubbo/Nacos 组合的兼容承诺。

1. 接口级注册名必须精确匹配

provider 的接口级 service name 是：

providers:{interface}:{version}:{group}

其中：

• providers 是默认 category；
• interface 是服务接口全名；
• version/group 为空时仍保留空段；
• Nacos group 默认 DEFAULT_GROUP，可由 dubbo.registry.group 改变；
• Nacos instance metadata 包含 provider URL 的完整参数。

排查时至少同时检查：

service name + Nacos group + version + provider metadata

只看到同一个 IP/端口或“实例健康”不能证明 consumer 的订阅条件已满足。

2. 默认配置可能产生应用级和接口级两套服务

应用级注册以 dubbo.application.name 为 Nacos service name，metadata 可包含：

• dubbo.metadata-service.url-params；
• meta-v；
• dubbo.metadata.storage-type=local；
• dubbo.metadata.revision；
• 多协议场景下的 dubbo.endpoints。

默认 register-mode=all 同时注册应用级和接口级服务；instance、interface 只保留对应层级。不要把“只看到 providers 服务”误判为应用级发现关闭，也不要把应用名服务当成接口级 provider 列表。

3. Consumer 有两条发现路径

接口级

consumer 订阅同名 providers:... 服务，由 Nacos naming event 推送实例。version/group 必须严格匹配；需要范围时才使用 * 或逗号表达式。

应用级

应用级发现依赖 Nacos Config mapping 与 MetadataService RPC：

• mapping group 为 mapping；
• 迁移默认策略为 APPLICATION_FIRST；
• application name、interface name 和 metadata revision 是不同字段。

两条路径的配置、service name 和故障表现不同，必须先判断当前 register-mode。

4. 启动检查与运行期失败

一个不混淆 URL 参数和顶层配置的最小示例：

dubbo.registry.address=nacos://127.0.0.1:8848?nacos.check=true&retry.period=5000&register-consumer-url=false
dubbo.registry.group=DEFAULT_GROUP
dubbo.registry.check=true
dubbo.registry.enable-empty-protection=false
dubbo.registry.register-mode=all

nacos.check、retry.period 和 register-consumer-url 是 registry URL 参数，可写在 address query 或 dubbo.registry.parameters.*；enable-empty-protection 还确认有 dubbo.registry.enable-empty-protection 顶层声明。namespace 默认 public 并直传给 Nacos client。

启动和运行期分开看：

• provider 先本地 export/绑定端口，再向 registry 注册；Nacos 不可达且 nacos.check=true 时启动失败；
• consumer 的 check=true 默认要求启动时存在 provider，否则抛 No provider available for the service；
• 运行期无可用实例时，默认 fail-fast 路由可能抛 FORBIDDEN No provider available from registry；
• failback 默认按 5 秒周期重试，但不会把首轮启动检查变成成功。

5. Nacos 心跳边界属于服务端

官方资料给出的默认保活值是：

• preserved.heart.beat.interval=5000ms；
• preserved.heart.beat.timeout=15000ms 后标记不健康；
• preserved.ip.delete.timeout=30000ms 后删除实例。

这些值属于 Nacos server 行为，不是 Dubbo registry 自己的稳定保证。部署版本或服务端配置变化时要重新核对。

最小真实 smoke test

用固定的本地 Nacos 2.x 和 provider/consumer fixture，按以下顺序验证：

1. Nacos 未启动时，分别观察 provider 的 nacos.check 失败与 consumer 的 check 失败；
2. Nacos 启动后，确认精确的 providers:{interface}:{version}:{group} service name；
3. 检查 metadata 是否包含 protocol、path、methods、version、group；
4. 默认 register-mode=all 下确认应用名服务和 providers 服务共存；切换 instance/interface 后确认只剩一层；
5. 完成一次真实 RPC；
6. provider 1.1.0、consumer 1.0.0 时确认不匹配 fail-fast，version=* 时确认允许范围可发现；
7. provider 下线后调用失败，重启并重新注册后调用恢复。

Dubbo registry-nacos 自带测试以 mock NamingService 为主，不能替代真实 Nacos 集成测试。本页没有把 smoke test 设为已执行结果。

常见误区与边界

• “Nacos 有实例就能调用。” service name、group、version 和 metadata 任一不匹配都可能无法发现。
• “默认只有一类注册。” register-mode=all 可能同时有应用级和接口级服务。
• “retry.period 是普通顶层键。” 当前固定证据首先证明它是 registry URL 参数；不要把未核实的 flat 形式当作通用语法。
• “心跳超时由 Dubbo 决定。” preserved.* 是 Nacos server 边界。
• “mock NamingService 测试证明端到端可用。” 真实 Nacos、版本匹配和 provider 下线恢复仍需 smoke test。

证据边界

固定提交、官方文档、配置键校正和未验证项见仓库 src/content/raw/zh-cn/dubbo-nacos-runtime-registration.md 与 dubbo-nacos-runtime-registration-correction.md。本页不包含私有地址、凭证或具体业务服务名。

来源与关联文档

• dubbo-nacos-runtime-registration
• dubbo-nacos-runtime-registration-correction
• 多服务启动就绪：running、ready 与依赖/失败/重启传播
• 微服务数据所有权：先定领域 owner，再谈拆库与迁移