服务注册与分布式协调 / 系统课时
验证注册与发现一致性
验证注册与发现一致性
注册成功只说明某一层写入了数据,不能证明客户端真的能调用。本节用启动、扩容、下线和重启四个场景同时观察 MCP 目录、Nacos 实例视图与客户端调用结果,建立一套能定位“有元数据但不可达”与“实例存活但版本不匹配”的验收方法。
学习目标
- 把 MCP 目录、运行时实例和客户端实际调用拆成三个独立观察面。
- 用固定场景验证注册、扩容、下线和重启后的最终一致性。
- 根据三层结果组合定位版本、健康状态、协议和网络可达性问题。
先建立三层一致性模型
第一层是 MCP 目录:关注服务名、版本、协议、启用状态、工具描述和后端端点声明。第二层是 Naming 实例:关注 IP、端口、healthy、enabled 与实例生命周期。第三层是 客户端结果:关注它最终发现了什么、选择了哪个端点,以及真实 MCP 调用是否成功。
故障排查时不要把控制台某一页当成全部真相。目录记录可以长期存在,而某个运行实例已经退出;实例也可能仍然健康,但它注册的服务引用、协议或版本与客户端期望不一致。

用两条查询建立基线
先在服务稳定时记录目录版本与实例集合。下面命令适合本地未启用鉴权的 Nacos 实验环境,并要求安装 jq;运维 API 在开启鉴权时需要对应命名空间的读取权限。
NACOS="${NACOS:-http://127.0.0.1:8848}"
MCP="${MCP:-weather-mcp-server}"
VERSION="${VERSION:-1.0.0}"
curl -sS "${NACOS}/nacos/v3/admin/ai/mcp?namespaceId=public&mcpName=${MCP}&version=${VERSION}" | jq '{name:.data.name,version:.data.versionDetail.version,enabled:.data.enabled}'
curl -sS "${NACOS}/nacos/v3/client/ns/instance/list?namespaceId=public&serviceName=${MCP}" | jq '[.data[] | {ip,port,healthy,enabled}]'预期输出
{
"name": "weather-mcp-server",
"version": "1.0.0",
"enabled": true
}
[
{
"ip": "<IP>",
"port": <PORT>,
"healthy": true,
"enabled": true
}
]<IP> 与 <PORT> 会随部署变化。第一段只证明目录中存在目标版本且处于启用状态;第二段才证明至少有运行时实例。两者都正常后,还必须执行一次真实 MCP Tool 调用,才能把“可发现”与“可调用”闭环。
按四个场景做一致性验收
| 场景 | MCP 目录 | 实例视图 | 客户端应观察到 |
|---|---|---|---|
| 启动首个实例 | 目标服务与版本存在 | 出现 1 个健康、启用实例 | 无需写死地址即可完成调用 |
| 扩容到两个实例 | 逻辑服务通常不变 | 健康实例从 1 增到 2 | 更新端点集合,调用持续成功 |
| 下线一个实例 | 目录记录通常仍保留 | 实例从 2 收敛到 1 | 不再长期命中下线端点 |
| 重启实例 | 服务名与版本不变 | 旧连接消失后重新出现实例 | 不改客户端配置即可恢复调用 |
测试时每个场景都按同一顺序取证:先查 MCP 目录,再查实例列表,最后做真实客户端调用并查看服务端日志或链路追踪中实际接收请求的实例。这样可以判断差异发生在注册、发现还是网络调用阶段。
根据组合结果定位根因
目录存在,但没有健康实例时,优先检查 Server 是否真的完成实例注册、连接是否仍存活、实例是否被禁用,以及下线流程是否误删或停止续约。此时修改客户端地址没有意义,因为客户端没有可靠的可用实例来源。
目录存在、实例也健康,但端点不可达时,用实例返回的 IP 和端口从客户端所在网络做连通性检查,再核对 MCP 路径、协议和鉴权。Nacos 能证明“注册了这个地址”,不能代替防火墙、容器网络、反向代理或应用自身的监听验证。
实例存活,但目录版本或协议不匹配时,检查服务名、版本、MCP 协议、服务引用与 Tool 结构。对同一版本做不兼容变更可能在自动注册阶段直接被拒绝;如果协议、服务引用或 Tool 契约发生破坏性变化,更稳妥的做法是发布新版本,并让客户端显式切换。
三层都看起来正常,但客户端仍命中过期端点时,检查客户端是否自行缓存了 IP、是否绕过了负载均衡 MCP Client,以及订阅或连接是否已经刷新。此类问题的根因往往不在 Nacos 数据本身,而在消费端把动态发现结果又静态化了。
用真实调用作为最终证据
通过标准不能只写“控制台里看到了实例”。每个场景至少要满足三件事:目录中的名称、版本和协议符合预期;实例视图最终只包含应当接收流量的健康端点;客户端在不修改地址配置的前提下连续完成 MCP 调用。
对于扩容场景,不必强求两台实例立刻平均分流;负载选择策略和长连接复用都会影响短期分布。对于下线和重启场景,更重要的是客户端是否在收敛后停止使用失效端点,并能自动恢复到新的可用集合。只有目录、实例和真实调用三层证据同时成立,才能判定注册与发现链路一致。