NoteFast

数据目录

data/ 目录里每一层是什么——SQLite、media、Markdown 影子副本与各配置文件。

NoteFast 的全部状态都在一个目录里。**复制这个目录 = 完整备份；移动这个目录 = 完整迁移。**桌面端可在「设置 → 通用与外观 → 数据目录」一键打开。

data/
├── notefast.db            # 权威存储：所有笔记、块、引用、实体、向量、索引
├── notefast.db-wal        # SQLite WAL（运行时存在，checkpoint 后合并回主文件）
├── media/                 # 图片原文件，按内容 SHA-256 命名（内容寻址去重）
├── markdown/              # Markdown 影子副本（默认开启，见下）
├── backup.config.json     # 数据库备份配置
├── sync.config.json       # 多端同步配置
├── storage-locations.json # 存储连接（S3 / WebDAV / 本地目录的凭据）
├── image-upload.config.json
├── sync-state.json        # 同步游标（本端发布序号 + 各设备消费水位）
└── rollback-<timestamp>/  # 恢复演练时旧库的兜底目录（见备份与恢复）

notefast.db：唯一权威

所有内容的权威存储就是这一个文件。它内部不是「一篇文档一行」，而是块树：每行一个块（标题 / 段落 / 代码 / 引用……），靠 parent_id 组成层级。全文索引（FTS）、语义向量、实体提及都是伴随写入维护的表——它们损坏了可以重建，正文永远在 blocks 表里。

media/：内容寻址的图片

图片按内容哈希命名（<sha256> 无扩展名），同一张图无论引用多少次只存一份。Markdown 里的 asset:<sha256> 引用由渲染层解析为 API 路径。这是备份快照不覆盖的部分——数据库备份只含 SQLite；media 随同步、归档、分享通道按引用传递，或直接整个目录拷走。

markdown/：给人看的影子副本

把文档实时投影为普通 Markdown 文件，供访达 / 资源管理器直接浏览：

  • 路径与归档同构：<首标签|untagged>/<标题 slug>--<id12>.md
  • 单向：改这些 .md 不会写回笔记——权威始终是 SQLite
  • 图片指向同一套 media/（改写为相对路径），不复制第二份
  • 默认开启，可在设置中关闭（关闭后停止写入，已生成的文件保留）

用途：用任何编辑器快速翻阅、纳入系统级文件搜索、给不打开 NoteFast 的人一个目录。

各配置文件

运行时配置全部落盘在 data/ 下的 JSON 文件，改配置都在 Web 设置页完成，一般不需要手改。注意 storage-locations.json 含存储凭据、backup.config.json 含备份目标配置，请保持文件权限 0600。

迁移与磁盘占用

  • 换机器：停服 → 拷走整个 data/ → 新机器放到同路径（或用 DATA_DIR 指定）→ 启动。桌面端与 Docker 形态之间迁移同理
  • 只想要内容：启用 Markdown 影子副本或归档，或单篇导出
  • 体积异常大：大量删除后运行一次 VACUUM；WAL 过大可在维护页手动触发 checkpoint