English | 简体中文

src/node 是桌面宿主使用的源码级 Node 适配层。它与浏览器安全的 Core 分离，不依赖 Electron、产品 SDK、账号、Provider 或应用路径。消费仓库直接合并这些 .mjs 源码；当前开发 版本没有把它作为 npm subpath 发布。

状态归属

宿主传入 stateDir 后，适配层只管理 stateDir/canvas：

路径 内容 恢复方式
index.sqlite Document、Journal、Receipt、引用和变体元数据 WAL 与损坏数据库备份
assets/<prefix>/<sha256> 内容寻址的不可变原图/原视频 再次导入相同内容时修复
cache/<prefix>/<key> 可重新生成的派生变体 LRU 淘汰或显式清空
tmp/*.partial 流式写入中的临时文件 失败/取消后删除，或显式 GC
uploads/* 宿主管理的导入暂存 适配层只观测；仅显式过期 GC 才删除

SQLite 保存元数据、Canvas Document 和 Transaction；图片/视频原始字节在 assets，缩略图等 派生文件在 cache。同一素材摆放多次只增加内容地址引用，不重复保存原文件。

默认限制与超限措施

限制 默认值 超出后的处理
单个 Document 引用的原始资产 512 MiB 原子拒绝 Document 事务，保留之前 revision 和引用
全部原始资产 2 GiB 只回收已过宽限期且无引用的原文件；仍不足则拒绝新导入
单个原始资产 256 MiB 在流式副本提交前拒绝
派生变体 128 MiB 优先淘汰最久未访问的变体，绝不删除原文件
活跃临时文件 256 MiB 预留前拒绝，并清除 partial 文件
Upload 暂存 256 MiB 向宿主报告用量/限额，由宿主拒绝新的暂存写入

无引用原文件默认保留 24 小时。临时导入 Owner 一小时后过期，避免中断任务永久占用原文件。 Upload 暂存的过期时间为 24 小时，但仍然只有显式 GC 才会删除。所有限制都能通过构造参数 调整，方便不同宿主和测试环境使用。

失败语义

  • 导入通过权限为 0600 的临时文件流式写入，同时计算 SHA-256。
  • 取消或校验和失败不会留下资产记录，并删除 partial 文件。
  • 引用变化与 Document revision 在同一个 SQLite immediate transaction 中提交。
  • 派生缓存淘汰和孤儿清理不会删除仍有引用的原文件。
  • SQLite 损坏时先把数据库及 sidecar 移入 recovery 目录，再初始化新库。
  • 输入路径先 realpath，可限制在宿主显式提供的 allowed roots 内。

该适配层要求 Node 提供 node:sqlite；当前已验证运行时为 Node 24。