{"title":"限速与配额","slug":"rate-limits","category":"api","summary":"Synapse API 的限速策略 — Bearer 头（无限制）、?key=（60 次/分钟）、公共端点。","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":130,"read_minutes":1,"llm_context":"Mind Key (Authorization: Bearer header) → NO rate limit\nMind Key (?key= query param) → 60 req/min per IP\nJWT (Authorization: Bearer header) → NO rate limit\nPublic endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit\nRate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After\nRecommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 限速与配额\n\nSynapse 采用简单、可预测的限速策略，既能防止滥用，又不妨碍正常使用。\n\n## 限速策略\n\n| 认证方式 | 限制 | 范围 |\n|-------------|-------|-------|\n| Mind Key（`Authorization: Bearer`） | **无限制** | 每个 Mind |\n| Mind Key（`?key=`） | 60 次/分钟 | 每个 IP |\n| JWT（`Authorization: Bearer`） | **无限制** | 每个用户 |\n| 公共端点 | **无限制** | 全局 |\n\n> [!TIP]\n> **尽可能始终使用 `Authorization: Bearer` 头**。它没有限速。仅在工具无法设置自定义请求头时才使用 `?key=`。\n\n## 限速响应头\n\n当你使用 `?key=` 认证时，响应会包含限速头：\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\n当你超过限制时：\n\n```\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\n## 当你触发限速时\n\n如果收到 429：\n\n1. **改用 Authorization 头**（推荐）：\n ```bash\n # 不要这样做：?key=YOUR_MIND_KEY（60 次/分钟限制）\n curl \".../memory/recall?key=YOUR_MIND_KEY\"\n \n # 推荐做法：Authorization 头（无限制）\n curl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n ```\n\n2. **或等待 `Retry-After` 秒**后重试。\n\n## 为什么存在 `?key=` 限制\n\n`?key=` 查询参数对于只能使用 URL 的工具（浏览器、`open` 命令）很方便，但带来安全与性能影响：\n\n- **安全**：查询参数会出现在服务器访问日志、浏览器历史和 Referer 头中。限制使用可以降低泄露面。\n- **性能**：基于查询参数的认证需要基于 IP 的限速器（每次请求都查询 Redis），会增加延迟。基于头的认证可以跳过这一步。\n- **防滥用**：泄露的 `?key=` URL 可能被分享并被疯狂调用。IP 限制可以减小爆炸半径。\n\n## 推荐模式\n\n### LLM Agent\n\n```python\n# 始终使用头部认证\nheaders = {\"Authorization\": f\"Bearer {MIND_KEY}\"}\nresponse = requests.get(f\"{URL}/memory/recall\", headers=headers)\n```\n\n### 基于浏览器的工具\n\n如果你的工具只能打开 URL：\n\n```bash\n# 偶尔使用尚可（保持在 60 次/分钟以内）\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# 频繁使用时，请改用支持请求头的工具\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n### MCP Server\n\nMCP Server 始终通过 `SYNAPSE_MIND_KEY` 环境变量使用头部认证 — 不受限速影响。\n\n### 批量导入\n\n对于批量操作（例如导入 1000 条记忆），请始终使用头部认证。通过 `?key=` 进行批量导入会在 1 分钟内触发限速。\n\n## 配额（Mind 级别）\n\n目前没有针对存储大小或记忆数量的 Mind 级配额。所有限制都在认证/IP 层，不在数据层。未来为多租户公平性可能会调整此策略。\n\n## 监控你的使用情况\n\n```bash\n# 查看当前限速状态（使用 ?key= 认证）\ncurl -i \"https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY\" | grep -i ratelimit\n\n# 输出：\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840\n```\n\n## 下一步\n\n- [Authentication](/docs/getting-started/authentication)\n- [错误与错误处理](/docs/api/errors)\n","content_html":"

限速与配额

\n

Synapse 采用简单、可预测的限速策略，既能防止滥用，又不妨碍正常使用。

\n

限速策略

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
认证方式限制范围
Mind Key（Authorization: Bearer）无限制每个 Mind
Mind Key（?key=）60 次/分钟每个 IP
JWT（Authorization: Bearer）无限制每个用户
公共端点无限制全局
\n
**尽可能始终使用 `Authorization: Bearer` 头**。它没有限速。仅在工具无法设置自定义请求头时才使用 `?key=`。

限速响应头

\n

当你使用 ?key= 认证时，响应会包含限速头：

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840

当你超过限制时：

\n
HTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

当你触发限速时

\n

如果收到 429：

\n
    \n

  1. 改用 Authorization 头（推荐）：

    \n
    # 不要这样做：?key=YOUR_MIND_KEY（60 次/分钟限制）\ncurl ".../memory/recall?key=YOUR_MIND_KEY"\n\n# 推荐做法：Authorization 头（无限制）\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
    2. \n

  2. 或等待 Retry-After 秒后重试。

    \n
    3. \n
\n

为什么存在 ?key= 限制

\n

?key= 查询参数对于只能使用 URL 的工具（浏览器、open 命令）很方便，但带来安全与性能影响：

\n\n

推荐模式

\n

LLM Agent

\n
# 始终使用头部认证\nheaders = {"Authorization": f"Bearer {MIND_KEY}"}\nresponse = requests.get(f"{URL}/memory/recall", headers=headers)

基于浏览器的工具

\n

如果你的工具只能打开 URL：

\n
# 偶尔使用尚可（保持在 60 次/分钟以内）\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# 频繁使用时，请改用支持请求头的工具\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP Server

\n

MCP Server 始终通过 SYNAPSE_MIND_KEY 环境变量使用头部认证 — 不受限速影响。

\n

批量导入

\n

对于批量操作（例如导入 1000 条记忆），请始终使用头部认证。通过 ?key= 进行批量导入会在 1 分钟内触发限速。

\n

配额（Mind 级别）

\n

目前没有针对存储大小或记忆数量的 Mind 级配额。所有限制都在认证/IP 层，不在数据层。未来为多租户公平性可能会调整此策略。

\n

监控你的使用情况

\n
# 查看当前限速状态（使用 ?key= 认证）\ncurl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit\n\n# 输出：\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840

下一步

\n\n","urls":{"html":"/docs/api/rate-limits","text":"/docs/api/rate-limits?format=text","json":"/docs/api/rate-limits?format=json","llm":"/docs/api/rate-limits?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}