Sub2API 中转站搭建教程（小白版）

资料核对日期：2026-07-07
推荐路线：VPS/云服务器 + Ubuntu LTS + Docker Compose + Sub2API + Caddy HTTPS + 国内 DNS 解析

适用对象：刚进群、会复制命令但还不熟 Linux/Docker/域名解析的小白。
使用边界：本教程只讲“自有账号、授权账号、内部学习或自用管理”的自部署方法，不提供绕过地区限制、绕过风控、盗用账号、公开转售、规避上游服务条款的做法。

0. 先读这个：安全与合规提醒

Sub2API 是一个 AI API 网关平台，可以把上游账号或 API Key 接入后台，再由平台生成自己的 API Key 给客户端调用。它能做鉴权、用量统计、调度、并发控制等事情。

但是，中转站这个形态天然涉及上游服务商条款、账号安全、数据安全和运营合规。你一定要先记住几条：

1. 只接入你自己拥有或明确授权的上游账号/API Key。
2. 不要把管理后台、数据库、Redis、Docker socket 暴露到公网。
3. 不要把 .env、管理员密码、上游 refresh token、API Key 发到群里。

1. 最终架构长什么样

部署完成后，用户一般只接触三样东西：

2. 购买服务器

2.1 买什么配置

Sub2API 自带 Web 后台，还会跑 PostgreSQL 和 Redis，太小的机器容易卡。

购买服务器建议按这个顺序看：

阿里云和腾讯云活动经常变化，购买前重点看首购价、续费价、带宽、系统镜像和退款规则。

购买服务器时重点看这几个页面选项：

1. 选择系统镜像：Ubuntu 24.04 LTS。
2. 选择实例规格：2C2G 或 2C4G。
3. 添加 SSH Key：会用 SSH Key 的同学建议添加；不会的先用密码也可以，后面再换。
4. 安全组/防火墙：先放行 22、80、443。8080 只作为临时测试端口，不建议长期公网开放。
5. 选择节点：优先选海外节点。国内节点通常涉及备案、接入或过白等问题，不推荐小白一开始选择。

域名购买不用纠结平台，阿里云、腾讯云、雨云都可以提供相关服务。你选择相对便宜、续费价能接受、实名/备案流程自己能处理的平台即可。

不推荐服务器选择中国内地地域，会被帽子叔叔打电话。

3. 连接服务器

3.1 Windows 连接方法

Windows 10/11 一般已经有 OpenSSH Client。打开 PowerShell：

ssh root@你的服务器IP

第一次连接会问：

Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入：

yes

再输入服务器密码。注意：Linux 输入密码时屏幕不会显示星号，这是正常的。

如果提示 ssh 不是内部或外部命令，说明 OpenSSH Client 没装好，可以在 Windows “可选功能”里安装 OpenSSH Client。

3.2 macOS / Linux 连接方法

打开终端：

ssh root@你的服务器IP

3.3 登录后先更新系统

下面命令默认你是 root。如果你用的是普通用户，请在命令前加 sudo。

apt update
apt upgrade -y
apt install -y curl wget git nano ca-certificates gnupg lsb-release ufw
timedatectl set-timezone Asia/Shanghai
hostnamectl set-hostname sub2api-01

检查：

date
hostname

4. 基础安全设置

4.1 创建普通管理用户（推荐）

你为了省事可以全程用 root，但长期运维建议创建一个普通用户：

adduser deploy
usermod -aG sudo deploy

测试：

su - deploy
sudo whoami

看到 root 就说明 sudo 正常。

4.2 配置 UFW 防火墙

先放行 SSH，再启用防火墙。不要顺序反了。

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

如果你想临时用 http://服务器IP:8080 访问 Sub2API，建议只放行自己的公网 IP：

curl -4 ifconfig.me
ufw allow from 你的本地公网IP to any port 8080 proto tcp

用完临时测试后删除这条规则，或者直接不开放 8080，走 Caddy 的 80/443。

ufw status numbered
ufw delete 规则编号

重要提醒：

Docker 端口映射可能绕过部分 UFW 规则，所以正式部署时建议把 Sub2API 绑定到 127.0.0.1:8080，让公网只能访问 Caddy。

5. 安装 Docker 和 Docker Compose

Docker 官方推荐在 Ubuntu 上使用 apt 仓库安装。执行：

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  apt-get remove -y "$pkg" 2>/dev/null || true
done

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

tee /etc/apt/sources.list.d/docker.sources <<EOF
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

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 hello-world

