如何用 VPS 搭建 New API 中转站：域名、HTTPS 与 Docker 完整教程

从 VPS 配置、域名解析、拉取 New API 源代码，到 Docker Compose、HTTPS、备份和 AI 排障，完整搭建一个不直接暴露 3000 端口的私有 AI API 网关。

公开更新时间：2026年07月28日文档维护：MatrixIDC 1 人阅读

你已经买了一台 VPS，手里也有自己合法获得授权的 AI API 渠道，但开发工具、脚本和团队成员各自填不同接口，排障和额度管理越来越乱。直接把 New API 的 3000 端口暴露到公网，看似能用，后面却会遇到 HTTPS、后台安全和数据备份的问题。

这篇教程给出一条完整但不过度复杂的路径：Ubuntu VPS + Docker Compose + PostgreSQL + Redis + Caddy。Caddy 只开放 80/443，New API、数据库和 Redis 留在容器内网。你需要准备一台 VPS、一个域名，以及自己拥有或被授权使用的上游 API。

New API 的官方定位是合法授权的 AI API 网关、组织认证和私有部署工具。请遵守上游服务条款和所在地规则；若对公众提供生成式 AI 服务，部署者还需要自行满足身份管理、日志、内容安全、税务和其他合规义务。

先选对 VPS：别只看价格

New API 官方当前的 Compose 示例会同时启动 New API、Redis 与 PostgreSQL。它不是只有一个静态网页，因此不建议把 1 核 1GB 当作这套教程的长期起点。

项目	本教程的起步建议	原因
系统	Ubuntu 24.04 LTS	Docker 官方文档完整，后续维护方便
CPU / 内存	2 核 4GB	给系统、New API、PostgreSQL 与 Redis 留出运行空间
磁盘	50GB SSD 起	容纳数据库、日志、镜像与备份
网络	独立 IPv4	便于域名解析和 HTTPS 验证
端口	22、80、443	SSH 管理、证书申请、HTTPS 访问

这是一套部署基线，不是并发承诺。真实容量取决于请求量、日志保留时间、模型响应大小和上游响应速度。上线后先看内存、磁盘和容器日志，再决定是否升级。

如果主要从中国大陆访问，选 VPS 时还要看线路、端口和流量说明。可以先在 MatrixIDC 查看当前上架的美国回程优化 VPS 配置；首次开通和 SSH 登录可参考新 VPS 开通与访问与 Linux SSH 登录与首次操作。

域名与端口：先准备好再启动容器

下面以 api.example.com 为例。请把它替换成你自己的子域名。

在 DNS 控制台添加一条 A 记录：

类型：A
主机记录：api
记录值：你的 VPS IPv4
TTL：自动

没有可用 IPv6 时，不要添加 AAAA 记录。部分网络会优先走 IPv6，一条错误的 AAAA 记录会造成“有些人能打开、有些人打不开”的问题。

同时在 VPS 提供商安全组和系统防火墙中允许：

TCP 22    SSH 管理
TCP 80    Caddy 申请 HTTPS 证书并跳转 HTTP
TCP 443   New API 后台与 API 访问

不要开放 3000、5432 或 6379。后文的 Compose 已经让它们只在 Docker 网络中通信。

安装 Docker：使用官方软件源

通过 SSH 登录 Ubuntu 后执行以下命令。Docker 官方不建议把来源不明的一键安装脚本直接用于生产环境。

sudo apt update
sudo apt install -y ca-certificates curl git ufw
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

cat <<EOF | sudo tee /etc/apt/sources.list.d/docker.sources
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker version
docker compose version

再配置 UFW。先允许 SSH，再允许网站端口，避免把自己锁在服务器外。

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Docker 的端口发布会影响防火墙策略，因此本教程只发布 Caddy 的 80/443；数据库、Redis 与 New API 不发布到宿主机。

拉取官方源代码并保留原始编排

进入 /opt 拉取 New API 官方仓库：

cd /opt
sudo git clone https://github.com/QuantumNous/new-api.git
sudo chown -R "$USER":"$USER" /opt/new-api
cd /opt/new-api
git remote -v
git rev-parse --short HEAD
cp docker-compose.yml docker-compose.upstream.yml

最后一条命令保留官方原始 Compose。以后升级时先阅读官方变更，再对照 docker-compose.upstream.yml 修改自己的配置，不要用 git pull 直接覆盖正在运行的文件。

先生成密钥，再创建 `.env`

执行三次下面的命令，得到三段不同的随机字符串：

openssl rand -hex 24

创建 .env：

nano .env

填入以下内容，尖括号内替换成你刚生成的随机值：

NEWAPI_DOMAIN=api.example.com
POSTGRES_PASSWORD=<第一段随机值>
REDIS_PASSWORD=<第二段随机值>
SESSION_SECRET=<第三段随机值>

保存后执行：

chmod 600 .env

.env 中有数据库密码和会话密钥。不要提交到 Git，不要截图发工单，也不要直接贴给 AI。

使用 Docker Compose：让 3000 端口不出现在公网

编辑 Compose 文件：

nano docker-compose.yml

