备份和恢复 SlideStage Pro

SlideStage Pro 的生产数据同时包含数据库和 .stage 文件。备份时必须保存整个数据卷，而不是只复制 SQLite 文件。

数据在哪里

默认 Docker Compose 部署使用 slidestage-data volume。

其中包含：

• SQLite 数据库：用户、session、deck 元数据、邀请、笔记、批注。
• .stage blobs：/data/decks/<deckId>/<versionId>.stage。
• SQLite WAL/SHM 辅助文件。

备份前提

你需要能在服务器上运行 Docker 命令，并且位于 SlideStagePro 部署目录。

1. 检查服务状态

docker compose ps

确认 api 正在运行，并且健康检查正常：

curl http://localhost/api/health

2. Checkpoint SQLite WAL

先让 SQLite 把 WAL 内容合并回主数据库文件：

docker compose exec api sh -c \
  'cd /data && sqlite3 slidestage-pro.sqlite "PRAGMA wal_checkpoint(FULL);"'

如果镜像里没有 sqlite3，可以跳过这步，但恢复时要确保同时保存 -wal 和 -shm 文件。

3. 备份整个 volume

docker run --rm \
  -v slidestage-pro_slidestage-data:/data:ro \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/slidestage-backup-$(date +%F).tar.gz -C / data

把生成的 .tar.gz 复制到安全位置，例如对象存储、备份服务器或离线介质。

4. 验证备份文件

列出压缩包内容：

tar tzf slidestage-backup-YYYY-MM-DD.tar.gz | head

至少应看到：

data/
data/slidestage-pro.sqlite
data/decks/

5. 恢复前停止服务

恢复会替换数据卷内容。先停止服务：

docker compose down

6. 清空并恢复 volume

谨慎执行。确认你使用的是正确的备份文件。

docker run --rm \
  -v slidestage-pro_slidestage-data:/data \
  alpine sh -c 'rm -rf /data/*'

docker run --rm \
  -v slidestage-pro_slidestage-data:/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/slidestage-backup-YYYY-MM-DD.tar.gz -C /

如果压缩包内路径是 data/...，上面的命令会把它恢复到 volume 根目录。

7. 启动并验证

docker compose up -d
curl http://localhost/api/health

登录 Pro，检查：

• 用户能登录。
• deck 列表存在。
• .stage 可以打开。
• 笔记和批注存在。
• 管理员邀请记录符合预期。

备份频率建议

小团队可每天备份一次，并保留最近 7 到 30 天。

上传频繁或 deck 很重要时，建议：

• 每天自动备份。
• 每次升级前手动备份。
• 定期做恢复演练。

常见问题

只备份 SQLite 可以吗

不可以。.stage 文件存放在同一个 volume 的 decks/ 目录。只备份数据库会导致恢复后 metadata 存在但 blob 丢失。

恢复后健康检查失败

检查 volume 权限、数据库文件路径，以及容器日志：

docker compose logs api

恢复后某些 deck 不能打开

检查对应的 /data/decks/<deckId>/<versionId>.stage 是否存在。若不存在，说明备份不完整或恢复路径错误。