选择部署方式
Sub2API 需要三个长期运行的组件：应用服务、PostgreSQL 和 Redis。区别只在于这些组件由 Docker、systemd 还是你现有的基础设施管理。
快速选择
| 你的情况 | 推荐方式 | 原因 |
|---|---|---|
| 第一次部署，希望简单可靠 | Docker Compose | 一次启动应用、PostgreSQL 和 Redis |
| 需要方便备份和整机迁移 | Docker Compose 本地目录版 | 数据都在部署目录下 |
| 已有托管 PostgreSQL 和 Redis | Linux 二进制 或 standalone Compose | 应用与数据服务解耦 |
| 需要修改代码或开发新功能 | 源码开发与构建 | 前后端调试方便，可构建自定义镜像 |
| 多副本、负载均衡、独立数据库 | 自定义容器编排 | 需要统一密钥、共享存储和容量规划 |
默认推荐
新部署优先使用仓库提供的 docker-deploy.sh。它下载本地目录版 Compose，自动生成关键密钥，并减少漏配持久化目录的风险。
推荐拓扑
text
Internet
│
▼
Caddy / Nginx / CDN
│ HTTPS、SSE、WebSocket
▼
Sub2API :8080
├── PostgreSQL
└── Redis生产环境只应把反向代理的 80/443 端口暴露到公网。PostgreSQL 和 Redis 应位于内网，应用端口也建议只允许反向代理访问。
最低依赖
Docker Compose
- Linux 主机。
- Docker Engine 20.10+。
- Docker Compose v2。
- 推荐至少 2 vCPU、4 GB 内存；实际规格取决于并发和用量数据规模。
二进制部署
- Linux amd64 或 arm64。
- Bash 4+。
- 可访问的 PostgreSQL 15+。
- 可访问的 Redis 7+。
- root 或 sudo 权限，用于安装 systemd 服务。
部署前准备
- 准备域名并将 DNS 指向服务器。
- 确定数据目录和备份位置。
- 生成固定的 JWT、TOTP 和数据库密钥。
- 确认上游 API 域名、代理和网络出口策略。
- 确认使用方式符合上游服务条款。
如果还没有估算数据库连接数、Redis、磁盘和长连接容量，先阅读部署前准备与容量规划。完整环境变量与 YAML 关系见配置方式与关键参数。
部署完成的判断标准
GET /health返回成功。- 管理员可以登录后台。
- PostgreSQL、Redis 均显示正常。
- 能创建分组、账号和用户 API Key。
- 测试请求可以完成并产生正确用量记录。
- HTTPS、SSE 和 WebSocket 不被反向代理缓冲或提前超时。
- 已完成一次可恢复的备份演练。
推荐的完整部署路径
单机 Docker
text
准备域名和机器
→ 容量规划
→ docker-deploy.sh
→ 固定密钥
→ 首次初始化
→ 创建账号/分组/测试 Key
→ Caddy/Nginx HTTPS
→ 安全加固
→ 备份恢复演练
→ 开放用户对应文档：
外部数据库或多实例
text
托管 PostgreSQL/Redis
→ standalone Compose 或二进制
→ 共享 Secret/Config
→ 多副本与 LB
→ leader lock/worker/连接池验证
→ 数据库和 Redis 故障演练额外阅读：
什么时候不要立即上线
以下任何一项成立，都应该先停在测试环境：
- 还没有固定
JWT_SECRET或TOTP_ENCRYPTION_KEY。 - PostgreSQL/Redis 暴露公网。
- 不知道数据库如何恢复。
- 只有一个未验证的上游账号。
- 流式请求在代理后一次性返回或频繁断流。
- 成功请求没有产生正确用量/扣费。
- 计划开放支付但未验证 webhook 幂等与对账。
- 尚未确认上游条款和运营合规边界。