跳转到主要内容
一个没有源限制的密钥是一份纯粹的持有者凭据：谁持有这个字符串 就能从任何地方出示它。allow_ips 字段把一个密钥变成一个 ip 白名单 api 密钥——它只有在从你列出的源地址出示时才工作。 一个从攻击者的机器、一个住宅代理或一个被攻陷的 CI 运行器重放 的泄露密钥，会在它触及一个模型之前就被拒绝。 这是 最小权限 的源绑定那一半： model_limits 限定一个密钥可以 触及哪些模型，而 allow_ips 限定密钥可以从哪里被出示。

​
1. allow_ips 做什么

allow_ips 持有一个源地址或 CIDR 段的列表。在每个请求上， OrcaRouter 把调用方的源 IP 与那个列表进行比对：
  • 匹配 → 请求继续进入模型限制、配额和策略检查。
  • 不匹配 → 请求在认证层以 HTTP 403（access_denied） 被拒绝，在任何上游模型调用之前。
  • 空列表 → 无限制；该密钥从任何地址被接受。
这是一个密钥通过的第一道门，与密钥有效性并列——它在防护栏 之前、防火墙之前、计量之前运行。一个未列出的源永远到不了你的 策略或你的余额。
一个空的 allow_ips 意味着允许所有 IP，而非无。把它留空 就是不受限的默认值——钉住该密钥才能让这个字段起任何作用。

​
2. 接受的格式

每一条条目是单个 IP 或一个 CIDR 段。两者可自由混用；每行 列一条条目。

单个地址

203.0.113.7 —— 恰好一个主机。最适合一个固定 IP 的服务器， 或一个带有稳定出口地址的 NAT 网关。

CIDR 段

203.0.113.0/24 —— 一整块。最适合一个云子网、一个 VPN 池， 或一个位于单一出口 CIDR 之后的自动伸缩组。
一个裸 IP 匹配那一个地址；一个 CIDR 匹配那一块中的每个地址。 IPv4 和 IPv6 字面量都可解析。
钉到仍能覆盖每个合法调用方的最窄范围。一个主机（/32）比 一个 /24 更紧；一个 /24 比 “任何地方” 更紧。你每丢掉一位， 就拓宽了一个泄露密钥仍能工作的地点集合。

​
3. 在控制台中设置它

在 /console/token 的密钥编辑器中设置 allow_ips。创建或编辑 一个密钥需要 Developer 角色或以上。
  1. 打开 Console → API Keys 并创建或编辑一个密钥。
  2. 在密钥编辑器中，把你受信任的地址输入 IP allow-list 字段——每行一个 IP 或 CIDR。
  3. 保存。该限制在那个密钥发出的下一次请求时适用——无需 重新部署、无需修改智能体代码。
在你锁定一个密钥之前，先验证网关所看到的真实源地址。如果 你的智能体位于一个 NAT、一个负载均衡器或一个出口代理之后， OrcaRouter 观察到的地址是那个出口跳——而非智能体的私有 IP。 把出口地址加入允许列表，并在你发布之前从已部署的环境中测试。

​
4. 一个具体的例子：一个定时智能体

一个汇总工单的定时作业只从一个云子网运行。把它的密钥钉到那个 子网，使该凭据在其他任何地方都无用。
字段取值效果
allow_ips203.0.113.0/24只有调度器的出口块能出示这个密钥
model_limits一个汇总模型无法升级到前沿模型
credit_limit_usd一个每周上限失控循环无法耗尽余额
中继调用本身不变——它仍然把 sk-orca-… 密钥用作一个持有者 令牌： 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this ticket..."}]
  }'
从 203.0.113.0/24 内部出示时，该调用继续进行。从任何其他 地址重放完全相同的请求，网关返回： 
{
  "error": {
    "message": "您的 IP 不在令牌允许访问的列表中 (request id: ...)",
    "type": "orcarouter_api_error",
    "code": "access_denied"
  }
}
模型从未被调用，没有配额被花掉，且该拒绝被记录。
allow_ips 完全通过控制台密钥编辑器配置——这是你工作区 会话上的一个 Developer 或以上的操作。它没有中继密钥自助方式： 一个密钥无法拓宽它自己的源允许列表。

​
5. 一个 IP 允许列表包含什么、不包含什么

一个 ip 白名单 api 密钥限定一个密钥在哪里工作——影响半径的 一个切片。它与其他范围字段组合，而非取代它们。
一份从日志、一次 git 提交或一台被攻破的笔记本电脑中外泄的 凭据是死重，除非攻击者还能从你允许列表的范围内发起流量。 这是该字段的核心职责——完整的事故响应参见 泄露密钥。
如果攻陷就发生在一个允许列表的主机上——一个运行在你自己 服务器上的被投毒依赖——源 IP 检查会通过。把 allow_ips 与 model_limits、一个 花费上限 和一个 防火墙策略 配对，使一次受信任源的 攻陷仍然被限定。
一个 IP 钉住不会让一个密钥变得短寿命。把它与一个 绝对到期 和一个 轮换 计划结合，使一个密钥既能 从新地点停止工作，又能最终停止工作。

​
6. 操作要点

如果你的调用方没有一个稳定的源地址（带轮换出口的无服务器、 移动客户端、宽泛的办公网络），IP 钉住是错误的控制——你要么 锁住真实流量，要么把范围拓宽到毫无意义。改为依靠 model_limits、花费上限、 到期，以及 策略附加项。
编辑 allow_ips 在下一次请求时生效——没有要等待的传播延迟。 当你新增一个区域或迁移一个子网时，先更新密钥、确认新范围 可用，然后再去掉旧的那个。
allow_ips 存在于单个密钥上，因此每个智能体都可以有它自己的 源绑定。一个调度器密钥可以钉到一个批处理子网，而一个交互式 密钥允许一个更宽的办公范围——两者在同一个工作区里。

​
7. 下一步

令牌对象

密钥上的每个字段，包括 allow_ips，汇于一处参考。

模型限制

限定一个密钥可以触及哪些模型——源 + 范围绑定的另一半。

泄露密钥

一个密钥暴露的那一刻该做什么。

最小权限检查清单

让每个密钥都经过同样的加固流程。
一个 IP 允许列表是你能做的最廉价的影响半径削减：一个字段、 没有代码变更，而一个泄露密钥就会从所有它本不该运行的地方 停止工作。把它与 限定范围密钥模型 的其余部分配对，实现纵深防御。