多维度限流

Claude Code Hub 实现了一套完整的多维度限流系统，在 User（用户）、Key（API Key） 和 Provider（供应商） 三个层面进行精细化控制，确保资源合理分配、成本可控。

限流维度概览

限流检查顺序

系统按照精心设计的顺序执行限流检查（rate-limit-guard.ts）：

Layer 1 - 永久硬限制（最先检查）
  1. Key 总消费限额
  2. User 总消费限额

Layer 2 - 资源/频率保护
  3. Key 并发会话数
  4. User 并发会话数
  5. User RPM 限制

Layer 3 - 短期周期限制
  6. Key 5小时滚动窗口
  7. User 5小时滚动窗口
  8. Key 日限额
  9. User 日限额

Layer 4 - 中长期周期限制
  10. Key 周限额
  11. User 周限额
  12. Key 月限额
  13. User 月限额

RPM 限制（Requests Per Minute）

RPM 限制用于控制用户的请求频率，防止高频滥用。

实现机制

• 滑动窗口算法：使用 Redis ZSET 存储请求时间戳，精确统计过去60秒内的请求数
• 并发安全：使用 Redis Pipeline 批量操作，确保高并发场景下的准确性
• 自动清理：2分钟 TTL 自动清理过期数据

配置方式

在用户管理界面设置 RPM 限制 字段：

RPM 限制: 60  # 表示每分钟最多 60 次请求

设为 0 或留空表示不限制。

触发时的响应

当 RPM 限制触发时，请求会被拒绝，返回 HTTP 429 状态码：

{
  "error": {
    "message": "Rate limit exceeded: User RPM limit reached (60/60)",
    "type": "rate_limit_error",
    "code": "429"
  }
}

成本限制（Cost-Based Limiting）

成本限制基于实际消费金额进行控制，支持多种时间窗口类型。

时间窗口类型

日限额重置模式

系统支持两种日限额重置模式：

固定时间模式（Fixed）

• 在配置的每日重置时间点重置计数
• 例如：设置重置时间为 18:00，则每天 18:00 重置
• 适合有固定结算时间点的场景

滚动窗口模式（Rolling）

• 统计过去24小时的累计消费
• 无固定重置时间点，平滑计算
• 适合需要连续流量控制的场景

配置示例

日限额: $50.00
日重置模式: 固定
日重置时间: 00:00

周限额: $300.00
月限额: $1000.00
5小时限额: $20.00

并发会话限制

并发会话限制控制同时进行的对话数量，防止资源被单个用户或 Key 独占。

会话生命周期

1. 会话创建 - 首次请求时创建会话记录
2. 会话活跃 - 每次请求更新会话时间戳
3. 会话过期 - 5分钟无活动后自动过期
4. 会话清理 - Redis ZSET 自动清理过期成员

配置建议

Lease 机制（租赁配额）

为了提升高并发场景下的性能，系统采用 Lease（租赁）机制减少数据库查询。

工作原理

1. 获取租赁：从数据库批量获取一段配额（如总限额的 5%）
2. 本地扣减：请求消费从租赁配额中扣减，无需访问数据库
3. 租赁刷新：租赁耗尽或过期时，重新从数据库获取
4. 原子操作：使用 Redis Lua 脚本确保扣减的原子性

租赁配置

通过系统设置配置租赁参数：

quotaLeasePercent5h: 5%      # 5小时限额的租赁比例
quotaLeasePercentDaily: 5%   # 日限额的租赁比例
quotaLeasePercentWeekly: 5%  # 周限额的租赁比例
quotaLeasePercentMonthly: 5% # 月限额的租赁比例
quotaLeaseCapUsd: 10.0       # 单次租赁金额上限（可选）
quotaDbRefreshIntervalSeconds: 10  # 租赁刷新间隔

Fail-Open 策略

当 Redis 不可用时，系统采用 Fail-Open 策略：允许请求通过，而不是阻断服务。

设计哲学

• 可用性优先：确保核心代理功能不受影响
• 优雅降级：限流功能失效时，系统继续提供服务
• 及时告警：所有 Fail-Open 情况都会记录 WARN 级别日志

降级行为

响应头信息

系统在响应中返回限流相关的 HTTP 头：

环境变量配置

限流功能通过以下环境变量控制：

# 启用限流（默认 true）
ENABLE_RATE_LIMIT=true

# Redis 连接（必需）
REDIS_URL=redis://localhost:6379

# 可选：Redis TLS 配置
REDIS_TLS_REJECT_UNAUTHORIZED=false

最佳实践

1. 分层设置限额

User 级别：
  - 月限额: $500（硬上限）
  - 周限额: $150（预警）
  - 日限额: $50（日常控制）
  - 5小时: $15（短期爆发）

Key 级别：
  - 月限额: $200（子账号控制）
  - 日限额: $20（细粒度）

2. RPM 设置建议

• 标准模型（如 Claude 3.5 Sonnet）：60-120 RPM
• 轻量模型（如 GPT-3.5）：120-300 RPM
• 批处理场景：根据实际并发需求调整

3. 监控与告警

关注以下指标：

• 限流触发频率（各维度）
• Redis 连接状态
• 租赁刷新频率
• Fail-Open 事件次数

4. 测试限流

使用脚本测试限流是否生效：

# 快速发送多个请求测试 RPM 限制
for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"claude-3-5-sonnet","messages":[{"role":"user","content":"hi"}]}' \
    http://localhost:23000/v1/chat/completions
done

故障排查

限流未生效

1. 检查 ENABLE_RATE_LIMIT 是否为 true
2. 检查 Redis 连接是否正常
3. 检查用户/Key 的限额配置是否大于 0
4. 查看日志中的 [RateLimit] 相关记录

误触发限流

1. 检查是否有其他请求共享同一 User/Key
2. 检查并发会话是否包含已过期但未清理的会话
3. 验证系统时间是否同步

Redis 性能问题

1. 检查 Redis 内存使用情况
2. 考虑调整租赁参数减少查询频率
3. 监控 Redis 慢查询日志

相关文档

• 配额管理 - 了解用户配额体系
• 会话管理 - 会话生命周期详解
• 成本追踪 - 成本统计与计费机制