部署前准备与容量规划

先规划域名、数据、密钥和容量，再执行安装命令。很多“部署后不稳定”其实是部署前没有确认依赖边界。

必需组件

组件	必需	建议
Sub2API	是	使用固定版本镜像或 Release
PostgreSQL	是	15+，生产使用 SSD 与自动备份
Redis	是	7+，启用认证和持久化
反向代理	生产必需	Caddy/Nginx/云 LB，支持 SSE/WS
域名与 TLS	生产必需	自动续期，API 独立域名
SMTP	可选	注册验证、找回密码、告警与通知
对象存储	部分功能	批量图片、备份或大文件
datamanagementd	可选	宿主机数据管理能力

推荐机器规格

下面只是起点，真实容量由并发、长连接、日志和账号池决定。

场景	应用	PostgreSQL	Redis
个人/测试	2 vCPU / 2–4 GB	可同机	可同机
小团队	4 vCPU / 8 GB	2–4 vCPU / 8 GB	1–2 GB
公开运营	4–8+ vCPU / 8–16 GB，多副本	独立或托管，主从/备份	独立或托管，高可用

AI 流量的带宽通常不大，但长连接多、单请求持续时间长。图片输入输出会显著增加带宽与内存。

文件描述符

每个 SSE/WS、上游连接、数据库连接、日志文件都会消耗 fd。Docker Compose 已提高 nofile，systemd 部署也应确认：

ulimit -n
systemctl show sub2api -p LimitNOFILE

高并发时应用、Nginx/Caddy 和 Redis 都要调整，不只是应用进程。

数据库连接预算

估算：

应用总连接上限
  = Sub2API 副本数 × DATABASE_MAX_OPEN_CONNS
  + 运维/迁移/备份连接
  + 其他共享应用连接

PostgreSQL max_connections 必须大于总和并留 20% 左右余量。连接数不是越大越好，过多会增加内存与上下文切换。

初次生产部署可以从每实例 50–100 个 max open connections 开始，再根据等待时间和数据库负载调整。

Redis 连接预算

Redis pool 同样按副本累加。默认 pool 可能很大，小规格 Redis 或托管实例有连接数限制时，应降低：

REDIS_POOL_SIZE=256
REDIS_MIN_IDLE_CONNS=16

观察连接等待、timeout 和 Redis CPU，再扩容。

磁盘规划

主要增长来源：

• PostgreSQL usage_logs、错误日志、运维指标和索引。
• PostgreSQL WAL 和临时文件。
• 应用滚动日志。
• Redis AOF/RDB。
• 数据库备份。
• 批量图片输入输出。

不要把在线数据库、日志和所有备份放在同一块小磁盘。至少监控 70%、80%、90% 三档使用率。

网络准备

入站

• 80/443：公网或 CDN。
• SSH：只允许管理网段。
• 8080：仅反向代理/本机。
• 5432/6379：仅应用网段。

出站

应用需要访问：

• 配置的 AI 上游域名。
• OAuth token/userinfo endpoint。
• 支付平台。
• SMTP。
• GitHub Release 与定价文件。
• 代理服务器和对象存储。

有企业防火墙时，应先列 allowlist，不要上线后临时开放全部出站。

域名规划

推荐使用独立 API 域名，例如：

api.example.com

管理后台和模型 API 默认同域。OAuth、支付和邮件链接都要使用最终 HTTPS 域名，不要先用 IP 上线再临时切换。

密钥清单

部署前生成并保存：

openssl rand -hex 32  # POSTGRES_PASSWORD
openssl rand -hex 32  # JWT_SECRET
openssl rand -hex 32  # TOTP_ENCRYPTION_KEY
openssl rand -hex 32  # REDIS_PASSWORD（如自建）

还可能需要：

• OAuth client secrets。
• SMTP password。
• 支付签名密钥与 webhook secret。
• S3/对象存储 key。
• Sora media signing key。

使用密码管理器或 secret manager 保存，不要只留在服务器 .env。

时间与时区

时区影响：

• 日/周/月配额窗口。
• 高峰倍率。
• 订阅到期。
• 日报、聚合和日志。

所有应用副本保持同一个 TZ，PostgreSQL 使用兼容设置，服务器启用 NTP。

上线前信息表

建议先填完：

项目	你的值
外部域名
应用版本
PostgreSQL 地址/备份策略
Redis 地址/持久化策略
数据目录
时区
上游域名与代理
管理员邮箱
告警接收人
回退负责人

完成后进入选择部署方式。