同步流程与代码位置

返回文档导航

• 本文记录当前手动或定时同步从渲染进程/主进程调度器进入托管远端、执行同步状态机，直到完成或等待重试的完整调用链。
• 桌面端仅提供托管同步 Beta；协议测试使用 test/helpers/memory-sync-remote.js 中的内存远端替身。

图中每个步骤都带有稳定编号和源码文件。编号后的代码索引提供可点击链接；移动或重构同步代码时，应同时更新本页的节点位置与索引。

1. 托管同步入口

flowchart TD
    S01["S01 用户点击“立即同步”<br/>src/renderer/runtime/sync/library.js"]
    S02["S02 预加载层调用 sync:run<br/>src/preload.js:48"]
    S03["S03 主进程取得当前笔记库并延迟加载 SyncManager<br/>src/main/sync-handlers.js:12-23"]
    S04["S04 读取托管配置和安全凭据<br/>src/main/sync/manager.js"]
    S05["S05 取得或初始化托管 SyncClient<br/>src/main/sync/manager.js"]
    S07["S07 合并并发触发，进入同一 SyncClient 状态机<br/>src/main/sync/client/transfer.js"]

    S01 --> S02 --> S03 --> S04 --> S05 --> S07

2. 客户端同步状态机

flowchart TD
    C01["C01 初始化身份、基线、队列和 cursor；状态改为 syncing<br/>src/main/sync/client/local.js, src/main/sync/client/transfer.js"]
    C02{"C02 是否为无基线的新副本？<br/>src/main/sync/client/transfer.js"}
    C03["C03 先拉取远端最终快照，防止空目录生成误删除<br/>src/main/sync/client/transfer.js"]
    C04["C04 开始最多两轮收敛<br/>src/main/sync/client/transfer.js"]
    C05["C05 扫描文件；校验未跟踪路径的远端身份后持久化本地操作队列<br/>src/main/sync/client/local.js"]
    C06["C06 按队首顺序幂等上传，逐项落盘结果<br/>src/main/sync/client/transfer.js"]
    C07["C07 按 cursor 拉取压缩快照、应用每个 fileId 的最终状态<br/>src/main/sync/client/transfer.js"]
    C08{"C08 两轮是否完成？<br/>src/main/sync/client/transfer.js"}
    C09["C09 标记 idle，记录成功时间并保存状态<br/>src/main/sync/client/transfer.js"]
    C10["C10 返回状态；界面刷新笔记库和托管详情<br/>src/main/sync/client/transfer.js, src/renderer/runtime/sync/library.js"]
    E01["E01 标记 error，保留 queue/cursor 并保存错误<br/>src/main/sync/client/transfer.js"]
    E02["E02 尝试上报有界错误摘要<br/>src/main/sync/manager.js"]
    E03["E03 界面显示错误并保留“重试”入口<br/>src/renderer/runtime/sync/library.js"]

    C01 --> C02
    C02 -->|是| C03 --> C04
    C02 -->|否| C04
    C04 --> C05 --> C06 --> C07 --> C08
    C08 -->|未完成| C05
    C08 -->|已完成| C09 --> C10
    C03 -.异常.-> E01
    C05 -.异常.-> E01
    C06 -.异常.-> E01
    C07 -.异常.-> E01
    E01 --> E02 --> E03

3. 上传、冲突与托管远端

flowchart TD
    U01["U01 读取持久化队首操作<br/>src/main/sync/client/transfer.js"]
    U04["U04 托管适配器发送鉴权 HTTP 请求<br/>src/main/sync/hosted-remote.js:31-68, 92-94"]
    U05["U05 HTTP 路由鉴权并转交托管存储<br/>server/hosted-sync/http-server.js:137-142"]
    U06["U06 托管存储检查幂等、权限、基线、路径和配额并提交 revision<br/>server/hosted-sync/store/index.js"]
    U07{"U07 远端是否接受？<br/>src/main/sync/client/transfer.js"}
    U08["U08 更新文件基线，移除队首并原子保存<br/>src/main/sync/client/transfer.js"]
    U09["U09 尝试 Markdown 三方合并；失败时保留相邻版本或冲突副本<br/>src/main/sync/client/files.js"]
    U10["U10 必要时把被远端删除或替换的文件移入同步回收目录<br/>src/main/sync/client/files.js"]

    U01 --> U04 --> U05 --> U06 --> U07
    U07 -->|accepted| U08
    U07 -->|conflict| U09 --> U10 --> U08

4. 拉取与本地应用

