企业官网建设流程全解析

本篇包含New API的安装部署与配置指引，以及一个采用标准 OpenAI 协议访问 New API 的 Python 调用示例程序。

1. 项目简介

1.1 到底什么是 New API？

简单来说，New API 就是大模型时代的“统一 API 网关 / 路由器”（类似于 Web 开发中的 Nginx，或支付领域的“聚合支付”）。

在没有 New API 时，不同厂商的模型（OpenAI、Claude、DeepSeek、阿里通义、智谱清言、腾讯混元、本地 Ollama 等）都有各自不同的接口格式、密钥体系、计费规则和调用限制。如果你的业务需要对接多个模型，你的代码就必须针对每个厂商写一套适配逻辑，极其繁琐。

而有了 New API 之后：

你只需对接 New API 这一个统一入口（标准的 OpenAI 协议），New API 在后台负责帮你转发、调度并抹平所有底层大模型的差异。

┌───> OpenAI (GPT-4o) ├───> Anthropic (Claude 3.5) 业务应用 / 客户端 │ (Python / Dify / NextChat) ───>│───> DeepSeek (官方 / 硅基流动) [统一走 OpenAI 接口协议] │ http://.../v1 ├───> 阿里百炼 / 智谱清言 / 火山引擎 └───> 本地模型 (Ollama / vLLM) 【New API 统一管理与路由】 (负载均衡 · 故障转移 · 额度分发 · 审计)

1.2 它具体能做什么？（核心功能）

1. 统一接口标准（格式转换）
   • 将全球各种各样的大模型（即使本身不是 OpenAI 格式，例如 Claude、Gemini、百度千帆等），全部在网关层无感转为 OpenAI 标准格式输出。客户端一行代码都不用改。
2. 多渠道聚合与负载均衡
   • 同一个模型（例如deepseek-chat），你可以同时配置多个上游渠道或多个 API Key。
   • 支持按权重轮询（Round-Robin）分发流量，有效避免单一 Key 被限速（Rate Limit）。
3. 高可用容灾与自动故障转移（Failover）
   • 当主渠道因上游欠费、宕机、超时或报错（如 429、500）时，系统自动无感重试并切换到备用渠道，保障线上业务永不中断。
4. 用户与令牌权限管控（多租户分发）
   • 可以为不同团队、不同系统或个人创建独立的 API 访问令牌（Token）。
   • 支持针对每个 Token 设置调用额度上限、限制允许访问的模型白名单、过期时间及调用频率（QPS/RPM）。
5. 模型别名重定向（Mapping）
   • 可以将请求的模型名进行动态映射。例如：用户客户端请求的是gpt-4，后台可以直接无感映射转给成本更低的deepseek-chat或claude-3-5-sonnet，业务端完全无感知。
6. 详尽的调用审计与统计看板
   • 记录每一次调用的Token 消耗明细、输入输出消耗、耗时、模型名称、调用者 IP 及日志，方便成本核算与异常溯源。

1.3 用了它有什么好处？（核心价值）

1.4 项目信息与开源协议

• 开源协议：完全开源，采用 AGPL-3.0 许可证（该协议具有强传染性，商业化衍生改造分发时需注意源码公开合规要求）。
• 技术栈：后端基于Go 语言（Gin + GORM）构建，轻量且高性能；前端基于React构建现代易用的后台管理控制台。
• 官方仓库：QuantumNous/new-api（基于知名开源项目 One API 深度二次开发）

2. 安装部署方式

方式一：Docker 部署（推荐）

官方推荐在 Linux / 服务器环境下使用docker-compose快速部署，具体配置可参考 官方文档。

# 克隆项目 git clone https://github.com/QuantumNous/new-api.git cd new-api # 编辑 docker-compose.yml 配置 nano docker-compose.yml # 启动服务 docker compose up -d docker-compose up -d

方式二：原生 Windows .exe 绿色运行（免安装）

在 Windows 环境下可直接下载单文件可执行程序免安装运行：

第 1 步：下载程序

访问 QuantumNous/new-api Releases 页面，下载最新的 Windows 版本可执行文件（例如：new-api-v1.0.0-rc.30.exe）。

💡建议：下载后可将其重命名为new-api.exe，便于后续维护与脚本编写。

第 2 步：创建工作目录

在任意磁盘分区（例如D:\new-api\）下新建一个文件夹，将下载好的new-api.exe放入该目录。

第 3 步：指定端口并启动

在程序所在目录打开 PowerShell，执行以下命令（默认监听端口为 3000）：

$env:PORT="3000";.\new-api.exe

