罗罗编程学习记录
本页内容 展开查看

04.7.18.3 传输、鉴权、生命周期与部署测试

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.18 FastMCP 服务端框架

覆盖范围

  • stdio 输出纪律:stdout 纯协议流、stderr 日志、print 污染与进程模型
  • SSE 与 Streamable HTTP 端点形态、会话标识、有状态/无状态模式与事件存储
  • 会话隔离、挂载前缀、root_path、CORS 与 TLS 终止
  • Bearer token、OAuth 2.1 资源服务器、token 校验器、scope 控制与发现端点
  • 容器镜像、启动参数、多副本粘性与会话扩展限制
  • 结构化日志、指标、trace id 贯穿与工具调用耗时
  • 内存内 client 测试、call_tool 断言、错误路径与契约测试、ASGI 链路测试
  • 入参校验、命令注入、路径穿越、资源 URI 校验、限流超时与脱敏
  • 同进程共存、健康检查、优雅停机与常见故障排查

04.7.18.3-001 stdio 传输下 stdout 为什么是纯协议流?

一句话结论

stdio 传输把 stdout 作为协议消息的唯一通道:每行一条 JSON-RPC 消息,客户端逐行解析。stdout 上任何非协议文本都会破坏帧格式,导致客户端 JSON 解析失败或消息错位。因此服务端所有调试、日志、打印都不能写入 stdout,协议响应与通知之外不得有其他输出。

概念解释

  • 通道分工:stdin 收请求,stdout 发响应与通知,stderr 走日志。
  • 帧格式:每条 JSON-RPC 消息一行,换行分隔,UTF-8 编码。
  • 污染后果:解析报错、请求响应错位、会话建立失败。

原理流程

  1. 客户端拉起服务端子进程,接管三条标准流。
  2. 服务端从 stdin 读消息,处理后只把协议报文写入 stdout。
  3. 客户端按行解析 stdout;混入的普通文本成为非法 JSON 帧。

代码或图示

stdin  <- client JSON-RPC lines
stdout -> client JSON-RPC lines (only protocol messages)
stderr -> log lines (not parsed as protocol)

常见误区

  • 用 print() 调试服务端代码:默认写到 stdout,直接污染协议流。
  • 框架日志配置默认输出到 stdout:需重定向到 stderr 或本地日志文件。

追问

  • stdout 能输出空行吗?答:空白帧可能被解析为空消息,应避免在协议报文外产生多余行。
  • 协议消息之间需要分隔符吗?答:stdio 按换行分帧,一行一条消息。
  • 如何检查 stdout 是否干净?答:本地用 stdio 客户端连接观察报文,或检查日志配置输出去向。

04.7.18.3-002 为什么日志、调试输出必须走 stderr 而不是 stdout?

一句话结论

stderr 不承载协议消息,客户端通常把它作为日志流读取展示,因此日志、警告、调试信息应写入 stderr;写入 stdout 会被当成协议帧解析。stdio 服务端应把应用日志、框架日志都配置到 stderr 或文件,避免任何标准输出混入协议通道。

概念解释

  • stderr 独立通道:不参与 JSON-RPC 分帧,日志内容可自由换行。
  • 客户端用途:展示服务端运行日志,辅助本地接入排查。
  • 本地落盘:生产排障仍应写结构化日志文件,stderr 只作对接输出。

原理流程

  1. 配置日志处理器输出到 stderr(或本地文件)。
  2. 运行期日志写入 stderr,不触碰 stdout。
  3. 客户端从 stderr 读取日志展示,stdout 保持纯协议。

代码或图示

import logging
import sys

logging.basicConfig(stream=sys.stderr, level=logging.INFO)

常见误区

  • 混用标准库 print:print() 默认 stdout,调试应写 stderr 或日志框架。
  • 第三方库默认往 stdout 打日志:需在初始化时调整日志处理器去向。

追问

  • stderr 日志会阻塞协议响应吗?答:stderr 写入是独立通道,正常日志量不影响 stdout 协议流;海量日志需评估 IO。
  • 生产环境 stderr 有用吗?答:容器环境 stderr 会被采集为日志流,可同时结构化落盘。
  • 错误信息也走 stderr 吗?答:日志级别都走 stderr;协议执行错误仍通过 stdout 的 error 响应返回。

04.7.18.3-003 误把 print 打到 stdout 会造成什么客户端故障?

一句话结论

stdout 混入普通文本后,客户端按行解析 JSON 会遇到非法帧:轻则某条消息解析失败、对应请求无响应,重则后续帧全部错位,握手或工具调用反复失败。故障表象像“服务端偶发不响应”,根因是协议流被日志污染,必须把打印全部改到 stderr。

概念解释

  • 单帧污染:一行普通文本解析失败,该请求丢失响应。
  • 错位污染:多行文本破坏按行分帧,后续消息边界错乱。
  • 典型来源:调试 print、第三方库启动横幅、进度条、依赖库日志。

原理流程

  1. 服务端向 stdout 写入非协议文本。
  2. 客户端逐行读取,遇到非法 JSON 帧报错。
  3. 帧边界错乱后请求响应无法关联,表现为超时、缺响应或会话失败。

代码或图示

# 错误:污染 stdout
print("connected to db")

# 正确:走 stderr
print("connected to db", file=sys.stderr)

常见误区

  • 只删除报错行不检查其他库:依赖库启动横幅、版本提示同样可能写 stdout。
  • 认为控制台能看到输出就正常:本地终端混在一起看不出通道区别,需按标准流区分。

追问

  • 如何定位哪段代码写了 stdout?答:检查所有 print 与日志配置,必要时重定向 stdout 捕获非协议输出。
  • 污染后客户端有什么报错特征?答:JSON 解析异常、请求挂起无响应、会话握手失败。
  • 修复后需要验证什么?答:stdio 客户端完整走完握手与一次工具调用,stdout 无额外文本。

04.7.18.3-004 stdio 下服务端进程由谁启动、生命周期如何管理?

一句话结论

stdio 服务端进程由客户端按配置拉起,客户端负责进程启动、标准流接管与退出回收;服务端不是常驻监听端口的守护进程。进程随会话开始而启动,随连接关闭或客户端退出而终止,进程内状态不跨进程保留。

概念解释

  • 启动方:客户端按 MCP 配置(命令、参数、环境变量)spawn 子进程。
  • 生命周期:进程退出即会话结束,stdin 关闭也触发服务端退出。
  • 隔离性:每个子进程独立环境与状态,凭据随进程环境隔离。

原理流程

  1. 客户端读取服务端启动配置,拉起子进程。
  2. 标准流建立,服务端进入消息读取循环。
  3. 连接关闭/客户端退出时,子进程被终止回收,内存状态释放。

代码或图示

client process
  └─ spawn: server subprocess (command + args + env)
       stdin/stdout/stderr 由 client 接管

常见误区

  • 把 stdio 服务端当后台服务长期运行:它按需启动,不自行监听端口。
  • 在进程内保留跨会话状态:进程退出即销毁,重启后不恢复。

追问

  • 子进程崩溃客户端如何感知?答:监听进程退出码与流关闭,重建会话。
  • stdio 服务端能常驻吗?答:可由外部守护进程托管,但默认模型是客户端按需拉起。
  • 进程环境变量由谁注入?答:客户端按启动配置传入,敏感配置不写死在脚本里。

04.7.18.3-005 stdio 消息的换行分隔与编码约定是什么?

一句话结论

stdio 消息以文本帧在标准流上传输:每条 JSON-RPC 消息一行,换行分隔,编码为 UTF-8。服务端不应在报文内插入额外换行或非 UTF-8 字节,避免破坏分帧。

概念解释

  • 编码:JSON 文本按 UTF-8 编码,与项目文档编码约定一致。
  • 分帧:换行作为消息边界,一行一条消息。
  • 稳健性:协议实现负责读写帧,业务代码不直接操作标准流分帧。

原理流程

  1. 消息序列化为 JSON 字符串。
  2. 按传输分帧规则写入 stdout(换行分隔)。
  3. 客户端按帧边界读取并解析 JSON。

代码或图示

{"jsonrpc":"2.0","id":1,"method":"ping"}\n
{"jsonrpc":"2.0","id":1,"result":{}}\n

常见误区

  • 在 JSON 字符串值里嵌入控制换行破坏帧边界:字符串内转义由 JSON 序列化器处理。
  • 假设分帧规则可随意改:跨端互通依赖双方遵循同一传输实现约定。

追问

  • 消息有大小上限吗?答:通道缓冲区与序列化层限制报文大小,超大响应需分页或改资源引用。
  • 非 ASCII 字符如何编码?答:按 UTF-8 序列化,不在标准流上做转义层处理。
  • 如何核对分帧细节?答:对照 MCP 规范 stdio 传输章节与本地 SDK 读写实现。

04.7.18.3-006 stdio 服务端如何避免阻塞 stdin 读取循环?

一句话结论

服务端主循环应持续从 stdin 读取消息并派发处理,避免在循环内做长时间同步阻塞;异步框架由事件循环调度请求,同步阻塞调用会卡住读取与响应。长任务应异步化或放到执行器,并在检查点让出控制权,保持通道可响应。

概念解释

  • 读取循环:等待 stdin 数据 → 解码消息 → 派发执行 → 写回响应。
  • 阻塞风险:同步长 IO、CPU 密集计算占住事件循环,后续请求无法读取处理。
  • 调度:异步工具直接 await;同步阻塞操作走执行器或异步驱动。

原理流程

  1. 事件循环等待标准流可读事件。
  2. 消息到达后派发对应工具/资源/提示执行。
  3. 处理中让出控制权,循环继续读取后续消息。

代码或图示