flowchart TD
    D01["D01 使用当前 cursor 请求压缩快照<br/>src/main/sync/client/transfer.js"]
    D04["D04 托管适配器调用 changes 接口<br/>src/main/sync/hosted-remote.js:95-97"]
    D05["D05 HTTP 路由解析 cursor 并转交存储<br/>server/hosted-sync/http-server.js"]
    D06["D06 托管存储从 files 头表返回每个 fileId 的最终状态<br/>server/hosted-sync/store/index.js"]
    D07["D07 校验 compacted 响应并按 fileId 防御性再压缩<br/>src/main/sync/client/transfer.js"]
    D08{"D08 是否存在正文偏离、路径占用或远端删除？<br/>src/main/sync/client/files.js"}
    D09["D09 覆盖前创建冲突副本或移入同步回收目录<br/>src/main/sync/client/files.js"]
    D10["D10 捕获本地身份快照并原子写入最终正文/墓碑<br/>src/main/sync/client/files.js"]
    D11["D11 逐项保存基线；整批完成后提交目标 cursor<br/>src/main/sync/client/transfer.js"]

    D01 --> D04 --> D05 --> D06 --> D07
    D07 --> D08
    D08 -->|是| D09 --> D10
    D08 -->|否| D10
    D10 --> D11 --> D13["返回主状态机<br/>src/main/sync/client/transfer.js"]

5. 关键持久化边界

• 本地操作先进入 queue 并保存，再开始上传：reconcileLocal。
• 上传结果先更新文件基线，再移除队首并保存：pushQueue。
• 拉取快照逐项安全写盘并保存文件基线，整批成功后再推进 cursor：pullChanges。
• 所有同步状态通过原子替换保存：SyncStateStore.save、atomicWriteBuffer。
• 主同步循环内的异常会保存错误状态，但不会主动清空未确认队列：runSync 异常分支。

因此重试的恢复点是“最后一次成功保存的队首/文件基线/cursor”，而不是界面内存中的临时进度；服务端再通过 operationId 幂等结果防止提交成功但响应丢失时产生重复 revision。

6. 远端仓库列表、克隆与删除

flowchart LR
    L01["同步中心读取当前账号仓库列表"] --> L02["用户选择仓库与克隆位置"]
    L02 --> L03["主进程验证目录与仓库归属；非空位置创建命名子目录"]
    L03 --> L04["写入 .mynote/library.json"]
    L04 --> L05["从 cursor 0 执行首次同步"]
    L05 --> L06["打开克隆目录作为当前工作区"]

7. 自动同步调度

flowchart LR
    A01["同步中心保存启用状态与秒数"] --> A02["主进程重建定时器"]
    A02 --> A03["合并当前仓库与后台同步仓库并去重"]
    A03 --> A04{"全局开关开启、存在目标、有效登录且未在同步？"}
    A04 -->|是| A05{"该仓库开启安全模式？"}
    A04 -->|否| A06["跳过本次触发"]
    A05 -->|否| A07["执行完整同步"]
    A05 -->|是| A10{"仅单向变化？"}
    A10 -->|是| A09["执行安全推送或安全拉取"]
    A10 -->|否| A06
    A07 --> A02
    A09 --> A02
    A06 --> A02

7.1 配置与目标

• 配置由 SyncConfigStore 保存到系统应用数据目录下的 sync-config-v1.json。
• autoSyncIntervalSeconds 为 null 时禁用；启用时默认 60 秒，允许 1–86400 的整数秒。
• 全局自动同步开启时，当前打开的仓库始终参与定时同步，不受仓库级开关影响。
• “切换仓库后仍自动同步”由 WorkspaceStateStore 保存为本机路径列表，默认关闭，但其选择不依赖全局开关。
• 全局关闭期间偏好仍可配置，只是不执行定时调度。
• 手动同步不检查该列表。

7.2 安全自动同步

• “安全的自动同步”使用独立的仓库路径列表，不依赖全局开关或“切换仓库后仍自动同步”。
• 当前仓库由全局定时器选中时也遵循该设置。
• 切换离开的仓库只有在“切换仓库后仍自动同步”开启、成为后台目标后才有机会执行。
• 选择安全模式后，SyncClient.safeSync 先用同一 cursor 检查远端最终快照，并以只读扫描检查本地待推送内容。
• 仅本地变化时安全推送，仅远端变化时安全拉取，两侧都有变化则跳过。
• 预检后的上传版本冲突会保留持久化队列。
• 拉取期间发现本地变化会在生成冲突副本前停止，因此安全模式不会自动进入冲突解决。

7.3 调度实现

• AutoSyncScheduler 只维护一个主进程定时器，对当前仓库和已启用后台同步的仓库去重后顺序执行，并以运行锁避免上一轮未结束时重入。
• 一个目标失败时记录空结果并继续其余目标。
• registerSyncHandlers 在应用启动时读取全局设置，在 sync:auto-config 保存后立即重建定时器，并在每次触发时合并当前仓库与仓库级后台目标。
• 退出时通过 src/main.js 停止定时器。
• 定时触发对任何未选择安全模式的目标仓库使用 SyncManager.runIfAuthenticated，对任何选择安全模式的目标仓库使用 runSafelyIfAuthenticated，不区分当前或后台位置。
• 未登录时，两种定时同步均不发请求。
• 手动“立即同步”始终使用完整同步与既有冲突恢复逻辑。

