服务注册与分布式协调 / 系统课时

处理实例变化与调用故障

处理实例变化与调用故障

MCP 调用失败时,最容易犯的错误是把所有异常都归结为“Router 坏了”。这一课用同一条调用链分别制造目录缺失、实例不可达和工具执行失败,并用可重复的探针把故障定位到真正出问题的层级。

学习目标

  • 区分目录发现失败、MCP 实例连接失败和工具执行失败。
  • 用 Router 的搜索、安装与代理调用结果定位故障边界。
  • 验证实例下线、地址变化后客户端是否恢复到正确端点。

先判定故障落在哪一层

Nacos MCP Router 在 Router 模式下主要经过三段动作:search_mcp_server 从目录找服务,add_mcp_server 根据目录信息建立或初始化目标 MCP Server,use_tool 再把工具调用代理到目标服务。三段都成功,才说明端到端链路成立。

观察点 典型现象 优先检查
目录层 搜索不到服务,或看到错误版本、错误命名空间 MCP 名称、命名空间、发布状态、目录记录
实例层 能找到目录,但安装或调用时连接拒绝、超时 实例是否在线、端点地址、端口、协议
工具层 目录与连接正常,但 use_tool 返回业务错误 工具参数、目标服务日志、下游依赖

Router 调用故障分层定位流程

这张分层图的关键不是错误文本长什么样,而是错误出现在哪一步。例如“搜索成功、安装失败”说明目录至少可见,此时继续修改搜索关键词通常没有意义。

用统一探针观察三段链路

下面的命令连接一个已经以 Streamable HTTP 暴露的 Router,并依次执行搜索、安装和工具代理。先把 <MCP_SERVER>、<MCP_TOOL> 与参数替换成实验环境中真实存在的服务和工具。

bash
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

预期输出

text
router_tools=add_mcp_server,search_mcp_server,use_tool
directory=found
add=ok
invoke=ok
result=<TOOL_RESULT>

<TOOL_RESULT> 是动态结果,实际内容由目标工具决定。若 Router 本身不可达,连接会在进入 MCP 会话前失败;这属于 Router 或网络入口问题,不应混进后端实例故障。

依次模拟下线、换址和后端错误

先保留一次基线成功结果,再逐个改变单一条件,这样才能把因果关系看清。

  1. 实例下线:停止目标 MCP Server,但不要删除 Nacos 中的 MCP 目录记录。再次运行探针。若仍是 directory=found,但 add 或 invoke 失败,应转向实例在线状态、端点和协议排查。
  2. 地址变化:让目标 MCP Server 改用新端口或新地址,并同步更新注册或端点信息。重新建立 Router 会话并再次运行探针,确认后续调用已经使用新端点,而不是继续依赖旧连接。
  3. 工具后端错误:保持 MCP Server 在线,主动让工具依赖的后端返回失败,或使用能触发业务错误的合法测试输入。此时目录和安装应正常,故障应集中出现在 invoke=error。

按故障层修复并重新验收

目录层问题应先修正命名空间、服务名、版本或发布状态,再重新搜索;实例层问题要核对 Nacos 中的端点与真实监听地址是否一致,并确认旧实例已经下线、新实例能够建立 MCP 会话;工具层问题则需要查看目标 MCP Server 和它的下游日志,而不是反复刷新目录。

重试也必须有边界。查询类、幂等工具可以在短暂网络失败后重试;创建订单、发送消息、扣费这类有副作用的工具若没有幂等键,不应由 Router 或 Agent 无条件重复调用。

最终验收应满足三点:实例下线后不会继续把成功建立在失效端点上;地址更新后新会话能够连接正确实例;工具后端返回错误时,客户端能把它识别为执行失败,而不是误报成“找不到 MCP 服务”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理实例变化与调用故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通