# 异步服务端主循环由框架驱动;工具内避免长时间同步阻塞
@mcp.tool
async def fetch(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        resp = await client.get(url)
        return {"status": resp.status_code}

常见误区

  • 在工具里调用阻塞型同步库且不放手:事件循环被占住,stdin 后续消息积压。
  • 主循环里做重计算预热:应放到启动生命周期阶段,不占用服务期读取循环。

追问

  • 阻塞库怎么接入?答:用异步驱动替代,或把阻塞操作放到线程执行器并设超时。
  • 读取循环卡死有什么现象?答:ping 无响应、后续调用挂起、客户端判定通道失效。
  • stdio 下能并发处理多个请求吗?答:FastMCP 2.x 事件循环可协程并发派发;同步函数经线程池卸载,阻塞调用会占住循环导致串行化。

04.7.18.3-007 stderr 日志级别配置在 stdio 下的去向是什么?

一句话结论

stderr 上的日志按级别输出到客户端读取的错误流;级别由日志配置控制,低级别调试信息可过滤。stdio 场景没有独立日志服务进程,stderr 是运行期可见日志的主要通道;生产容器部署中 stderr 会被日志采集系统收集。

概念解释

  • 级别:debug/info/warning/error,配置阈值以下不输出。
  • 去向:本地客户端展示;容器环境随标准错误流被采集。
  • 与协议日志通知区别:Context 日志通知走 stdout 协议消息,本地日志走 stderr。

原理流程

  1. 初始化日志配置,设置级别与 stderr 处理器。
  2. 运行期按级别写入 stderr。
  3. 客户端/采集系统读取 stderr 展示或归集。

代码或图示

import logging, sys
logging.basicConfig(stream=sys.stderr, level=logging.INFO)

常见误区

  • 协议日志通知与本地日志混用:前者是 stdout 通知消息,后者是 stderr 日志流。
  • 日志级别生产环境开 debug:stderr 输出量大,影响 IO 与对接排查。

追问

  • 日志能写本地文件吗?答:可以,按需增加文件处理器;stdio 场景 stderr 是默认可见通道。
  • 级别能被客户端调整吗?答:协议 logging/setLevel 调整的是协议日志通知,不等同本地日志配置。
  • stderr 日志需要脱敏吗?答:需要,不记录密钥、令牌与完整敏感参数。

04.7.18.3-008 stdio 场景下多客户端与并发会话有什么限制?

一句话结论

stdio 模型下每个客户端通常拉起独立子进程,进程内会话与状态隔离;单进程内多会话并发支持取决于框架实现。stdio 不适合集中式多客户端共享服务,需要多会话并发、网络访问与鉴权时应选择 HTTP 类传输。

概念解释

  • 进程隔离:独立进程天然隔离,但资源按进程复制,并发规模受进程数约束。
  • 单进程多会话:stdio 通道模型以单连接单会话为主,多会话并发应改用 HTTP 传输。
  • 扩展瓶颈:进程创建开销、内存占用、下游连接池按进程拆分。

原理流程

  1. 每个客户端启动各自服务端子进程。
  2. 进程内处理本会话消息,状态不跨进程共享。
  3. 客户端数量增长时进程数同步增长,资源消耗线性放大。

代码或图示

client A -> process A
client B -> process B
client C -> process C

常见误区

  • 用 stdio 承载网络多租户服务:进程模型无法集中治理,鉴权与限流也缺乏网络层入口。
  • 在模块级单例里期待跨客户端共享状态:不同进程互不可见。

追问

  • stdio 服务端能被多个进程同时调用吗?答:每个调用方拉起独立进程,不共享同一进程实例。
  • 什么场景转 HTTP 传输?答:多客户端集中接入、统一鉴权、负载均衡与可观测性要求时。
  • 进程内并发请求怎么判断?答:看事件循环派发模型与同步函数的线程池卸载方式。

04.7.18.3-009 Streamable HTTP 默认端点路径 /mcp 是怎么来的?

一句话结论

Streamable HTTP 传输把协议消息挂在单一 HTTP 端点上,默认路径为 /mcp,可在创建 ASGI 应用或运行配置时修改。客户端向该路径 POST 请求,握手后通过会话标识头关联后续请求;挂载到子路径时,最终 URL 由挂载前缀加端点路径拼成。

概念解释

  • 单端点:请求与响应都走同一 URL,不再有独立服务端推送连接。
  • 路径配置:http_app(path="/mcp") 或运行参数决定端点位置。
  • 拼接规则:父应用挂载前缀 + 子应用内路径,测试与代理配置按完整 URL 对齐。

原理流程

  1. 生成 MCP ASGI 应用时配置端点路径。
  2. 挂载到父应用前缀下,形成完整访问 URL。
  3. 客户端 POST 到完整 URL 发起 initialize 与后续调用。

代码或图示

mcp_app = mcp.http_app(path="/mcp")
api.mount("/analytics", mcp_app)
# 最终端点: /analytics/mcp

常见误区

  • 路径只记 /mcp 忽略挂载前缀:经父应用挂载后实际 URL 带前缀,客户端连接地址算错。
  • 把 SSE 旧端点 /sse 套到 Streamable HTTP:两套传输路径模型不同。

追问

  • 端点路径能改到根路径吗?答:可以,子应用 path 设为 /,挂载前缀即完整路径。
  • 路径区分大小写吗?答:Starlette/FastAPI 路由默认大小写敏感,路径匹配按 ASGI 路由规则。
  • 多实例挂载如何区分路径?答:每个子应用独立路径前缀,避免路由冲突。

04.7.18.3-010 SSE legacy 传输的 /sse 与消息端点结构是什么?

一句话结论

旧 SSE 传输是双端点结构:GET 到 /sse 建立服务端到客户端的事件流,POST 到消息端点把请求发回服务端,两端点通过会话标识关联。该传输已被 Streamable HTTP 取代,保留仅为兼容旧客户端,新项目不应选用。

概念解释

  • 服务端推送:SSE 长连接持续推送事件。
  • 客户端请求:独立 POST 端点携带会话标识回写请求。
  • 脆弱点:两条 HTTP 连接拼合双向通道,代理与空闲超时更易中断。

原理流程

  1. 客户端 GET /sse 建立长连接,获得会话通道标识。
  2. 客户端 POST 请求到消息端点并带回标识。
  3. 服务端响应通过已建立的 SSE 流推回客户端。

代码或图示

client --GET /sse----------> server  (SSE long link)
client --POST /messages----> server  (request post)
server --SSE events--------> client

常见误区

  • 把 SSE 传输与 Streamable HTTP 混为一谈:前者双端点旧方案,后者单端点新方案。
  • 新部署沿用 SSE:代理兼容性、可恢复性与双向流式体验均不如 Streamable HTTP。

追问

  • SSE 默认消息端点路径是什么?答:legacy SSE 传输 GET /sse 建流,POST /messages 回传请求(SDK 旧版默认)。
  • SSE 支持多客户端吗?答:支持,每连接独立会话,但水平扩展受会话内存限制。
  • 何时必须保留 SSE?答:接入尚未升级 Streamable HTTP 的旧客户端时。

04.7.18.3-011 Streamable HTTP 响应的 JSON 与 SSE 两种形态如何选择?

一句话结论

短结果可用一次性 JSON 响应返回;需要持续推送进度、后续消息或长任务流式输出时,响应采用 SSE 事件流,由框架按是否需要流式推送选择。服务端按任务时长与推送需求设计,代理链路需同时兼容两种响应。

概念解释

  • JSON 响应:单次请求单次返回,适合快速工具调用。
  • SSE 流:响应保持打开,事件逐条推送,适合进度上报与流式结果。
  • 兼容要求:反向代理不能缓冲 SSE 流,否则事件被攒批延迟推送。

原理流程

  1. 工具执行前判断结果形态:短结果或长任务流式。
  2. 框架按模式返回 JSON 响应或 SSE 事件流。
  3. 客户端按响应格式解析:一次性 JSON 或事件流逐条读取。

代码或图示

short result  -> HTTP JSON response
long task     -> HTTP SSE stream: progress ... result

常见误区

  • 代理按普通 JSON 接口缓冲 SSE:事件积压到响应结束才发出,进度失去意义。
  • 所有调用都开 SSE 流:短结果增加连接与流管理开销,应按场景选择。

追问

  • 纯 JSON 响应能关闭 SSE 流吗?答:短结果框架直接返回 JSON;需要流式事件时才升级 SSE 流,代理按两种形态兼容。
  • SSE 流里能混 JSON 事件吗?答:事件按 SSE 帧格式承载 JSON-RPC 消息。
  • 客户端如何区分响应形态?答:按响应 Content-Type 与是否为事件流判断。

04.7.18.3-012 Mcp-Session-Id 会话标识头如何生成与携带?

一句话结论

握手成功后服务端在 initialize 响应中下发会话标识,客户端后续请求通过 Mcp-Session-Id 头携带;服务端按标识查找会话上下文。未携带或标识失效时请求无法路由到原会话。

概念解释

  • 生成:首次握手由服务端创建会话并返回标识。
  • 携带:后续每个请求在请求头带回,不用写进工具 arguments。
  • 失效:会话空闲超时或关闭后标识失效,需重新握手。

原理流程

  1. 客户端首次 POST initialize,无会话标识。
  2. 服务端创建会话,响应返回标识。
  3. 后续请求头携带标识,服务端匹配会话处理。

代码或图示

POST /mcp
Mcp-Session-Id: <握手响应返回值>

常见误区

  • 把会话标识放进工具参数:它是传输层关联信息,不属于业务入参。
  • 多副本下假定标识全局有效:状态在某实例内存中,其他实例查不到。

追问

  • 会话标识会过期吗?答:按空闲超时与生命周期回收,过期后重新握手。
  • 标识头在无状态模式还需要吗?答:无状态模式不保留会话状态,请求自包含。
  • 标识泄露有风险吗?答:会话标识可被用于复用会话,网络层应配合 TLS 与访问控制。

04.7.18.3-013 无状态 HTTP 模式 stateless_http 与 json_response 有什么区别?

一句话结论

stateless_http 控制服务端是否保存会话上下文:无状态模式每个请求自包含,不依赖服务端内存会话,可在构造实例或 run 时传 stateless_http=True,也可用环境变量 FASTMCP_STATELESS_HTTP=true。响应是否流式由框架按推送需求选择,与会话模式是两个不同维度。

概念解释

  • 无状态:便于多副本水平扩展,会话内推送与持久订阅受限。
  • JSON 响应:弱化 SSE 流依赖,配合无状态模式简化链路。
  • 有状态:保留会话上下文,支持进度推送、订阅与跨请求关联。

原理流程

  1. 部署侧决定会话模型:需要会话记忆选有状态,追求扩展选无状态。
  2. 按模式配置响应格式开关。
  3. 请求处理按所选模式路由与返回。

代码或图示

import os

os.environ["FASTMCP_STATELESS_HTTP"] = "true"
mcp = FastMCP("stateless", stateless_http=True)

常见误区

  • 无状态模式仍依赖服务端记住上次参数:需要的数据必须每次请求带上。
  • 把响应格式开关当成会话开关:两者独立,需分别配置。

追问

  • 无状态模式支持资源订阅吗?答:订阅与推送依赖会话上下文,无状态模式下受限,客户端通常降级为主动读取。
  • 无状态模式下进度怎么上报?答:流式推送受限,长任务结果需在响应或重连后获取。
  • 混合模式存在吗?答:按框架实现判断,有状态/无状态通常二选一配置。

04.7.18.3-014 EventStore 事件存储与断线重连续传如何工作?

一句话结论

配置事件存储后,服务端把会话事件(进度、结果等)按标识保存;连接断开重连时,客户端带 Last-Event-ID 头补收缺失事件,避免长任务进度丢失。FastMCP 2.x 默认使用内存 EventStore;持久化后端需按安装版本核实(待确认:验证点:当前版本 EventStore 支持的外部存储后端与配置参数)。

概念解释

  • 事件标识:每个事件带序号或标识,重连后据此补收。
  • 存储生命周期:与会话或任务绑定,过期后清理。
  • 适用场景:代理中断、空闲超时、客户端短暂掉线后的任务恢复。

原理流程

  1. 服务端配置事件存储,任务过程事件逐条写入。
  2. 连接断开后客户端重连,带回会话标识与断点位置。
  3. 存储补发缺失事件,客户端续收进度与最终结果。

代码或图示

from fastmcp.server.event_store import EventStore

event_store = EventStore(max_events_per_stream=1000, ttl=3600)
app = mcp.http_app(event_store=event_store, retry_interval=2000)

常见误区

  • 以为重连天然能恢复任务:无事件存储时任务状态与事件不保留,只能重新发起。
  • 事件存储无限期保留:需配置过期清理,避免内存与磁盘膨胀。

追问

  • 事件存储存哪些事件?答:进度通知、工具结果与后续消息。
  • 重连续传需要会话粘性吗?答:事件存在内存实例时需要粘到同一实例;共享存储才可跨实例补收。
  • 存储能持久化到外部系统吗?答:EventStore 支持注入外部存储后端;外部后端可用性见 037 题的未核实项。

04.7.18.3-015 反向代理为什么必须关闭响应缓冲?

一句话结论

Streamable HTTP/SSE 响应是持续事件流,代理若开启响应缓冲,会把事件攒到响应结束或缓冲区满才转发,进度通知延迟甚至丢失。代理必须关闭对 MCP 端点的响应缓冲,让事件实时透传;这是 HTTP 部署最关键的代理设置之一。

概念解释

  • 缓冲行为:代理默认聚合响应体,适合普通 JSON 接口,不适合事件流。
  • 事件时效:进度、日志等事件需要即时到达客户端。
  • 配置位置:反向代理站点配置中针对 MCP 路径关闭缓冲。

原理流程

  1. 客户端经代理请求 MCP 端点。
  2. 服务端写入 SSE 事件流。
  3. 代理关闭缓冲后逐事件转发;缓冲开启则事件被攒批延迟。

代码或图示

location /mcp {
    proxy_buffering off;
    proxy_pass http://127.0.0.1:8000;
}

常见误区

  • 只在全局关闭缓冲:其他普通接口可能受影响,应针对 MCP 路径配置。
  • 忽略 Web 服务器自身缓冲:应用服务器与代理两层缓冲都需确认关闭。

追问

  • 不关闭缓冲有什么现象?答:进度长时间不更新,任务结束后事件一次性涌出,客户端误判卡死。
  • 缓冲关闭影响普通 API 吗?答:按路径分别配置,MCP 路径关缓冲,其他接口保留默认。
  • 云托管网关也支持关缓冲吗?答:取决于网关能力,需确认其 SSE/流式透传配置。

04.7.18.3-016 代理读超时、空闲超时与长任务的关系是什么?

一句话结论

代理与网关的读超时、空闲超时决定长连接能存活多久:长任务期间若没有事件输出,空闲超时会切断连接;应放宽 MCP 端点超时,并通过进度上报保持链路活跃。超时预算需与客户端超时、工具执行超时逐层对齐,避免中间层先断开。

概念解释

  • 读超时:等待响应数据的最大间隔;空闲超时:连接无活动的最大时长。
  • 长任务风险:阻塞期间无事件,触发代理空闲断开。
  • 活跃信号:进度通知、周期日志或心跳维持链路活性。

原理流程

  1. 梳理各层超时:代理、网关、应用服务器、客户端、工具下游。
  2. 按最长任务预算放宽代理空闲超时。
  3. 任务中定期上报进度保持活跃,超时不可控时配合事件存储重连续传。

代码或图示

proxy_read_timeout 300s;
proxy_send_timeout 300s;

常见误区

  • 只调应用服务器超时,代理默认 60 秒仍断开:中间层超时先触发。
  • 长任务不打进度:无活跃事件,空闲超时误判连接死亡。

追问

  • 超时设置多长合适?答:按任务最长执行时间加余量压测确定,不套用默认值。
  • 超时断开后任务还在跑吗?答:服务端任务可能继续,客户端需靠事件存储或重新发起恢复结果。
  • 客户端超时如何配合?答:客户端等待时间应大于代理与任务预算,避免先放弃。

04.7.18.3-017 会话状态在内存中如何存放与隔离?

一句话结论

有状态 HTTP 模式下,会话上下文保存在服务端进程内存:协商版本、能力、认证结果、订阅关系与任务状态按会话标识区分。不同会话条目独立存放,工具函数经 Context 访问当前会话,不使用模块级全局变量保存身份与状态。

概念解释

  • 存储结构:会话表按标识索引会话上下文对象。
  • 隔离边界:会话间数据互不可见,认证结果按会话隔离。
  • 生命周期:连接关闭或超时后条目清理,内存释放。

原理流程

  1. 握手创建会话条目,写入版本、能力与身份信息。
  2. 请求进入时按标识取出会话上下文,注入工具调用。
  3. 会话结束清理条目,避免内存残留。

代码或图示

session_id -> {protocolVersion, capabilities, auth, subscriptions, taskState}

常见误区

  • 用全局 dict 按参数名存用户身份:并发会话互相覆盖,身份串扰。
  • 会话状态长期驻留不清理:内存随连接数增长,需过期回收。

追问

  • 会话内存能跨进程共享吗?答:默认保存在进程内存,跨进程共享需接入外部会话/事件存储后端。
  • 认证结果存在会话哪里?答:鉴权通过后写入会话上下文,工具经 Context 读取。
  • 会话并发上限受什么约束?答:内存、下游连接池与事件循环并发能力。

04.7.18.3-018 不同客户端调用如何互不污染会话上下文?

一句话结论

会话隔离按连接与会话标识实现:每个客户端连接对应独立上下文,工具执行时注入当前会话的 Context,读取的身份、日志与资源读取都只作用于本会话。避免污染的关键是不在模块作用域保存请求级数据,共享资源放生命周期层。

概念解释

  • 注入隔离:框架按调用会话构造 Context,函数内不跨会话共享。
  • 共享与隔离分层:连接池、配置等共享资源放 lifespan;身份、临时状态放会话。
  • 并发安全:异步协程间靠 ContextVar/会话上下文隔离,不靠全局变量。

原理流程

  1. 每个连接握手后建立独立会话上下文。
  2. 工具调用时框架注入对应 Context。
  3. 会话数据只在本会话读写,共享资源跨会话复用。

代码或图示

@mcp.tool
def current(ctx: Context) -> dict:
    return {"client": ctx.client_id}

常见误区

  • 在工具内把用户信息存到全局变量:下一并发会话读到错误身份。
  • 复用 Context 对象给多个会话:框架按调用注入,不应手工跨会话传递。

追问

  • 异步协程间上下文如何隔离?答:框架按会话构造 Context,经上下文变量在协程间隔离,不使用模块级全局变量。
  • 会话级缓存放哪里?答:放会话上下文,不放模块级缓存。
  • 如何测试隔离性?答:内存内并发两个会话调用同一工具,断言身份与状态互不干扰。

04.7.18.3-019 客户端重连后会话丢失的典型场景是什么?

一句话结论

会话丢失常见于:有状态会话只存内存且重连落到另一实例、空闲超时会话已回收、无状态模式本就不保留上下文、事件存储未配置导致任务事件不补收。重连后拿不到原会话时,客户端需重新握手;需要恢复任务结果时依赖共享会话存储或事件存储。

概念解释

  • 实例漂移:多副本无粘性,重连到未持有会话的实例。
  • 过期回收:空闲超时后会话条目被清理。
  • 无状态限制:请求自包含,无跨请求记忆可恢复。

原理流程

  1. 连接断开后客户端重连,带回会话标识。
  2. 服务端查找会话:存在则续接;不存在则标识失效。
  3. 客户端重新握手,必要时重新发起任务或从事件存储补收。

代码或图示

reconnect -> 查 session_id -> 命中: 续接
                          -> 未命中: 重新握手 / 重新发起任务

常见误区

  • 多副本部署不做粘性也不共享存储:会话必然漂移丢失。
  • 长任务结果依赖会话保留:无存储支撑时断线即结果不可恢复。

追问

  • 如何避免重连丢会话?答:会话粘性或共享会话/事件存储;无状态设计则让请求自包含。
  • 会话超时在哪里配置?答:由传输层空闲超时与框架会话回收策略控制;具体超时参数名与默认值需按安装版本核实(待确认:验证点:会话空闲超时配置参数)。
  • 重连后旧任务还能拿到结果吗?答:事件可补收时可以,否则需重新发起。

04.7.18.3-020 挂载前缀与 root_path 对端点 URL 有什么影响?

一句话结论

MCP 子应用挂载到父应用前缀下后,最终端点 URL = 挂载前缀 + 子应用内路径;代理或网关再外层映射时需考虑 root_path 与路径重写。客户端连接地址、OAuth 发现 URL 与内部路由都要按完整路径对齐,路径错位会导致握手 404 或回调失败。

概念解释

  • 挂载前缀:父应用 mount 的路径段。
  • root_path:代理后部署时告知应用的外部路径前缀,影响内部生成的 URL。
  • 路径一致性:端点、发现文档、回调地址使用同一套路径基准。

原理流程

  1. 父应用挂载 MCP 子应用,确定前缀。
  2. 子应用内配置端点路径,拼成完整内部 URL。
  3. 代理/网关映射外部路径,必要时配置 root_path,客户端按外部完整地址连接。

代码或图示

mcp_app = mcp.http_app(path="/mcp")
api.mount("/analytics", mcp_app)
# 内部: /analytics/mcp
# 代理外层若加 /api 前缀, 需对齐 root_path 与重写规则

常见误区

  • 只按子应用路径配置客户端地址:漏掉挂载前缀导致 404。
  • 代理重写路径后应用内部生成 URL 不一致:OAuth 回调与发现文档路径错乱。

追问

  • root_path 在哪里设置?答:由父 ASGI 应用按代理外部前缀配置 root_path,作为应用内部生成 URL 的路径基准。
  • 路径错位怎么排查?答:对比客户端请求 URL、代理转发路径、父应用挂载路由与子应用路径。
  • 多实例挂载如何避免前缀冲突?答:每个实例分配独立挂载前缀。

04.7.18.3-021 CORS 配置与 OAuth 路由中间件如何避免冲突?

一句话结论

跨域访问需要在父应用或传输层配置 CORS 中间件,放行来源、方法与凭据头;OAuth 发现、回调与鉴权中间件按路由顺序挂载,避免 CORS 预检被鉴权拦截。中间件顺序错误会导致预检失败或凭据头被剥离,需在挂载 MCP 子应用前统一规划。

概念解释

  • CORS 预检:OPTIONS 请求由 CORS 中间件先处理,不应被鉴权拦截。
  • 凭据头:Authorization、会话标识头需在允许列表内。
  • 顺序原则:CORS 包装在最外层,鉴权与业务路由在内层。

原理流程

  1. 父应用先挂 CORS 中间件,配置允许来源与凭据头。
  2. 再挂鉴权/OAuth 路由与 MCP 子应用。
  3. 浏览器预检 OPTIONS 由 CORS 应答,实际请求再走鉴权。

代码或图示

from fastapi.middleware.cors import CORSMiddleware

api.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["Authorization", "Mcp-Session-Id"],
)