💡长期后台运行提示：若希望开机自启并在后台静默运行，可以使用 Windows 服务注册工具（如 NSSM）将其注册为 Windows 系统服务。

第 4 步：访问系统并初始化

1. 打开浏览器访问：http://localhost:3000

2. 首次访问时，系统会引导您进入设置向导，设置超级管理员账号与密码。比如admin/admin123.
   

3. 登录后台后，点击「令牌」（Tokens）生成访问密钥（以sk-开头），供客户端应用接入调用。

第 5 步：配置渠道（以 DeepSeek 为例）

1. 点击左侧管理员菜单栏的「渠道」（Channels）。

2. 点击右上角「+ 创建渠道」按钮。
   

3. 在弹出的配置页面中填写参数：

   • 类型：选择DeepSeek（若无该选项可选择OpenAI）。
   • 渠道名称：自定义名称（例如：deepseek）。
   • API 地址：默认留空即可使用内置官方地址，若走第三方中转可自定义填写。
   • API 密钥：填入申请到的 DeepSeek 官方密钥。
   • 模型列表：填入需要使用的模型名称（例如：deepseek-chat、deepseek-reasoner或deepseek-v4-flash等，支持同时添加多个）。
   • 模型映射（可选，高级功能）：将请求模型名称映射到实际提供商模型名称（JSON 格式）。若上游模型名与对外暴露名称不一致时使用（如{"deepseek-chat": "deepseek-ai/DeepSeek-V3"}）。

• 💡密钥添加技巧：添加模式选择“批量添加（每行一个密钥）”，可填入同平台的多个 API Key 实现自动分流；亦可创建多个独立渠道分别绑定不同平台的 Key。

4. 保存后可在渠道列表右侧点击「测试」验证渠道连通性。

3. 应用程序接入（Python 示例）

New API 完全兼容OpenAI 标准协议，任何支持自定义base_url的 OpenAI SDK 或客户端应用均可无缝接入。

配置说明

快速运行示例

1. 安装依赖

pip install-r requirements.txt

2. 配置环境变量

修改项目根目录下的.env文件：

# New API 地址（末尾带 /v1） OPENAI_BASE_URL=http://localhost:3000/v1 # New API 中生成的令牌 (以 sk- 开头) OPENAI_API_KEY=sk-your-token-key # 使用的模型名称 OPENAI_MODEL=deepseek-v4-flash

3. 执行测试

python main.py

Python 核心代码 (main.py)

importosimportsysfromdotenvimportload_dotenvfromopenaiimportOpenAI,OpenAIError# 适配 Windows 控制台输出编码ifsys.stdout.encodingandsys.stdout.encoding.lower()!='utf-8':try:sys.stdout.reconfigure(encoding='utf-8')sys.stderr.reconfigure(encoding='utf-8')exceptException:passload_dotenv()defmain():base_url=os.getenv("OPENAI_BASE_URL")api_key=os.getenv("OPENAI_API_KEY")model=os.getenv("OPENAI_MODEL","deepseek-v4-flash")ifnotbase_urlornotapi_key:print("【错误】请先在 .env 文件中设置 OPENAI_BASE_URL 和 OPENAI_API_KEY！")sys.exit(1)# 初始化 OpenAI 客户端client=OpenAI(base_url=base_url,api_key=api_key,)try:response=client.chat.completions.create(model=model,messages=[{"role":"system","content":"你是一个乐于助人的 AI 助手。"},{"role":"user","content":"你好，请用一句话介绍你自己，并确认连接成功。"},],temperature=0.7,)print("【模型回复】:")print(response.choices[0].message.content)ifresponse.usage:print(f"\n[Token 统计] 输入:{response.usage.prompt_tokens}| 输出:{response.usage.completion_tokens}| 总计:{response.usage.total_tokens}")exceptOpenAIErrorase:print(f"【请求失败】调用 NewAPI 发生异常:{e}")if__name__=="__main__":main()

4. 常见问题排查 (FAQ)

4.1 请求报错与异常处理

Q1：请求报错503 - system disk overloaded (current: 96%, threshold: 95%)？

• 📌现象描述：调用 API 时直接返回 HTTP 503，错误提示code: system_disk_overloaded。
• 🔍根本原因：这是 New API 内置的系统级磁盘过载保护机制。当宿主机系统盘（Windows 环境下默认检测 C 盘）的使用率达到或超过95%时，系统会主动熔断并拦截所有转发请求，以避免数据库写入失败或服务崩溃。
• 🛠️排查与解决：
  1. 检查 C 盘使用率：在 PowerShell 中执行Get-PSDrive C查看 C 盘已用空间。
  2. 快速清理释放空间（通常仅需释放 2~3 GB 即可降回 95% 以下）：
     • 按Win + R输入%temp%，清空用户临时缓存文件。
     • 清空系统桌面「回收站」。
     • 按Win + R输入cleanmgr，运行 Windows 自带磁盘清理工具清理临时文件与系统更新缓存。
  3. 恢复：C 盘使用率降到 95% 以下后，无需重启 New API 即可自动恢复请求转发。