如果 hello-world 能打印欢迎信息，Docker 就正常了。

6. 部署 Sub2API

6.1 推荐：一键准备 Docker Compose 文件

创建部署目录：

mkdir -p /opt/sub2api-deploy
cd /opt/sub2api-deploy

运行官方准备脚本：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

这个脚本会做几件事：

1. 下载 Docker Compose 文件。
2. 下载 .env.example。
3. 生成 .env。
4. 自动生成 POSTGRES_PASSWORD、JWT_SECRET、TOTP_ENCRYPTION_KEY。
5. 创建 data/、postgres_data/、redis_data/ 三个数据目录。

脚本当前会把本地目录版 compose 保存为 docker-compose.yml。有些官方文档会写 docker-compose.local.yml，这是文件命名差异。你照这个判断：

ls -la

如果你看到 docker-compose.yml，后续用：

docker compose up -d

如果你是手动 clone 仓库并且看到 docker-compose.local.yml，后续用：

docker compose -f docker-compose.local.yml up -d

6.2 首次启动前编辑 .env

打开配置：

nano .env

你至少检查这些项：

下面只是示例，不要整段复制覆盖你的 .env。保留脚本已经生成的随机密钥，只改你明确知道用途的字段。

# 临时用 IP:8080 测试时可先用 0.0.0.0
# 正式域名 + Caddy 后建议改成 127.0.0.1
BIND_HOST=0.0.0.0

SERVER_PORT=8080
TZ=Asia/Shanghai

# 第一次启动前设置管理员账号，避免去日志里翻随机密码
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=replace_with_a_long_random_password

# 脚本已经自动生成，确认不是空即可
POSTGRES_PASSWORD=keep_the_random_value_generated_by_script
JWT_SECRET=keep_the_random_value_generated_by_script
TOTP_ENCRYPTION_KEY=keep_the_random_value_generated_by_script

# 默认完整模式
RUN_MODE=standard

nano 保存方式：

1. 按 Ctrl + O
2. 回车
3. 按 Ctrl + X

说明：

6.3 启动

cd /opt/sub2api-deploy
docker compose up -d
docker compose ps

看日志：

docker compose logs -f sub2api

看到服务启动、数据库迁移、监听 8080 等信息基本就正常。另开一个 SSH 窗口测试健康检查：

curl http://127.0.0.1:8080/health

正常会返回：

{"status":"ok"}

如果你临时开放了 8080，可以在浏览器访问：

http://服务器IP:8080

截图位 4：docker compose ps 输出，圈出 sub2api、postgres、redis 都是 running/healthy。
截图位 5：浏览器打开 http://服务器IP:8080 的登录页或首页。

7. 配置域名和 HTTPS

生产环境建议用域名访问，不要长期用 IP:8080。

7.1 域名解析

你可以直接使用阿里云云解析 DNS，也可以用腾讯云 DNSPod 或雨云自带解析。字段名字可能不同，但核心就是添加一条 A 记录：

访问域名会是：

https://api.example.com

如果你的域名不是在当前 DNS 服务商购买的，需要先按控制台提示把域名的 DNS 服务器切到当前服务商，或者把域名添加到该服务商的解析控制台。阿里云、腾讯云、雨云都能做域名购买和解析，选相对便宜、续费价可接受的平台即可。

保存解析后等待生效。国内 DNS 有时几分钟内生效，有时会更久。可以在本机测试：

nslookup api.example.com

看到返回你的服务器公网 IPv4 后，再继续配置 Caddy。

7.2 安装 Caddy

apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install -y caddy
systemctl status caddy --no-pager

7.3 写 Caddyfile

编辑：

nano /etc/caddy/Caddyfile

替换成：

api.example.com {
    encode zstd gzip

    reverse_proxy 127.0.0.1:8080 {
        transport http {
            versions h2c 1.1
        }
    }

    header {
        -Server
    }
}

把 api.example.com 换成你的真实域名。

检查并重载：

caddy fmt --overwrite /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
systemctl status caddy --no-pager

测试：

curl -I https://api.example.com/health

浏览器打开：

https://api.example.com

确认 HTTPS 可用后，把 Sub2API 改成只监听本机：

cd /opt/sub2api-deploy
sed -i 's/^BIND_HOST=.*/BIND_HOST=127.0.0.1/' .env
docker compose up -d
curl http://127.0.0.1:8080/health

再确认服务器没有公网监听 8080：

ss -lntp | grep 8080

