当前位置：首页 > news >正文

18_FastMCP 2.x 中文文档之FastMCP服务端高级功能：后端存储详解

news 2025/11/10 7:25:26

一、后端存储

为缓存和 OAuth 状态管理配置持久化和分布式存储

版本 2.13.0 新增：

FastMCP 使用可插拔的存储后端进行缓存响应和管理 OAuth 状态。默认情况下，所有存储都在内存中，这非常适合开发，但不会在重启后持久化。FastMCP 支持多个后端存储，您可以轻松使用自定义实现进行扩展。

提示：存储层由 py-key-value-aio 提供支持，这是一个由核心 FastMCP 维护者维护的异步键值库。该库为多个后端提供了统一接口，使得根据部署需求交换实现变得容易。

二、存储类型

2.1 内存存储

最适合：开发、测试、单进程部署

内存存储是所有 FastMCP 存储需求的默认设置。它速度快，无需设置，非常适合入门。

from key_value.aio.stores.memory import MemoryStore# 默认使用 - 无需配置
# 但您也可以显式指定：
cache_store = MemoryStore()

特性：

✅ 无需设置
✅ 非常快
❌ 重启后数据丢失
❌ 不适合多进程部署

2.2 磁盘存储

最适合：单服务器生产部署、持久缓存

磁盘存储将数据持久化到文件系统，使其在服务器重启后仍然存在。

from key_value.aio.stores.disk import DiskStore
from fastmcp.server.middleware.caching import ResponseCachingMiddleware# 持久化响应缓存
middleware = ResponseCachingMiddleware(cache_storage=DiskStore(directory="/var/cache/fastmcp")
)

或与 OAuth 令牌存储一起使用：

from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.disk import DiskStoreauth = GitHubProvider(client_id="your-id",client_secret="your-secret",base_url="https://your-server.com",client_storage=DiskStore(directory="/var/lib/fastmcp/oauth")
)

特性：

✅ 数据在重启后持久化
✅ 对于中等负载具有良好的性能
❌ 不适合分布式部署
❌ 需要文件系统访问

2.3 Redis

最适合：分布式生产部署、跨多个服务器的共享缓存

注意：Redis 支持需要可选依赖：pip install ‘py-key-value-aio[redis]’

Redis 提供分布式缓存和状态管理，非常适合具有多个服务器实例的生产部署。

from key_value.aio.stores.redis import RedisStore
from fastmcp.server.middleware.caching import ResponseCachingMiddleware# 分布式响应缓存
middleware = ResponseCachingMiddleware(cache_storage=RedisStore(host="redis.example.com", port=6379)
)

带身份验证：

from key_value.aio.stores.redis import RedisStorecache_store = RedisStore(host="redis.example.com",port=6379,password="your-redis-password"
)

用于 OAuth 令牌存储：

import os
from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.redis import RedisStoreauth = GitHubProvider(client_id=os.environ["GITHUB_CLIENT_ID"],client_secret=os.environ["GITHUB_CLIENT_SECRET"],base_url="https://your-server.com",jwt_signing_key=os.environ["JWT_SIGNING_KEY"],client_storage=RedisStore(host="redis.example.com", port=6379)
)

特性：

✅ 分布式和高可用性
✅ 快速的内存性能
✅ 跨多个服务器实例工作
✅ 内置 TTL 支持
❌ 需要 Redis 基础设施
❌ 与本地存储相比有网络延迟

2.4 py-key-value-aio 的其他后端存储

py-key-value-aio 库包含针对各种存储系统的额外实现：

DynamoDB - AWS 分布式数据库
MongoDB - NoSQL 文档存储
Elasticsearch - 分布式搜索和分析
Memcached - 分布式内存缓存
RocksDB - 嵌入式高性能键值存储
Valkey - Redis 兼容服务器

有关这些后端的配置详细信息，请查阅 py-key-value-aio 文档。

警告：在生产环境中使用这些后端之前，请查看 py-key-value 文档以了解所选后端的成熟度级别和限制。某些后端可能处于预览状态或有特定约束，使其不适合生产使用。

三、FastMCP 中的用例

3.1 服务器端 OAuth 令牌存储

OAuth 代理和 OAuth 认证提供程序使用存储来持久化 OAuth 客户端注册和上游令牌。默认情况下，存储使用 FernetEncryptionWrapper 自动加密。当提供自定义存储时，将其包装在 FernetEncryptionWrapper 中以加密静态的敏感 OAuth 令牌。

开发（默认行为）：

默认情况下，FastMCP 根据您的平台自动管理密钥和存储：

Mac/Windows：密钥通过系统密钥环自动管理，存储默认为磁盘。仅适用于开发和本地测试。
Linux：密钥是临时的，存储默认为内存。

无需配置：

from fastmcp.server.auth.providers.github import GitHubProviderauth = GitHubProvider(client_id="your-id",client_secret="your-secret",base_url="https://your-server.com"
)

生产：

对于生产部署，配置显式密钥和持久的网络可访问存储，并进行加密：

import os
from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernetauth = GitHubProvider(client_id=os.environ["GITHUB_CLIENT_ID"],client_secret=os.environ["GITHUB_CLIENT_SECRET"],base_url="https://your-server.com",# 显式 JWT 签名密钥（生产环境必需）jwt_signing_key=os.environ["JWT_SIGNING_KEY"],# 加密的持久存储（生产环境必需）client_storage=FernetEncryptionWrapper(key_value=RedisStore(host="redis.example.com", port=6379),fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"]))
)

两个参数都是生产环境必需的。将您的存储包装在 FernetEncryptionWrapper 中以加密静态的敏感 OAuth 令牌 - 没有它，令牌将以明文形式存储。有关完整设置详细信息，请参阅 OAuth 令牌安全和密钥和存储管理。

3.2 响应缓存中间件

响应缓存中间件缓存工具调用、资源读取和提示请求。存储配置通过 cache_storage 参数传递：

from fastmcp import FastMCP
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
from key_value.aio.stores.disk import DiskStoremcp = FastMCP("我的服务器")# 缓存到磁盘而不是内存
mcp.add_middleware(ResponseCachingMiddleware(cache_storage=DiskStore(directory="cache")
))

对于共享 Redis 实例的多服务器部署：

from fastmcp.server.middleware.caching import ResponseCachingMiddleware
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.prefix_collections import PrefixCollectionsWrapperbase_store = RedisStore(host="redis.example.com")
namespaced_store = PrefixCollectionsWrapper(key_value=base_store,prefix="my-server"
)middleware = ResponseCachingMiddleware(cache_storage=namespaced_store)

3.3 客户端 OAuth 令牌存储

FastMCP 客户端使用存储在本地持久化 OAuth 令牌。默认情况下，令牌存储在内存中：

from fastmcp.client.auth import OAuthClientProvider
from key_value.aio.stores.disk import DiskStore# 将令牌存储在磁盘上以便在重启后持久化
token_storage = DiskStore(directory="~/.local/share/fastmcp/tokens")oauth_provider = OAuthClientProvider(mcp_url="https://your-mcp-server.com/mcp/sse",token_storage=token_storage
)