数据备份与恢复

Slite 提供两个层级的数据保护方案：用于轻量迁移的短链接 JSON 快照，以及用于灾难恢复的停机全量文件系统冷备份。

1. 短链接 JSON 快照

应用级短链接备份通过 unstorage 文件系统驱动保存在 /data/backups 目录下：

• 备份内容： SQLite 中保存的全部短链接记录的完整 JSON 快照，包括自定义分流规则、创建时间、标签和受保护的密码哈希。
• 排除内容： 快照不包含 DuckDB 访问分析历史、上传的图片文件以及进程内的短链接内存缓存。
• 自动备份： 计划任务默认在服务进程启动后每 24 小时自动执行一次，并自动保留最新的 30 份快照文件。手动触发的备份不受自动清理影响。
• 关闭自动备份： 在 .env 中设置 NUXT_DISABLE_AUTO_BACKUP=true 并重新创建容器。
• 手动触发： 可在后台仪表盘中点击备份，或向服务端发送 POST /api/backup 请求。

文件命名规则：

• 自动备份：backups/links-<timestamp>.json
• 手动备份：backups/manual-links-<timestamp>.json

快照属于机密数据

快照文件中包含受保护的访问密码哈希与未公开的目标 URL 地址，请严格限制对 /data/backups 目录的访问权限，将备份文件视同敏感机密妥善保管。

如需从快照还原短链接，请通过导入 API 分批提交记录。

2. 停机全量冷备份

如需完整保留所有数据（包括权威短链接、DuckDB 访问分析历史、上传图片与备份文件），必须在容器停止状态下对宿主机挂载的 /data 目录进行冷备份。

全量备份操作步骤

1. 停止运行容器：

   docker compose stop

   切勿在 Slite 运行时直接拷贝数据库文件，运行中的文件拷贝极易产生损坏的 SQLite 或 DuckDB 文件。
2. 打包 /data 目录： 从宿主机完整复制或打包挂载的数据卷目录：
   • slite.sqlite（权威短链接与状态数据库）
   • analytics.duckdb（访问分析数据库）
   • files/images（上传的预览图片）
   • backups（短链接 JSON 快照）
3. 备份配置文件： 妥善保存当前的 .env 配置文件，并记录运行的 Docker 镜像标签或 Git 提交哈希。
4. 重启容器：

   docker compose start

请将打包好的备份归档另存至异地或独立的存储磁盘上。

3. 全量灾难恢复

将 Slite 实例还原至历史状态的流程如下：

1. 停止当前运行的容器（docker compose stop）。
2. 将备份归档中的全部内容解压还原到挂载的数据卷目录中。
3. 确保容器运行用户 UID 5483 对还原后的目录具有读写权限：

   sudo chown -R 5483:5483 /path/to/data

4. 启动与原版本匹配的容器（docker compose up -d）。
5. 登录 /dashboard，验证登录鉴权、短链接重定向、访问分析报表以及图片渲染是否均恢复正常。

短链接内存缓存纯粹存在于进程内存中，启动后会自动按需从 SQLite 回填，无需任何手动恢复操作。