访问控制与限额
XSI 在每个请求上执行一条固定顺序的准入流水线。所有规则都在账号上配置,并沿账号树向下收窄。
准入顺序
| 顺序 | 检查 | 失败时 |
|---|---|---|
| 1 | API Key 格式与有效性 | 401 |
| 2 | IP 白名单 AllowIPs | 403 |
| 3 | 账号状态 Status | 403 |
| 4 | 冻结状态(余额低于阈值) | 429(触发冻结的那次为 401) |
| 5 | 日额度 DailyLimit、月额度 HardLimit | 429 |
| 6 | 账号级限速 RPM … TPD | 429 |
| 7 | 资源白名单 Resources | 403 |
| 8 | 模型白名单 AllowModels | 403 |
| 9 | 模型级限额 ModelLimits / MODEL_LIMITS | 429 |
- 第 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 或 CIDR | 203.0.113.10 10.0.0.0/8 |
Resources | 路径精确或前缀匹配 | /v1/chat/completions /v1/responses |
AllowModels | 精确或 * 通配;同时检查请求模型、映射后的模型与计费模型 | gpt-6* claude-sonnet-5-5 |
AllowLevels | Level 编号,供 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 / TPM | 1 分钟 | 1 分钟后 |
| RPH / TPH | 1 小时 | 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,防止单个账号耗尽上游配额。