New API Docker 部署教程：自建 AI API 中转站

git clone https://github.com/QuantumNous/new-api.git
cd new-api
# 先编辑 docker-compose.yml：替换 123456 等示例密码，设置 SESSION_SECRET
docker compose up -d
docker compose logs -f new-api

New API 是 QuantumNous 维护的开源 AI 网关，在 One API（MIT 许可证）基础上二次开发，本身采用 AGPLv3 许可证。它把 OpenAI、Anthropic、Google Gemini、DeepSeek 等上游接到同一个入口，对外提供 /v1/chat/completions、/v1/responses、/v1/messages 等接口，并在网页控制台里管理渠道、令牌、用量和计费。

部署前准备：服务器、域名与 Docker

Docker 按 Docker 官方的 Install Docker Engine 文档安装，Compose 插件见 Install the Docker Compose plugin。装好后确认两条命令都有输出：

docker --version
docker compose version

官方 docker-compose.yml 与数据库选择

仓库自带的 docker-compose.yml 默认启动三个容器：New API、PostgreSQL 和 Redis，另外以注释形式给出 MySQL 和独立 ClickHouse 日志库的示例。官方文档把 PostgreSQL 列为生产首选，MySQL 作为兼容选项；不设置 SQL_DSN 时使用 SQLite，官方说明 SQLite 更适合本地体验和临时测试，不建议用于生产。

如果要换成 MySQL，按文件头注释操作：注释掉 postgres 服务和 PostgreSQL 的 SQL_DSN 行，取消注释 mysql 服务和 MySQL 的 SQL_DSN 行，再取消注释 depends_on 里的 mysql 和 volumes 里的 mysql_data。文件头注释漏了一步：还要把 depends_on 里的 - postgres 注释掉，否则 Compose 会因为依赖了不存在的服务而报错。MySQL 服务的 MYSQL_ROOT_PASSWORD 和 MySQL SQL_DSN 里的 123456 也要一并改掉。官方支持的版本下限是 MySQL 5.7.8、PostgreSQL 9.6。

克隆后先找到下面这几行，它们原样摘自仓库的 docker-compose.yml（省略了行尾注释）。其中四处 123456 密码在文件里都标着生产环境必须修改；3000:3000 端口映射没有这个标记，但下一节建议改成只监听本机：

services:
  new-api:
    ports:
      - "3000:3000"
    environment:
      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://:123456@redis:6379

  redis:
    command: ["redis-server", "--requirepass", "123456"]

  postgres:
    environment:
      POSTGRES_PASSWORD: 123456

启动前必改：密码、SESSION_SECRET 与监听地址

官方 README 要求启动前同时替换数据库、Redis 服务及对应连接串里的示例密码，并设置固定的随机 SESSION_SECRET（可用 openssl rand -hex 32 生成）。先生成三个值：

openssl rand -hex 24   # 用作 PostgreSQL 密码
openssl rand -hex 24   # 用作 Redis 密码
openssl rand -hex 32   # 用作 SESSION_SECRET

十六进制字符串里没有 @、:、/ 这类字符，直接放进连接串不需要转义。然后把上面那几行改成下面的样子：只改列出的行，其余内容保持原文件不动；PG_PASSWORD、REDIS_PASSWORD、SESSION_SECRET_VALUE 换成刚生成的值，同一个密码出现的两处必须一致，api.example.com 换成你的域名。

services:
  new-api:
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - SQL_DSN=postgresql://root:PG_PASSWORD@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://:REDIS_PASSWORD@redis:6379
      - SESSION_SECRET=SESSION_SECRET_VALUE
      - SESSION_COOKIE_SECURE=true
      - SESSION_COOKIE_TRUSTED_URL=https://api.example.com

  redis:
    command: ["redis-server", "--requirepass", "REDIS_PASSWORD"]

  postgres:
    environment:
      POSTGRES_PASSWORD: "PG_PASSWORD"

• 只监听本机：官方 README 的单容器示例用的就是 -p 127.0.0.1:3000:3000。Docker 文档说明，发布端口时如果不写主机地址，会发布到所有地址；而且已发布的容器端口不受 ufw 规则约束。反向代理和 New API 在同一台机器上时，让 3000 只监听 127.0.0.1。
• SESSION_SECRET：所有节点必须一致，重启后也不要换。官方文档写明不能设成 random_string，否则程序拒绝启动。
• HTTPS 控制台：通过 HTTPS 访问控制台时设 SESSION_COOKIE_SECURE=true，并在 SESSION_COOKIE_TRUSTED_URL 填控制台对外的精确 HTTPS Origin：不带路径、不支持通配符，多个用英文逗号分隔。
• 可信代理：TRUSTED_PROXIES 未配置时，默认信任 127.0.0.0/8、::1、RFC1918 私网和 fc00::/7，并在启动时打印告警；设为 none 则不信任任何代理，写明确列表会完全替换默认值。官方建议按实际网络显式配置。令牌的 IP 白名单要配合可信反向代理使用。

