备份与恢复

NoteFast 的全部数据都在一个 SQLite 文件里，这决定了它的备份模型异常简单：备份 = 对这个文件做一致性快照，恢复 = 把快照放回去。向量、全文索引、AutoLink 关系都由写入过程持续维护，快照里天然包含，恢复后无需重建。

与 Markdown 归档的区别

能力	作用	覆盖范围
数据库备份	SQLite 一致快照 → 本地目录 或 S3	完整实例数据（blocks、引用、向量、FTS、AutoLink 等）
Markdown 归档	单向推送 .md（见同步与归档）	正文 + YAML frontmatter；丢失引用图、向量等关系数据

完整灾备请使用数据库备份。Markdown 归档用于可读副本与内容主权，不能替代恢复。

配置备份

设置 → 备份与归档，备份目标二选一（互斥）：

• 本地目录：快照写入 <目录>/<前缀>snapshots/。零外部依赖，单机 / 桌面端即可用
• 存储连接：S3 兼容存储（AWS / R2 / MinIO），适合异地容灾。连接在「存储连接」中统一管理，备份 / 同步 / 归档共用

设置项：

项	说明
前缀	快照对象的键前缀（如 notefast/）
保留天数	默认 30 天；每次备份完成后自动删除超过天数的旧恢复点
间隔	自动备份周期（默认 1 小时）

操作路径：填好目标 →「测试连接」→「立即备份」。恢复点列表（GET /api/v1/backup/restore-points）可在设置页查看。

配置落盘 data/backup.config.json（建议权限 0600）。密钥不会通过 API 明文回传；保存时传 ***set*** 表示沿用旧值。

快照流程

每次备份执行以下步骤，保证拿到的是可恢复的一致性快照：

1. 互斥锁——禁止重叠执行
2. VACUUM INTO 生成临时一致快照（不锁写、不含 WAL 半提交状态）
3. PRAGMA quick_check + SHA-256 校验
4. 上传唯一对象键 + .manifest.json（含校验和与 schema 版本）
5. 按保留策略清理过期的旧恢复点

恢复（停服务 + CLI）

必须先停止 NoteFast（Compose：docker compose stop notefast）。CLI 不做占用探测——在 WAL 模式下强行占用写锁既不可靠，也可能干扰仍在运行的实例。

# 1. 停止 NoteFast
docker compose stop notefast   # 或等价操作

# 2. 预演（可选）
bun --filter @notefast/server backup:restore -- \
  --data-dir ./data \
  --object-key notefast/snapshots/<恢复点>.db \
  --dry-run

# 3. 正式恢复（需 --yes）
bun --filter @notefast/server backup:restore -- \
  --data-dir ./data \
  --object-key notefast/snapshots/<恢复点>.db \
  --yes

# 4. 启动服务
docker compose start notefast

要点：

• 本地目录目标走同一 CLI——目标类型自动从 backup.config.json 读取，--object-key 为目录下的相对键（如 backup/snapshots/....db）
• 恢复前校验：manifest、SHA-256、quick_check、schema 版本（快照 schema 不得高于当前程序）
• 现有库不覆盖删除：当前 notefast.db / WAL / SHM 会移入 data/rollback-<timestamp>/ 兜底
• 写入顺序：write staging → fsync(file) → rename → fsync(dir)，避免崩溃后留下空库 / 残缺库
• Web 不提供一键覆盖恢复——这是有意的安全边界，防止误操作把当前库顶掉

桌面端（客户端）如何用备份文件恢复

桌面端没有 CLI，恢复的原理与服务器一致：关掉应用 → 用快照替换数据库文件 → 重新打开。引擎在应用退出时会优雅停机并关闭 SQLite（数据不处于半写状态），所以替换文件是安全的。

1. 定位数据目录

打开 NoteFast →「设置 → 通用与外观 → 数据目录」→「打开数据目录」，直接在访达 / 资源管理器中定位。手工查找时按安装形态区分：

形态	数据目录
macOS / Windows 安装版	%APPDATA%/com.notefast.desktop/data（macOS 在 ~/Library/Application Support/com.notefast.desktop/data）
Windows 便携版	<exe 同目录>/data（整个文件夹即完整安装）
自定义	设置了 NOTEFAST_DATA_DIR 环境变量时以它为准

2. 恢复

1. 完全退出 NoteFast（Windows 从托盘退出；macOS ⌘Q），确认进程不在后台
2. 进入数据目录，把现有 notefast.db（连同 notefast.db-wal / notefast.db-shm，如果存在）改名或移走保存——不要直接覆盖删除，这是你的回退余地
3. 从备份对象（S3 快照，或本地目录备份的 <目录>/<前缀>snapshots/<恢复点>.db）把快照文件复制进来，重命名为 notefast.db
4. 重新启动 NoteFast，检查文档与引用完整

注意：快照文件必须是数据库备份生成的 .db（含 manifest 校验和），不是 Markdown 归档的 .md 文件——后者只是正文副本，无法作为库恢复。

3. 更省事的选择

如果只是想在两台机器间同步，不需要手工搬运文件——配置多端同步后数据自动对齐；桌面端同样可在「设置 → 数据库备份」配置周期快照，日常恢复优先从恢复点列表取最新一份。

验收清单

建议完成一次完整演练再信任这套流程：

• 配置目标后「立即备份」成功，恢复点列表可见
• 停服后从快照恢复到空目录，启动后文档与引用完整
• 恢复演练后检查 data/rollback-<timestamp>/ 里是恢复前的旧库
• Markdown 归档（若启用）无同名覆盖，删除文档后陈旧文件被清理