服务注册与分布式协调 / 系统课时
处理实例变化与调用故障
处理实例变化与调用故障
MCP 调用失败时,最容易犯的错误是把所有异常都归结为“Router 坏了”。这一课用同一条调用链分别制造目录缺失、实例不可达和工具执行失败,并用可重复的探针把故障定位到真正出问题的层级。
学习目标
- 区分目录发现失败、MCP 实例连接失败和工具执行失败。
- 用 Router 的搜索、安装与代理调用结果定位故障边界。
- 验证实例下线、地址变化后客户端是否恢复到正确端点。
先判定故障落在哪一层
Nacos MCP Router 在 Router 模式下主要经过三段动作:search_mcp_server 从目录找服务,add_mcp_server 根据目录信息建立或初始化目标 MCP Server,use_tool 再把工具调用代理到目标服务。三段都成功,才说明端到端链路成立。
| 观察点 | 典型现象 | 优先检查 |
|---|---|---|
| 目录层 | 搜索不到服务,或看到错误版本、错误命名空间 | MCP 名称、命名空间、发布状态、目录记录 |
| 实例层 | 能找到目录,但安装或调用时连接拒绝、超时 | 实例是否在线、端点地址、端口、协议 |
| 工具层 | 目录与连接正常,但 use_tool 返回业务错误 |
工具参数、目标服务日志、下游依赖 |

这张分层图的关键不是错误文本长什么样,而是错误出现在哪一步。例如“搜索成功、安装失败”说明目录至少可见,此时继续修改搜索关键词通常没有意义。
用统一探针观察三段链路
下面的命令连接一个已经以 Streamable HTTP 暴露的 Router,并依次执行搜索、安装和工具代理。先把 <MCP_SERVER>、<MCP_TOOL> 与参数替换成实验环境中真实存在的服务和工具。
export ROUTER_URL="http://127.0.0.1:8000/mcp"
export MCP_SERVER="<MCP_SERVER>"
export MCP_TOOL="<MCP_TOOL>"
export MCP_PARAMS='{}'
uv run --with mcp python - <<'PY'
import asyncio
import json
import os
from mcp import Client
# Router 的工具结果可能包含多个内容块,先统一抽取文本。
def text_of(result):
parts = []
for item in result.content:
text = getattr(item, "text", None)
if text:
parts.append(text)
return "\n".join(parts)
# 某些 Router 版本会把代理失败写进文本而不是 is_error。
def failed(result):
text = text_of(result).lower()
return bool(
result.is_error
or "failed" in text
or "error" in text
or "失败" in text
)
async def main():
url = os.environ["ROUTER_URL"]
server = os.environ["MCP_SERVER"]
tool = os.environ["MCP_TOOL"]
params = json.loads(os.environ["MCP_PARAMS"])
async with Client(url) as client:
# 先确认连接的是 Router,而不是误连到其他 MCP Server。
tools = await client.list_tools()
names = {item.name for item in tools.tools}
core = {"search_mcp_server", "add_mcp_server", "use_tool"}
print("router_tools=" + ",".join(sorted(core & names)))
# 搜索只判断候选是否可见,不能替代后续连接与执行验证。
search = await client.call_tool(
"search_mcp_server",
{"task_description": server, "key_words": server},
)
found = server.lower() in text_of(search).lower()
print("directory=" + ("found" if found else "missing"))
if not found:
return
add = await client.call_tool(
"add_mcp_server",
{"mcp_server_name": server},
)
print("add=" + ("error" if failed(add) else "ok"))
if failed(add):
return
result = await client.call_tool(
"use_tool",
{
"mcp_server_name": server,
"mcp_tool_name": tool,
"params": params,
},
)
print("invoke=" + ("error" if failed(result) else "ok"))
print("result=" + text_of(result)[:160].replace("\n", " "))
asyncio.run(main())
PY预期输出
router_tools=add_mcp_server,search_mcp_server,use_tool
directory=found
add=ok
invoke=ok
result=<TOOL_RESULT><TOOL_RESULT> 是动态结果,实际内容由目标工具决定。若 Router 本身不可达,连接会在进入 MCP 会话前失败;这属于 Router 或网络入口问题,不应混进后端实例故障。
依次模拟下线、换址和后端错误
先保留一次基线成功结果,再逐个改变单一条件,这样才能把因果关系看清。
- 实例下线:停止目标 MCP Server,但不要删除 Nacos 中的 MCP 目录记录。再次运行探针。若仍是
directory=found,但add或invoke失败,应转向实例在线状态、端点和协议排查。 - 地址变化:让目标 MCP Server 改用新端口或新地址,并同步更新注册或端点信息。重新建立 Router 会话并再次运行探针,确认后续调用已经使用新端点,而不是继续依赖旧连接。
- 工具后端错误:保持 MCP Server 在线,主动让工具依赖的后端返回失败,或使用能触发业务错误的合法测试输入。此时目录和安装应正常,故障应集中出现在
invoke=error。
按故障层修复并重新验收
目录层问题应先修正命名空间、服务名、版本或发布状态,再重新搜索;实例层问题要核对 Nacos 中的端点与真实监听地址是否一致,并确认旧实例已经下线、新实例能够建立 MCP 会话;工具层问题则需要查看目标 MCP Server 和它的下游日志,而不是反复刷新目录。
重试也必须有边界。查询类、幂等工具可以在短暂网络失败后重试;创建订单、发送消息、扣费这类有副作用的工具若没有幂等键,不应由 Router 或 Agent 无条件重复调用。
最终验收应满足三点:实例下线后不会继续把成功建立在失效端点上;地址更新后新会话能够连接正确实例;工具后端返回错误时,客户端能把它识别为执行失败,而不是误报成“找不到 MCP 服务”。