首次启动与默认端口

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

docker compose up -d 会自动拉取镜像并在后台启动服务；docker compose ps 查看各容器状态；logs -f 跟随 New API 日志，按 Ctrl+C 退出跟随，不会停止服务。

New API 默认监听 3000 端口（环境变量 PORT 的默认值）。官方 compose 的健康检查会请求 /api/status，并检查返回内容里有 "success": true。在服务器上可以手动确认一次：

curl -s http://127.0.0.1:3000/api/status

启动时如果看到 Compose 提示 version 属性已过时，可以忽略：Docker 文档说明顶层 version 只作提示用。

配置 HTTPS 反向代理：Caddy 或 Nginx

官方 README 要求正式部署使用 HTTPS，并让反向代理支持流式响应和 WebSocket 升级。下面两种任选其一。

方案一：Caddy（自动申请证书）

按 Caddy 官方安装文档安装。用 Debian/Ubuntu 软件包安装后，Caddy 会作为名为 caddy 的 systemd 服务自动运行。编辑 /etc/caddy/Caddyfile：

api.example.com {
	reverse_proxy 127.0.0.1:3000
}

sudo systemctl reload caddy
journalctl -u caddy --no-pager | less +G

Caddy 默认为所有站点启用 HTTPS，并把 HTTP 自动重定向到 HTTPS。自动签发证书的前提是：域名的 A/AAAA 记录指向这台服务器，80 和 443 端口对外开放，Caddy 能绑定这两个端口，数据目录可写且持久。Content-Type: text/event-stream 的响应会被立即刷新给客户端，SSE 流式输出不需要额外配置；WebSocket 也能直接代理。

方案二：Nginx

证书用你习惯的 ACME 客户端签发，把路径填进 ssl_certificate 和 ssl_certificate_key。Let's Encrypt 的 HTTP-01 验证只走 80 端口，请求路径是 /.well-known/acme-challenge/，所以 80 端口的 server 块单独放行这个路径，其余请求跳转到 HTTPS。下面以 certbot 的 webroot 方式为例，webroot 目录用 /var/www/html。

首次签发时证书文件还不存在。如果一开始就写入带 443 块的完整配置，nginx -t 会因为加载不到证书而报错，配置不会生效，80 端口的验证路径也就用不了。所以分两步做。

第一步：只写入 80 端口的 server 块，重新加载 Nginx，再用 certbot 签发证书。

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

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

sudo mkdir -p /var/www/html
sudo nginx -t && sudo nginx -s reload
sudo certbot certonly --webroot -w /var/www/html -d api.example.com --deploy-hook "nginx -s reload"

--deploy-hook 的命令会在这次签发成功后执行，之后每次续期成功也会执行，这里用它让 Nginx 重新加载、换上新证书。证书放在 /etc/letsencrypt/live/证书名/ 下，没有用 --cert-name 指定时，证书名取第一个 -d 域名，所以这里是 /etc/letsencrypt/live/api.example.com/。

第二步：签发成功后，在同一份配置里加上 map 和 443 端口的 server 块，再检查并重新加载。map 必须写在 http 块内：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 128m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

sudo nginx -t && sudo nginx -s reload

80 端口的 server 块保持不动，certbot renew 续期时会沿用签发时的 webroot 方式。可以先用 sudo certbot renew --dry-run 演练一次续期。

四个 proxy_set_header 的写法与 New API 官方集群部署文档中的 Nginx 示例一致。

打开域名完成初始化向导

官方文档的流程是：服务启动后访问站点，会自动进入初始化页面，按页面指引手动设置管理员账号和密码，只在首次安装时需要。完成后用这个管理员账号登录。

1. 浏览器打开 https://api.example.com，自动进入初始化向导（当前源码中的路由是 /setup）。
2. 向导会显示检测到的数据库类型。用官方 compose 时应显示 PostgreSQL；如果显示的不是你配置的数据库，先回去检查 SQL_DSN。
3. 设置管理员用户名和密码。当前源码按字节检查用户名长度，要求不超过 12 个字节：英文字母和数字最多 12 位，一个汉字按 UTF-8 占 3 个字节；密码 8 到 128 个字符，两次输入一致。
4. 选择使用模式：对外运营（多用户或团队，带计费与配额）、个人使用（即自用模式，隐藏定价和计费选项）、演示站点。只给自己或内部用，选个人使用。

添加上游渠道

渠道对应一个上游服务商的 API Key。用管理员账号登录后，在左侧导航进入「渠道」（当前源码路由为 /channels；官方使用指南中写的是 /console/channel，以你部署版本的导航为准）。

