企业内部部署 New API 大模型网关的完整实践指南
New API 是一款开源的 LLM 网关系统，能够将众多 AI 服务商的接口整合为标准的 OpenAI 兼容 API。当企业购买了各大模型的 Token 套餐后，通常需要这样一个统一的平台来进行分发、权限管控及计费。本文详细记录了利用 New API 落地该方案的全过程。
一、部署安装
这是整个流程的基础。New API 提供了丰富的部署方式，包括 Docker 单容器、Docker Compose、1Panel、宝塔以及集群部署等。对于企业内网环境，强烈推荐使用 Docker Compose，因为它自带 postgres 和 Redis，能确保数据安全不丢失。
1.1 前置条件
准备一台 Linux 服务器（Ubuntu 或 CentOS），并预先安装好 Docker 和 Docker Compose。硬件配置建议至少为 4 核 8G。
1.2 Docker Compose 部署
```bash
git clone https://github.com/QuantumNous/new-api.git
cd new-api
git checkout v1.0.0-rc.4 #请checkout最新版本，这是2026年5月7日最新版本
vim docker-compose.yml # 根据实际修改端口、密码（改成强密码，默认都是123456）
docker compose up -d
```
项目自带的 `docker-compose.yml` 已配好 postgres、Redis 和 New API 三个服务，只需改端口和密码。
1.3 初始化
服务启动后访问 `http://服务器IP:3000`（端口建议使用80，并做外网的映射），首次打开会进入初始化引导，设置管理员账号密码。记好这个密码，后面所有管理操作都靠它。
模式采用自用模式
1.4 常用运维命令
```bash
docker logs -f new-api # 看实时日志
docker logs --tail=100 new-api # 看最近100行
docker ps # 查看服务状态
docker compose down # 在compose.yml同级目录执行，停止移除服务
docker compose up -d # 在compose.yml同级目录执行，重启服务
```
二、基础设置
2.1 速率设置
在“系统设置”→“速率限制设置”中，启用用户模型请求速率限制：
限制周期1分钟用户每周期最多请求次数50次
2.2 系统设置
内部进行账号统一管理，不允许除管理员外的任何人登录该平台，所以做账号限制
在“系统设置”→“系统设置”中的配置登录注册处。关闭允许通过免密码进行注册和允许新用户注册
在“系统设置”→“顶栏管理”中关闭模型广场、关于
2.3 绘图设置关闭
在“系统设置”→“绘图设置”中关掉全部绘图功能（如果你有生图模型就在此注意配置）
三、CodingPlan 的采集与分发
通常建议仅从一家采购同样的模型，提供团队内部统一使用
```text
模型厂商采购 API Key
│
▼
New API 添加渠道，统一录入 Key
│
▼
渠道分组，按部门/项目隔离
│
▼
创建订阅套餐，设定配额与有效期
│
▼
分发令牌给用户，绑定分组与限额
│
▼
用户通过令牌调用标准 API
│
▼
日志审计与看板，全链路监管
```
3.1 渠道分组
不同部门、不同项目可能需要用不同的 Key 池。通过“分组”实现渠道隔离：创建分组（如“研发一部”、“产品二部”），在渠道中指定该渠道属于哪个分组，用户只能访问自己分组内的渠道。
在“系统设置”→“分组与模型定价设置”的分组管理中添加内部各部门的分组。
倍率都按照1设计
每个组视人数给分配账号，一般设定比人数多1个~2个账号即可
3.2 模型定价
模型定价的主要目的，是为了统一内部模型叫法，给模型设置统一的价格，方便后续的管理
设计示例如下：
```text
xxx-glm-4.7：1$/1M Token
xxx-kimi-k2.5：2$/1M Token
xxx-kimi-k2.6：3$/1M Token
xxx-glm-k2.6：3$/1M Token
```
3.3 添加渠道
每个采购到的 API Key 对应一个渠道。管理员登录后进入「渠道」页面：
选择服务商类型（一般使用 OpenAI / Claude 等）名称，按照key来源构建，如厂商-key结尾4字符填入 API Key（密钥）勾选该 Key 支持的模型高级配置中可设 Base URL（代理地址）代理地址必须填写，根据国内模型厂商给的地址进行填写。一般国内模型厂商会给 Claude、OpenAI 两种接入方式的地址，跟选择的工具有关系。
3.4 多 Key 轮询
同一个服务商采购了多个 Key 时，用“多 Key 模式”：一个渠道挂多个 Key，系统自动轮询使用。单个 Key 失败自动跳过，恢复后重新启用。支持两种轮询策略：顺序轮询和加权随机（建议按照加权随机的模式使用）。
3.5 模型映射（自定义模型名）
企业内部通常希望给模型起统一的、有辨识度的名字，而不是用服务商那串原始 ID。New API 的模型映射功能可以在渠道层面把自定义名映射到实际的模型 ID。
配置位置：编辑渠道 → 高级配置 → 模型映射，填入 JSON 格式的映射关系。
示例：
```json
{
"xxxx-kimi-k2.5": "kimi-k2.5",
"xxxx-kimi-k2.6": "kimi-k2.6",
"xxxx-glm-4.7": "glm-4.7",
"xxxx-glm-5.1": "glm-5.1"
}
```
左侧 `xxxx-kimi-2.6` 是用户调用时传的模型名，右侧 `kimi-2.6` 是上游服务商的实际模型 ID。
操作步骤：
管理员进入「渠道」，编辑对应渠道在“模型”列表中手动输入自定义模型名（如 `xxxx-kimi-2.6`），不要从下拉列表选在“模型重定向”字段填入上面的 JSON保存后，用户调用 model: `"xxxx-kimi-2.6"` 就会自动路由到 `kimi-2.6`
右侧的值必须是对应服务商的真实模型 ID，可以在渠道的模型下拉列表中查看。映射关系只在当前渠道生效，不同渠道可以有不同的映射规则。
四、令牌（Token）管理
管理员统一创建令牌和分发，令牌是调用 API 的凭证。
用户在「令牌管理」页面创建，可配置：
名称：按使用人命名，如“张三”令牌分组：按使用人所在组区分过期时间：永不过期配额上限：初始给5亿Tken模型限制：所有配置模型提供
五、API 接入
New API 对外暴露标准 OpenAI 兼容接口和Claude接口。团队里不管用Opencode还是Claude都可以支持，直接把 Base URL 指向 New API 的地址就行。
5.1 Opencode接入配置
修改`~/config/opencode/opencode.jsonc`
Base URL:
`http://你的服务器IP:PORT/v1`（openAI）
API Key: 管理员提供给的 New API 中创建的令牌
```json
{
"plugin": [
"oh-my-openagent@latest"
],
"provider": {
"xxxx": {
"name": "xxxx",
"npm": "@ai-sdk/openai-compatible",
"models": {
"xxxx-glm-4.7": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-glm-4.7"
},
"xxxx-kimi-k2.5": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-kimi-k2.5"
},
"xxxx-kimi-k2.6": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-kimi-k2.6"
}
},
"options": {
"baseURL": "XXXX",
"apiKey": "XXXXX"
}
}
},
"$schema": "https://opencode.ai/config.json",
"disabled_providers": []
}
```
5.2 ClaudeCode接入配置
修改`~/.claude/setting.json`
Base URL:
`http://你的服务器IP:PORT`（claude）
```json
"env": {
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "xxxx-glm-4.7",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "xxxx-kimi-k2.5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "xxxx-kimi-k2.6",
"ANTHROPIC_AUTH_TOKEN": "在 New API 中创建的令牌",
"ANTHROPIC_BASE_URL": "XXXX",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "85",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
},
```
六、组织监管
6.1 日志审计
管理员在「使用」中可查看全站所有 API 调用记录：
调用时间、用户、模型、Token 消耗量配额扣减详情请求成功/失败状态
支持按时间范围、用户、模型、关键词等多维度筛选。
6.2 数据看板
控制台首页提供数据看板，展示：
总调用量、总 Token 消耗各模型使用占比各用户消费排行渠道响应时间分布
6.3 渠道健康监控
管理员可对渠道进行单个测试或批量测试，查看响应时间。开启“自动禁用”后，渠道连续失败达阈值会自动禁用，避免请求打到已经挂了的 Key 上。
6.4 自动化监管
可使用newAPI的skills进行自动化的监管（如批量创建Key）
一、部署安装
这是整个流程的基础。New API 提供了丰富的部署方式，包括 Docker 单容器、Docker Compose、1Panel、宝塔以及集群部署等。对于企业内网环境，强烈推荐使用 Docker Compose，因为它自带 postgres 和 Redis，能确保数据安全不丢失。
1.1 前置条件
准备一台 Linux 服务器（Ubuntu 或 CentOS），并预先安装好 Docker 和 Docker Compose。硬件配置建议至少为 4 核 8G。
1.2 Docker Compose 部署
```bash
git clone https://github.com/QuantumNous/new-api.git
cd new-api
git checkout v1.0.0-rc.4 #请checkout最新版本，这是2026年5月7日最新版本
vim docker-compose.yml # 根据实际修改端口、密码（改成强密码，默认都是123456）
docker compose up -d
```
项目自带的 `docker-compose.yml` 已配好 postgres、Redis 和 New API 三个服务，只需改端口和密码。
1.3 初始化
服务启动后访问 `http://服务器IP:3000`（端口建议使用80，并做外网的映射），首次打开会进入初始化引导，设置管理员账号密码。记好这个密码，后面所有管理操作都靠它。
模式采用自用模式
1.4 常用运维命令
```bash
docker logs -f new-api # 看实时日志
docker logs --tail=100 new-api # 看最近100行
docker ps # 查看服务状态
docker compose down # 在compose.yml同级目录执行，停止移除服务
docker compose up -d # 在compose.yml同级目录执行，重启服务
```
二、基础设置
2.1 速率设置
在“系统设置”→“速率限制设置”中，启用用户模型请求速率限制：
限制周期1分钟用户每周期最多请求次数50次
2.2 系统设置
内部进行账号统一管理，不允许除管理员外的任何人登录该平台，所以做账号限制
在“系统设置”→“系统设置”中的配置登录注册处。关闭允许通过免密码进行注册和允许新用户注册
在“系统设置”→“顶栏管理”中关闭模型广场、关于
2.3 绘图设置关闭
在“系统设置”→“绘图设置”中关掉全部绘图功能（如果你有生图模型就在此注意配置）
三、CodingPlan 的采集与分发
通常建议仅从一家采购同样的模型，提供团队内部统一使用
```text
模型厂商采购 API Key
│
▼
New API 添加渠道，统一录入 Key
│
▼
渠道分组，按部门/项目隔离
│
▼
创建订阅套餐，设定配额与有效期
│
▼
分发令牌给用户，绑定分组与限额
│
▼
用户通过令牌调用标准 API
│
▼
日志审计与看板，全链路监管
```
3.1 渠道分组
不同部门、不同项目可能需要用不同的 Key 池。通过“分组”实现渠道隔离：创建分组（如“研发一部”、“产品二部”），在渠道中指定该渠道属于哪个分组，用户只能访问自己分组内的渠道。
在“系统设置”→“分组与模型定价设置”的分组管理中添加内部各部门的分组。
倍率都按照1设计
每个组视人数给分配账号，一般设定比人数多1个~2个账号即可
3.2 模型定价
模型定价的主要目的，是为了统一内部模型叫法，给模型设置统一的价格，方便后续的管理
设计示例如下：
```text
xxx-glm-4.7：1$/1M Token
xxx-kimi-k2.5：2$/1M Token
xxx-kimi-k2.6：3$/1M Token
xxx-glm-k2.6：3$/1M Token
```
3.3 添加渠道
每个采购到的 API Key 对应一个渠道。管理员登录后进入「渠道」页面：
选择服务商类型（一般使用 OpenAI / Claude 等）名称，按照key来源构建，如厂商-key结尾4字符填入 API Key（密钥）勾选该 Key 支持的模型高级配置中可设 Base URL（代理地址）代理地址必须填写，根据国内模型厂商给的地址进行填写。一般国内模型厂商会给 Claude、OpenAI 两种接入方式的地址，跟选择的工具有关系。
3.4 多 Key 轮询
同一个服务商采购了多个 Key 时，用“多 Key 模式”：一个渠道挂多个 Key，系统自动轮询使用。单个 Key 失败自动跳过，恢复后重新启用。支持两种轮询策略：顺序轮询和加权随机（建议按照加权随机的模式使用）。
3.5 模型映射（自定义模型名）
企业内部通常希望给模型起统一的、有辨识度的名字，而不是用服务商那串原始 ID。New API 的模型映射功能可以在渠道层面把自定义名映射到实际的模型 ID。
配置位置：编辑渠道 → 高级配置 → 模型映射，填入 JSON 格式的映射关系。
示例：
```json
{
"xxxx-kimi-k2.5": "kimi-k2.5",
"xxxx-kimi-k2.6": "kimi-k2.6",
"xxxx-glm-4.7": "glm-4.7",
"xxxx-glm-5.1": "glm-5.1"
}
```
左侧 `xxxx-kimi-2.6` 是用户调用时传的模型名，右侧 `kimi-2.6` 是上游服务商的实际模型 ID。
操作步骤：
管理员进入「渠道」，编辑对应渠道在“模型”列表中手动输入自定义模型名（如 `xxxx-kimi-2.6`），不要从下拉列表选在“模型重定向”字段填入上面的 JSON保存后，用户调用 model: `"xxxx-kimi-2.6"` 就会自动路由到 `kimi-2.6`
右侧的值必须是对应服务商的真实模型 ID，可以在渠道的模型下拉列表中查看。映射关系只在当前渠道生效，不同渠道可以有不同的映射规则。
四、令牌（Token）管理
管理员统一创建令牌和分发，令牌是调用 API 的凭证。
用户在「令牌管理」页面创建，可配置：
名称：按使用人命名，如“张三”令牌分组：按使用人所在组区分过期时间：永不过期配额上限：初始给5亿Tken模型限制：所有配置模型提供
五、API 接入
New API 对外暴露标准 OpenAI 兼容接口和Claude接口。团队里不管用Opencode还是Claude都可以支持，直接把 Base URL 指向 New API 的地址就行。
5.1 Opencode接入配置
修改`~/config/opencode/opencode.jsonc`
Base URL:
`http://你的服务器IP:PORT/v1`（openAI）
API Key: 管理员提供给的 New API 中创建的令牌
```json
{
"plugin": [
"oh-my-openagent@latest"
],
"provider": {
"xxxx": {
"name": "xxxx",
"npm": "@ai-sdk/openai-compatible",
"models": {
"xxxx-glm-4.7": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-glm-4.7"
},
"xxxx-kimi-k2.5": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-kimi-k2.5"
},
"xxxx-kimi-k2.6": {
"limit": {
"context": 200000,
"output": 65536
},
"name": "xxxx-kimi-k2.6"
}
},
"options": {
"baseURL": "XXXX",
"apiKey": "XXXXX"
}
}
},
"$schema": "https://opencode.ai/config.json",
"disabled_providers": []
}
```
5.2 ClaudeCode接入配置
修改`~/.claude/setting.json`
Base URL:
`http://你的服务器IP:PORT`（claude）
```json
"env": {
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "xxxx-glm-4.7",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "xxxx-kimi-k2.5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "xxxx-kimi-k2.6",
"ANTHROPIC_AUTH_TOKEN": "在 New API 中创建的令牌",
"ANTHROPIC_BASE_URL": "XXXX",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "85",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
},
```
六、组织监管
6.1 日志审计
管理员在「使用」中可查看全站所有 API 调用记录：
调用时间、用户、模型、Token 消耗量配额扣减详情请求成功/失败状态
支持按时间范围、用户、模型、关键词等多维度筛选。
6.2 数据看板
控制台首页提供数据看板，展示：
总调用量、总 Token 消耗各模型使用占比各用户消费排行渠道响应时间分布
6.3 渠道健康监控
管理员可对渠道进行单个测试或批量测试，查看响应时间。开启“自动禁用”后，渠道连续失败达阈值会自动禁用，避免请求打到已经挂了的 Key 上。
6.4 自动化监管
可使用newAPI的skills进行自动化的监管（如批量创建Key）
评论
暂无评论。