8. 模块职责与依赖方向

同步代码按“入口与调度 → 应用编排 → 仓库状态机 → 协议/持久化/网络”分层。上层可以组合下层，下层不得依赖 Electron 界面或工作区状态：

依赖注入边界也用于测试：SyncClient 只要求远端实现 applyOperation() 和 pull()；AutoSyncScheduler 注入计时器和执行回调；HostedSyncRemote 注入 fetchImpl。因此协议故障、定时器竞态和 HTTP 错误可以分别测试，不需要启动完整界面。

9. 本地持久化数据模型

9.1 仓库身份

<笔记库>/.mynote/library.json 随仓库移动或复制，用来说明“这是哪个逻辑仓库”：

{
  "protocolVersion": 1,
  "libraryId": "稳定的仓库 UUID",
  "formatVersion": 1
}

身份文件存在但损坏时客户端会停止，不会生成新 ID 覆盖它；只有文件确实不存在时才创建身份。这避免损坏被误解释成一个全新远端仓库。

9.2 账号与服务命名空间

• 托管状态位于 <笔记库>/.mynote/sync-hosted-v1/<namespaceKey>/state.json。
• namespaceKey 来自规范化服务地址和服务端账号 ID 的 SHA-256 前 16 位，只用于本地隔离，不承担鉴权或加密作用。
• 切换服务地址会清除旧凭据与内存客户端，旧状态文件仍保留在原命名空间中。
• 设备 ID 独立于登录 token 持久化；重新登录相同环境（包括远程退出当前设备后再次登录）会在密码验证成功后复用并重新激活该 ID，因此可继续使用原状态文件和 cursor，不会重新全量遍历远端。

9.3 同步检查点

state.json 的核心字段如下：

• files 只保存基线元数据。
• 可自动合并且不超过 2 MB 的 Markdown 共同祖先按正文哈希保存在账号命名空间的 merge-bases/，不放入有界的 state.json。
• 用户可读的 Markdown 和图片仍以工作区磁盘文件为准。
• queue 中的 upsert 会保存扫描当时的正文和哈希，保证文件随后再次变化时，已经排队的操作仍表示同一份待确认内容。

10. 崩溃恢复与并发不变量

维护同步逻辑时必须保持以下顺序；颠倒其中任意一项都可能造成静默跳过或重复提交：

1. 本地扫描产生的操作必须先写入 queue 并原子保存，之后才能发出 HTTP 请求。
2. 上传只能处理持久化队首；远端结果更新基线后，才能移除队首并原子保存。
3. 同一 operationId 的重试必须保持相同操作内容；服务端负责返回第一次提交的幂等结果。
4. 拉取必须先捕获受影响身份的本地正文，逐项安全应用最终状态并保存文件基线；整份压缩快照完成后才能更新 cursor。
5. Markdown 三方合并必须先写出 Base/Local/Remote；干净合并的新操作持久化后才能删除临时文件并发出请求。其余冲突必须先保留本地正文，再应用远端当前文件、路径拥有者或墓碑。
6. 没有任何基线的新副本必须先从 cursor 0 拉取，不能先把空目录解释为一组删除。
7. 同一客户端的手动和定时触发必须合并到一个运行中的 Promise；定时器也必须跳过尚未结束的上一轮。
8. 网络、遥测或界面错误不得清空队列、回退 cursor，或覆盖原始同步异常。

• 如果进程在上传响应后、保存队列前退出，重启后会重发相同 operationId，服务端返回之前的结果。
• 如果进程在压缩快照部分写入后、保存目标 cursor 前退出，重启后会重新请求同一快照，并依据已保存文件基线跳过完成项。
• 两种窗口都允许重复工作，但不允许丢失未确认工作。

11. 修改与排障指南

11.1 修改协议或支持新文件类型

• 当前 /v1/libraries/:id/changes 已按产品决定原地切换为不兼容的 compacted: true 单快照响应；客户端和服务端必须成套升级。后续再次改变该契约时，应重新明确是否继续接受不兼容部署。
• 文件类型、编码、大小和哈希规则集中在 protocol.js；客户端和服务端必须共享同一组验收用例。
• 新增持久化字段应提供安全默认值，并验证旧 state.json、损坏状态隔离和首次拉取行为。
• 冲突策略变化至少回归双设备离线编辑、重命名/删除并发、路径占用、提交后断网、乱序/重复拉取和符号链接逃逸。

11.2 常见状态定位

相关最小验证：

npm run lint
node --test test/sync-*.test.js test/auto-sync-scheduler.test.js test/clone-target.test.js
node --test test/hosted-sync-http.test.js

涉及主进程 IPC 或打包边界时还应执行完整 npm run validate。