Q2：请求报错401 - Invalid token / 额度不足 / 用户已被封禁？

• 📌现象描述：客户端发起请求返回 HTTP 401 认证失败。
• 🔍根本原因：
  1. .env中的OPENAI_API_KEY填写错误，或仍保留了示例中的占位符（sk-your-token-key）。
  2. 填写的是下游模型（如 DeepSeek）的官方密钥，而非New API 系统内生成的访问令牌（Token）。
  3. 该令牌绑定的用户在 New API 内设定的调用额度已耗尽。
• 🛠️排查与解决：
  1. 登录 New API 控制台，进入「令牌」页面。
  2. 检查使用的 Token 是否为有效状态，额度是否充足。
  3. 点击「编辑」确认“模型范围”已勾选了当前调用的模型（或设置为“全部模型”）。

Q3：请求报错404 / 500 - 无可用渠道 (No available channel)？

• 📌现象描述：调用时提示找不到模型或没有可用渠道提供服务。
• 🔍根本原因：
  1. 请求传入的模型名称（model）与 New API 渠道中配置的模型名不一致。
  2. 对应的渠道已被系统临时禁用（由于多次超时、连续报错或已被手动停用）。
• 🛠️排查与解决：
  1. 进入「渠道」列表，检查对应的渠道开关是否处于“已启用”状态。
  2. 点击该渠道右侧的「测试」按钮，查看上游接口是否可正常连通。
  3. 检查渠道编辑页中的「模型列表」，确认已包含客户端所请求的模型名（如deepseek-chat）。

4.2 渠道调度与高可用机制

Q4：如何配置“多渠道负载均衡与故障转移”？

在 New API 中，实现多 Key 轮询与多服务商容灾备份主要有两种配置方式：

1. 方式一：单渠道内挂载多 Key（同服务商分流）

   • 适用：在同一家平台申请了多个 Key，用来分摊并发和限频。
   • 操作：编辑该渠道，在「API 密钥」输入框中换行填入多个 Key（一行一个），系统会自动加权轮询调用。

2. 方式二：创建多个独立渠道但配置相同模型名（跨服务商容灾与负载均衡）

   • 适用：同时接入多个供应商（例如：官方 DeepSeek + 硅基流动 + 火山引擎）。
   • 操作：分别创建对应各厂商的独立渠道，并将「模型名称」都填写为相同的名字（如deepseek-chat），通过设置优先级与权重进行调度。

Q5：New API 内部是如何进行路由与故障调度的？

当客户端请求某个具体模型（例如model="deepseek-chat"）时，底层调度流转机制如下：

客户端发起请求 ───> 命中模型池 (所有包含 deepseek-chat 的可用渠道) │ ├──> ① 筛选出【最高优先级】的可用渠道 │ ├──> ② 同一优先级内，按【权重比例】加权轮询分发 │ └──> ③ 遇故障 (429/500/超时) ──> 自动无感重试并切换下一渠道 (Failover)

• 🔄加权轮询：相同优先级的渠道，New API 会根据设定的权重比例（如 10 : 5 即 2 : 1）分发流量。
• 🛡️自动故障转移（Failover）：请求过程中若主渠道返回网络异常、500 错误或被上游 429 限速，New API 会在本次请求内自动透明重试并故障降级转移到同池内的其它可用渠道，客户端业务无感知报错。
• 🩺自动熔断与探活：连续异常超阈值的渠道会被暂时熔断挂起，后台周期性发起健康探测，一旦恢复立即自动重回服务池。

Q6：各厂商模型名称不一致时，如何通过「模型映射」实现负载均衡与故障转移？

• 📌问题背景：不同平台对同一款模型的命名往往不同。例如：

  • DeepSeek 官方：deepseek-chat
  • 硅基流动 (SiliconFlow)：deepseek-ai/DeepSeek-V3
  • 阿里云百炼：deepseek-v3
  • 火山引擎 ARK：ep-20250203-xxxxxx(接入点 Endpoint ID)
  • 本地 Ollama：deepseek-r1:32b

  如果直接按原名添加渠道，客户端就无法将它们汇入同一个模型池做负载均衡和互备容灾。

