一、项目简介

New-API（QuantumNous/new-api）是一个统一 AI 模型网关系统，可以把多种大模型接口统一成标准 API（如 OpenAI 格式），方便开发者和企业进行模型管理与调用。

官方项目地址：
https://github.com/QuantumNous/new-api

✨ 核心能力

New-API 的核心功能包括：

🤖 统一 OpenAI / Claude / Gemini API 格式
🔌 多模型聚合（多渠道负载均衡）
📊 请求统计与计费管理
🔁 自动失败重试与路由
🧠 支持多种模型接口（Chat / Embedding / Image 等）
🐳 Docker 一键部署
🔐 支持 MySQL / PostgreSQL / SQLite

二、系统架构说明

New-API 的本质是一个 AI API Gateway（网关层）：


客户端（OpenAI SDK / 应用）
        ↓
New-API 网关
        ↓
路由系统（负载均衡 / 计费 / 限流）
        ↓
上游模型（OpenAI / Claude / Gemini / 第三方API）

三、环境要求

安装前请确认：

Docker 20+
Docker Compose（推荐）
Linux / Windows / macOS / VPS
端口：3000（默认）

四、Docker 一键安装（推荐）

1. 拉取镜像

官方镜像：


docker pull calciumion/new-api:latest

2. 启动容器（SQLite 版本，最简单）


docker run -d \
  --name new-api \
  -p 3000:3000 \

五、Docker Compose 生产级部署（推荐）

相比 docker run，生产环境更推荐使用 Compose，方便后期扩展数据库与持久化。

1. 创建目录


mkdir -p /opt/new-api
cd /opt/new-api

2. 编写 docker-compose.yml


version: "3.8"

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
      - SQL_DSN=sqlite3:/data/new-api.db
    volumes:
      - ./data:/data

3. 启动服务


docker compose up -d

4. 访问系统

浏览器打开：


http://你的IP:3000

六、首次初始化与登录

1. 默认访问

首次打开后进入初始化页面：

设置管理员账号
设置密码
初始化数据库

2. 登录后台

登录后你会看到：

用户管理
渠道管理
模型管理
令牌（API Key）
日志监控

七、核心配置说明（非常重要）

New-API 的核心是“渠道（Channel）”。

1. 添加 OpenAI 渠道

后台操作：

渠道管理 → 添加渠道
类型选择：OpenAI
填写：


API Key: sk-xxxxxx
Base URL: https://api.openai.com/v1

2. 添加 Claude / Gemini

类似方式：

Claude（示例）


Base URL: https://api.anthropic.com
Key: xxxxx

Gemini：


https://generativelanguage.googleapis.com

3. 渠道负载均衡

支持：

轮询
随机
权重
失败自动切换

👉 可以实现“多 API 自动容灾”

八、API 使用方式（重点）

New-API 会统一成 OpenAI 标准接口。

1. Chat API 示例


curl http://IP:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

2. Python 调用


from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKEN",
    base_url="http://IP:3000/v1"
)

res = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)

print(res.choices[0].message.content)

九、用户与 API Key 管理

New-API 支持：

多用户系统
API Token 生成
额度控制
计费统计

1. 创建 Token

后台：

用户管理 → 创建 Token
设置：


额度限制
过期时间
权限范围

2. 使用 Token


Authorization: Bearer sk-xxxx

十、Nginx 反向代理（生产必备）

1. 配置域名


server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. HTTPS（推荐）

使用 certbot：


certbot --nginx -d api.yourdomain.com

十一、性能优化建议

1. 使用 MySQL（推荐生产）


environment:
  - SQL_DSN=mysql://user:pass@tcp(127.0.0.1:3306)/newapi

2. 开启缓存

Redis（可选）
请求缓存
减少重复调用

3. 限流配置

防止 API 被刷爆：

IP限流
用户限额
Token限制

十二、常见问题（FAQ）

Q1：访问不了 3000？

检查：

Docker 是否启动
端口是否占用
防火墙是否拦截

Q2：API 返回 401？

原因：

Token错误
没有权限
渠道未配置

Q3：模型不可用？

可能：

上游 API Key 失效
渠道未启用
网络问题

十三、适用场景

New-API 非常适合：

AI API 聚合平台
SaaS AI 服务
企业内部模型网关
开发统一 API 接口
多模型调度系统

十四、总结

New-API 的核心价值一句话：

🔥 把“多个 AI 模型接口”统一成一个 OpenAI API

你可以用它实现：

多模型聚合
自动切换供应商
API 计费系统
企业级 AI 网关