概览

策略保护

策略保护是绑定到 API Key 的治理策略。创建 API Key 时，系统会把策略复制成一份快照；模型请求进入 api-gateway 后，网关按这份快照做校验，而不是每次重新读取最新策略。

这意味着更新策略不一定会改变已创建 API Key 的行为。要让新策略生效，建议创建新 Key，验证后再撤销旧 Key。

已在网关执行的约束

当前 api-gateway 在 POST /openai/v1/chat/completions 请求路径里会执行这些约束：

约束当前行为
blocked / block_reason如果快照标记 blocked，请求直接被拒绝
ip_blacklist客户端 IP 命中黑名单时拒绝
ip_whitelist配置白名单时，客户端 IP 必须命中 IP 或 CIDR
tiers / allowed_tiers归一化为 economy / standard / premium，并和 API Key tier、请求 tier 取交集
model_blacklist选中模型或固定模型命中黑名单时拒绝
fixed_modelAPI Key 绑定固定模型时，请求模型只能是 auto 或该固定模型
routing_strategy传给路由器，支持 BALANCE、COST_FIRST、QUALITY_FIRST、SPEED_FIRST
tag作为场景标签传给路由器，会被小写归一化
industry_packs作为行业场景包传给路由器
required_feature_tags网关根据请求内容补充，例如图片输入会要求 vision

请求执行顺序

extract API key
  -> ValidateApiKey
  -> parse policy_snapshot_json
  -> blocked / IP checks
  -> tier intersection
  -> fixed model / model blacklist
  -> wallet balance precheck
  -> Route
  -> wallet freeze
  -> provider invoke
  -> usage record and wallet settle

Tier 约束

tier 的最终可用集合来自多层约束：

  1. 策略快照的 allowed_tiers，没有时使用 tiers。
  2. API Key 自己绑定的 tier。
  3. 请求体里的 tier。
  4. 钱包余额检查会移除余额为 0 的 tier。

如果最终没有任何可用 tier，请求会失败。对 model: "auto"，如果第一次选中的 tier 钱包预冻结不足，网关会尝试在允许范围内回退到其他 tier。

IP 策略

网关会从这些位置解析客户端 IP：

来源说明
X-Forwarded-For优先使用第一段 IP
X-Real-IP反向代理常用真实 IP
remote address没有代理头时使用连接来源

IP 规则支持精确 IP 和 CIDR，例如：

IP policy
1{
2  "ip_whitelist": ["203.0.113.10", "10.0.0.0/24"],
3  "ip_blacklist": ["198.51.100.23"]
4}

模型策略

策略行为
fixed_model强制绑定模型。请求 auto 时路由器会被约束到该模型；请求其他固定模型时直接拒绝
model_blacklist禁止选中黑名单模型；固定模型也会被检查
required_feature_tags由请求内容推导，例如图片输入必须选支持 vision 的模型

预算与钱包

API Key 校验会返回 limit_total、limit_daily、limit_weekly，策略也可以包含 daily_limit / weekly_limit。在当前网关请求链路里，钱包余额和预冻结是更直接的执行点：

执行点当前行为
filterPolicyTiersByBalance移除余额为 0 的 tier
freezeSelectedModel按模型费率和 token 估算预冻结 Credits
billing-service Calculate提供方成功后计算真实 Credits
wallet-service Settle / Release计算和记录成功则结算；失败、空金额或 0 金额则释放冻结

推荐策略

场景建议
本地开发单独 Key，低预算，允许较宽 IP，BALANCE 或 COST_FIRST
生产后端IP 白名单、明确 tier、模型黑名单、预算限制
IDE / 编码 Agent单独 Key，低每日/每周额度，优先 COST_FIRST
RAG 索引单独 Key，固定 embedding 或 batch 相关模型
高风险 Agent运行时停止条件 + JoyToken Key 预算双保险

常见拒绝原因

错误类型常见原因
policy_rejectedIP、tier、固定模型、模型黑名单或 blocked 策略不满足
insufficient_quota钱包余额不足、预算不足或预冻结失败
invalid_api_keyKey 无效、撤销、过期或状态不是 ACTIVE