​
概述

IP 白名单功能允许为每个 API Key 设置允许访问的来源 IP 或网段。设置白名单后，只有白名单内的 IP 才能使用该 API Key 调用 API；未设置白名单（空）时，不限制来源 IP。

​
功能组成

项目说明
Web 管理界面在 apikey.html 页面为单个 Key 设置/查看 IP 白名单，或批量应用到分组/独立 Key
API 管理端点通过 API 接口管理 IP 白名单（需默认 Key 鉴权）
运行时拦截所有 LLM API 调用和 API Key 管理接口均会在鉴权时校验来源 IP

​
IP 格式说明

每行一个 IP 地址或网段，支持两种写法：

​
1. 标准 CIDR 格式

56.78.45.0/24
65.78.0.0/16
10.0.0.1/32

​
2. 纯 IP 格式（自动推断网段）

当未包含 / 时，系统根据末尾连续为 0 的段数自动推断网段：
示例末尾0段数推断网段覆盖范围
56.78.45.10/32（单机）仅 56.78.45.1
56.78.45.01/2456.78.45.0 ~ 56.78.45.255
65.78.0.02/1665.78.0.0 ~ 65.78.255.255
10.0.0.03/810.0.0.0 ~ 10.255.255.255
⚠️ 0.0.0.0 会被视为非法条目。

​
Web 管理界面

​
单个 Key 操作

在 apikey.html 页面的每个 API Key 卡片上，点击 IP白名单 图标按钮：
  1. 弹出 IP 白名单弹窗，显示当前白名单规则
  2. 在文本框中编辑（每行一个 IP/网段）
  3. 点击”保存IP白名单”提交
  4. 清空文本框并保存 = 清除白名单，恢复不限制来源 IP

​
批量操作

点击页面顶部的 “批量设置IP白名单” 按钮：
  1. 勾选目标分组（分组下所有 Key 都会被应用）
  2. 或勾选独立 API Key（支持多选）
  3. 也可同时勾选分组和独立 Key（系统自动去重）
  4. 填入白名单规则后保存

​
API 接口

​
1. 设置单个 API Key 的 IP 白名单

POST /apikey/set-ip-whitelist
ℹ️ 此接口为 Web UI 内部接口，需 Cookie 鉴权（用户登录态）。

​
请求体

{
  "apikey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "ip_whitelist": "56.78.45.1\n56.78.45.0\n65.78.0.0"
}
字段类型必需说明
apikeystring✅目标 API Key（完整）
ip_whiteliststring✅多行 IP/网段文本，空字符串 = 清除白名单

​
成功响应

{
  "success": true,
  "message": "IP白名单已更新，共 3 条规则",
  "ip_whitelist": ["56.78.45.1/32", "56.78.45.0/24", "65.78.0.0/16"]
}

​
错误响应

{
  "success": false,
  "error": "以下IP/网段格式不正确: \"999.1.1.1\": 无效的IP格式: 999.1.1.1、\"not.an.ip\": 无效的IP格式: not.an.ip"
}
状态码说明
400参数错误或 IP 格式非法
401未登录
404API Key 不存在或不属于当前用户

​
2. 批量设置 API Key 的 IP 白名单

POST /apikey/batch-set-ip-whitelist
ℹ️ 此接口为 Web UI 内部接口，需 Cookie 鉴权（用户登录态）。

​
请求体

{
  "group_ids": ["6a06f7db38b3bf1609a9c200", "ungrouped"],
  "apikeys": ["sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"],
  "ip_whitelist": "56.78.45.0/24\n65.78.0.0/16"
}
字段类型必需说明
group_idsstring[]❌分组 ID 列表，特殊值："all"（全部）、"ungrouped"（未分组）
apikeysstring[]❌独立 API Key 列表
ip_whiteliststring✅多行 IP/网段文本，空字符串 = 清除白名单
⚠️ group_ids 和 apikeys 至少需要提供一项。

​
成功响应

{
  "success": true,
  "message": "批量设置IP白名单成功，共更新 5 个API Key，白名单共 2 条规则",
  "updated_count": 5,
  "failed_count": 0,
  "ip_whitelist": ["56.78.45.0/24", "65.78.0.0/16"]
}

​
运行时拦截

当通过 API Key 调用 LLM API 时，系统会自动校验请求来源 IP 是否在该 Key 的白名单内。

​
涉及的路由（均以 Authorization: Bearer <API Key> 鉴权）

路由说明
/llmLLM 生成
/v1/chat/completionsOpenAI 兼容 chat
/v1/embeddings向量嵌入
/anthropic/v1/messagesAnthropic 兼容
/v1/videos / /v1/videos/<id>视频生成
/v1/images/generations图片生成
/v1/images/generations/async异步图片生成
/v1/responsesResponses API
/v1/balance查询余额
/v1/costofapikey查询费用
/v1/apikey_groups分组管理
/v1/apikeysKey 管理
/autoeval自动评测

​
白名单为空时

不做任何限制，所有来源 IP 均可正常调用。这与 budget、daily_limit 等字段的”0/空 = 不限制”约定一致。

​
白名单有规则时

# 来源 IP 不在白名单内 → 403
curl -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Forwarded-For: 1.2.3.4" \
  https://api.nonelinear.com/v1/chat/completions \
  -d '{"model": "gpt-oss-20b", "messages": [{"role": "user", "content": "Hello"}]}'

# 响应
HTTP/1.1 403 Forbidden
该请求来源IP不在API Key允许的白名单内

​
存储结构

IP 白名单存储在 user.costofapikey 集合的 ip_whitelist 字段： 
{
  "_id": { "$oid": "..." },
  "apikey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "userid": "lijian",
  "cost": 0.000647,
  "budget": 100,
  "ip_whitelist": [
    "56.78.45.1/32",
    "56.78.45.0/24",
    "65.78.0.0/16"
  ]
}
ip_whitelist 不存在或为 [] 时，表示该 Key 不限制来源 IP。

​
最佳实践

​
1. 安全隔离

  • 为生产环境的 Key 设置 IP 白名单，限制为公司办公网络 IP 或服务器出口 IP
  • 测试环境的 Key 可以不设置白名单

​
2. 网段规划

  • 使用网段而非单个 IP，避免因 IP 更换频繁修改白名单
  • 例如公司办公网络 192.168.0.0/16 或云服务器出口 10.0.0.0/8

​
3. 备用通道

  • 建议至少保留一个不限制 IP 的 Key（或使用宽泛网段），防止因白名单配置错误导致完全无法访问

​
4. 来源 IP 说明

  • 目前系统通过 X-Forwarded-For → X-Forwarded-For-Pound → request.remote_addr 的优先级获取来源 IP
  • 如果你的请求经过了反向代理，请确保代理正确设置了 X-Forwarded-For 头