New API：开源大模型API网关与AI资产管理系统安装与使用指南

官方信息

项目背景

在大模型百花齐放的今天，几乎每个开发者和小团队手里都捏着好几个 API：OpenAI、Claude、Gemini、DeepSeek、文心一言、讯飞星火、Midjourney、Suno……每一家的接口格式、计费规则、限流策略都不一样，想要把它们统一管理、统一分发、统一计费，传统做法就是自己写一层代理，结果越写越乱。

New API 就是为解决这个痛点而生的。它由 QuantumNous 团队在知名开源项目 One API 基础上二次开发，把所有主流大模型的调用接口统一转换成 OpenAI 兼容格式，一个端点接入全部 AI 服务。项目采用 Go + JavaScript 编写，在 GitHub 上已收获 30k+ Star，社区活跃、Issue 修复极快，是目前国内最流行的大模型中转分发系统之一。

它不仅能做渠道聚合，还内置了在线充值、按次计费、缓存计费、令牌分组、用户限流、数据看板等一整套运营功能，非常适合做"AI API 中转站"、团队内部模型统一入口，或者给小产品做模型层的中间件。

核心特性

• 全品类模型接入：OpenAI、Azure、Claude、Gemini、DeepSeek、文心、星火、Midjourney-Proxy、Suno、自定义渠道一网打尽。
• 智能渠道调度：支持渠道加权随机分配、默认渠道指定、故障自动重试与禁用。
• 统一接口格式：OpenAI Chat Completions、Claude Messages、Gemini 格式互相转换，客户端无需改造。
• 完善计费体系：在线充值（易支付）、模型按次收费、缓存命中按比例计费、令牌分组限额。
• 细粒度权限：GitHub OAuth、LinuxDO、Telegram、OIDC 多种登录；用户分组、模型可见范围控制。
• 数据可视化看板：调用量、消耗、用户分布、渠道分布一屏尽览。
• 思考模式支持：支持 o 系列与 Claude 的 reasoning effort 设置，实时 API（Realtime API）。
• 高可用：Redis 缓存、批量更新、流式超时可调、多机 Session 共享。

环境要求

• 操作系统：Linux（Ubuntu 22.04/24.04、CentOS、Debian 均可），推荐 2 核 4G 以上内存。
• 已安装 Docker 与 Docker Compose v2。
• 生产环境建议搭配 PostgreSQL + Redis；测试环境可用内置 SQLite。
• 开放端口 3000（如需对外访问）。

详细部署步骤

方式一：Docker Compose 部署（官方推荐，生产环境）

第一步，拉取项目源码：

git clone https://github.com/QuantumNous/new-api.git
cd new-api

第二步，编辑 docker-compose.yml。项目自带的 compose 已按推荐方案配置 PostgreSQL + Redis，按需修改端口和密码：

version: '3.4'
services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    command: --log-dir /app/logs
    ports:
      - '3000:3000'
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      - SQL_DSN=postgresql://root:你的数据库密码@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://redis
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true
      - BATCH_UPDATE_ENABLED=true
    depends_on:
      - redis
      - postgres
  redis:
    image: redis:latest
    container_name: redis
    restart: always
  postgres:
    image: postgres:15
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: 你的数据库密码
      POSTGRES_DB: new-api
    volumes:
      - pg_data:/var/lib/postgresql/data
volumes:
  pg_data:

逐行说明：SQL_DSN 是数据库连接串，生产环境务必改成强密码；REDIS_CONN_STRING 启用 Redis 缓存，显著降低重复请求成本；BATCH_UPDATE_ENABLED 开启批量统计更新，高并发下避免数据库锁。

第三步，启动服务：

docker compose up -d
docker compose logs -f new-api

方式二：Docker 单容器（快速体验，SQLite）

mkdir -p /data/new-api
docker run -d --name new-api \
  --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /data/new-api:/data \
  calciumion/new-api:latest

如需连接外部 MySQL：

docker run -d --name new-api \
  --restart always \
  -p 3000:3000 \
  -e SQL_DSN="用户名:密码@tcp(数据库地址:3306)/数据库名" \
  -e TZ=Asia/Shanghai \
  -v /data/new-api:/data \
  calciumion/new-api:latest

方式三：1Panel / 宝塔面板

在 1Panel 应用商店或宝塔 Docker 管理器中搜索 "New-API"，一键安装，按提示填端口和数据库即可，适合不熟悉命令行的用户。

初始化与首次登录

服务启动后，浏览器访问 http://服务器IP:3000，会自动跳转到初始化页面。首次安装没有默认账号密码，需要按照页面指引手动设置管理员账号和密码，请务必妥善保存。初始化完成后用设置的管理员账号登录即可。

常用环境变量

• GENERATE_DEFAULT_TOKEN：新注册用户是否自动生成初始令牌。
• STREAMING_TIMEOUT：流式回复超时，默认 300 秒，空补全时可调大。
• SESSION_SECRET：多机部署必须设置为随机字符串，否则登录态丢失。
• CRYPTO_SECRET：数据库敏感字段加密密钥，务必备份。
• GEMINI_VISION_MAX_IMAGE_NUM：Gemini 多模态最大图片数，默认 16。

使用方法

登录后台后，进入"渠道"页面，点击"添加渠道"，填入上游供应商的 API Key 和代理地址，选择模型类型即可。然后在"令牌"页面创建一个属于自己的令牌（Token），把客户端的 base_url 改成 http://你的域名:3000/v1，api_key 填刚创建的令牌，即可像调用 OpenAI 一样使用所有接入的模型：

curl http://你的域名:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的令牌" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

常见问题（FAQ）

Q1：容器启动后访问 3000 端口打不开？
A：先执行 docker compose ps 看容器是否 healthy；再检查服务器安全组/防火墙是否放行 3000 端口；用 docker logs new-api 查看报错，常见原因是数据库密码不一致或 PostgreSQL 未就绪。

Q2：多机部署登录态丢失？
A：必须给每个实例设置相同的 SESSION_SECRET 和 CRYPTO_SECRET，并接入同一个 Redis，否则会话和加密数据无法互通。

Q3：SQLite 和 MySQL/PostgreSQL 怎么选？
A：个人测试用 SQLite 即可；日调用量超过几千次、或者要对外运营，务必上 PostgreSQL/MySQL，否则数据库锁会导致流式回复卡顿。

Q4：缓存计费怎么配置？
A：在"系统设置"中开启缓存计费，设置缓存倍率（0-1 之间），对支持 Prompt Caching 的渠道（OpenAI、DeepSeek、Anthropic）按命中比例折扣收费。

跳转链接

• GitHub 仓库：https://github.com/QuantumNous/new-api
• 官方文档：https://docs.newapi.ai/zh/
• Docker 镜像：calciumion/new-api
• 上游项目 One API：songquanpeng/one-api