将内容替换为：

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: unless-stopped
    command: --log-dir /app/logs
    environment:
      SQL_DSN: postgresql://newapi:${POSTGRES_PASSWORD}@postgres:5432/newapi
      REDIS_CONN_STRING: redis://:${REDIS_PASSWORD}@redis:6379
      TZ: Asia/Shanghai
      ERROR_LOG_ENABLED: "true"
      SESSION_SECRET: ${SESSION_SECRET}
      SESSION_COOKIE_SECURE: "true"
      SESSION_COOKIE_TRUSTED_URL: https://${NEWAPI_DOMAIN}
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    depends_on:
      - redis
      - postgres
    networks:
      - backend

  redis:
    image: redis:7-alpine
    container_name: new-api-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD}"]
    networks:
      - backend

  postgres:
    image: postgres:15
    container_name: new-api-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: newapi
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: newapi
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - backend

  caddy:
    image: caddy:2-alpine
    container_name: new-api-caddy
    restart: unless-stopped
    environment:
      NEWAPI_DOMAIN: ${NEWAPI_DOMAIN}
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - new-api
    networks:
      - backend

volumes:
  postgres_data:
  caddy_data:
  caddy_config:

networks:
  backend:

这份配置的关键不是“容器多”，而是边界清楚：浏览器只访问 Caddy；Caddy 再通过 new-api:3000 访问应用；PostgreSQL 和 Redis 没有映射公网端口。

配置 Caddy：域名和 HTTPS 自动处理

创建 Caddyfile：

nano Caddyfile

填入：

{$NEWAPI_DOMAIN} {
    encode zstd gzip
    reverse_proxy new-api:3000
}

只要域名已解析到 VPS、80/443 能从公网访问，Caddy 会自动申请并续期 HTTPS 证书，同时把 HTTP 跳转到 HTTPS。具体机制可查看 Caddy 反向代理文档。

先检查 Compose 语法，不输出包含密钥的完整渲染配置：

docker compose --env-file .env config --quiet

没有报错后拉取镜像并启动：

docker compose pull
docker compose up -d
docker compose ps

查看关键日志：

docker compose logs --tail=100 new-api
docker compose logs --tail=100 caddy

浏览器访问：

https://api.example.com

能打开后台页面，代表域名、HTTPS、反向代理和 New API 已经连通。也可以检查健康状态：

curl -fsS https://api.example.com/api/status

后台配置：渠道、令牌和最小权限

添加你自己拥有或获得授权的上游渠道。
按项目、人员或环境创建不同的调用令牌，不要全员共用一个长期令牌。
如果只供自己或团队使用，在系统设置中关闭不需要的新用户注册。
给不同令牌设置必要的模型和额度边界，并记录负责人。

不要把上游 Key 放进前端代码、公开仓库或截图。渠道需要测试时，优先使用后台的测试功能；报错时只保留请求 ID、状态码与脱敏日志。

AI 应该怎样参与：做检查员，不做密钥保管员

AI 很适合帮助你节省排障时间，但不应该拿到你的 .env、上游 API Key、SSH 私钥或数据库备份。

部署前，可以把下面提示词交给 AI：

你是 Linux 运维审查助手。我在 Ubuntu 24.04 上部署 New API，
使用 Docker Compose、PostgreSQL、Redis 和 Caddy。

请检查我提供的 docker-compose.yml、Caddyfile 和脱敏日志：
1. 是否错误暴露了 3000、5432 或 6379；
2. 域名、HTTPS 与 SESSION_COOKIE 配置是否一致；
3. 数据是否有持久化与备份路径；
4. 是否存在明显 YAML 或反向代理问题。

只输出问题清单和最小修改建议。不要要求我提供密码、Token、私钥、完整 .env 或上游 API Key。

容器异常时，先收集这三项脱敏信息，再让 AI 判断：

docker compose ps
docker compose logs --tail=150 new-api
docker compose logs --tail=150 caddy

让 AI 给出“下一步最小检查动作”，不要让它建议删除 volume、重置数据库或盲目重装。数据库被删掉后，渠道、用户、令牌和用量记录不会自己回来。

备份：上线当天就做，不要等出故障

至少备份 PostgreSQL 数据库与 /opt/new-api/data、/opt/new-api/logs。先创建备份目录：

mkdir -p /opt/new-api/backups

执行数据库备份：

cd /opt/new-api
docker compose exec -T postgres sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' | gzip > "backups/newapi-$(date +%F).sql.gz"

备份完成后，把 backups 同步到另一台机器或对象存储。备份只放在同一台 VPS，只能防误操作，不能防磁盘或整机故障。

常见问题

为什么不直接把 `3000:3000` 暴露到公网？

直接暴露能快速测试，但会绕开统一 HTTPS 与反向代理边界。教程使用 Caddy 对外提供 443，New API 的 3000 端口只供 Docker 内网访问。

HTTPS 证书申请失败怎么办？

依次检查：域名 A 记录是否指向当前 VPS；安全组和 UFW 是否允许 80/443；是否有其他程序占用这两个端口；docker compose logs caddy 是否显示具体错误。

为什么浏览器打开了，但 API 调用仍报错？

先在 New API 后台测试渠道，再确认令牌是否有对应模型权限。后台能访问不代表上游渠道、模型名、额度和令牌权限都已经正确。

以后如何更新？

先备份，再阅读 New API 官方发布说明和 Compose 差异；确认后执行 docker compose pull 与 docker compose up -d。不要把“升级”理解成删除 volume 后重新安装。

结语

一台配置合适、线路说明清楚的 VPS，加上独立域名、HTTPS、容器隔离和异地备份，就能构成一个可维护的 New API 私有网关。真正重要的不是把页面跑起来，而是四条底线：不暴露数据库和 Redis、不泄露上游 Key、定期备份、只接入你有权使用的渠道。

参考资料：New API 官方仓库、New API 官方 Compose 示例、Docker Ubuntu 安装文档。