NewAPI 搭建教程：从零部署新一代 AI 大模型网关 ​

当你同时在使用 OpenAI、Claude、Gemini、DeepSeek 等多家大模型时，最头疼的往往是三件事：密钥散落各处、额度无法统一管控、客户端不兼容各家协议。NewAPI 正是为解决这类问题而生——它是一个开源的「大模型网关」，把几十种上游模型统一收敛成一套 OpenAI 兼容的接口。

本文是一份完整的 NewAPI 搭建教程，覆盖简介、环境准备、Docker / Docker Compose 部署步骤、排错与生产环境使用建议，帮你尽快完成一次可用的 API 网关部署。

一、NewAPI 简介与核心功能 ​

1.1 NewAPI 是什么？ ​

NewAPI（项目名 new-api）是一个新一代大模型网关与 AI 资产管理系统，由社区在 One API 基础上二次开发而来。它的定位是：

• 把多家大模型供应商的接口，统一转换为 OpenAI 格式的 API；
• 在你的团队 / 个人项目中，作为统一的 API 网关部署层，对外只暴露一个地址、一套密钥；
• 提供 Web 管理后台，负责渠道管理、令牌配额、计费与统计。

官方 Docker 镜像为 calciumion/new-api:latest，默认端口 3000，默认管理员账号 root / 密码 123456（首次登录必须修改）。

1.2 核心功能一览 ​

1.3 支持的上游渠道 ​

NewAPI 在 One API 的基础上扩展了更多协议，典型包括：

• 对话模型：OpenAI、Azure OpenAI、Claude（Anthropic）、Gemini、智谱 GLM、文心一言、通义千问、DeepSeek、Moonshot 等；
• 图像 / 创作：Midjourney Proxy、Suno；
• 检索增强：Rerank（Cohere / Jina）；
• Agent 平台：Dify、Coze 等自定义渠道。

1.4 NewAPI 与 One API 的关系 ​

NewAPI 并非另起炉灶，而是 One API 的增强分支：它兼容 One API 的数据库结构（one-api.db 可直接迁移），并新增了更现代的 UI、更多模型协议与运营能力。如果你已经在用 One API，迁移到 NewAPI 几乎无需改动数据。

如果你也在比较不同的自托管 AI 网关方案，可以对照阅读 OpenClaw 自托管指南，理解网关类产品各自的取舍。

二、搭建前的环境准备 ​

在开始 NewAPI Docker 部署 之前，请确认以下条件。

2.1 服务器基础要求 ​

提示：NewAPI 本身是轻量的 Go 服务，瓶颈通常在数据库与上游网络，而非 CPU。

2.2 安装 Docker 与 Docker Compose ​

推荐直接使用官方一键脚本：

# 安装 Docker（含 Compose 插件）
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

# 验证
docker --version
docker compose version

2.3 选择数据库 ​

NewAPI 支持三种数据库，部署前需明确选择：

• SQLite（默认）：开箱即用，适合个人 / 测试。Docker 部署必须挂载 /data 目录到宿主机，否则重启后数据丢失。
• MySQL：版本 >= 5.7.8，生产环境推荐。
• PostgreSQL：版本 >= 9.6，生产环境可选。

2.4 端口与网络规划 ​

• 默认服务端口：3000；
• 如需公网访问，建议前置 Nginx 反向代理 + HTTPS（Let's Encrypt）；
• 开放防火墙 / 安全组：仅放行 80、443，或仅放行 3000（内网 / 临时调试）。

三、NewAPI 详细搭建步骤 ​

下面给出两种主流方式。API 网关部署 生产环境推荐方式二（Docker Compose + MySQL + Redis）。

3.1 方式一：Docker 一键部署（SQLite，最快上手） ​

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

启动后访问 http://你的服务器IP:3000，使用 root / 123456 登录并立即修改密码。

3.2 方式二：Docker Compose 部署（推荐，含 MySQL + Redis） ​

新建 docker-compose.yml：

version: "3.8"

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
      - SQL_DSN=root:123456@tcp(mysql:3306)/oneapi
      - REDIS_CONN_STRING=redis://redis:6379
      - SESSION_SECRET=请改成一段随机长字符串
      - LOG_LEVEL=info
    volumes:
      - ./data:/data
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    container_name: new-api-mysql
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=123456
      - MYSQL_DATABASE=oneapi
    volumes:
      - ./mysql:/var/lib/mysql

  redis:
    image: redis:7-alpine
    container_name: new-api-redis
    restart: always
    volumes:
      - ./redis:/data

启动：

docker compose up -d

说明：SESSION_SECRET 在多机 / 多实例部署时必须设置，否则登录态会错乱；若多实例共用 Redis，还需设置 CRYPTO_SECRET，否则无法读取 Redis 中的加密内容。

3.3 初始化与首次配置 ​

1. 浏览器打开 http://服务器IP:3000；
2. 按引导设置管理员账户（务必修改默认密码）；
3. 进入后台 渠道管理 → 添加渠道，选择上游类型（如 OpenAI），填入 API Key 与模型名；
4. 进入 令牌管理 → 创建令牌，设置名称与额度，复制生成的 sk-xxx；
5. 用令牌测试调用。

3.4 验证部署（curl 测试） ​

curl -X POST http://你的服务器IP:3000/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

若返回正常 JSON 结果，说明 NewAPI 搭建 成功，网关已可对外提供服务。

