升级、备份与迁移
Sub2API 会在启动时执行向前数据库迁移。任何升级都应先备份，再更新应用，最后验证网关和计费数据。
Docker 升级
bash
cd /path/to/sub2api-deploy
# 先备份，再升级
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 sub2api
curl -fsS http://127.0.0.1:8080/health生产环境建议固定具体版本镜像，而不是长期使用 latest：
yaml
services:
sub2api:
image: weishaw/sub2api:0.1.149确认新版本稳定后再更新固定版本号。
二进制升级
bash
sudo /opt/sub2api/install.sh upgrade
sudo systemctl status sub2api
sudo journalctl -u sub2api -n 200 --no-pager也可以通过管理后台执行在线升级。无论入口是什么，升级前都要独立备份数据库。
数据库迁移与回退
迁移文件按文件名顺序执行，并记录到 schema_migrations。它们是向前迁移，不提供自动 down migration。
这意味着：
- 回退应用二进制不等于回退数据库。
- 新数据库结构未必兼容旧程序。
- 正式升级前必须验证数据库备份可以恢复。
- 大版本或高风险迁移应先在备份副本上演练。
PostgreSQL 逻辑备份
本地目录版 Compose 示例：
bash
mkdir -p backups
docker compose exec -T postgres \
pg_dump -U sub2api -d sub2api -Fc \
> "backups/sub2api-$(date +%F-%H%M%S).dump"检查文件不是空文件：
bash
ls -lh backups/恢复操作会覆盖数据，不要直接在生产库上试命令。应定期把备份恢复到隔离 PostgreSQL 实例，并运行登录、账号查询和用量查询作为验收。
完整停机备份
使用本地目录版 Compose 时，可以得到包含配置和数据目录的一致快照：
bash
cd /path/to/sub2api-deploy
docker compose down
cd ..
tar czf "sub2api-complete-$(date +%F-%H%M%S).tar.gz" sub2api-deploy/
cd sub2api-deploy
docker compose up -d停机期间不会产生新请求、异步用量或 Redis 队列变化，因此比在线直接复制数据库目录更安全。
不要在线复制 PostgreSQL 数据目录
PostgreSQL 正在运行时直接 cp -r postgres_data 不能保证得到可恢复的一致备份。使用 pg_dump、文件系统快照或在停机状态下复制。
迁移到新服务器
本地目录版：
bash
# 旧服务器
cd /path/to/sub2api-deploy
docker compose down
cd ..
tar czf sub2api-migration.tar.gz sub2api-deploy/
scp sub2api-migration.tar.gz user@new-server:/srv/bash
# 新服务器
cd /srv
tar xzf sub2api-migration.tar.gz
cd sub2api-deploy
docker compose up -d
docker compose ps切换 DNS 前验证：
.env中的固定密钥未变化。- 容器健康检查通过。
- 管理员可以登录。
- API Key、账号、余额和用量存在。
- 上游网络出口和代理符合预期。
建议保留周期
一个实用的起点：
| 备份 | 周期 | 保留 |
|---|---|---|
| PostgreSQL 逻辑备份 | 每日 | 7～30 天 |
| 升级前备份 | 每次发布 | 至少保留两个稳定版本周期 |
| 完整停机快照 | 每周或重大变更前 | 4～8 份 |
| 异地备份 | 每日同步 | 至少一个独立账号或区域 |
备份文件包含用户信息、上游凭证和业务数据，必须加密存储并限制访问。