中转站搭建指南 - New API、Docker、Nginx、HTTPS 与 Codex 接入

01

PREPARATION

准备服务器与域名

先把基础资源准备齐，后面的部署会顺很多。生产环境不建议直接把 3000、5432、6379 暴露到公网。

一台可公网访问的 Linux VPS
Ubuntu 22.04 / 24.04 或 Debian 12
至少 2 核 CPU、2 GB 内存、20 GB 磁盘
一个域名或二级域名，如 api.example.com
开放 TCP 22、80、443 端口
准备合法有效的上游 API Key

先确认合规：本指南用于自建 API 网关、统一管理本人或团队获授权的模型接口。你仍需遵守云厂商、模型提供商和所在地区的服务条款与法律要求。

登录服务器并更新系统

Ubuntu / Debian

ssh root@你的服务器IP
apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg git ufw

配置基础防火墙

UFW

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

避免把自己锁在门外：务必先放行 OpenSSH，再执行 ufw enable。如果云厂商还有安全组，也要同步开放 22、80、443。

02

CONTAINER RUNTIME

安装 Docker 与 Compose

优先使用 Docker 官方仓库，安装后用 hello-world 和 Compose 版本命令确认环境正常。

Docker 官方安装方式

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $VERSION_CODENAME stable" \
  > /etc/apt/sources.list.d/docker.list

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

验证安装

docker --version
docker compose version
docker run --rm hello-world

如果你不是 Ubuntu，请按 Docker 官方安装文档切换到对应发行版，不要盲目套用 Ubuntu 软件源。

03

NEW API STACK

用 Docker Compose 部署 New API

下面采用 New API 官方推荐的 PostgreSQL + Redis 组合，并把 Web 端口仅绑定到 127.0.0.1:3000，避免绕过 Nginx 直接访问。

创建部署目录与随机密钥

/opt/new-api

mkdir -p /opt/new-api/{data,logs,backups}
cd /opt/new-api

POSTGRES_PASSWORD=$(openssl rand -hex 24)
SESSION_SECRET=$(openssl rand -hex 32)
printf 'POSTGRES_PASSWORD=%s\nSESSION_SECRET=%s\n' \
  "$POSTGRES_PASSWORD" "$SESSION_SECRET" > .env
chmod 600 .env

创建 `docker-compose.yml`

先从 .env 读取数据库密码，再创建配置；不要把真实密码写进公开文档或仓库。

生成最终配置

cd /opt/new-api
set -a
. ./.env
set +a

cat > docker-compose.yml <<EOF
services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: unless-stopped
    command: --log-dir /app/logs
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      - SQL_DSN=postgresql://root:$POSTGRES_PASSWORD@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://redis
      - TZ=Asia/Shanghai
      - SESSION_SECRET=$SESSION_SECRET
      - ERROR_LOG_ENABLED=true
      - BATCH_UPDATE_ENABLED=true
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -q '\"success\":true'"]
      interval: 30s
      timeout: 10s
      retries: 5

  postgres:
    image: postgres:15
    container_name: new-api-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: new-api
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U root -d new-api"]
      interval: 10s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    container_name: new-api-redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

volumes:
  pg_data:
  redis_data:
EOF

启动并验证服务

启动命令

cd /opt/new-api
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 new-api
curl -fsS http://127.0.0.1:3000/api/status

不要照抄弱密码。官方示例里的 123456 只能用于演示。生产环境应使用随机强密码，且数据库与 Redis 不映射公网端口。

04

DNS

解析域名到服务器

在域名 DNS 控制台添加 A 记录，让专用子域名指向 VPS 公网 IPv4。

记录类型	主机记录	记录值	TTL
A	api	你的服务器 IPv4	300 / 默认
AAAA	api	服务器 IPv6（可选）	300 / 默认

例如你的域名是 example.com，填写主机记录 api 后，最终访问地址就是 api.example.com。

检查解析

getent ahostsv4 api.example.com
# 或
dig +short api.example.com A

先确认域名已经解析到当前服务器，再申请 HTTPS 证书。否则 Certbot 的 HTTP-01 验证会失败。

05

REVERSE PROXY

配置 Nginx 与 HTTPS

Nginx 负责公网入口、TLS、真实 IP 与长连接转发；New API 继续只监听本机 3000 端口。

客户端

HTTPS :443

Nginx

127.0.0.1:3000

New API

安装 Nginx 与 Certbot

安装软件

apt install -y nginx certbot python3-certbot-nginx
systemctl enable --now nginx

创建站点配置

/etc/nginx/sites-available/new-api.conf

server {
    listen 80;
    listen [::]:80;
    server_name api.example.com;

    client_max_body_size 50m;

    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 "upgrade";
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        proxy_buffering off;
    }
}

启用配置并申请证书

Nginx + Let's Encrypt

ln -s /etc/nginx/sites-available/new-api.conf \
  /etc/nginx/sites-enabled/new-api.conf
nginx -t
systemctl reload nginx

