备份与恢复 | SubLane

备份内容与保存

完整归档包含 sublane.db、匹配的 credentials.key 和记录版本、大小、SHA-256 校验和的 manifest.json。数据库快照包含已提交的 WAL 数据，覆盖用户、密钥、账号、权限、设置、请求与用量。

归档包含解密密钥，且没有密码加密。 持有完整归档的人可以恢复其中的凭据。保存在私有位置，需要时使用加密存储。校验和检测损坏，不能证明来源可信。

部署文件、环境变量、浏览器本地偏好与尚未完成的 OAuth 尝试不在归档中。恢复会清除浏览器会话，用户必须重新登录。

命令行备份

在有足够空间的目录执行：

创建与校验备份

mkdir -p backups
./bin/sublane backup --output ./backups/team.sublane-backup.tar.gz
./bin/sublane backup verify --input ./backups/team.sublane-backup.tar.gz

默认读取 SUBLANE_DATA_DIR 或 ./data，也可使用 --data-dir 指定。已有归档不会被覆盖。CLI 数据库快照上限为 4 GiB，校验和恢复还需要解压与迁移空间。维护命令不会启动 HTTP 服务或供应商执行器。

恢复流程

恢复目标必须是尚不存在的新目录，即使已有空目录也会被拒绝；父目录必须存在。

恢复到独立目录

./bin/sublane restore --input ./backups/team.sublane-backup.tar.gz --data-dir ./data-restored

恢复成功不代表运行实例已切换。停止原服务、保留原目录，再使用新目录启动：

启用恢复后的数据

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

重新登录并检查成员、组、密钥与订阅账号，再恢复团队流量。回滚时停止服务并切回原目录，不要让两个进程同时使用同一数据库。恢复会回到快照时刻，之后的撤销和密码修改不再存在；上游可能已废弃旧刷新令牌，必要时重新授权。

网页操作

管理员进入「系统设置 → 备份与恢复」。可在线下载归档、上传校验，或「准备恢复」到当前数据目录下的 restore-ready。准备完成后仍需运维人员停止服务并切换目录。

网页压缩文件上限 256 MiB，更大归档使用 CLI。同一实例一次只处理一个网页维护操作。已有 restore-ready 会阻止再次准备，不会覆盖。检查该目录后再决定下一步，或用 CLI 指定其他新目录。

Docker Compose

容器内导出并复制归档

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec sublane sublane backup --output /data/backups/team.sublane-backup.tar.gz
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz ./team.sublane-backup.tar.gz

恢复归档放入容器可访问的私有目录后执行：

容器内准备恢复

docker compose -f docker.compose.yaml exec sublane sublane restore --input /data/backups/team.sublane-backup.tar.gz --data-dir /data/restore-ready

创建 docker.compose.restore.yaml：

恢复目录的 Compose 覆盖配置

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

停止服务并切换数据目录

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

后续部署保持使用覆盖配置，勿删除命名数据卷。容器已停止时，可用 docker compose -f docker.compose.yaml run --rm --no-deps sublane ... 执行维护命令。

校验边界

校验检查归档条目、大小、摘要、gzip 完整性、迁移历史、SQLite 完整性与外键，并验证凭据解密。路径穿越、符号链接、重复条目、缺失文件及未知未来数据库版本会被拒绝。旧结构只在临时副本中迁移，不修改当前运行数据库，也不联系供应商验证账号。