# 备份和恢复 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. 检查服务状态

```bash
docker compose ps
```

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

```bash
curl http://localhost/api/health
```

## 2. Checkpoint SQLite WAL

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

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

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

## 3. 备份整个 volume

```bash
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. 验证备份文件

列出压缩包内容：

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

至少应看到：

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

## 5. 恢复前停止服务

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

```bash
docker compose down
```

## 6. 清空并恢复 volume

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

```bash
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. 启动并验证

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

登录 Pro，检查：

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

## 备份频率建议

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

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

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

## 常见问题

### 只备份 SQLite 可以吗

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

### 恢复后健康检查失败

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

```bash
docker compose logs api
```

### 恢复后某些 deck 不能打开

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