certbot --nginx -d api.example.com
certbot renew --dry-run

关于 CDN：首次排障建议先用 DNS only 直连源站。确认 HTTPS、流式输出和大请求正常后，再按需要接入 CDN，并保留真实客户端 IP 配置。

06

FIRST RUN

初始化管理员与系统设置

访问你的域名，首次启动会进入初始化页。只需初始化一次，随后用管理员账号登录后台。

打开 https://api.example.com。
按照页面提示创建管理员账号和强密码。
登录后进入“设置”，确认站点名称、额度单位、日志与注册策略。
如果只供自己使用，建议关闭公开注册；需要团队成员时，再设置邮箱验证、邀请或手动创建用户。
不要直接把管理员令牌放进日常客户端，日常调用应使用普通用户令牌。

建议打开

错误日志、批量更新、合理的流式超时、管理后台登录保护。

建议关闭或限制

开放注册、无限额度、公共测试令牌、无需认证的管理入口。

07

UPSTREAM CHANNEL

添加上游渠道与模型

“渠道”保存的是你获得授权的上游接口；对外令牌与上游 Key 应分开管理，不要把上游 Key 直接交给客户端。

进入后台的“渠道”页面，点击“添加渠道”。
选择与上游协议相符的类型，如 OpenAI、Anthropic、Gemini 或 OpenAI-compatible。
填写上游 Base URL。多数 OpenAI-compatible 服务使用类似 https://provider.example/v1 的地址。
填写上游 API Key，并选择或手动填写允许调用的模型列表。
根据需要设置模型映射，例如客户端请求 gpt-5.5，上游实际模型名不同，可通过映射统一。
保存后使用后台“测试”功能验证连通性与模型可用性，再开启渠道。

字段	作用	常见问题
渠道类型	决定协议、鉴权和请求转换方式	类型选错会出现 400 / 404
Base URL	上游 API 根地址	重复写 `/v1/v1`
API Key	向上游鉴权	Key 失效、额度不足、IP 限制
模型	允许网关路由的模型名	客户端模型名与上游不一致
优先级 / 权重	多渠道路由与分流	测试阶段不建议配置太复杂

先简单后复杂：首次部署只添加一个确认可用的上游渠道，先跑通单模型，再增加多渠道、权重、分组和故障转移。

08

ACCESS TOKEN

创建对外访问令牌

令牌用于客户端调用你的中转站。建议按设备、项目或人员分别创建，便于限额、审计和单独吊销。

进入“令牌”页面，新建一个令牌。
设置清晰名称，如 codex-laptop、cursor-work。
设置到期时间、额度、可用模型或 IP 白名单（如版本支持）。
创建后立即复制并安全保存；不要写进公开仓库、网页源码、聊天记录或截图。

用 curl 验证 OpenAI-compatible 接口

列出模型

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer sk-your-relay-token"

Chat Completions 测试

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-relay-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "stream": false
  }'

09

CODEX CLIENT

接入 Codex 与 CC-Switch

最省心的方式是用 CC-Switch 图形化新增一个 Codex 渠道；也可以直接编辑 Codex 的认证和配置文件。

方案 A：使用 CC-Switch

在 CC-Switch 中选择 Codex，新增供应商或渠道。
Base URL 填 https://api.example.com/v1。
API Key 填刚刚创建的中转令牌。
模型填写后台实际开放给该令牌的模型名。
保存并应用配置，重开 Codex 终端后测试。

方案 B：手动配置 Codex

不同 Codex 版本对 wire_api、Responses API 与 Chat Completions 的支持会变化。下面以 OpenAI-compatible Chat Completions 为例；如果你的上游支持 Responses API，可按实际版本改为 responses。

~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-your-relay-token"
}

~/.codex/config.toml

model = "你的模型名"
model_provider = "my-relay"

[model_providers.my-relay]
name = "My New API Relay"
base_url = "https://api.example.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

如果出现 404：优先检查 Base URL 是否重复包含 /v1，以及当前渠道到底支持 /v1/chat/completions 还是 /v1/responses。

10

SECURITY

安全加固与备份

中转站保存上游 Key、用户令牌和用量记录，最低限度的安全与备份不能省。

管理员使用独立强密码，不与服务器密码复用
关闭不需要的公开注册与测试令牌
只开放 22、80、443；数据库和 Redis 不对公网映射
为每个客户端创建独立令牌并设置额度
定期检查异常请求、错误日志与用量突增
备份数据库、Compose、.env 和必要数据目录

备份 PostgreSQL 与配置

手动备份

cd /opt/new-api
STAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p backups/$STAMP

docker exec new-api-postgres pg_dump -U root -d new-api \
  > backups/$STAMP/new-api.sql
cp docker-compose.yml .env backups/$STAMP/
tar -czf backups/new-api-$STAMP.tar.gz -C backups/$STAMP .
chmod 600 backups/new-api-$STAMP.tar.gz

恢复前先做演练

数据库恢复示例

