生命不息，折腾不止。这篇记录一下 Sub2API 的完整部署过程，包括 Docker Compose 部署、反向代理、HTTPS 证书等实战经验。

这是什么

Sub2API 是一个开源的 AI API 网关中转项目（GitHub 上 37k+ stars），核心功能是：

  • 一个订阅，全家共享：把 Claude、ChatGPT、Gemini、Grok 等官方订阅接入进来，按配额分配给多个用户/工具使用，也就是俗称的”拼车”
  • 原生工具无缝使用：接入后，Claude Code、Codex、Gemini CLI 等原生工具可以直接指向自己的服务地址，体验和官方几乎一致
  • 自带管理后台：账号管理、配额分配、用量统计，还内置了支付系统（易支付 / 支付宝 / 微信 / Stripe），开箱即用

简单说：订阅是”一个包月账号”，Sub2API 把它变成”一个 API 服务”，谁都能用。

技术栈：Go 后端 + Vue 前端管理面板 + PostgreSQL + Redis，Docker 一键部署。

架构一览

Sub2API 部署架构

整个链路分三块：

部分 说明
订阅源 Claude Pro / ChatGPT Plus / Gemini / Grok 等官方订阅
Sub2API 网关 核心服务（配额分配 + API 中转 + 管理后台），搭配 PostgreSQL（数据）和 Redis（缓存/队列）
使用端 Claude Code、Codex、Gemini CLI、任意 OpenAI 兼容客户端

部署步骤

前置条件

  • 一台 Linux 服务器（本教程用 Docker 方式，不需要会编程）
  • Docker 20.10+ 和 Docker Compose v2+

方式一：官方一键脚本（最省事）

1
2
3
4
5
6
7
8
# 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 下载并运行部署准备脚本（自动生成密钥、下载 compose 模板）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 启动
docker compose up -d

脚本会自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等安全凭证并写入 .env，记得保存好输出的凭证。

方式二：手动部署（可控性更强）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 1. 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. 复制环境变量模板
cp .env.example .env
chmod 600 .env

# 3. 生成安全密钥
openssl rand -hex 32   # 用作 JWT_SECRET
openssl rand -hex 32   # 用作 TOTP_ENCRYPTION_KEY
openssl rand -hex 32   # 用作 POSTGRES_PASSWORD

# 4. 编辑 .env，至少填这几项
# POSTGRES_PASSWORD=上面生成的
# JWT_SECRET=上面生成的
# TOTP_ENCRYPTION_KEY=上面生成的
# ADMIN_EMAIL=admin@example.com
# ADMIN_PASSWORD=你的管理员密码

# 5. 创建数据目录并启动
mkdir -p data postgres_data redis_data
docker compose up -d

# 6. 查看状态和日志
docker compose ps
docker compose logs -f sub2api

两种 Compose 模板怎么选

模板 数据存储 迁移便利性 适用场景
docker-compose.local.yml 本地目录 ✅ 打包整个目录即可 生产环境、频繁备份
docker-compose.yml Docker 命名卷 ⚠️ 需要 docker 命令 简单体验

推荐用 docker-compose.local.yml（数据在本地目录，备份迁移都方便）。

初始管理员

如果是手动部署，首次启动后管理员账号密码会在日志里输出：

1
docker compose logs sub2api | grep "admin password"

用日志里的账号登录管理后台，首次登录会强制要求修改密码。之后就可以在后台添加订阅、创建用户、分配配额了。

反向代理 + HTTPS（实战经验）

服务默认监听 8080 端口。安全第一：不要让 8080 直接暴露公网，建议：

  1. 只绑定本机回环地址（.env 里 BIND_HOST=127.0.0.1），对外只开放 80/443
  2. 用 Nginx / OpenResty 做反向代理
  3. 套一层 HTTPS 证书

我的部署是：Cloudflare 灰云解析 → OpenResty 反向代理 → 127.0.0.1:8080，证书用 Let’s Encrypt（acme.sh 自动续期，到期前自动换新），HTTP 访问自动 301 跳转 HTTPS。

关键配置参考：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
server {
    listen 80;
    server_name sub-api.example.com;
    return 301 https://$host$request_uri;
}

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}

小坑提醒：如果 Nginx/OpenResty 跑在 Docker 容器里，证书路径必须是挂载进容器的目录，容器内看不到宿主机其他路径的证书文件。

升级与维护

1
2
3
4
5
6
7
8
# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

# 重启
docker compose restart

也可以直接在**管理后台左上角点”检测更新”**在线升级（支持一键更新和回滚）。

日常维护就三件事：备份数据目录、定期升级、看日志。

注意事项

  • ⚠️ 上游条款风险：该项目官方声明，使用它可能违反 Anthropic 等上游服务商的用户协议，账号风险自行承担，请确认合规后再使用
  • 📖 项目仅供技术学习与研究，作者不对账号封禁、服务中断、数据丢失等损失负责
  • 🚫 未经授权，请勿用本项目从事商业运营

参考