如果看到 127.0.0.1:8080，就是对的。不要看到 0.0.0.0:8080。

8. 第一次进入 Sub2API 后台

打开：

https://api.example.com

用 .env 里的管理员邮箱和密码登录。

第一次进去建议按这个顺序做：

8.1 先做安全设置

在后台里先找这些入口：

1. 个人资料/账户设置：修改管理员密码。
2. 2FA/双因素认证：建议开启。
3. 系统设置：确认站点名、注册开关、邮件设置、公告、文档链接。
4. 合规提示：如果后台要求确认协议，先认真读完再确认。

小白建议：

9. 后台核心配置：分组、账号、用户、Key

9.1 先理解 4 个概念

顺序不要反：

创建分组 -> 接入上游账号 -> 账号绑定分组 -> 创建用户 -> 用户生成 API Key -> 客户端调用

9.2 创建分组

后台路径通常是：

管理员后台 -> 分组管理 / Group Management

建议至少按平台分开：

建议先设置保守的并发和 RPM：

注意：Anthropic Claude 和 Antigravity Claude 不建议混在同一上下文里使用。按分组隔离，少出奇怪问题。

9.3 接入上游账号

后台路径通常是：

管理员后台 -> 账号管理 / Account Management -> 新增账号

常见类型：

每加一个账号后都做三件事：

1. 点击测试/检测账号是否可用。
2. 绑定到正确分组。
3. 给账号起能看懂的名字，比如 openai-main-01、gemini-aistudio-01。

如果 OAuth 会跳到浏览器授权，有些流程会回调到本地地址，例如 http://localhost:1455/auth/callback?...。这时按后台提示，把完整 callback URL 或 code 复制回后台即可。

9.4 创建用户

后台路径通常是：

管理员后台 -> 用户管理 / User Management

小群建议管理员手动创建用户：

9.5 用户生成 API Key

用户登录后，一般到：

用户控制台 -> API Keys / 密钥

创建 Key 时注意：

1. 选择正确分组。
2. 名字写清楚，例如 lingyu-laptop-codex。
3. 生成后只显示一次就立刻保存到自己的密码管理器。
4. 不要截图发群，不要写进公开仓库。

截图位 9：分组管理页，圈出平台和并发/RPM。
截图位 10：账号管理页，圈出账号测试按钮。
截图位 11：用户管理页，圈出可用分组。
截图位 12：用户 API Key 页面，遮住 Key 后圈出分组和创建按钮。

10. 客户端怎么填地址

下面假设你的域名是：

https://api.example.com

你的 Key 是：

sk-xxxxxxxx

10.1 常见 Base URL 表

不同客户端对 Base URL 的拼接规则不完全一样：

1. 如果客户端会自动拼 /v1/chat/completions，Base URL 填 https://api.example.com/v1。
2. 如果客户端会自动拼 /v1/messages，Base URL 填 https://api.example.com。
3. 如果客户端要求填完整 endpoint，就把上面表格里的路径和具体接口拼完整。
4. 优先看 Sub2API 后台或用户页生成的接入说明。

10.2 curl 测试 OpenAI 兼容接口

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

Chat Completions 测试：

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

10.3 curl 测试 Claude/Anthropic 兼容接口

curl https://api.example.com/v1/messages \
  -H "x-api-key: sk-xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

10.4 curl 测试 Gemini 接口

curl https://api.example.com/v1beta/models \
  -H "x-goog-api-key: sk-xxxxxxxx"

10.5 Claude Code 示例

普通 Anthropic/Claude 兼容入口：

export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"

Antigravity 专用入口：

export ANTHROPIC_BASE_URL="https://api.example.com/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"

如果客户端要求 ANTHROPIC_API_KEY 而不是 ANTHROPIC_AUTH_TOKEN，就按客户端文档改成对应变量。

11. 日常维护命令

所有命令默认在：

cd /opt/sub2api-deploy

11.1 查看状态

docker compose ps
docker compose logs --tail=200 sub2api
docker compose logs -f sub2api

11.2 重启

docker compose restart sub2api

重启全部：

docker compose restart

11.3 更新

先备份，再更新：

cd /opt/sub2api-deploy
docker compose pull
docker compose up -d
docker image prune -f
docker compose ps

如果更新后异常，先看日志：

docker compose logs --tail=300 sub2api

11.4 备份

最稳的新手备份方式：短暂停机，打包整个目录。

