限额与配额
请求限速与配额
Clouisle 不实现按端点或按 API Key 的请求限流中间件，也不在普通响应中返回 X-RateLimit-* 或 Retry-After 头。限速只存在于少数安全敏感或配额受限的操作上，各机制的窗口与计数器相互独立。
API Key 的 rate_limit 字段
创建 API Key 时可设置 rate_limit，默认 1000，单位为「每分钟请求数」，0 表示无限制。
该字段当前不被强制执行
rate_limit 会按 Key 存储并展示，但当前后端并未在请求链路中强制它，也不产生限速响应头。任何拥有 apikey:create 权限的用户都能修改该值。因此它目前是声明性元数据，不能作为实际的流量保护。需要立即阻断调用时，应禁用该 API Key 或撤销团队模型授权。
实际生效的限速机制
1. 登录失败锁定
失败密码登录会累计计数并最终锁定账户。默认值可通过站点设置 max_login_attempts、lockout_duration_minutes 调整：
| 设置 | 默认 | 说明 |
|---|---|---|
max_login_attempts | 5 | 连续失败多少次后锁定账户 |
lockout_duration_minutes | 15 | 锁定时长（分钟） |
- 锁定前，失败登录返回
2003（INVALID_CREDENTIALS），data.remaining_attempts给出剩余次数。 - 达到上限后返回
5300（ACCOUNT_LOCKED），data.remaining_seconds给出剩余锁定时间。
2. TOTP 验证锁定
TOTP 两步验证失败达到上限会临时锁定验证（常量定义于 backend/app/core/totp_security.py）：
| 常量 | 默认 |
|---|---|
MAX_ATTEMPTS | 5 次失败 |
ATTEMPT_WINDOW | 300 秒（5 分钟） |
LOCKOUT_DURATION | 900 秒（15 分钟） |
5 分钟内失败 5 次后锁定 15 分钟，返回 5312（TOTP_RATE_LIMITED）与剩余秒数。
3. 批量邮件配额
POST /api/v1/admin/users/send-email 的批量发信限制为每小时 100 封/发件人，超出返回 5400（RATE_LIMITED）：
- 达到上限：
data携带limit与period（如100/hour）。 - 剩余额度不足以覆盖本次收件人：
data携带requested与remaining。
此外还有每个收件人每天最多接收 5 封的限制：超出该上限的收件人会被跳过（计入 skipped_count），不会让整个请求失败。
4. 上游模型供应商限速
即使 Clouisle 侧不限制，上游模型服务商仍可能返回 HTTP 429。此时：
- 知识库文档处理（嵌入）遇到供应商
RateLimitError会映射为业务码5400；其他供应商错误映射为配额（6103）、配置（6104）或不存在（6100）等。 - 流式聊天中的供应商限速以 SSE
error事件下发，已生成的部分响应会保留。 - 服务端没有固定的重试计划，应在供应商的限流窗口重置后重试。
建议做法
- 对
5300、5312、5400、6103一律采用带抖动的指数退避，不要立即密集重试。 - 登录失败时在客户端也做退避，避免触发账户锁定。
- 监控批量邮件配额与上游供应商额度，并与团队模型配额分开告警。
- 不要依赖
X-RateLimit-*头或retry_after字段（它们不存在），也不要把5400当作全局 API 限速——它只对应邮件配额或供应商限速映射。
这篇文章对你有帮助吗？