API Key IP 白名单

概述

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 格式

78.45.0/24
78.0.0/16
0.0.1/32

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

当未包含 / 时，系统根据末尾连续为 0 的段数自动推断网段：

示例	末尾0段数	推断网段	覆盖范围
`56.78.45.1`	0	`/32`（单机）	仅 `56.78.45.1`
`56.78.45.0`	1	`/24`	`56.78.45.0` ~ `56.78.45.255`
`65.78.0.0`	2	`/16`	`65.78.0.0` ~ `65.78.255.255`
`10.0.0.0`	3	`/8`	`10.0.0.0` ~ `10.255.255.255`

⚠️ 0.0.0.0 会被视为非法条目。

Web 管理界面

单个 Key 操作

在 apikey.html 页面的每个 API Key 卡片上，点击 IP白名单 图标按钮：

弹出 IP 白名单弹窗，显示当前白名单规则
在文本框中编辑（每行一个 IP/网段）
点击”保存IP白名单”提交
清空文本框并保存 = 清除白名单，恢复不限制来源 IP

批量操作

点击页面顶部的 “批量设置IP白名单” 按钮：

勾选目标分组（分组下所有 Key 都会被应用）
或勾选独立 API Key（支持多选）
也可同时勾选分组和独立 Key（系统自动去重）
填入白名单规则后保存

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"
}

字段	类型	必需	说明
`apikey`	string	✅	目标 API Key（完整）
`ip_whitelist`	string	✅	多行 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	未登录
404	API 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_ids`	string[]	❌	分组 ID 列表，特殊值：`"all"`（全部）、`"ungrouped"`（未分组）
`apikeys`	string[]	❌	独立 API Key 列表
`ip_whitelist`	string	✅	多行 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>` 鉴权）

路由	说明
`/llm`	LLM 生成
`/v1/chat/completions`	OpenAI 兼容 chat
`/v1/embeddings`	向量嵌入
`/anthropic/v1/messages`	Anthropic 兼容
`/v1/videos` / `/v1/videos/<id>`	视频生成
`/v1/images/generations`	图片生成
`/v1/images/generations/async`	异步图片生成
`/v1/responses`	Responses API
`/v1/balance`	查询余额
`/v1/costofapikey`	查询费用
`/v1/apikey_groups`	分组管理
`/v1/apikeys`	Key 管理
`/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 头

平台系列

文本系列

图像系列

视频系列

概述

功能组成

IP 格式说明

1. 标准 CIDR 格式

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

Web 管理界面

单个 Key 操作

批量操作

API 接口

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

请求体

成功响应

错误响应

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

请求体

成功响应

运行时拦截

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

白名单为空时

白名单有规则时

存储结构

最佳实践

1. 安全隔离

2. 网段规划

3. 备用通道

4. 来源 IP 说明

​概述

​功能组成

​IP 格式说明

​1. 标准 CIDR 格式

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

​Web 管理界面

​单个 Key 操作

​批量操作

​API 接口

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

​请求体

​成功响应

​错误响应

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

​请求体

​成功响应

​运行时拦截

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

​白名单为空时

​白名单有规则时

​存储结构

​最佳实践

​1. 安全隔离

​2. 网段规划

​3. 备用通道

​4. 来源 IP 说明

概述

功能组成

IP 格式说明

1. 标准 CIDR 格式

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

Web 管理界面

单个 Key 操作

批量操作

API 接口

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

请求体

成功响应

错误响应

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

请求体

成功响应

运行时拦截

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

白名单为空时

白名单有规则时

存储结构

最佳实践

1. 安全隔离

2. 网段规划

3. 备用通道

4. 来源 IP 说明