介绍

sync vault同步算法是一种设备无关的文件同步方式，主要有两种实现：一是基于云盘的同步；二是peer to peer的同步。
本文档针对云盘同步和p2p同步做详细描述，包含如下内容：

本文档不是使用手册，如需了解如何使用，可参考：sync vault使用手册

  1. 同步对象：介绍算法处理的文档对象，描述方式。
  2. 同步状态。
  3. 同步过程：算法处理流程。
  4. 冲突处理：文件冲突的解决方式。

同步对象

不论是云盘同步还是p2p同步，sync vault当前的同步对象为obsidian仓库中的文件，除了如下对象：

  1. 隐藏文件。
  2. 隐藏文件夹。
  3. 空文件夹。

为什么排除这三种对象? 隐藏文件和隐藏文件夹通常是配置文件，一般涉及到用户的关键信息，对用户不可见。
文件夹作为文件的组织单元，本身并不存储数据信息，因此排除空文件夹。

可能带来的影响：

  1. 有的第三方插件依赖隐藏文件。
    部分第三方插件可能会在用户使用插件的过程中访问隐藏文件。如果隐藏文件缺失，可能引起这类插件功能异常。

同步对象的抽象表示

每一个同步对象由以下类型表示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    path: 仓库中的文件路径,
    isFolder: 是否是目录;
    fsid: 云盘中的唯一标识;
    ctime: 文件创建时间，秒级;
    mtime: 文件修改时间，秒级;
    size: 文件大小，字节为单位;
    /* 可选参数 */
    contentHash?: 文件内容hash值;
    mimetype?: MIME类型;
    pickCode?: 115网盘提取码;
    pid?: 父文件唯一标识;
    dlLink?: 文件下载地址;
}

同步控制

在同步过程中，文件有以下几种状态：

  1. 完全同步。
  2. 本地创建：远端不存在，本地存在。
  3. 本地更新：云端未修改，本地修改。
  4. 远端创建：本地不存在，远端存在。
  5. 远端更新：本地未修改，云端修改。
  6. 冲突：同步对象本地和云端都发生修改。

不同的同步状态会触发不同的操作：

  1. 完全同步：无操作。
  2. 本地创建：上传。
  3. 本地更新：上传。
  4. 远端创建：下载。
  5. 远端更新：下载。
  6. 冲突：冲突解决。

2~6状态经过相应的同步操作成功后，进入状态1。

初始同步

在第一次同步的时候，由于远端文件不存在，因此所有文件的初始状态都为本地创建。
等待文件上传成功后，文件同步状态为完全同步。

同步触发事件

同步算法会监听如下文件事件：

  1. 文件删除。
  2. 文件重命名。
  3. 文件创建。
  4. 文件修改。
  5. 文件打开。

其中的1～4会触发文件同步。事件5会引起同步界面的变化，不会触发同步。

除了事件触发同步外，sync vault还支持周期性同步，以1分钟、5分钟、10分钟和30分钟为周期进行同步。

同步轮次

一个文件在某一个时刻从开始同步到结束同步的过程称为一个轮次。
每一个轮次的处理过程如下：

graph TD
A(获取本地文件事件)
B(获取云端文件事件)
A --> C(冲突识别)
B --> C(冲突识别)
C --> D(冲突处理)
D --> E(同步后处理)

可以看到冲突识别和处理位于算法的核心地位。

举例：本地删除文件A，远端修改文件A，则发生冲突。sync vault会选择远端的文件修改，而忽略本地的文件删除。

冲突识别和处理

在同步过程中，冲突分为两种：元数据冲突和内容冲突。sync vault当前支持的冲突类型如下表所示：

云端删除 云端移动 云端修改
本地删除 删除 下载云端新文件，删除本地旧文件 下载云端新文件
本地移动 上传本地新文件 下载云端新文件，上传本地新文件 先移动云端文件，再下载移动后的新文件
本地修改 上传本地新文件 本地移动文件，上传本地文件 下载云端文件（内容冲突解决）