访问控制与限额

XSI 在每个请求上执行一条固定顺序的准入流水线。所有规则都在账号上配置,并沿账号树向下收窄。

准入顺序

顺序检查失败时
1API Key 格式与有效性401
2IP 白名单 AllowIPs403
3账号状态 Status403
4冻结状态(余额低于阈值)429(触发冻结的那次为 401)
5日额度 DailyLimit、月额度 HardLimit429
6账号级限速 RPM … TPD429
7资源白名单 Resources403
8模型白名单 AllowModels403
9模型级限额 ModelLimits / MODEL_LIMITS429
  • 第 5、6、9 项受计费档位(Role)影响,见下文。
  • GET /dashboard/*(含 /dashboard/models)与 /user/balance 不受资源白名单、冻结与额度限制,便于查看账号状态;GET /v1/models 只豁免资源白名单。
  • 模型白名单与模型限额只拦截 POST 请求。
  • 部署时设置 USER_FILTER=false 会跳过普通 HTTP 代理的第 2–9 项检查与 XAPI_FEE(按量计费照常进行);Responses WebSocket、Live 与 Realtime WebRTC 仍执行各自的准入。仅适合完全受信的内部环境。

计费档位(Role)

Role名称日/月额度、账号级限速、模型限额
0、1不限不检查
2严格全部检查
3订阅使用订阅额度时检查;订阅额度用尽或触发限额而账号有按量余额时,改用按量余额并放行
其他—按严格处理

由 INIT_USERS 创建的 root 为 Role 0;单租户模式下自助注册账号继承 root 当前的 Role(通常为 0),多租户模式下默认 Role 1;子账号继承父账号的 Role。需要额度与限速生效的账号,请由租户所有者将其 Role 设为 2 或 3。 余额检查与冻结对所有 Role 生效。

白名单

字段匹配方式示例
AllowIPs精确 IP 或 CIDR203.0.113.10 10.0.0.0/8
Resources路径精确或前缀匹配/v1/chat/completions /v1/responses
AllowModels精确或 * 通配;同时检查请求模型、映射后的模型与计费模型gpt-6* claude-sonnet-5-5
AllowLevelsLevel 编号,供 Gear ≤ 0 账号跨组重试1 3
  • 为空表示不限制。更新时不带前缀的列表是追加;要完整替换,写成 -*,+a,+b。
  • 更新语法支持 +x 添加、-x 删除、* 恢复为父账号范围,见《账号管理 API》。
  • 资源白名单拒绝 POST 或 WebSocket 请求、模型白名单拒绝 POST 请求时,收取一次 XAPI_FEE。

额度

字段含义
DailyLimit当日消费上限(CNY),次日恢复
HardLimit当月消费上限(CNY),次月恢复
SoftLimit可保存与查询的月度参考值;当前版本不据此拒绝请求或发送通知
USER_MIN_BALANCE冻结阈值(部署级)。余额低于该值减 0.01 时冻结,充值后恢复

余额每 10 个请求检查一次,并在每次扣费后检查,因此余额可能被短暂透支为负,欠款在下次入账时抵扣。

限速

账号级:RPM、RPH、RPD、TPM、TPH、TPD。

模型级:{"<上游模型名>": {"rpm", "rph", "rpd", "tpm", "tph", "tpd"}}。账号的 ModelLimits 优先,其次是租户的 MODEL_LIMITS;按映射后的上游模型名精确匹配,不支持通配。

维度窗口触发后恢复
RPM / TPM1 分钟1 分钟后
RPH / TPH1 小时1 小时后
RPD / TPD自然日次日零点
  • 请求数在请求进入时计数;Token 数在请求完成后累计,因此 Token 限额决定的是下一次请求能否进入。
  • 模型限额中显式给出的较长窗口上限会向下约束较短窗口;账号级的六项请填写彼此一致的值。
  • 999999999999999999 表示不限。
  • 实时接口:新建 Realtime WebSocket 时检查一次(通过 call_id 附着已有通话不再检查);Responses WebSocket 每轮检查一次;Live 主 WebSocket 在首帧检查;Live WebRTC 建会当前可能消耗两次请求配额。

认证保护

  • 同一 IP 1 分钟内认证失败 12 次,封禁 2 分钟;10 分钟内失败 48 次,封禁 15 分钟。
  • 同一个无效 Key 在 90 秒内直接拒绝,不再查库。
  • 客户端 IP 只在请求来自 TRUSTED_PROXY_CIDRS 内的代理时才从转发头读取,见《反向代理》。

实践建议

  • 按用途拆分账号:生产、测试、个人开发分别使用独立的子账号与 Key。
  • 生产账号设置 AllowIPs,对外分发的账号设置 AllowModels 与 Resources。
  • 需要预算控制的账号使用 Role 2,并同时设置 DailyLimit 与 HardLimit。
  • 为高成本模型设置模型级 tpm 或 rpd,防止单个账号耗尽上游配额。

相关文档