# 在维护窗口、确认目标数据库为空或允许覆盖后执行
cat /path/to/new-api.sql | \
  docker exec -i new-api-postgres psql -U root -d new-api

备份也包含敏感信息。不要把 .env、数据库备份和上游 Key 上传到公共网盘或公开 Git 仓库；异地备份应加密并限制访问。

11

MAINTENANCE

安全升级与日常维护

升级前备份，升级后检查健康状态、渠道和真实调用。不要只看容器“Up”就认定业务正常。

标准升级流程

cd /opt/new-api

# 1. 先按上一节完成备份
# 2. 拉取新镜像并重建

docker compose pull
docker compose up -d

# 3. 验证
docker compose ps
docker compose logs --tail=120 new-api
curl -fsS https://api.example.com/api/status
curl -fsS https://api.example.com/v1/models \
  -H "Authorization: Bearer sk-your-test-token"

日常观察

docker compose ps、容器日志、磁盘空间、证书续期、上游余额和渠道错误率。

版本策略

关键业务可固定镜像版本，先在旁路实例测试，再切换生产；不要长期无审查地自动追 latest。

12

TROUBLESHOOTING

常见问题排查

按照“DNS → Nginx → New API → 渠道 → 上游”的顺序逐层定位，避免一上来就反复重装。

打开域名显示 502 Bad Gateway

先执行 curl http://127.0.0.1:3000/api/status。如果本机也失败，检查 docker compose ps 和 New API 日志；如果本机成功，检查 Nginx 的 proxy_pass、端口和 nginx -t。

Certbot 申请证书失败

确认域名 A/AAAA 记录已指向本机、80 端口公网可达、Nginx 正常监听，且 CDN/代理没有阻断 HTTP-01 验证。

客户端返回 401 Unauthorized

确认使用的是 New API 生成的对外令牌，而不是管理员密码；检查 Authorization 格式是否为 Bearer sk-...，令牌是否过期、被禁用或额度耗尽。

客户端返回 404 Not Found

检查 Base URL 是否多写或漏写 /v1，并确认客户端调用的是 Chat Completions 还是 Responses API。部分上游或渠道只实现其中一种。

有模型列表，但调用提示模型不存在

检查渠道允许模型、模型映射、令牌模型限制和客户端配置中的模型名是否完全一致。先用后台渠道测试功能确认上游真实模型名。

流式输出中断或长任务超时

Nginx 应关闭 proxy_buffering 并提高 proxy_read_timeout；New API 可按版本配置流式超时。若经过 CDN，还要检查 CDN 的连接时长限制。

服务器重启后服务没有起来

确认 Docker 已启用开机启动，Compose 中服务设置了 restart: unless-stopped 或 always，并检查磁盘空间、数据库健康检查和容器日志。

↗

REFERENCES

官方资料与延伸阅读

本文以官方文档为基础重新整理，命令和界面可能随版本更新，请在正式部署前交叉核对。

最后更新：2026 年 7 月。New API 与 Codex 更新较快，部署前建议优先查看官方版本说明和升级指南。

从零搭建
自己的 AI 中转站

个人与小团队

OpenAI-compatible

只接入授权资源

准备服务器与域名

登录服务器并更新系统

配置基础防火墙

安装 Docker 与 Compose

用 Docker Compose 部署 New API

创建部署目录与随机密钥

创建 `docker-compose.yml`

启动并验证服务

解析域名到服务器

配置 Nginx 与 HTTPS

安装 Nginx 与 Certbot

创建站点配置

启用配置并申请证书

初始化管理员与系统设置

建议打开

建议关闭或限制

添加上游渠道与模型

创建对外访问令牌

用 curl 验证 OpenAI-compatible 接口

接入 Codex 与 CC-Switch

方案 A：使用 CC-Switch

方案 B：手动配置 Codex

安全加固与备份

备份 PostgreSQL 与配置

恢复前先做演练

安全升级与日常维护

日常观察

版本策略

常见问题排查

官方资料与延伸阅读

从零搭建自己的 AI 中转站

个人与小团队

OpenAI-compatible

只接入授权资源

准备服务器与域名

登录服务器并更新系统

配置基础防火墙

安装 Docker 与 Compose

用 Docker Compose 部署 New API

创建部署目录与随机密钥

创建 docker-compose.yml

启动并验证服务

解析域名到服务器

配置 Nginx 与 HTTPS

安装 Nginx 与 Certbot

创建站点配置

启用配置并申请证书

初始化管理员与系统设置

建议打开

建议关闭或限制

添加上游渠道与模型

创建对外访问令牌

用 curl 验证 OpenAI-compatible 接口

接入 Codex 与 CC-Switch

方案 A：使用 CC-Switch

方案 B：手动配置 Codex

安全加固与备份

备份 PostgreSQL 与配置

恢复前先做演练

安全升级与日常维护

日常观察

版本策略

常见问题排查

官方资料与延伸阅读

从零搭建
自己的 AI 中转站

创建 `docker-compose.yml`