Sub2API 101

Appearance

中国与亚太部署方案速览 ​

更新时间：2026-07-18。本页是执行入口：先给出可以直接照做的决策与命令，细节全部链接到两篇深度文档——分阶段方案与云厂商调研。

整体拓扑：四个部署单元 ​

当前业务由四个部署单元组成。C 端门户是独立仓库（sub2api-frontend，产品名 OneSeat），跑在 Cloudflare Workers 上；管理后台是 Sub2API 内置前端，跟着 Go 进程走，不需要单独部署。

组件载体说明
OneSeat C 端前端Cloudflare Workers（React Router SSR，绑定 oneseatai.com/*）Worker 同时把 /api/v1/* 反代到 Sub2API 源站，浏览器只用相对路径、无 CORS
Sub2API 应用Docker 容器（镜像 weishaw/sub2api）API 网关 + 内置管理后台，8080 端口
PostgreSQL 15+第一阶段同机容器 → 第二阶段云托管 HA事实来源：用户、Key、余额、订单、用量
Redis第一阶段同机容器 → 第二阶段云托管标准主从并发槽位、限流、锁、队列，不是可清空缓存
text
用户浏览器 ─ oneseatai.com ──> CF Worker（SSR + /api/v1/* 反代）──┐
SDK / CLI ─ api.oneseatai.com ───────（直连，不经过 Worker）──────┼─> Sub2API :8080 ─> PostgreSQL / Redis
管理员 ──── Sub2API 源站域名（内置管理后台，加 IP/VPN 限制）──────┘

本页下文说的「服务器部署」指的是 Sub2API + PostgreSQL + Redis 这三件；前端的部署与切换见下一节。

C 端前端（Cloudflare Workers）怎么部署 ​

  • 部署命令：在 sub2api-frontend 仓库执行 npm run deploy（= build + wrangler deploy）。
  • Worker 反代的上游由 wrangler.jsonc → vars.SUB2API_ORIGIN 控制，当前指向测试环境（https://testsub.zeabur.app）。生产切换 = 把 SUB2API_ORIGIN 改成生产 Sub2API 域名后重新 deploy，业务代码不动。
  • 网关 API 流量（api.oneseatai.com/v1）应直连 Sub2API 源站，不要走 Worker 反代——SSE/WS 长流多一跳加延迟，还受 Worker CPU/连接限制。
  • 大陆访问注意：*.workers.dev 在大陆基本不可用；自定义域名走 Cloudflare 全球网络在大陆可达，但质量随运营商和时段波动。如果大陆成为核心市场且已备案，备选方案是把 SSR 前端用 react-router-serve 打成 Node 容器搬到大陆源站同机部署（Cloudflare 中国网络需企业版 + 备案，不作为默认方案）。
  • 管理后台不在这个仓库里，直接访问 Sub2API 源站域名，并按生产安全加固加 IP/VPN/零信任限制。

先选路线（合规决定架构） ​

你的情况路线说明
主要用户在大陆，已有/可办 ICP 备案大陆 Region（广州/深圳或上海）入口延迟最低；域名解析到大陆服务器必须完成 ICP 备案
想尽快上线，还没备案中国香港免备案，大陆与 APAC 的折中；大陆访问质量随运营商/时段波动
东南亚用户为主新加坡国际链路稳定；不解决大陆低延迟，也不等于获得上游地区授权

云厂商默认选阿里云（大陆/香港/新加坡/东京全栈最完整），腾讯云同级备选（香港精品 BGP 值得实测）。不要跨云拼接核心数据层。详见云厂商调研 §1。

大陆 + APAC 双低延迟没有捷径

短期只能选一个数据主地域。不要让大陆应用远程连香港/新加坡的 PostgreSQL/Redis——Redis 里的并发槽位、锁和 Pub/Sub 对跨境 RTT 极度敏感。真正的双区域 active-active 需要数据分区与账务一致性改造，是独立研发项目。

分阶段架构 ​

阶段触发条件架构月成本量级（大陆）
一：0～100 用户验证期，可接受单机停服1 台 4C8G，docker-compose.local.yml 全家桶 + Caddy/Nginx300～900 元
二：100～500 用户已收费 / 峰值活跃流 >20～302 台 4C8G 跨可用区跑 docker-compose.standalone.yml，托管 PG HA + 托管 Redis 主从 + ALB/CLB1,800～4,500 元
三：500+ 用户收入关键 / 要求 99.9%+3+ 副本、蓝绿发布、PITR、第二地域冷/温灾备8,000～20,000+ 元

只要开始稳定收费，即使用户不到 100 也直接按第二阶段建设。 各阶段的规格、连接池参数、扩容阈值和压测验收标准见分阶段方案。

第一阶段部署命令 ​

在服务器上：

bash
mkdir -p /srv/sub2api && cd /srv/sub2api
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh
chmod +x docker-deploy.sh
./docker-deploy.sh          # 生成 .env（含随机密钥）、数据目录
docker compose up -d
docker compose logs sub2api | grep "admin password"   # 初始管理员密码

上线前的生产修订（不要跳过）：

  • 镜像固定具体版本号，禁止长期 latest。
  • .env 设 BIND_HOST=127.0.0.1，由宿主机 Caddy/Nginx 终止 HTTPS 后转发 8080；5432/6379 不暴露。
  • 保管好 .env 里的 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD——它们必须终身固定，丢失或变更会导致会话失效、2FA 全部作废。
  • 小机器收敛连接池：DATABASE_MAX_OPEN_CONNS=20、REDIS_POOL_SIZE=64（默认值偏大）。
  • 开启 URL allowlist，反向代理配置见反向代理与 HTTPS。

数据库迁移怎么做 ​

  • 应用启动时自动执行 backend/migrations/*.sql 向前迁移，按文件名顺序应用并记录到 schema_migrations（文件名 + 校验和）。升级 = 换镜像重启，迁移自动完成，无需手工跑 SQL。
  • 迁移是 forward-only，没有自动回滚。回退应用版本不等于回退库结构，因此每次升级前必须先 pg_dump。
  • 换服务器迁移（本地目录版）：docker compose down → tar 整个部署目录 → scp 到新机 → 解压 up -d。配置、密钥、数据一次带走。详见升级、备份与迁移。

备份怎么做 ​

备份周期保留命令/方式
PostgreSQL 逻辑备份每日7～30 天docker compose exec -T postgres pg_dump -U sub2api -d sub2api -Fc > backups/xxx.dump
升级前备份每次发布两个版本周期同上，发布流程第一步
完整停机快照每周4～8 份down 后 tar 整个目录，再 up -d
异地备份每日独立账号/区域的对象存储rclone/ossutil 同步，客户端加密

三条铁律：

  1. 不要在线 cp -r postgres_data——运行中的数据目录复制不保证一致性。
  2. 每月把最近备份恢复到隔离实例演练一次，验证登录、API Key、余额和历史用量；没恢复过的备份不算备份。
  3. 备份含用户信息与上游凭证，必须加密存储、最小权限。

第二阶段改用托管 PostgreSQL 后，开启自动备份 + PITR（7～30 天）+ 跨地域备份，逻辑备份降为兜底。

进入第二阶段时的已知坑 ​

  • 所有副本必须共享同一套 PG、Redis、JWT_SECRET、TOTP_ENCRYPTION_KEY 和时区，见多实例与高可用。
  • 当前 deploy/docker-compose.standalone.yml 没有透传 TOTP_ENCRYPTION_KEY，多副本上线前要在部署模板中自行补齐，否则每次启动随机生成会打断所有 2FA。
  • PostgreSQL 用直连主库地址（项目依赖会话级 advisory lock，不要默认接 transaction-mode PgBouncer）；Redis 选标准主从单分片，不要 Cluster。
  • LB 需支持 WebSocket/SSE，idle timeout ≥600 秒并开启 connection draining。

深入阅读 ​

本文档用于帮助你理解、部署和运维 Sub2API。使用前请确认上游服务条款与当地法律要求。

Sub2API Docs 101