备份、轮换与恢复

完整恢复需要同时保有 bootstrap 身份与根、PostgreSQL 权威数据、S3 对象字节。单独导出密钥或仅备份数据库都不够。

先建立可恢复的备份

固定当前清单、应用镜像与数据库版本。
为 PG 建立一致备份，为 S3 保存对象字节。
保护 bootstrap 目录，并显式备份 keyring。
在隔离实例演练恢复，检查同一个 instanceId、受限 SK、节点、对象内容和 Mailbox。

tb setup status
tb maintenance status
tb keys status
tb keys backup --out ./tool-bridge-keys.json

keys backup 新建权限为 0600 的文件，不覆盖旧文件。它包含加密、签名和 OAuth 根，不是 PG/S3 备份，也不产生新的 Admin SK；妥善离线保存。

网关仓库另有 scripts/compose-backup.mjs 与 scripts/compose-restore.mjs，仅针对默认单副本 Compose 的完整卷快照。它们会停服务、校验精确镜像身份并恢复原运行状态；恢复目标必须是显式隔离项目。外部数据库、自定义 S3、Redis 和 Railway 平台备份不在这套脚本范围内，执行前阅读对应版本脚本说明。

数据库与 Redis 使用专项维护

tb maintenance status
tb maintenance database --help
tb maintenance rotate-database-credentials --help
tb maintenance redis --help

数据库迁移使用官方 pg_dump / pg_restore，目标必须是不同的空 PG 数据库。流程校验实例身份、排空工作、复制并切换受保护指针，持久屏障保证旧库不会重新成为可写权威。连接串只通过文件或 stdin 输入。

数据库凭证轮换需要独立管理员连接，用新登录验证连接后再退役旧登录。Redis 切换会验证读写和 pub/sub，并可能要求设备重连；Redis 不持有 operation 或权限的唯一状态。

维护要求其他副本先正常排空并退出。心跳过期不能证明工作已停止；崩溃残留或持久屏障需要本机离线协调，不要删行或等待 TTL 猜测解锁。

轮换加密根和签名根

tb keys status
tb keys rotate --target encryption --revision <keyring-revision>
tb keys resume <job-id>

加密轮换会持久保存新根，再分批重加密 SecretStore 与 Mailbox；中断可 resume。旧根仍被引用时不能 retire，任务完成应以状态与引用复核为准。

tb keys rotate --target signing --revision <keyring-revision>

签名轮换默认保留旧 token 的有效窗口。--revoke-existing 会立即使既有授权失效，影响在途上传、call、share 和旧 ref；只有明确需要撤销这些授权时才选择它。

实例进入恢复态

PG 不可达或 bootstrap 不完整时，已初始化实例会进入恢复态。先修复连接与持久文件，不重新初始化空库。

在部署主机创建独立 recovery token：

docker compose -f deploy/compose/docker-compose.yml exec app \
  node /app/dist/admin.js recover

通过 Dashboard 恢复页，或 tb setup recover --help 指引的文件输入恢复同实例连接与必要的 key backup。身份不匹配、空库或替代根不能绕过原实例保护。

数据库复制、指针切换或回滚出现“可能已提交但确认丢失”时，保留现场并停止盲目重试，先确认唯一可写权威。恢复成功后仍需实际读取业务记录和对象字节。