# 限速与配额

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

## 限速策略

| 认证方式 | 限制 | 范围 |
|-------------|-------|-------|
| Mind Key（`Authorization: Bearer`） | **无限制** | 每个 Mind |
| Mind Key（`?key=`） | 60 次/分钟 | 每个 IP |
| JWT（`Authorization: Bearer`） | **无限制** | 每个用户 |
| 公共端点 | **无限制** | 全局 |

> [!TIP]
> **尽可能始终使用 `Authorization: Bearer` 头**。它没有限速。仅在工具无法设置自定义请求头时才使用 `?key=`。

## 限速响应头

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

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840
```

当你超过限制时：

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

## 当你触发限速时

如果收到 429：

1. **改用 Authorization 头**（推荐）：
   ```bash
   # 不要这样做：?key=YOUR_MIND_KEY（60 次/分钟限制）
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # 推荐做法：Authorization 头（无限制）
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

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

## 为什么存在 `?key=` 限制

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

- **安全**：查询参数会出现在服务器访问日志、浏览器历史和 Referer 头中。限制使用可以降低泄露面。
- **性能**：基于查询参数的认证需要基于 IP 的限速器（每次请求都查询 Redis），会增加延迟。基于头的认证可以跳过这一步。
- **防滥用**：泄露的 `?key=` URL 可能被分享并被疯狂调用。IP 限制可以减小爆炸半径。

## 推荐模式

### LLM Agent

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

### 基于浏览器的工具

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

```bash
# 偶尔使用尚可（保持在 60 次/分钟以内）
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# 频繁使用时，请改用支持请求头的工具
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### MCP Server

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

### 批量导入

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

## 配额（Mind 级别）

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

## 监控你的使用情况

```bash
# 查看当前限速状态（使用 ?key= 认证）
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# 输出：
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840
```

## 下一步

- [Authentication](/docs/getting-started/authentication)
- [错误与错误处理](/docs/api/errors)