常见误区

  • 鉴权中间件先于 CORS:预检请求无凭据被 401 拦截,浏览器拿不到 CORS 头。
  • 允许所有来源又携带凭据:浏览器安全模型禁止通配来源与凭据组合,应显式列出来源。

追问

  • 服务端到服务端调用需要 CORS 吗?答:不需要,CORS 是浏览器跨域限制,后端直连不涉及。
  • 会话标识头需要加入允许头吗?答:需要,浏览器跨域时自定义头必须在 CORS 允许列表。
  • 中间件顺序怎么验证?答:浏览器开发者工具看预检响应头与状态码。

04.7.18.3-022 TLS 终止位置与内网 HTTP 部署如何取舍?

一句话结论

TLS 可在客户端到代理之间终止,代理到内网服务走 HTTP;也可在应用层直接终止。终止位置决定证书管理、内网明文风险与配置复杂度。公网入口应在代理或网关层终止 TLS,内网链路按安全等级决定是否再加密;凭据与会话标识在链路上必须受保护。

概念解释

  • 代理终止:代理持有证书,后端内网 HTTP,证书集中管理。
  • 应用终止:应用直接持有证书,链路端到端加密,证书分散到实例。
  • 内网风险:内网 HTTP 链路可被监听,敏感部署需评估内网隔离等级。

原理流程

  1. 确定部署拓扑:公网入口、代理层、应用实例。
  2. 选择 TLS 终止位置,配置证书与转发协议。
  3. 内网链路按安全要求决定 HTTP 或 HTTPS,凭据不通过明文公网传输。

代码或图示

client --TLS--> reverse proxy --HTTP--> app (内网隔离)
client --TLS--> reverse proxy --HTTPS--> app (内网再加密)

常见误区

  • 公网直连应用却用 HTTP:令牌与会话标识明文暴露。
  • 代理终止 TLS 后内网完全不设防:内网仍需网络隔离与访问控制。

追问

  • 证书在哪里更新?答:终止 TLS 的一层持有证书并负责续期。
  • 代理转发如何保留原始协议信息?答:按代理头传递,应用据此生成正确的外部 URL。
  • 本地开发可以 HTTP 吗?答:本地回环调试可走 HTTP,公网与跨机部署必须加密。

04.7.18.3-023 Bearer token 请求头校验流程是什么?

一句话结论

客户端在 Authorization: Bearer <token> 头携带令牌,服务端在请求进入协议处理前校验令牌:格式解析、签名/有效性/过期时间校验,通过后把身份与 scope 写入会话;失败返回鉴权错误。校验在传输层中间件完成,工具内不再重复解析原始令牌。

概念解释

  • 令牌来源:请求头 Authorization,按 Bearer 方案提取。
  • 校验项:签名、过期时间、签发方、受众、scope 等(按令牌类型)。
  • 结果落位:校验通过的身份信息写入会话上下文,供工具与鉴权判断使用。

原理流程

  1. 请求到达,鉴权中间件提取 Bearer 令牌。
  2. 调用校验器验证签名、有效期与声明。
  3. 通过则写入会话身份并放行;失败返回 401/鉴权错误,不进入工具执行。

代码或图示