• 🛠️核心解法：使用渠道高级设置中的「模型映射 (Model Mapping)」

  核心思想：“对外统一叫一个名字（汇入同一模型池），对内转发给上游时由 New API 自动翻译为供应商实际的模型名。”

• 📝JSON 配置语法：

  {"客户端请求的统一模型名":"上游服务商实际真实模型名"}

• 🚀多厂商统一聚合实战配置（以客户端统一调用deepseek-chat为例）：

  渠道	渠道名称	模型列表（对外暴露）	模型映射（JSON 配置）	说明
  渠道 1	DeepSeek 官方	deepseek-chat	(留空)	官方原生名称即为deepseek-chat
  渠道 2	硅基流动	deepseek-chat	{"deepseek-chat": "deepseek-ai/DeepSeek-V3"}	转发时自动重写为硅基流动的模型名
  渠道 3	火山引擎	deepseek-chat	{"deepseek-chat": "ep-20250203-xxxxxx"}	转发时自动替换为火山引擎接入点 ID

• ⚠️避坑与深度解析（关于截图中黄色警告提示的含义）：

  1. 黄色提示详解（如截图中提示：添加 "gpt-3.5-turbo" 到模型列表，以便用户在映射将流量发送到上游之前可以使用它们。）：
     • 这不是要求系统中必须存在真实的 OpenAI/gpt-3.5-turbo 渠道！
     • 其真实含义是：你在映射规则中写了"gpt-3.5-turbo": "deepseek-v4-flash"（允许用户请求gpt-3.5-turbo），但是当前渠道的「模型列表」中尚未勾选或录入gpt-3.5-turbo。
     • 底层逻辑：New API 收到客户端请求时，首先通过渠道的「模型列表」来筛选“谁支持此模型”。如果当前渠道的模型列表里没有声明gpt-3.5-turbo，请求就会直接将其跳过，根本走不到映射步骤。
     • 解决方式：直接点击提示右侧的「添加缺失模型」按钮，系统就会自动将对外暴露的模型名添加到当前渠道的模型列表中。
  2. 跨模型/跨家族降级容灾（进阶）：甚至可以对外提供一个统一虚拟名称（如primary-chat或xxxx），主渠道（高优先级）映射为deepseek-chat，备用渠道（低优先级）映射为gpt-4o-mini。平时享受极低成本，一旦 DeepSeek 突发大面积宕机或 429 限流，New API 自动透明降级切换至 OpenAI 兜底，保障核心业务永续可用！
  3. 至关重要的原则：左边可虚拟，右边必真实：

     {"xxxx":"gpt-4o-mini"↑ ↑ 左边右边(完全自定义)(必须是该厂商真实模型)

     • 左边（Key / 请求模型名）：可以天马行空，是任何你自定义的名字（如xxxx、my-bot），也可以是其他厂商的名字。唯一要求：必须在当前渠道的「模型列表」中勾选或录入该名字。
     • 右边（Value / 目标模型名）：必须是当前渠道服务商真实支持、且你的密钥有权限调用的模型名！因为 New API 转发时会将右边的名字直接写入发送给上游服务商的数据体（Payload）中。如果右边填了该厂商没有的模型，上游官方服务器会直接拒收报错（如 OpenAI 报错404 Model Not Found）。

5. 邮件服务配置（以 QQ 邮箱为例）

配置 SMTP 邮件服务后，系统可支持新用户注册邮箱验证码、绑定邮箱、密码找回以及系统告警通知等功能。

第一步：配置前准备（获取 QQ 邮箱授权码）

⚠️重要提示：这是最关键的一步，密码栏填的是授权码，不是你的 QQ 登录密码。

1. 访问 QQ 邮箱网页版：https://mail.qq.com，建议切换到电脑版模式（手机浏览器需勾选“请求桌面站点”）。
2. 进入设置：点击顶部“设置”（齿轮图标） ->“邮箱设置”。
3. 注意路径：进入设置页后，请点击顶部的“帐户”标签（不是左侧或下方的“安全设置”）。
4. 生成授权码：向下滚动到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”区域，点击“生成授权码”。
5. 获取并保存：验证后获取一串 16 位字母组合（如：abcdefghijklmnop），复制保存（只显示一次）。

第二步：New API 后台填写配置

进入 New API 后台“系统设置”->“邮箱设置”，严格按照以下参数填写：

填写完毕后，点击页面底部的“保存”按钮。

第三步：验证邮箱设置是否正确

1. 添加用户：在管理后台添加用户，设置用户名和密码。
2. 登录账户：打开网页，以新的用户名和密码登录。
3. 绑定邮箱验证：进入设置页面绑定邮箱。如果邮箱成功收到了验证码，说明 SMTP 邮件服务设置成功。