服务注册与分布式协调 / 系统课时
排查注册或发现失败
排查注册或发现失败
当 MCP Server 自动注册失败、目录里查不到服务,或实例长期不更新时,最容易浪费时间的是在客户端、Nacos 和后端之间来回猜。本篇按“控制面是否有资源 → 服务发现是否有实例 → 实例是否健康 → 客户端是否拿到新数据”的顺序建立一条可重复的排查链。
学习目标
- 能区分自动注册失败、目录发现失败和实例更新失败
- 能用 Nacos 3.x 接口核对命名空间、MCP 目录与实例健康状态
- 能根据元数据兼容性、心跳和客户端缓存现象快速缩小故障范围
先按链路切分故障
自动注册后的 MCP 信息会进入 Nacos 的 AI 管理体系,并与服务发现能力协同;因此“控制台看不到”“Router 搜不到”“服务名存在但无健康实例”并不是同一类故障。先确认故障停在哪一层,再处理配置。Nacos 的 MCP 自动注册还会校验同名同版本数据的兼容性,例如协议、服务引用以及 Tool 名称和参数结构不一致都可能阻止注册。([Nacos 官网][1])

用最小请求建立健康基线
先不要改配置。准备 curl 与 jq,分别检查 Nacos 存活、MCP 目录记录和 Naming 实例。MCP_NAME 是 AI Registry 中的 MCP 名称,SERVICE_NAME 是实际被注册到服务发现模块的服务名;两者不要想当然地写成同一个值。Nacos 3.x 提供 MCP 管理列表接口和实例查询接口,前者按命名空间读取目录,后者按已知服务名读取实例。([Nacos 官网][2])
NACOS_BASE="${NACOS_BASE:-http://127.0.0.1:8848}"
NAMESPACE="${NAMESPACE:-public}"
MCP_NAME="${MCP_NAME:-<MCP_NAME>}"
SERVICE_NAME="${SERVICE_NAME:-<MCP_SERVICE_NAME>}"
TOKEN="${NACOS_TOKEN:-}"
AUTH=()
if [ -n "$TOKEN" ]; then
AUTH=(-H "Authorization: Bearer $TOKEN")
fi
echo "== liveness =="
curl -fsS "${AUTH[@]}" "$NACOS_BASE/nacos/v3/admin/core/state/liveness" | jq -r '.data'
echo "== mcp catalog =="
curl -fsS "${AUTH[@]}" --get "$NACOS_BASE/nacos/v3/admin/ai/mcp/list" --data-urlencode "pageNo=1" --data-urlencode "pageSize=20" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "mcpName=$MCP_NAME" --data-urlencode "search=accurate" |
jq -c '{totalCount:.data.totalCount,items:[.data.pageItems[]|{name,protocol,latestPublishedVersion}]}'
echo "== naming instances =="
curl -fsS "${AUTH[@]}" --get "$NACOS_BASE/nacos/v3/client/ns/instance/list" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "serviceName=$SERVICE_NAME" |
jq -c '[.data[]|{ip,port,healthy,enabled,ephemeral}]'预期输出(健康基线,实际地址、端口和版本可能不同):
== liveness ==
ok
== mcp catalog ==
{"totalCount":1,"items":[{"name":"<MCP_NAME>","protocol":"<PROTOCOL>","latestPublishedVersion":"<VERSION>"}]}
== naming instances ==
[{"ip":"<IP>","port":<PORT>,"healthy":true,"enabled":true,"ephemeral":true}]如果第一段就失败,先处理 Nacos 地址、网络和鉴权;如果存活正常但 totalCount 为 0,优先检查命名空间、MCP 名称以及自动注册日志;如果目录有记录但实例数组为空,问题已经缩小到服务引用、实例注册或心跳链路。
从命名空间和兼容性开始定位
命名空间是最先核对的变量。服务端注册到 public,而 Router 或客户端连接另一个 namespace 时,双方都可能“正常运行”,但永远互相看不到。除了 namespace,还要确认注册地址、账号凭据和目标集群一致,避免开发环境写入 A 集群、排查时却查询 B 集群。
自动注册在同名同版本已有数据时会做兼容性判断。若日志出现 mcp server info is not compatible 或 check mcp server compatible false,不要通过重试掩盖问题,应逐项对齐 MCP 协议、服务引用、Tool 名称、Tool 数量、参数类型和可选性;仅描述文案变化通常不是这类兼容性错误的关键。([Nacos 官网][3])
如果调用方还依赖实例 metadata 做筛选、路由或环境标识,应查看实例查询接口的完整响应,确认关键元数据是否真的注册成功,尤其注意键名、值和大小写。服务存在但过滤条件匹配不到,同样会表现为“发现失败”。([Nacos 官网][4])
处理实例不更新和缓存错觉
目录记录存在不代表实例可调用。实例列表中重点观察 healthy、enabled 和 ephemeral。临时实例依赖续约;进程退出、网络中断或续约失败后,健康状态与实例存活会发生变化。若后端已经重启但实例仍指向旧地址,要继续检查注册进程是否真的重新连接到了目标 Nacos,以及实际注册的 IP、端口和服务引用是否符合预期。([Nacos 官网][4])
当服务端状态已经正确,而某个长运行客户端仍查不到或持续命中旧实例时,再把怀疑点移到客户端订阅与本地缓存。最有效的做法不是直接重启所有组件,而是用一个新启动的客户端或 Router 进程做对照:新进程能发现、旧进程不能发现,才值得继续检查客户端缓存、订阅连接和刷新机制。
修复后按同一路径回归
修复后重新执行健康基线脚本,并按原故障路径复测。验收标准应同时满足:目标 namespace 中只有预期的 MCP 记录、目标版本正确、Naming 至少有一个健康且启用的实例、客户端或 Router 能重新发现服务。这样才能避免“目录修好了,但调用链仍然坏着”的半修复状态。