Authorization: Bearer eyJhbGciOi...

常见误区

  • 工具内再从头解析令牌:身份应在中间层校验后注入会话,避免重复解析与绕过。
  • 只检查令牌存在不验签名:伪造令牌可通过,必须验签与有效期。

追问

  • 令牌过期返回什么?答:401 鉴权失败,客户端按刷新流程重新获取。
  • 令牌能放在查询参数吗?答:不推荐,查询参数易进日志与代理记录,优先请求头。
  • 校验失败是否记录详细错误?答:只记通用失败与必要标识,不泄露校验细节。

04.7.18.3-024 OAuth 2.1 中服务端作为资源服务器(RS)承担什么角色?

一句话结论

MCP 服务端在 OAuth 2.1 模型中通常作为资源服务器:接收并校验访问令牌,按令牌 scope 决定开放哪些工具/资源,不负责用户登录与令牌签发。授权服务器(AS)负责认证、发令牌与发现元数据;客户端持令牌访问 RS。角色边界决定了服务端实现只做令牌校验与授权判断。

概念解释

  • 资源服务器 RS:保护受保护资源,校验令牌,执行 scope 授权。
  • 授权服务器 AS:签发访问令牌,提供发现与令牌端点。
  • 客户端:向 AS 取得令牌后访问 RS。

原理流程

  1. 客户端向 AS 完成授权流程取得访问令牌。
  2. 客户端带令牌请求 MCP 服务端(RS)。
  3. RS 校验令牌与 scope,放行对应能力;不通过则拒绝。

代码或图示

client --token--> MCP server (RS)
AS 签发 token; RS 校验 token + scope

常见误区

  • 在 MCP 服务端实现登录页面与令牌签发:那是 AS 职责,RS 只做校验授权。
  • 把所有 scope 检查放到工具内部散落判断:应集中在鉴权层按能力映射。

追问

  • RS 需要访问 AS 数据库吗?答:不需要,靠令牌内声明或远程校验/ JWKS 验签。
  • 令牌校验能离线完成吗?答:JWT 可凭公钥/JWKS 离线验签;不透明令牌需远程校验。
  • 多服务端共享 AS 吗?答:可以,同一 AS 为多个 RS 签发带不同 scope 的令牌。

04.7.18.3-025 token 校验器与 JWT Verifier 的职责是什么?

一句话结论

FastMCP 2.x 通过 TokenVerifier 子类把原始令牌转换为可信任的身份与声明对象:JWTVerifier 验签名、查 JWKS、校验过期/签发方/受众;StaticTokenVerifier 比对预配置令牌并附带 client_id 与 scope;IntrospectionTokenVerifier 按 RFC 7662 远程校验不透明令牌。校验通过输出 AccessToken(含 client_id、scopes、expires_at、claims),鉴权层据此授权。

概念解释

  • JWT Verifier:基于公钥或 JWKS 验证 JWT 签名与标准声明。
  • 静态 token 校验器:开发/内部场景比对固定令牌,映射身份与 scope。
  • 输出统一:无论令牌类型,校验结果结构一致,便于会话写入与授权判断。

原理流程

  1. 配置校验器:JWT 提供 issuer/audience/JWKS;静态提供令牌映射表。
  2. 请求令牌进入校验器,逐项校验。
  3. 通过返回身份声明;失败抛鉴权错误,中间件拒绝请求。

代码或图示

from fastmcp.server.auth.providers.jwt import StaticTokenVerifier

verifier = StaticTokenVerifier(
    tokens={
        "dev-token": {"client_id": "cli-1", "scopes": ["tools:read"]}
    },
    required_scopes=["tools:read"],
)

常见误区

  • 静态令牌用于生产:固定令牌不可轮换、无过期与 scope 粒度,仅限内部/开发环境。
  • 验签跳过 audience/issuer 校验:跨服务令牌可能被误用,标准声明必须校验。

追问

  • JWKS 地址如何配置?答:JWTVerifier 传 jwks_uri 定期拉取公钥,或传 public_key 固定公钥;HMAC 时传对称密钥。
  • 校验器缓存 JWKS 吗?答:JWTVerifier 定期拉取 JWKS 公钥,密钥轮换由 JWKS 端点保证。
  • 校验失败异常如何映射?答:统一映射为 401/协议鉴权错误,不暴露内部校验细节。

04.7.18.3-026 scope 权限控制如何按能力收窄?

一句话结论

scope 是令牌携带的授权范围声明,服务端按 scope 决定暴露或允许调用哪些工具、资源与提示。能力到 scope 的映射集中配置:缺少对应 scope 时拒绝调用或在清单中隐藏对应组件。收窄原则是最小权限,每个能力只要求必要 scope,不按粗粒度角色一刀切。

概念解释

  • scope 粒度:按能力划分(读、写、特定资源),而非整服务端放行。
  • 映射位置:鉴权层或组件元数据标注所需 scope。
  • 两种策略:调用前拒绝(返回权限错误)或清单隐藏(不列出无权限组件)。

原理流程

  1. 定义能力与 scope 映射表。
  2. 令牌校验后解析 scope 集合。
  3. 清单生成与调用检查时按映射放行;无 scope 拒绝或隐藏。

代码或图示

tools:read  -> 只读工具可见可调用
tools:write -> 写工具额外要求该 scope

常见误区

  • 一个大 scope 覆盖全部能力:权限无法细分,泄露后影响面过大。
  • 只在清单隐藏不做调用校验:客户端可直接构造调用,服务端必须二次鉴权。

追问

  • scope 检查放在哪一层?答:鉴权中间件统一拦截,工具内只做业务规则判断。
  • 匿名访问能配 scope 吗?答:匿名按最小开放范围,仅暴露公开组件。
  • 多 scope 是 AND 还是 OR?答:按映射规则定义,敏感能力通常要求全部命中。

04.7.18.3-027 认证结果如何写入会话并供工具读取身份?

一句话结论

鉴权通过后,身份声明(client_id、scope、过期时间等)写入当前会话上下文;工具函数经 Context 或会话对象读取身份,做数据归属与审计,不直接从请求头重新解析。会话随请求生命周期隔离,身份信息不跨会话共享。

概念解释

  • 写入时机:令牌校验通过、会话建立后。
  • 读取路径:Context 暴露身份字段;工具按字段做授权与归属判断。
  • 审计价值:调用记录关联 client_id,便于追溯。

原理流程

  1. 鉴权中间件校验令牌,得到身份声明。
  2. 框架把声明挂到会话上下文。
  3. 工具执行时经 Context 读取身份,记录调用日志与权限判断。

代码或图示

@mcp.tool
def whoami(ctx: Context) -> dict:
    return {"client_id": ctx.client_id}

常见误区

  • 工具内再读 Authorization 头:跳过会话身份模型,易与鉴权层结论不一致。
  • 身份信息放全局变量:并发会话身份串扰。

追问

  • Context 暴露哪些身份字段?答:经 get_access_token() 取得 AccessToken,读取 client_id、scopes、expires_at 与 claims。
  • 令牌刷新后会话身份更新吗?答:按会话与令牌生命周期判断,过期后需重新鉴权。
  • 无鉴权环境身份字段是什么?答:可能为空或默认标识,工具需处理匿名情况。

04.7.18.3-028 OAuth 发现端点与 RFC 8414/9728 元数据如何提供?

一句话结论