cd /opt/sub2api-deploy
docker compose down
cd /opt
tar czf "sub2api-deploy-backup-$(date +%F-%H%M).tgz" sub2api-deploy
cd /opt/sub2api-deploy
docker compose up -d

在线数据库备份：

cd /opt/sub2api-deploy
set -a
. ./.env
set +a
docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" | gzip > "sub2api-db-$(date +%F-%H%M).sql.gz"

建议至少备份：

1. .env
2. data/
3. postgres_data/ 或 SQL dump
4. redis_data/

11.5 迁移到新服务器

旧服务器：

cd /opt/sub2api-deploy
docker compose down
cd /opt
tar czf sub2api-complete.tar.gz sub2api-deploy
scp sub2api-complete.tar.gz root@新服务器IP:/opt/

新服务器：

cd /opt
tar xzf sub2api-complete.tar.gz
cd /opt/sub2api-deploy
docker compose up -d
docker compose ps

域名切换：

1. 在阿里云 DNS / DNSPod / 雨云 DNS 里把 A 记录改到新服务器 IP。
2. 等解析生效。
3. 浏览器访问 https://api.example.com/health。

12. 故障排查

12.1 SSH 连不上

检查：

1. IP 是否复制错。
2. 服务器是否开机。
3. 云厂商安全组是否放行 22。
4. 本地网络是否屏蔽 SSH。
5. 防火墙是否误删了 SSH 规则。

如果还能从云厂商控制台进 VNC/救援模式，执行：

ufw allow OpenSSH
ufw reload
systemctl status ssh --no-pager

12.2 Docker 启动失败

systemctl status docker --no-pager
journalctl -u docker -n 100 --no-pager
docker info

常见原因：

12.3 Sub2API 访问不了

先看容器：

cd /opt/sub2api-deploy
docker compose ps
docker compose logs --tail=200 sub2api
curl http://127.0.0.1:8080/health

再看端口：

ss -lntp | grep 8080

12.4 Caddy 证书申请失败

检查：

systemctl status caddy --no-pager
journalctl -u caddy -n 100 --no-pager
curl -I http://api.example.com

常见原因：

1. DNS 还没解析到服务器。
2. 80/443 没放行。
3. A 记录填错了，或者域名的 DNS 服务器还没有切到当前解析服务商。
4. Caddyfile 域名写错。

12.5 后台登录失败

如果你没有设置 ADMIN_PASSWORD，首次随机密码可在日志里找：

cd /opt/sub2api-deploy
docker compose logs sub2api | grep -i "admin password"

如果已经改过密码但忘了，不要随便删数据库。先备份，再查项目最新重置方式或在群内让有经验的人协助。

12.6 上游账号测试失败

排查顺序：

1. 上游账号/API Key 是否有效。
2. 账号是否绑定到正确分组。
3. API Key 使用的分组平台是否匹配，例如 Gemini Key 不要拿去请求 Claude 分组。
4. 上游是否有额度、并发、地区、服务条款限制。
5. 后台账号测试日志和 docker compose logs -f sub2api 有没有具体错误。

不要用代理、住宅 IP、批量账号等方式去规避上游限制。本教程不覆盖这类做法。

13. 小白验收清单

部署完按这个表打勾：

14. 给群公告用的精简版

可以把下面这段贴到群公告：

使用规则：
1. API Key 只限本人使用，不要外传、不要公开到 GitHub。
2. 禁止高并发压测，禁止批量滥用，禁止绕过上游服务条款。
3. 客户端地址：
   - OpenAI 兼容：https://api.example.com/v1
   - Claude 兼容：https://api.example.com
   - Gemini：https://api.example.com/v1beta
4. 出问题先发：时间、客户端、模型、错误截图、请求 ID（如有），不要发完整 API Key。
5. 管理员会根据上游额度和稳定性调整并发/RPM。

资料来源

1. Sub2API GitHub 仓库
2. Sub2API 中文 README
3. Sub2API 部署文档
4. Sub2API Docker 镜像页
5. Docker Ubuntu 安装文档
6. Caddy 安装文档
7. Caddy 自动 HTTPS 文档
8. Caddy 反向代理快速开始
9. 阿里云云解析 DNS A 记录文档
10. 腾讯云 DNSPod 快速添加解析文档
11. 雨云添加解析文档
12. 雨云域名服务文档
13. 雨云链接
14. 阿里云轻量应用服务器入口
15. 腾讯云活动入口
16. Ubuntu UFW 文档
17. Microsoft OpenSSH for Windows 文档