选择部署方式

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 幂等与对账。
尚未确认上游条款和运营合规边界。