四、常见问题与排错方法 ​

4.1 无法访问后台（:3000 打不开） ​

• 确认容器已运行：docker ps | grep new-api；
• 确认端口映射：docker logs new-api 查看是否监听 3000；
• 检查防火墙 / 安全组是否放行 3000；
• 云服务器注意：部分厂商默认禁止公网直连，建议改走 Nginx 443。

4.2 渠道测试失败（添加渠道后「测试」报错） ​

• 核对 API Key 是否有效、是否欠费或 region 受限；
• 确认模型名填写正确（区分大小写，如 gpt-4o 而非 GPT-4O）；
• 服务器需能访问上游域名；国内机器调用境外模型时注意网络连通性；
• Docker 内访问宿主机服务，Windows / Mac 用 host.docker.internal，Linux 用宿主机真实内网 IP。

4.3 数据库相关问题 ​

• SQLite 数据丢失：未挂载 /data。务必在 docker run 中加 -v /path:/data；
• MySQL 连接失败：检查 SQL_DSN 格式 user:pass@tcp(host:port)/db，确认数据库已建库（oneapi）；
• 从 One API 迁移：可直接复用 one-api.db，无需重建数据。

4.4 多机 / 多实例部署异常 ​

• 登录态错乱 → 设置 SESSION_SECRET；
• Redis 内容读不到 → 设置 CRYPTO_SECRET；
• 负载不均 → 在 设置 → 运营设置 → 通用设置 中配置渠道权重与重试次数。

4.5 令牌无额度 / 调用 401 ​

• 令牌创建时若未设额度，可能受 DEFAULT_TOKEN 默认值影响；
• 确认请求头 Authorization: Bearer sk-xxx 的 Key 与后台一致；
• 查看 日志 页面定位具体拒绝原因。

五、搭建完成后的使用建议 ​

5.1 安全加固（必做） ​

• 改密码：第一时间修改 root 默认密码；
• 上 HTTPS：通过 Nginx 反代 + Let's Encrypt 证书，避免密钥明文传输；
• 收窄暴露面：生产环境不要直接把 3000 暴露在公网；
• 密钥隔离：为不同应用签发不同令牌，便于额度与权限管控。

5.2 渠道与流量管理 ​

• 同一模型配置多个渠道并设权重，提升可用性；
• 开启 渠道重试（运营设置中配置重试次数），并启用缓存降低重复成本；
• 周期性在 渠道管理 中做健康检查，及时下线失效 Key。

5.3 配额、计费与客户端接入 ​

• 利用令牌额度做成本隔离，适合团队 / 多项目共用网关；
• NewAPI 兼容任意 OpenAI 格式客户端，例如 Cherry Studio、Lobe Chat、Next Chat；
• 接入方式：API 地址填 http://你的IP:3000/v1，API Key 填后台令牌。

5.4 备份与更新 ​

• 定期备份 /data（SQLite）或 MySQL 数据卷；
• 更新：拉取新镜像 docker pull calciumion/new-api:latest 后重建容器；不建议用 Watchtower 自动更新，可能导致数据库不兼容。

六、FAQ：NewAPI 常见问题 ​

Q：NewAPI 是什么？
A：NewAPI（new-api）是一个开源的新一代大模型网关，基于 One API 二次开发，能把 OpenAI、Claude、Gemini、DeepSeek 等多种大模型统一为 OpenAI 兼容接口，并提供渠道管理、令牌配额与计费能力。

Q：NewAPI 默认端口和管理员密码是多少？
A：默认端口 3000；默认管理员账号 root，密码 123456，首次登录必须修改。

Q：NewAPI 支持哪些数据库？
A：支持 SQLite（默认，需挂载 /data）、MySQL（>= 5.7.8）、PostgreSQL（>= 9.6）。

Q：NewAPI 和 One API 有什么区别？
A：NewAPI 是 One API 的增强分支，数据库结构兼容、可直接迁移，并新增了更现代的 UI、更多模型协议（Midjourney Proxy、Suno、Rerank、Dify、Coze 等）与运营能力。

Q：如何把 NewAPI 接入 ChatGPT 类客户端？
A：在客户端中将 API 地址设为 http://你的IP:3000/v1，API Key 填 NewAPI 后台创建的令牌即可，兼容 Cherry Studio、Lobe Chat、Next Chat 等。

Q：生产环境推荐哪种 NewAPI 部署方式？
A：推荐 Docker Compose 部署，配合 MySQL（或 PostgreSQL）+ Redis + Nginx（HTTPS），并设置 SESSION_SECRET 与 CRYPTO_SECRET 以保证多实例一致性。

Q：NewAPI Docker 镜像名是什么？
A：官方镜像为 calciumion/new-api:latest。

七、总结 ​

NewAPI 是当下搭建个人 / 企业级 AI 大模型网关最省心的选择之一：部署简单（一条 docker run 即可起步）、协议统一（OpenAI 兼容）、运维能力完整（配额、计费、重试、统计）。本文从环境准备到 API 网关部署、从排错到生产建议，给出了一条可落地的 NewAPI 搭建教程 路径。

下一步，你可以从一个 SQLite 实例开始快速验证，再平滑过渡到 Docker Compose + MySQL 的生产架构；若你还在评估其他自托管方案，也可一并参考 OpenClaw 自托管指南。