OAuth 资源服务器可提供元数据发现端点:/.well-known/oauth-authorization-server 描述授权服务器位置、令牌端点、JWKS 与支持的 scope,/.well-known/oauth-protected-resource/* 描述受保护资源;客户端据此动态配置授权流程。元数据标准涉及 RFC 8414(OAuth 2.0 授权服务器元数据)与 RFC 9728(OAuth 2.0 受保护资源元数据)。

概念解释

  • 发现元数据:避免客户端硬编码授权服务器地址与端点。
  • RS 暴露点:保护资源时引导客户端发现 AS 配置。
  • 标准演进:MCP OAuth 配置随规范版本调整,按当前 MCP 规范与所装 SDK 版本核对。

原理流程

  1. 服务端配置授权服务器元数据或发现端点。
  2. 客户端访问发现端点获取 AS 地址、JWKS、scope 等信息。
  3. 按元数据完成授权与令牌交换,再带令牌访问 MCP 端点。

代码或图示

/.well-known/oauth-authorization-server  -> AS metadata
/.well-known/oauth-protected-resource   -> RS metadata

常见误区

  • 硬编码授权服务器地址到所有客户端:AS 迁移后配置全量改动。
  • 照抄旧规范端点路径:MCP OAuth 规范版本演进,路径与字段需核对当前实现。

追问

  • 元数据由 RS 还是 AS 提供?答:AS 元数据在 AS;RS 保护资源描述在 RS 侧,两者配套。
  • 如何核对支持的标准版本?答:对照当前 MCP 规范版本页与 FastMCP 迁移说明。
  • 发现端点需要鉴权吗?答:元数据通常公开访问,敏感声明不放入公开元数据。

04.7.18.3-029 静态 token 如何通过环境变量注入与轮换?

一句话结论

开发或内部场景可用静态令牌映射,但令牌必须从环境变量或配置注入,不写进源码与文档;轮换时更新环境变量并重启/重载实例。静态令牌无过期与细粒度授权,生产环境应切换到 OAuth/JWT 方案。

概念解释

  • 注入方式:进程启动环境变量读取令牌与映射,配置与代码分离。
  • 轮换:更换环境变量值后重启服务端实例,旧令牌随之失效。
  • 适用边界:本地联调、内网工具,不作为生产鉴权主方案。

原理流程

  1. 环境变量配置令牌、client_id 与 scope。
  2. 启动时读取并构造静态校验器。
  3. 轮换时更新环境变量、重启实例,旧令牌失效。

代码或图示

import os

token = os.environ["MCP_STATIC_TOKEN"]
# 校验器用环境变量构造,源码中不出现令牌字面量

常见误区

  • 把示例令牌提交进仓库:令牌泄露后需全部轮换。
  • 多实例环境变量不一致:部分实例旧令牌仍生效,轮换不彻底。

追问

  • 静态令牌支持多客户端吗?答:映射表可配多组令牌与身份,按条目区分。
  • 环境变量里令牌会出现在进程列表吗?答:环境变量对同主机进程可见,主机需控制访问边界。
  • 生产能长期用静态令牌吗?答:不推荐,缺过期、吊销与审计粒度,应使用 OAuth 方案。

04.7.18.3-030 鉴权失败时 HTTP 状态码与协议错误如何区分?

一句话结论

传输层鉴权失败(缺少/无效令牌)通常返回 HTTP 401,未授权访问返回 403;协议层业务错误在已握手会话内以 JSON-RPC error 返回。两层错误不要混同:连接建立前的访问控制走 HTTP 状态,握手后的工具权限与业务失败走协议错误。

概念解释

  • 401:未认证,令牌缺失或无效,客户端需重新获取凭据。
  • 403:已认证但无权限,scope 不足。
  • 协议 error:会话内方法执行失败,带协议错误码与 data。

原理流程

  1. 请求进入先过鉴权层:失败返回 401/403。
  2. 鉴权通过后进入协议处理:业务/校验失败返回 JSON-RPC error。
  3. 客户端按 HTTP 状态处理重认证,按协议错误处理业务失败。

代码或图示

no/invalid token  -> HTTP 401
authenticated, no scope -> HTTP 403
session tool failure -> JSON-RPC error {code, message, data}

常见误区

  • 把鉴权失败包装成协议 error:握手前没有会话上下文,无法形成协议响应。
  • 业务权限不足返回 403:会话内鉴权失败应走协议错误,HTTP 403 留给传输层授权。

追问

  • 401 响应需要带 WWW-Authenticate 吗?答:按 OAuth/HTTP 鉴权规范建议提供,便于客户端识别方案。
  • 错误响应能返回内部细节吗?答:不能,只给通用提示,细节落服务端日志。
  • 客户端如何重试 401?答:重新走授权流程获取新令牌后重试原请求。

04.7.18.3-031 代理链路中头信息透传与客户端自带凭据如何处理?

一句话结论

代理转发时需保留 Authorization、会话标识与必要的追踪头,同时避免把内部头暴露给不可信客户端;客户端凭据由客户端按授权方案自带,服务端不替客户端保存或注入下游凭据。头透传规则在代理与中间件层统一配置,敏感头不进入业务日志。

概念解释

  • 透传头:授权、会话、追踪标识在链路各层传递。
  • 防伪造:内部信任头(原始 IP、内部标识)只由代理写入,客户端伪造需被覆盖。
  • 凭据归属:下游调用凭据在服务端侧管理,不依赖客户端头传递密钥。

原理流程

  1. 代理配置转发允许头列表,剥离或覆盖不可信内部头。
  2. 服务端中间件读取透传的授权与追踪信息。
  3. 业务处理按会话身份与追踪标识记录日志,不回显敏感头。

代码或图示

client -> proxy: Authorization, Mcp-Session-Id, X-Trace-Id
proxy  -> app:   透传必要头, 覆盖伪造的内部头

常见误区

  • 信任客户端直传的内部头:攻击者可伪造身份头,必须由代理重写。
  • 把 Authorization 头写进访问日志:令牌泄露到日志系统。

追问

  • 原始客户端 IP 怎么获取?答:由代理按可信头写入,应用只信任代理来源。
  • 头名大小写敏感吗?答:HTTP 头不区分大小写,读取按框架归一化处理。
  • 多余头会被转发吗?答:按代理配置的头白名单或默认转发策略,敏感部署应显式控制。

04.7.18.3-032 容器镜像如何选择基础镜像、依赖与启动命令?

一句话结论

镜像应锁定受维护的基础镜像与依赖版本,分层安装运行时与应用代码,启动命令明确传输方式、监听地址与端口。镜像内不打包密钥与本地路径,配置通过环境变量注入;多阶段构建可减小最终镜像体积。具体运行时版本与框架依赖以项目锁定文件为准。

概念解释

  • 基础镜像:选择带安全更新的官方运行时镜像,避免宿主机无关工具。
  • 依赖锁定:按锁文件安装,保证可复现构建。
  • 启动命令:容器入口明确启动 MCP 服务端,参数由环境变量覆盖。

原理流程

  1. 构建阶段安装依赖与代码,最终阶段只保留运行所需。
  2. 镜像设置非 root 用户、工作目录与启动命令。
  3. 运行时通过环境变量注入配置,密钥从密钥管理获取。

代码或图示

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "-m", "mcp_server"]

常见误区

  • 镜像内写死开发配置与令牌:构建产物可被导出,敏感信息必须外置。
  • 用通用大镜像跑服务:体积大、攻击面广,应精简运行时镜像。

追问

  • 容器内用什么用户运行?答:建议非 root 用户,限制文件与进程权限。
  • 依赖版本怎么锁定?答:按项目锁文件安装,不在镜像构建时随意升级。
  • stdio 服务端适合容器吗?答:stdio 由客户端拉起子进程,容器化通常用于 HTTP 传输服务端。

04.7.18.3-033 启动参数 host/port/path 与环境变量如何配置?

一句话结论

FastMCP 2.x 的 mcp.run(transport="http") 默认 host 127.0.0.1、port 8000、路径 /mcp,可在运行参数或 http_app(path=...) 中覆盖;host 绑定回环还是全网卡按部署拓扑决定。参数优先从环境变量读取并给安全默认值,不在代码各处硬编码。

概念解释

  • host:监听地址,本地调试绑回环,容器内绑 0.0.0.0 由代理访问。
  • port:监听端口,避免与同机其他服务冲突。
  • path:MCP 端点路径,与代理路由和客户端地址对齐。

原理流程

  1. 启动入口读取环境变量,解析 host/port/path。
  2. 用解析值启动 HTTP 传输服务。
  3. 代理与客户端按同一组配置连接。

代码或图示

import os

host = os.environ.get("MCP_HOST", "0.0.0.0")
port = int(os.environ.get("MCP_PORT", "8000"))
path = os.environ.get("MCP_PATH", "/mcp")

常见误区

  • 公网环境绑回环地址:外部无法访问;内网调试绑全网卡又缺访问控制。
  • 端口写死在代码里:同机多实例冲突,应可配置。

追问

  • 端口冲突怎么排查?答:检查监听端口占用与代理转发目标。
  • 环境变量缺失用什么默认值?答:给开发安全默认值,生产环境显式配置。
  • 启动参数命令行与环境变量谁优先?答:FastMCP 全局设置以 FASTMCP_ 前缀环境变量为基准,显式传入的运行参数覆盖环境变量值。

04.7.18.3-034 容器内进程模型与信号处理有什么注意点?

一句话结论

容器内服务端应以前台进程运行,正确处理终止信号:收到 SIGTERM 后停止接收新请求,等待进行中调用完成后释放资源退出。单容器单进程模型下不要在应用内 fork 后台进程;信号转发由容器运行时与启动命令共同保证。

概念解释

  • 前台运行:容器主进程即服务进程,日志走标准流。
  • 信号处理:SIGTERM 触发优雅停机,SIGINT 用于本地中断。
  • 子进程:应用内派生的后台任务需在停机时一并清理。

原理流程

  1. 容器启动主进程,注册信号处理器。
  2. 收到终止信号后关闭监听,停止新请求。
  3. 等待在途调用与后台任务结束,释放连接池后退出。

代码或图示

SIGTERM -> stop accepting -> drain in-flight -> release resources -> exit

常见误区

  • 启动命令用 shell 后台化进程:信号无法直达主进程,容器停机超时。
  • 忽略在途任务直接退出:进行中工具调用被硬切断,结果丢失。

追问

  • 停机等待多久?答:设优雅超时,超过后强制退出,与编排层终止期限对齐。
  • 后台定时任务怎么处理?答:停机时取消或等待完成,避免任务悬挂。
  • 多进程模型需要什么?答:按运行时并发模型评估,容器内避免手工 fork 工作进程。

04.7.18.3-035 多副本部署时为什么有状态会话需要粘性?

一句话结论

有状态会话与事件存在单实例内存中,客户端后续请求必须落到持有该会话的实例,否则会话标识查不到、上下文丢失。粘性(会话亲和)通过代理按会话标识路由到固定实例解决;但粘性会削弱负载均衡,实例故障时会话仍会丢失。

概念解释

  • 状态位置:会话上下文、订阅关系、事件存储在实例内存。
  • 粘性依据:会话标识或客户端标识作为路由键。
  • 局限:实例重启/漂移导致会话失效;负载不均与扩缩容受影响。

原理流程

  1. 握手请求落到实例 A,会话保存在 A。
  2. 代理按会话标识把后续请求路由回 A。
  3. A 故障或扩缩容后会话丢失,客户端重新握手。

代码或图示

session-1 -> instance A (sticky)
session-2 -> instance B (sticky)

常见误区

  • 无粘性多副本跑有状态服务:请求随机漂移,会话时有时无。
  • 把粘性当高可用:实例故障会话不可恢复,需共享存储或无状态设计兜底。

追问

  • 粘性按什么键路由?答:会话标识优先,其次客户端标识,按代理能力配置。
  • 粘性会话能跨实例迁移吗?答:内存状态不能自动迁移,需外部共享存储。
  • 健康检查会打断粘性吗?答:实例摘除后其会话需重建,客户端应能重连。

04.7.18.3-036 无状态服务水平扩展的前提与局限是什么?

一句话结论

无状态模式下请求自包含、不依赖实例内存会话,多副本可自由负载均衡,水平扩展简单;局限是跨请求的会话记忆、资源订阅与长任务进度推送受限,需要结果可重算或外部存储支撑。适合调用短、可重复、无会话推送需求的场景。

概念解释

  • 扩展前提:身份与所需参数每次请求带上,共享资源外置(数据库、缓存、对象存储)。
  • 局限:无会话上下文,订阅/进度推送降级;重复调用需保证幂等。
  • 适用边界:读多写少、短事务、可水平扩容的工具服务。

原理流程

  1. 设计服务不保存请求间状态,所需数据来自请求与外部存储。
  2. 多副本前置于负载均衡,请求任意落到实例。
  3. 长任务与推送需求由外部队列/存储补偿。

代码或图示

client -> load balancer -> replica A / B / C (stateless, shared backend)

常见误区

  • 宣称无状态却在模块级缓存会话数据:实例间缓存不一致,破坏扩展性。
  • 无状态模式下保留会话内订阅预期:功能受限,需在接口文档说明。

追问

  • 无状态下长任务怎么跟踪?答:任务状态与结果放外部存储,客户端按任务标识查询。
  • 共享缓存算无状态吗?答:进程外共享存储支持水平扩展,本地内存缓存仍有状态限制。
  • 混合部署可行吗?答:按能力拆分,有状态组件与无状态组件分别扩展。

04.7.18.3-037 当前版本对共享会话存储的支持情况如何?

一句话结论

跨副本共享会话/事件存储依赖框架提供的外部后端:FastMCP 2.x 默认内存存储,会话与事件只在本实例有效;接入 Redis 等共享后端后才可跨实例恢复。未核实后端可用性前,不要在架构上假设会话可跨实例恢复(待确认:验证点:当前版本外部会话/事件存储后端)。

概念解释

  • 内存后端:默认实现,单机进程内有效。
  • 外部后端:共享存储支撑多副本会话与事件续传。
  • 核实路径:查框架文档与存储接口定义,跑跨实例重连用例验证。

原理流程

  1. 确认版本提供的会话/事件存储后端清单。
  2. 若有外部后端,按配置接入共享存储。
  3. 跨实例重连测试会话与事件是否可恢复;不支持则按粘性或无状态方案部署。

代码或图示

# 外部会话/事件存储后端、配置参数与数据结构需按安装版本核实

常见误区

  • 凭其他框架经验假设 Redis 后端存在:版本未提供时多副本会话必然漂移。
  • 共享存储未做过期清理:会话与事件长期堆积,存储膨胀。

追问

  • 怎么核实是否支持?答:查当前版本文档与存储接口定义,实跑跨实例重连用例验证。
  • 共享存储挂了影响什么?答:会话恢复与事件续传降级,需评估可用性与兜底。
  • 会话存储需要持久化吗?答:按恢复需求决定,短期会话可内存,长任务结果需外部持久化。

04.7.18.3-038 结构化日志应包含哪些字段与级别?

一句话结论

运行日志应结构化输出:时间、级别、事件类型、会话标识、client_id、工具/资源名称、耗时与错误标识;敏感参数与令牌不进入日志。级别区分 debug/info/warning/error,生产默认 info 以上,关键调用与异常强制留痕。日志字段贯穿请求链路,便于按会话与工具检索。

概念解释

  • 基础字段:时间、级别、事件、服务端名称。
  • 关联字段:会话标识、client_id、trace id、组件名。
  • 业务字段:入参摘要、耗时、错误码;敏感内容脱敏。

原理流程

  1. 日志初始化配置结构化格式与级别输出。
  2. 请求进入、组件调用、返回与异常各阶段记录字段。
  3. 日志采集按会话与 trace 检索,错误日志关联错误码。

代码或图示

{
  "level": "info",
  "event": "tool_call",
  "session": "sess-1",
  "client_id": "cli-1",
  "tool": "get_order",
  "duration_ms": 12
}

常见误区

  • 日志只写自由文本:无法按会话/工具聚合检索。
  • 完整记录入参与令牌:敏感信息泄露到日志系统。

追问

  • 入参能记哪些?答:记标识与摘要,大对象与敏感字段脱敏或不记。
  • 日志级别怎么选?答:启动与关键流程 info,排查细节 debug,异常 warning/error。
  • Context 日志与本地日志关系?答:Context 日志通知发往客户端,本地结构化日志落服务端。

04.7.18.3-039 调用次数、耗时、错误率等指标如何采集?

一句话结论

围绕组件调用采集指标:调用次数、成功/失败计数、耗时分布、错误码分布与并发数;在框架边界埋点,不侵入每个工具函数。指标按工具/资源/提示与身份维度聚合,配合日志与追踪定位慢调用与错误上涨。具体指标导出接口按所选可观测性栈实现。

概念解释

  • 计数器:调用总数、成功数、失败数,按错误码分类。
  • 耗时指标:直方图或摘要记录延迟分布,不只记平均值。
  • 维度:组件名、会话/客户端、错误类型,便于下钻定位。

原理流程

  1. 在请求进入与返回边界统一埋点。
  2. 记录组件名、结果状态、耗时与错误码。
  3. 指标导出到监控栈,配置阈值告警。

代码或图示

tool_calls_total{tool="get_order",status="ok|error"}
tool_call_duration_ms{tool="get_order"} histogram

常见误区

  • 只记录总耗时不分类:慢工具与错误调用无法区分。
  • 在工具内部散落打点:重复且口径不一致,应集中在边界层。

追问

  • 指标需要记标签基数吗?答:高基数标签(如 user_id)需控制,避免指标爆炸。
  • 慢调用阈值怎么定?答:按 SLA 与分布基线设定告警线。
  • 框架自带指标吗?答:FastMCP 2.x 未在公开文档中承诺内置指标导出端点;调用计数、耗时与错误率通常在 ASGI/边界层自行埋点(待确认:验证点:当前版本是否提供内置指标导出接口)。

04.7.18.3-040 trace id 如何贯穿一次调用链路?

一句话结论

一次调用从请求入口生成或接收 trace id,写入会话上下文并随日志、指标与下游调用传递;同一会话的工具调用、资源读取与日志记录共享同一追踪标识,便于串起完整链路。客户端传入的追踪头需校验来源,不可信时重新生成。

概念解释

  • 生成与继承:入口无标识则生成,有合法传入则沿用。
  • 传递范围:日志字段、下游请求头、异步任务上下文。
  • 关联粒度:trace id 串联整条链路,span 标识具体阶段。

原理流程

  1. 请求入口读取或生成 trace id,挂入上下文。
  2. 工具执行各阶段日志携带 trace id。
  3. 下游调用透传追踪头,链路在监控系统按 id 聚合。

代码或图示

incoming request -> trace_id = X-Trace-Id or new
log/metrics/downstream headers all carry trace_id

常见误区

  • 异步任务丢失上下文:trace id 未传递到协程/后台任务,链路断裂。
  • 信任任意客户端传入的内部追踪值:需限定来源与格式,避免注入伪造标识。

追问

  • trace id 存在哪里?答:请求/会话上下文,随调用链路传递,不落全局变量。
  • 多轮调用共享一个 trace 吗?答:按会话与链路约定,单次调用与跨请求关联分别设计。
  • 日志与指标如何对齐?答:都带同一 trace id 与组件名,便于交叉检索。

04.7.18.3-041 工具调用耗时与下游超时预算如何划分?

一句话结论

一次调用的总耗时预算应分层分配:协议等待、工具执行、下游 API/数据库/文件 IO 各占一段,任一下游超时按预算取消并返回错误。工具不能无限等待下游,超时值与重试策略按下游 SLA 设定;长任务通过进度上报与异步结果衔接,不阻塞会话通道。

概念解释

  • 总预算:客户端等待与服务端执行的总时限。
  • 下游预算:外部依赖调用单独设超时,留出序列化与处理余量。
  • 取消传播:超时后取消下游请求,释放连接与协程资源。

原理流程

  1. 确定调用总时限,拆分到工具与各下游依赖。
  2. 下游客户端按预算设超时,失败后映射为业务错误。
  3. 记录分段耗时指标,定位慢在协议、工具还是下游。

代码或图示

budget: 30s
  tool execute: 25s
    downstream API: 10s
    DB: 5s
  response serialize: remainder

常见误区

  • 下游调用不设超时:连接悬挂占用并发,拖垮整体吞吐。
  • 多层超时叠加不核算:外层已超时,内层仍在等待,资源不释放。

追问

  • 下游超时重试几次?答:按幂等性与 SLA 设定,敏感写操作不盲目重试。
  • 长任务如何不占住预算?答:转异步任务,进度/结果经事件或查询接口衔接。
  • 耗时指标怎么分段?答:记录下游与工具内部分段耗时,边界层汇总。

04.7.18.3-042 如何搭建内存内 client 直连测试?

一句话结论

单元测试不启动网络端口:from fastmcp import Client, FastMCP,把 FastMCP 实例直接传给 Client,async with Client(mcp) as client: 即在内存内直连,完成握手并调用组件。这样测试快、无端口依赖,能覆盖工具逻辑、schema 与错误路径。

概念解释

  • 内存内传输:不经过真实 socket/stdio,双方在同一进程内交换报文。
  • 测试入口:框架测试辅助提供 client 或 transport 构造。
  • 覆盖范围:注册清单、调用结果、参数校验、鉴权与会话隔离。

原理流程

  1. 测试中构造 FastMCP 实例并注册组件。
  2. 用内存内传输建立测试客户端连接,触发 initialize 握手。
  3. 调用工具/资源/提示并断言结果与错误。

代码或图示

from fastmcp import Client, FastMCP

async with Client(mcp) as client:
    result = await client.call_tool("add", {"a": 1, "b": 2})
    assert result.data == 3

常见误区

  • 测试先起真实 HTTP 服务再连:测试慢且受端口与环境影响,应优先内存内。
  • 只测成功路径:校验失败、鉴权拒绝、下游异常同样需要用例覆盖。

追问

  • 内存内测试能覆盖传输层吗?答:覆盖协议报文与序列化,网络代理行为需另行集成测试。
  • 测试需要生命周期启动吗?答:共享资源在 lifespan 初始化,测试按框架辅助触发启动/关闭。
  • 并发会话隔离怎么测?答:内存内建立两个 client 会话并发调用,断言上下文互不干扰。

04.7.18.3-043 call_tool 断言如何校验结果内容块与结构化数据?

一句话结论

测试调用工具后,从返回结果中提取内容块或结构化输出,断言字段值、类型与内容块类型符合预期;不只断言“调用没报错”。结构化输出按模型/字典字段校验,文本内容块校验文本片段,媒体块校验编码与 MIME 类型。

概念解释

  • 结果结构:成功结果含内容块列表,结构化输出可能单独提供数据字段。
  • 断言层次:组件名存在、调用成功、字段值正确、类型匹配。
  • 数据还原:必要时把内容块解析为对象再断言,避免只比对原始字符串。

原理流程

  1. 测试客户端调用工具,传入固定入参。
  2. 提取结果:内容块文本或结构化数据。
  3. 断言关键字段、类型与数量,边界值与空结果单独覆盖。

代码或图示

result = await client.call_tool("add", {"a": 1, "b": 2})
assert result.data == 3
assert result.content[0].type == "text"

常见误区

  • 断言返回对象整体相等:内部字段演进导致测试脆弱,应断言关键契约字段。
  • 忽略空结果与错误码分支:边界条件未覆盖,回归时易漏。

追问

  • 文本块怎么取内容?答:result.content 为内容块列表,文本块读 text 字段;多块时按顺序定位。
  • 模型返回怎么断言?答:用模型字段断言,必要时校验 model_dump 结构。
  • 结果含二进制块怎么测?答:断言 MIME 类型、编码与长度,不直接比对大段字节。

04.7.18.3-044 错误路径断言应覆盖哪些场景?

一句话结论

测试必须覆盖失败路径:参数校验失败、鉴权/scope 不足、工具业务异常、下游超时与不存在的组件调用。断言错误类型、协议错误码或 HTTP 状态、安全 message,以及日志/指标中的失败记录;确保错误不外泄堆栈与敏感信息。

概念解释

  • 校验错误:缺参、类型不符、约束越界。
  • 鉴权错误:无令牌、令牌无效、scope 不足。
  • 业务与依赖错误:未找到、冲突、下游超时、内部异常兜底。

原理流程

  1. 为每类错误构造触发用例(非法入参、伪造令牌、下游异常桩)。
  2. 调用后捕获协议 error 或 HTTP 状态。
  3. 断言错误码、message 不含堆栈与敏感信息,必要时核对日志记录。

代码或图示

import pytest
from fastmcp.exceptions import ToolError

with pytest.raises(ToolError):
    await client.call_tool("get_order", {"order_id": "missing"})

常见误区

  • 只测成功路径:失败分支无回归保护,线上错误处理易被改坏。
  • 断言错误 message 完整长文本:文案调整会打断测试,应断言错误码与关键提示。

追问

  • 校验失败错误码是哪类?答:协议层参数错误对应 JSON-RPC -32602(invalid params),业务错误由工具抛出并经业务错误码返回。
  • 下游异常如何模拟?答:测试桩抛出超时/异常,验证服务端包装后的错误。
  • 错误日志断言什么?答:记录失败事件与错误标识,不出现令牌与完整敏感入参。

04.7.18.3-045 契约测试如何校验工具清单与 schema 快照?

一句话结论

契约测试调用 list 方法获取工具/资源/提示清单,核对组件名、描述与 inputSchema 结构;可把 schema 快照保存为基准文件,变更时比对差异并人工确认。快照防止签名调整意外改变对外契约,schema 演进需走显式变更流程。

概念解释

  • 清单契约:组件名称集合与描述是客户端依赖的接口面。
  • Schema 快照:字段、类型、约束、必填项的结构基准。
  • 变更管理:快照 diff 需确认是有意演进,而非误改类型或默认值。

原理流程

  1. 测试连接后拉取 tools/resources/prompts 清单。
  2. 提取名称集合与 schema 结构,与快照基准比对。
  3. 不一致时失败提示;有意变更则更新快照并记录说明。

代码或图示

tools = await client.list_tools()
names = {t.name for t in tools}
assert "add" in names

常见误区

  • 快照包含易变字段(时间、版本号):diff 噪声大,应固定稳定契约字段。
  • schema 变更不更新客户端:服务端契约演进需同步调用方适配。

追问

  • 快照存什么格式?答:JSON 结构基准,纳入版本管理。
  • 描述文案变更算契约变更吗?答:影响模型选择与使用,应在 diff 中确认。
  • 快照测试能替代运行时校验吗?答:不能,还需成功/失败调用用例验证行为。

04.7.18.3-046 经 ASGI transport 测试挂载后的完整链路怎么做?

一句话结论

集成测试把 MCP 子应用挂载到父 ASGI 应用,用 ASGI 测试传输发起真实 HTTP 风格请求,覆盖路由前缀、中间件、鉴权与协议处理全链路。相比内存内直连,它验证挂载顺序、路径拼接与中间件协作;挂载 Starlette 子应用时必须把 mcp_app.lifespan 传给父应用 Mount 的 lifespan 参数。

概念解释

  • 挂载验证:父应用前缀、子应用端点路径与中间件顺序。
  • 全链路:请求进入 → 中间件 → 协议解析 → 工具执行 → 响应返回。
  • 生命周期:测试需正确启动/关闭 ASGI lifespan,共享资源可用。

原理流程

  1. 构造父应用,挂载 MCP 子应用并配置中间件。
  2. 用 ASGI 测试传输发起 initialize 与工具调用。
  3. 断言路由可达、鉴权生效、结果正确,覆盖前缀与路径拼接。

代码或图示

from starlette.applications import Starlette
from starlette.routing import Mount

parent = Starlette(routes=[Mount("/mcp-server", app=mcp_app, lifespan=mcp_app.lifespan)])

常见误区

  • 挂载后未传子应用 lifespan:共享资源未初始化,测试中连接池/配置为空。
  • 只测子应用直连:漏掉父应用前缀与中间件,部署后才暴露路由问题。

追问

  • ASGI 测试需要真实端口吗?答:不需要,测试传输在进程内模拟 ASGI 调用。
  • 中间件顺序怎么在测试体现?答:构造不同顺序父应用,验证 CORS/鉴权行为。
  • 集成测试覆盖哪些边界?答:404 路径、401 鉴权、挂载前缀拼接与 SSE 响应形态。

04.7.18.3-047 协议 schema 校验与业务校验如何分层?

一句话结论

入参先过协议 schema 校验:类型、必填、枚举、范围与格式;通过后再做业务校验:存在性、归属、权限与领域规则。两层职责分离,协议层拒绝格式非法请求,业务层拒绝规则不满足的请求,错误分别映射到协议参数错误与业务错误。

概念解释

  • 协议层:由签名类型与 Field 约束生成 schema,框架自动校验。
  • 业务层:领域规则无法用类型表达,在工具函数内判断。
  • 错误映射:格式问题归参数错误,规则问题归业务错误,便于客户端区分处理。

原理流程

  1. 请求参数进入框架,按 inputSchema 校验类型与约束。
  2. 校验通过后执行工具,函数内做业务规则判断。
  3. 业务不满足抛领域异常,映射业务错误返回。

代码或图示

@mcp.tool
def get_order(order_id: str) -> dict:
    if not order_id:
        raise ValueError("order_id 不能为空")  # 业务校验
    order = repo.find(order_id)
    if order is None:
        raise NotFoundError("订单不存在")
    return order

常见误区

  • 把业务规则塞进 schema 枚举:规则动态变化,schema 无法表达存在性与归属。
  • 业务校验在协议层之前手写重复判断:应利用框架 schema 自动校验,避免双份维护。

追问

  • 严格校验模式影响哪层?答:影响协议 schema 校验严格程度,业务规则仍在工具内。
  • 两层错误怎么区分?答:错误码与 message 分层,客户端按类型提示重试或修正参数。
  • 校验失败信息暴露内部规则吗?答:对外给必要提示,敏感规则细节不泄露。

04.7.18.3-048 命令注入、路径穿越与资源 URI 校验如何防护?

一句话结论

工具执行外部命令时不拼接用户输入进 shell 字符串,使用参数数组并限制命令白名单;文件路径规范化后限制在允许根目录内,禁止 .. 逃逸;资源 URI 按 scheme 与模板白名单校验,不把输入直接拼成本地路径或 URI 访问。所有外部输入先校验再使用。

概念解释

  • 命令注入:避免 shell 解释元字符,参数化调用,最小权限执行。
  • 路径穿越:规范化路径后检查前缀是否在允许目录内。
  • URI 校验:限定 scheme、主机/模板段,拒绝非法字符与未登记 scheme。

原理流程

  1. 接收外部输入,先做格式与白名单校验。
  2. 命令调用走参数数组;路径规范化并做根目录前缀检查;URI 按模板匹配。
  3. 校验通过才访问下游资源,失败返回安全错误。

代码或图示

from pathlib import Path

BASE = Path("/data/files").resolve()

def safe_path(name: str) -> Path:
    p = (BASE / name).resolve()
    if not str(p).startswith(str(BASE)):
        raise ValueError("路径越界")
    return p

常见误区

  • 用字符串拼接 shell 命令:输入含分号/管道符即可注入。
  • 只过滤 .. 字符串:编码、符号链接与规范化绕过,应解析后做前缀检查。
  • 资源 URI 直接转本地文件路径:未限定 scheme 可访问敏感本地资源。

追问

  • 外部命令用什么执行方式?答:参数数组形式调用,不经 shell 解释(按运行时 API 选择)。
  • 路径校验要防符号链接吗?答:需要,解析真实路径后再比对根目录。
  • URI 白名单在哪里维护?答:资源注册模板与 scheme 清单集中配置。

04.7.18.3-049 速率限制与整体超时防护放在哪一层?

一句话结论

速率限制在传输/中间件层按客户端或会话维度限流,保护服务端不被突发调用打垮;整体超时在框架边界与下游调用双层控制。限流规则按身份、组件与时段配置,超限返回限流错误;工具内部不再各自实现全局限流,避免口径分散。

概念解释

  • 限流维度:client_id、会话、IP、组件名,按业务风险选择。
  • 超时防护:请求总时限、下游超时、长任务异步化。
  • 位置:传输中间件统一拦截,工具函数聚焦业务逻辑。

原理流程

  1. 中间件识别身份与组件,检查配额与时间窗口。
  2. 超限返回限流错误,不进入工具执行。
  3. 执行中按超时预算取消下游调用,记录限流与超时指标。

代码或图示

request -> rate limit check (client, tool, window) -> allow / 429
        -> tool execute with per-call timeout

常见误区

  • 限流只在单实例内存计数:多副本下配额被放大,需共享计数或按实例配额估算。
  • 工具内自行 sleep 等待:占用并发资源,应在入口拒绝排队。

追问

  • 限流返回什么状态/错误?答:HTTP 429 或协议限流错误,附带重试提示。
  • 限流阈值怎么定?答:压测容量与业务 SLA 确定,区分读写与重资源工具。
  • 超时与限流区别?答:限流控制单位时间请求量,超时控制单次调用时长。

04.7.18.3-050 敏感信息为什么不能进入日志与错误返回?

一句话结论

令牌、密钥、密码、个人敏感数据与完整凭据不得写入日志、错误 message、响应 data 或指标标签;错误对外只给通用提示与必要标识,细节落受控服务端日志。日志与错误通道可能被采集、展示给调用方,泄露面必须按最小化原则控制。

概念解释

  • 泄露通道:本地日志、stderr、错误响应、指标标签、事件存储。
  • 脱敏范围:认证凭据、密钥、身份证/手机号等个人信息、内部路径。
  • 最小返回:对外错误不含堆栈、SQL、内部主机与参数明文。

原理流程

  1. 定义敏感字段清单与脱敏规则。
  2. 日志记录前过滤/掩码;错误响应构造时剥离敏感细节。
  3. 代码审查与日志扫描检查敏感信息残留。

代码或图示

def mask(value: str) -> str:
    if len(value) <= 4:
        return "***"
    return value[:2] + "***" + value[-2:]

常见误区

  • 异常 message 拼接完整入参:堆栈与参数随错误返回调用方。
  • 指标标签记 user_id 等敏感高基数值:既泄露身份又造成标签膨胀。

追问

  • 调试需要看敏感值怎么办?答:受控环境临时开启,脱敏规则默认开启,不持久化明文。
  • 第三方库日志会带敏感信息吗?答:需检查并配置日志脱敏,避免库默认打印请求头。
  • 错误返回能带 request id 吗?答:可以,用标识关联服务端受控日志,不暴露内部细节。

04.7.18.3-051 MCP 服务端与既有 Web 服务同进程共存如何协调端口?

一句话结论

MCP 子应用可挂载到既有 ASGI/Web 应用的同一进程与端口下,按路径前缀区分路由,避免另开端口;挂载时共享父应用的中间件、CORS 与鉴权体系。端口冲突只在各自监听不同端口时出现,同进程共存应通过路由前缀而非多端口拆分。

概念解释

  • 同进程挂载:父应用 mount MCP 子应用,复用事件循环与 HTTP 服务。
  • 路由隔离:业务 API 与 MCP 端点使用不同前缀,避免路由冲突。
  • 资源共享:连接池、配置与后台任务在 lifespan 统一初始化。

原理流程

  1. 父应用创建时挂载 MCP 子应用到独立前缀。
  2. 统一配置中间件顺序、CORS 与鉴权。
  3. 监听单一端口,请求按路径分发到业务路由或 MCP 端点。

代码或图示

mcp_app = mcp.http_app(path="/mcp")
app.mount("/mcp", mcp_app)
# 业务路由: /api/...
# MCP 端点: /mcp

常见误区

  • MCP 与业务各起一个端口:进程与连接翻倍,部署与鉴权分散。
  • 挂载前忽略子应用 lifespan:共享资源未随父应用启动初始化。

追问

  • 同进程会互相阻塞吗?答:异步模型下共享事件循环,任一方阻塞都会影响另一方,需避免同步长阻塞。
  • 端口被占用怎么判断?答:启动报错或检查监听端口,调整父应用端口配置。
  • 鉴权能复用业务中间件吗?答:可以,挂载前在父应用统一配置,按路径区分策略。

04.7.18.3-052 同进程下 lifespan 与后台任务如何协调?

一句话结论

共享资源(数据库连接池、下游客户端、配置)在 MCP 实例或父应用的 lifespan 中初始化与清理;后台定时任务、消费者与服务端同生命周期启停。同进程共存时,lifespan 启动顺序保证资源先于路由就绪,停机时先停后台任务再释放共享连接。

概念解释

  • 启动顺序:lifespan 进入阶段初始化配置、连接池与后台任务。
  • 运行期:MCP 工具复用 lifespan 注入的共享资源。
  • 关闭顺序:停止后台任务 → 等待在途调用 → 释放连接池与客户端。

原理流程

  1. 应用启动触发 lifespan,创建共享资源并启动后台任务。
  2. 组件执行从上下文/依赖获取共享资源,不在函数内新建连接。
  3. 关闭信号触发 lifespan 退出阶段,按相反顺序清理资源。

代码或图示

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app):
    pool = create_pool()
    yield {"pool": pool}
    await pool.close()

mcp = FastMCP("demo", lifespan=lifespan)

常见误区

  • 工具函数内新建连接池:高频调用反复建连,资源泄漏。
  • 后台任务脱离生命周期管理:停机后任务仍在跑,占用连接与协程。

追问

  • lifespan 注入对象怎么传给工具?答:经 Context 读取,如 ctx.fastmcp 实例与 ctx.set_state/get_state 存放的共享状态。
  • 启动失败如何处理?答:lifespan 抛错应阻断启动,不进入服务就绪状态。
  • 同进程两个应用 lifespan 顺序?答:按父应用与挂载子应用的启动嵌套顺序,测试中验证。

04.7.18.3-053 健康检查端点与就绪/存活探针如何设计?

一句话结论

健康检查区分存活探针(进程在跑、未死锁)与就绪探针(依赖可用、可接流量):就绪检查覆盖下游连接池、关键外部依赖;存活检查只反映进程与事件循环状态。MCP 端点本身不作为健康探针,避免把协议握手误当健康判断。探针路径不经过鉴权或按内部网络单独放行。

概念解释

  • 存活 liveness:进程存活、事件循环可响应,失败由编排层重启。
  • 就绪 readiness:依赖可用、连接池健康,失败时摘流不重启。
  • 探针位置:父应用独立健康路由,与 MCP 协议端点分离。

原理流程

  1. 父应用提供 /health/live 与 /health/ready 路由。
  2. 就绪检查探测下游依赖与连接池状态。
  3. 编排层按探针结果重启实例或摘除流量。

代码或图示

GET /health/live  -> process alive
GET /health/ready -> dependencies reachable, pool healthy

常见误区

  • 用 MCP 握手做健康检查:协议协商开销大,且鉴权/会话状态干扰探针结果。
  • 就绪检查不区分依赖:下游抖动时实例被反复重启,应摘流等待恢复。

追问

  • 探针需要鉴权吗?答:内部网络按白名单放行,公开暴露的探针不泄露依赖细节。
  • 健康检查超时多久?答:短超时快速失败,与编排探测周期对齐。
  • 指标能接入探针吗?答:可暴露基础存活信息,详细指标走独立监控端点。

04.7.18.3-054 优雅停机如何处理进行中调用、连接与资源释放?

一句话结论

优雅停机流程:停止接收新请求 → 等待在途工具调用与后台任务完成(或超过宽限强制取消)→ 关闭下游连接池与客户端 → 退出进程。长任务需配合事件存储或外部状态,避免停机硬切断导致结果丢失;停机宽限与编排层终止期限对齐。

概念解释

  • 停止接流:关闭监听与新会话,不再派发新调用。
  • 在途排空:等待进行中调用收尾,宽限期内未完成则取消。
  • 资源释放:连接池、文件句柄、后台任务按顺序清理。

原理流程

  1. 收到 SIGTERM/关闭信号,进入停机阶段。
  2. 拒绝新请求,等待在途调用与后台任务结束。
  3. 释放共享资源,进程退出;超时未结束则强制取消。

代码或图示

signal -> stop accept -> drain in-flight (grace period) -> release pool -> exit

常见误区

  • 直接退出进程:在途调用被切断,下游事务与连接残留。
  • 等待无限期:编排层到点强杀,应设宽限并记录未完成任务。

追问

  • 长任务停机后结果怎么办?答:状态落外部存储,新实例或客户端重连后查询恢复。
  • 停机时新会话能建立吗?答:优雅阶段应拒绝新会话,只排空已有调用。
  • 资源释放顺序?答:先停后台任务与新连接,再关池,最后释放配置。

04.7.18.3-055 协议流被日志污染如何系统排查?

一句话结论

排查按通道分工展开:确认 stdout 只含协议报文、stderr 承载日志;检查所有 print、第三方库启动横幅、日志处理器去向与标准流重定向。stdio 场景可抓取子进程 stdout 逐行检查是否为合法 JSON;HTTP 场景则检查响应体是否混入非协议文本。定位后把输出改到 stderr 或文件。

概念解释

  • 污染源清单:业务 print、库日志、进度条、横幅、调试输出。
  • 检查手段:标准流抓包、日志配置审计、第三方库初始化输出。
  • 修复方向:所有非协议输出离开 stdout,配置归一化到 stderr。

原理流程

  1. 复现握手与一次调用,抓取 stdout/响应体。
  2. 逐行核对协议帧,定位非文本来源模块。
  3. 修改输出去向,复测协议流干净。

代码或图示

stdout lines -> JSON parse check
bad line    -> trace source print/log handler -> redirect to stderr

常见误区

  • 只改业务代码,忽略依赖库默认 stdout:库横幅与日志仍污染通道。
  • 本地终端看不出通道:需按标准流分别抓取,不能凭控制台混排判断。

追问

  • 怎么抓 stdio 子进程输出?答:客户端/调试器分别接管 stdin/stdout/stderr 记录。
  • 框架日志默认走哪?答:检查日志处理器配置,必要时显式设为 stderr。
  • 污染修复后验证什么?答:完整握手、list、一次工具调用,stdout 无额外文本。

04.7.18.3-056 阻塞调用卡死 transport 的现象与定位方法是什么?

一句话结论

事件循环被同步阻塞调用占住后,stdin/HTTP 读取暂停,后续请求无人处理:ping 超时、工具调用挂起、连接逐渐堆积。定位方法看日志时间线与线程/协程栈,确认是否有同步 IO、CPU 密集计算或锁等待在异步上下文执行;修复为异步驱动、执行器卸载或限制阻塞操作。

概念解释

  • 阻塞类型:同步网络 IO、本地文件/计算、阻塞锁、同步库调用。
  • 现象:无报错但不响应,健康检查可能通过而业务通道卡死。
  • 定位:栈快照、耗时日志、事件循环阻塞监控。

原理流程

  1. 工具内同步阻塞调用占住事件循环。
  2. 后续消息无法读取派发,连接挂起。
  3. 抓栈定位阻塞点,改为异步或卸载线程,补充超时与阻塞监控。

代码或图示

# 问题: 同步阻塞在异步事件循环
# data = requests.get(url).json()

# 修复: 异步客户端
async with httpx.AsyncClient() as client:
    resp = await client.get(url)

常见误区

  • 把挂起当下游慢:下游有超时返回才是慢,完全不响应且无新日志多为循环阻塞。
  • 用后台线程补救但不释放主循环:阻塞点仍占资源,需按并发模型改造。

追问

  • 阻塞库必须用怎么办?答:放到线程执行器并设超时,不阻塞事件循环。
  • 怎么监控事件循环阻塞?答:记录循环延迟/心跳,配合栈快照定位。
  • 同步工具在异步框架里如何调度?答:FastMCP 2.x 把同步函数经线程池卸载执行,阻塞操作建议用 anyio.to_thread.run_sync,避免直接占住事件循环。

04.7.18.3-057 超大响应导致解析或上下文失败如何处理?

一句话结论

超大响应可能撑大报文、截断传输或挤占客户端上下文。服务端应控制结果体积:分页、字段投影、摘要化,大文件/大列表改资源 URI 按需读取;响应设大小阈值并记录超限指标。客户端解析失败时应能区分传输截断与上下文超限,服务端不默认返回全量明细。

概念解释

  • 体积风险:JSON 序列化、代理缓冲区、通道报文上限。
  • 上下文风险:结果进入客户端模型上下文后挤占后续空间。
  • 降级策略:分页、摘要、URI 引用、流式分段返回。

原理流程

  1. 工具评估结果规模,超阈值走分页/摘要/引用方案。
  2. 响应只包含决策所需字段,大对象不内嵌。
  3. 客户端按需读取后续页或资源,错误按截断/超限分类处理。

代码或图示

@mcp.tool
def list_items(page: int = 1, size: int = 20) -> dict:
    return {"page": page, "items": repo.page(page, size)}

常见误区

  • 工具返回全表大对象:报文与上下文双重失控,模型只能看到截断内容。
  • 只在客户端裁剪:服务端已把大数据推到通道,带宽与解析成本无法收回。

追问

  • 响应大小上限在哪里设?答:由传输层、反向代理与序列化层按部署限制配置,框架不提供统一硬编码默认上限。
  • 大文件怎么给?答:资源 URI 或外部链接,分块读取,不嵌入响应。
  • 超限错误怎么返回?答:业务错误提示结果过大,给出分页/引用方式。

04.7.18.3-058 客户端重连丢会话的原因有哪些,如何规避?

一句话结论

丢会话原因:有状态会话存内存且重连漂移到其他实例、空闲超时已回收、无状态模式本不保留上下文、事件存储缺失导致任务事件不补收、代理未正确转发会话标识头。规避按场景选:粘性路由、共享会话/事件存储、无状态自包含设计、保留会话头与超时配置,并验证重连用例。

概念解释

  • 状态位置决定可恢复性:内存状态绑定实例,外部存储才可跨实例恢复。
  • 头与超时:会话标识未透传或空闲回收过快都会导致续接失败。
  • 重连验证:测试断线后重连是否恢复会话与任务事件。

原理流程

  1. 梳理部署会话模型:有状态/无状态、存储位置。
  2. 检查代理头透传、超时与事件存储配置。
  3. 构造断线重连用例验证恢复行为,不满足则调整架构。

代码或图示

reconnect fail -> 实例漂移 / 会话过期 / 无状态 / 头丢失 / 无事件存储
remedy        -> 粘性 / 共享存储 / 自包含请求 / 透传头 / 配置存储

常见误区

  • 重连后默认会话还在:未验证恢复行为就上线,断线即丢任务。
  • 只靠客户端重试:服务端状态不保留时重试只能重新发起,不能续接原会话。

追问

  • 如何测试重连续传?答:断开连接后带原会话标识重连,断言会话与事件可恢复。
  • 会话过期时间设多长?答:按业务空闲时长配置,兼顾内存回收与体验。
  • 多副本无共享存储怎么办?答:启用粘性,或改造为无状态/外部状态方案。

04.7.18.3-059 部署上线前自检清单包含哪些项?

一句话结论

上线前逐项验证:传输握手成功、鉴权拒绝与放行正确、端点路径与代理前缀对齐、会话隔离与重连行为、日志/指标/trace 落地、健康探针可用、限流超时生效、错误响应脱敏、依赖与配置经环境变量注入。清单在测试与预发环境逐项跑通,遗留问题记录验证点并跟踪。

概念解释

  • 连通性:握手、list 清单、一次成功调用、一次失败调用。
  • 安全:鉴权、scope、脱敏、限流、路径/URI 校验。
  • 运行:可观测性、探针、优雅停机、会话与扩展方案。

原理流程

  1. 按清单构造测试用例覆盖各检查项。
  2. 在预发环境经代理链路验证,不只本机直连。
  3. 记录结果与遗留风险项,通过后上线。

代码或图示

握手 -> 清单 -> 成功调用 -> 鉴权拒绝 -> 路径/前缀 -> 会话隔离
日志指标 -> 探针 -> 限流超时 -> 错误脱敏 -> 优雅停机

常见误区

  • 只在本机验证:代理前缀、缓冲、超时与头透传问题在真实链路才暴露。
  • 跳过失败路径自检:鉴权与错误脱敏问题上线后才被外部触发。

追问

  • 自检需要自动化吗?答:核心链路纳入集成测试,部署后做冒烟回归。
  • 未核实项怎么处理?答:标注验证点与负责人,未核实不写成对外承诺。
  • 回滚预案包含什么?答:版本回退、配置回退与会话/任务状态兜底说明。

04.7.18.3-060 本章常见版本差异与待确认验证点有哪些?

一句话结论

版本敏感点包括:传输 API 与默认端点路径、会话标识头名称、有状态/无状态与 JSON 响应开关、事件存储后端、鉴权校验器类名与参数、测试传输辅助 API、指标与生命周期钩子接口、超时与大小默认值。这些不能凭旧版经验写死,应在目标版本核对文档、类型定义与运行报文后固化结论。

概念解释

  • 差异类别:API 命名、默认值、配置开关、支持后端、行为口径。
  • 验证路径:迁移说明 → 源码类型定义 → 内存内/ASGI 实跑 → 记录实际报文。
  • 标注规则:真正版本敏感且未核实的项标注验证点,核实后移除标注。

原理流程

  1. 列出影响部署、鉴权、测试与观测的版本敏感点。
  2. 在当前安装版本逐项核对文档、源码与运行结果。
  3. 把确定结论写入测试断言,未核实项保留标注并跟踪。

代码或图示

已核实(FastMCP 2.x):
- 传输: run(transport="stdio"|"http"|"sse"), http 默认 127.0.0.1:8000/mcp
- 会话头: Mcp-Session-Id; 无状态: stateless_http=True 或 FASTMCP_STATELESS_HTTP=true
- 校验器: JWTVerifier / StaticTokenVerifier / IntrospectionTokenVerifier / DebugTokenVerifier
- 测试: from fastmcp import Client; Client(mcp) 内存内直连, call_tool / list_tools
- lifespan: 构造器 lifespan= 接异步上下文管理器

保留未核实项:
- EventStore 外部持久化后端与配置参数
- 内置指标导出接口是否存在
- 会话空闲超时参数名与默认值

常见误区

  • 照搬其他语言 SDK 或旧版示例:Python 实现命名与默认值可能不同。
  • 把未核实假设写进部署文档:未验证行为不应作为上线承诺。

追问

  • 如何查当前框架版本?答:pip show fastmcp 查安装版本,对照该版本文档与类型定义。
  • 未核实项何时关闭?答:目标版本观察到确定报文并补测试断言后关闭。
  • 版本升级要回归什么?答:握手、鉴权、会话、重连、挂载链路与错误路径全量冒烟。

本节高频题

  • stdio 通道纪律:stdout 协议流、stderr 日志、print 污染(001、002、003)
  • stdio 进程模型、编码分帧、读取循环与并发限制(004、005、006、008)
  • Streamable HTTP /mcp 端点与 SSE legacy 双端点(009、010)
  • JSON/SSE 响应形态、会话标识头、有状态/无状态与事件存储(011、012、013、014)
  • 代理缓冲、超时、会话隔离与重连丢会话(015、016、017、018、019)
  • 挂载前缀、root_path、CORS 与 TLS(020、021、022)
  • Bearer 校验、OAuth 资源服务器、校验器、scope 与会话身份(023、024、025、026、027)
  • OAuth 发现元数据、静态令牌注入与鉴权错误分层(028、029、030)
  • 容器镜像、启动参数、进程信号与多副本粘性(032、033、034、035)
  • 无状态扩展前提、共享存储后端与结构化日志(036、037、038)
  • 指标、trace id 与超时预算(039、040、041)
  • 内存内测试、结果断言、错误路径与契约快照(042、043、044、045)
  • ASGI 链路测试、校验分层与注入防护(046、047、048)
  • 限流超时与敏感信息脱敏(049、050)
  • 同进程共存、lifespan、探针与优雅停机(051、052、053、054)
  • 故障排查:日志污染、阻塞卡死、超大响应与重连(055、056、057、058)
  • 部署自检与版本敏感项(059、060)