1. 添加渠道：选择服务商类型（如 OpenAI、Claude、Gemini），填写渠道名称和上游 API Key。
2. 勾选该渠道支持的模型，也可以用页面上的按钮从上游获取模型列表再勾选。
3. 按需展开高级配置：Base URL（代理或私有部署时用）、优先级、权重、模型映射、参数覆盖、自动禁用。
4. 提交后，在渠道列表里点「测试」，看响应时间和成功或失败。

优先级数字越大越先被使用；同一优先级下按权重比例分配请求，例如两个渠道权重 2:1，请求大致按 2:1 分配。

官方 README 的首次请求步骤里还有一步：配置模型价格，确保调用用户有可用额度或有效订阅。初始化时选了「个人使用」的，定价和计费选项会被隐藏；选「对外运营」的，渠道测试如果报“倍率或价格未配置”，去系统设置里给模型配置倍率或价格。

官方渠道页面提示：上游渠道必须是部署方合法拥有或已获授权的账号、API Key、模型服务或企业合约，负载均衡、多 Key 等功能用于高可用和企业多账号管理，使用时要遵守上游服务条款。

创建令牌（API 密钥）

1. 左侧导航点「API 密钥」，或直接访问 /keys。
2. 点「创建 API 密钥」，填写名称（按用途区分，如“生产环境”“测试用”）。
3. 按需设置分组、过期时间、额度、模型限制和 IP 白名单。分组要能访问你刚配置的渠道和模型。
4. 保存后在列表里点掩码密钥，按提示查看并复制完整值。

令牌额度和账户额度是分开的：令牌额度只是这个密钥的使用上限。账户余额够、请求却提示额度不足时，先查令牌额度。官方文档提醒，API 密钥等同于密码，不要提交到代码仓库、截图、日志或聊天工具；怀疑泄露时立即删除并重新创建。轮换和存储做法见API Key 安全指南。

用 curl 验证 /v1/models 与 /v1/chat/completions

在你自己的电脑上测试，请求经过域名和 HTTPS，能同时验证反向代理。your-enabled-model 换成渠道里已启用、且令牌有权使用的模型名。

macOS / Linux（bash、zsh）：

export NEW_API_BASE_URL="https://api.example.com"
export NEW_API_KEY="在 /keys 页面复制的令牌"

curl --fail-with-body "${NEW_API_BASE_URL}/v1/models" \
  -H "Authorization: Bearer ${NEW_API_KEY}"

curl --fail-with-body "${NEW_API_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-enabled-model","messages":[{"role":"user","content":"Hello!"}]}'

Windows PowerShell：

$env:NEW_API_BASE_URL = "https://api.example.com"
$env:NEW_API_KEY = "在 /keys 页面复制的令牌"
$headers = @{ Authorization = "Bearer $env:NEW_API_KEY" }

Invoke-RestMethod -Uri "$env:NEW_API_BASE_URL/v1/models" -Headers $headers

$body = @{
  model    = "your-enabled-model"
  messages = @(@{ role = "user"; content = "Hello!" })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post -Uri "$env:NEW_API_BASE_URL/v1/chat/completions" -Headers $headers -ContentType "application/json" -Body $body

再测一次流式，确认反向代理没有缓冲（-N 让 curl 不缓冲输出）：

curl -N --fail-with-body "${NEW_API_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-enabled-model","messages":[{"role":"user","content":"Hello!"}],"stream":true}'

• /v1/models 返回该令牌能访问的模型列表。返回 401 时检查令牌是否复制完整、是否被禁用或过期；返回 403 并提示 IP 不在允许列表时，检查令牌的 IP 白名单和 TRUSTED_PROXIES。
• /v1/chat/completions 返回 200 和 choices。报“无可用渠道”时检查用户分组、渠道分组和渠道的模型设置。
• 流式请求应看到 data: 开头的事件逐条到达。如果最后一次性全部出现，检查 Nginx 的 proxy_buffering。
• 每次请求都能在控制台的使用日志里查到，扣费与你配置的倍率或价格一致。

状态码的分层排查可以参考API 中转站错误码排查指南。

升级、备份与回滚

官方更新指南建议更新前先备份数据库和重要配置文件，并在 GitHub Releases 查看新版本的更新内容。PostgreSQL 的数据在命名卷 pg_data 里，用 pg_dump 导出最直接；data、logs 是 compose 挂载到宿主机的目录，docker-compose.yml 里有你改过的密码和密钥，一起打包：

cd new-api
mkdir -p backup
docker compose exec -T postgres pg_dump -U root -d new-api > backup/new-api-$(date +%F).sql
tar czf backup/new-api-files-$(date +%F).tar.gz data logs docker-compose.yml

-T 关闭伪终端分配，输出重定向到文件时要加。备份文件含数据库全部内容和密钥，按密钥同等级别保管，并复制到另一台机器或对象存储。只用 SQLite 时，数据库文件在 data 目录里，先 docker compose stop new-api 再打包。

