用户、API Key 与权限
用户是权益和审计主体，API Key 是模型网关凭证。登录 JWT 与模型 API Key 是两套不同认证体系。
用户字段决定什么
| 字段 | 作用 |
|---|---|
| email / identity | 登录与账号绑定 |
| role | 普通用户或管理员 |
| status | 是否允许登录和调用 |
| balance | 可扣减余额 |
| frozen_balance | 异步任务预占金额 |
| concurrency | 用户同时执行的请求数 |
| rpm_limit | 分组未设置 RPM 时的用户兜底值 |
| allowed_groups | 独占或指定分组权限 |
| platform_quotas | 用户在各平台的日/周/月费用限制 |
| TOTP | 登录二次验证 |
管理员修改用户余额、状态、并发或授权后，要确认鉴权缓存已经失效。多实例环境中可在不同副本各发送一次测试请求，排除局部旧缓存。
登录认证与网关认证
Web 登录
用户通过 /api/v1/auth/* 登录，获得访问和刷新 token，用于管理后台和用户 API。
模型请求
客户端把 Sub2API Key 放在常见认证头中。API Key middleware 解析后加载用户、Key、分组和订阅快照。
两者的差别：
- 修改登录密码不会自动更换模型 API Key。
- 删除或禁用 API Key 不应注销 Web 登录。
- JWT secret 影响后台会话；API Key 数据存储在数据库。
API Key 生命周期
- 用户创建 Key，并选择有权限的分组。
- 系统生成唯一 key，写入 PostgreSQL。
- 客户端使用 Key，鉴权快照进入 L1/Redis 缓存。
- 请求更新
last_used_at和 quota usage。 - 用户可以修改名称、分组、IP ACL、额度或到期时间。
- 禁用或软删除后触发缓存失效。
真实 key 应只在创建或必要页面显示。截图、工单和日志中都应脱敏。
API Key 限制
总额度
quota = 0 不限制 Key 总费用
quota > 0 quota_used 必须小于 quota总额度只是 Key 层限制。即使 Key 还有 quota，用户余额或订阅也可能已经不足。
时间窗口
Key 可以设置：
- 5 小时费用上限。
- 1 天费用上限。
- 7 天费用上限。
每个窗口保存开始时间和已用费用。重置不是定时把所有 Key 清零，而是在读取或更新时根据窗口是否过期推进。
到期时间
expires_at 为空表示不过期。临时发放给脚本、测试人员或外部合作方时应设置到期时间。
IP ACL
- whitelist 非空时，只允许匹配的 IP/CIDR。
- blacklist 用于显式拒绝地址。
- 真实 IP 是否可信取决于反向代理和
trust_forwarded_ip_for_api_key_acl。
如果应用直接信任任意客户端传入的 X-Forwarded-For，攻击者可能绕过 IP ACL。只有流量必经受控代理时才开启转发 IP 信任。
分组权限判断
创建或修改 Key 时，系统会综合：
- 分组是否 active。
- 是否为独占分组。
- 用户是否在 allowed groups。
- 分组平台和系统策略。
- 管理员是否显式分配。
Key 绑定了后来被禁用或删除的分组时，请求会失败；不会自动选择任意其他分组。
用户并发与排队
用户并发槽位在具体账号选择之前获取，避免一个用户占满整个账号池。达到上限后可能等待，并通过 SSE ping 保持连接。
并发设置太小：Agent 的并行工具调用会频繁排队。设置太大：单个用户可能占用大量上游账号并发。需要结合客户端模式和账号池容量设置。
用户平台配额
平台配额对同一个用户在不同平台分别限制：
User 42
├── anthropic: daily / weekly / monthly
├── openai: daily / weekly / monthly
├── gemini: daily / weekly / monthly
└── grok: daily / weekly / monthlyRedis 保存当前窗口快照，后台 flusher 可以批量回写 PostgreSQL。启用 flusher 时需要监控 dirty keys、readd、flush error 和 FK violation。
推荐策略
内部团队
- 关闭公开注册。
- 每个人独立用户和 Key。
- 按团队角色分配分组。
- 使用平台配额而不是共用一个 Key。
外部用户
- 默认余额为 0。
- 注册加 Turnstile 和邮箱验证。
- Key 默认设置合理并发和到期策略。
- 新用户只开放低风险分组。
- 对敏感 API 开启内容审核和 IP 风险监控。
排查清单
Key 返回 401/403 时依次检查：
- Key 是否完整、有没有多余空格。
- API Key 状态、到期时间和软删除状态。
- 用户状态和角色。
- IP whitelist/blacklist 与真实客户端 IP。
- 分组状态与用户授权。
- 多实例鉴权缓存是否已刷新。
- 内容审核或客户端类型限制。