备份要定期验证能恢复。下面把备份导入一个临时库检查，然后删掉临时库，不影响正在运行的 new-api 库。把 YYYY-MM-DD 换成要验证的备份文件日期：

docker compose exec -T postgres createdb -U root new_api_restore_test
docker compose exec -T postgres psql -U root -d new_api_restore_test < backup/new-api-YYYY-MM-DD.sql
docker compose exec -T postgres dropdb -U root new_api_restore_test

Docker Compose 部署的官方升级命令：

cd new-api
docker compose pull
docker compose down
docker compose up -d

docker compose down 默认只删除容器和网络，命名卷 pg_data 会保留。不要加 -v，它会删除命名卷，也就是整个数据库。

README 建议从 New API Releases 页面选定一个明确版本，读完升级说明、备份后再升级；latest 会随发布构建变化。固定版本只需改镜像标签，例如截至 2026-10-09 的最新版本：

image: calciumion/new-api:v1.0.0-rc.42

升级后按官方清单检查：能否正常登录管理界面，日志里有没有错误或警告，API 调用是否正常，数据库迁移是否成功，渠道状态是否正常。出问题时，官方的回滚方式是换回之前的版本标签重新创建容器；如果 Release 说明提到数据库结构变更，回滚前先确认旧版本是否兼容，必要时用升级前的备份恢复。官方还提醒，Watchtower 一类自动更新工具在数据库结构变更时可能出问题，生产环境应手动控制更新。

安全清单

• 替换 docker-compose.yml 里全部 123456 示例密码：PostgreSQL、Redis，以及两条连接串。
• 设置固定的随机 SESSION_SECRET，不要用 random_string。
• 3000 端口只监听 127.0.0.1；不要取消 postgres、mysql 服务里 ports 的注释，数据库和 Redis 只在 compose 内部网络访问。
• 云安全组或防火墙只放行 SSH、80、443。别指望 ufw 拦住 Docker 发布的端口，Docker 文档说明这类流量不经过 ufw 规则。
• 启动后立即完成初始化；管理员密码用密码管理器生成。
• 只给自己或内部用时，在系统设置的 /system-settings/auth「基本身份验证」里关掉「注册已启用」。
• 控制台走 HTTPS，并配好 SESSION_COOKIE_SECURE 与 SESSION_COOKIE_TRUSTED_URL。
• 镜像固定到具体版本，关注 Releases，升级前备份。
• 上游 Key 只放在渠道配置里，令牌按应用分开创建，并设置额度、过期时间和模型限制。

合规方面，官方 README 写明：本项目仅面向合法授权的 API 网关、组织内部鉴权、多模型管理和私有化部署等场景；作为面向公众的生成式 AI 服务或 API 转售服务运营时，使用者要先完成备案、内容安全、实名、日志留存、税务、支付和上游授权等义务。项目采用 AGPLv3，第 7 条附加条款要求修改版本保留作者署名，带界面的修改版本还要保留指向原项目的可见链接。更多检查项见API 中转站合规风险清单。

常见问题排查

改 PostgreSQL 密码的命令如下。它在 postgres 容器内通过本地连接执行，官方镜像对容器内的本地连接使用 trust 认证，不需要旧密码。PG_PASSWORD 换成 SQL_DSN 里的新密码，改完执行 docker compose up -d，让 compose 里改过的配置生效：

docker compose exec postgres psql -U root -d new-api -c "ALTER USER root WITH PASSWORD 'PG_PASSWORD';"
docker compose up -d

下一步：选型、架构与托管方案

如果还没决定用哪个开源项目，先看开源 API 中转站源码选型指南；想了解自建网关在鉴权、路由、流式转发、计量和限流熔断上要承担哪些工作，看API 中转站搭建与网关架构教程。上线后的指标和告警可参考API 中转站可观测性指南。

如果不想自己维护服务器、数据库、证书和升级，也可以直接用托管的 API 中转服务，例如 GPTZZZ（OpenAI 兼容 Base URL 为 https://gptzzz.ai/v1，接入方式见 GPTZZZ API 文档，GPTZZZ 即本站运营方，利益关系见文首披露）。

官方资料

• New API 官方 GitHub 仓库（README 与 docker-compose.yml）
• New API 文档：Docker Compose 部署
• New API 文档：环境变量配置指南
• New API 文档：系统更新指南
• New API 文档：常见问题
• Docker 文档：Port publishing and mapping、Packet filtering and firewalls
• Caddy 文档：reverse_proxy、Automatic HTTPS
• Nginx 文档：ngx_http_proxy_module、WebSocket proxying
• Certbot 文档：User Guide（webroot 插件、证书路径与续期）、Let's Encrypt 文档：Challenge Types
• PostgreSQL 文档：pg_dump