Baidu Sync Safe
Sync files with Baidu Netdisk using conflict copies, optional end-to-end encryption, and recoverable desktop file replacement.
- Overview
- Scorecard
- Updates5
Baidu Sync Safe synchronizes an Obsidian desktop vault with Baidu Netdisk. It supports manual and scheduled bidirectional sync, conflict copies, optional AES-256-GCM end-to-end encryption, and encrypted configuration transfer between desktop devices.
Requirements: Obsidian 1.14.4 or later on desktop, a Baidu Netdisk account, and a personal Baidu developer application with AppKey/AppSecret. Mobile support is not released.
Install: Download main.js, manifest.json, and styles.css from this repository's latest release. Place them in <vault>/.obsidian/plugins/baidu-sync/ and enable Baidu Sync Safe under Community plugins. For a custom configuration folder, replace .obsidian with your configuration folder.
Set up: Create an application in the Baidu Netdisk developer console, enter its AppKey and AppSecret in plugin settings, open the authorization page, exchange the authorization code for a token, and test connectivity. Choose a remote directory before starting sync. To enable encryption, set a nonempty encryption password on every device. Keep an independent backup before the first sync.
File safety: Desktop replacement uses native filesystem rename with verified backup and journal files and pre-commit fsync. Startup recovery only processes plugin-owned journal entries. This is single-file replacement and recovery, not a distributed transaction across the vault and Baidu Netdisk or a guarantee against arbitrary physical power loss. The plugin makes requests to Baidu for authorization, uploads and downloads and uses the clipboard for user-triggered configuration transfer.
Credits: The link to owl234's project in the Chinese acknowledgements below is intentional attribution for encryption and configuration-sharing design references; installation and downloads for this plugin use the minLaoGe repository linked above.
中文
为 Obsidian 桌面版打造的百度网盘双向同步插件。当前 1.0.4 仅支持桌面端，最低 Obsidian 版本为 1.14.4；移动端尚未实机验证，暂不发布移动端支持。依托百度网盘大容量云存储，提供单设备串行执行、单文件替换与事务恢复、3-Way 冲突副本保护，并支持端到端零知识加密 (E2EE) 与多设备一键跨端快速配对机制。
🌟 致谢
特别感谢社区优秀开源项目 owl234/obsidian-baidu-netdisk-sync 在端到端加密（E2EE）与多设备跨端配对设计上带来的启发与技术参考。
📖 百度网盘账号授权（OAuth 2.0）保姆级获取步骤
只需在电脑端首次操作一次，后续多设备可直接通过加密配对码一键导入！
第一步：登录百度网盘开放平台
- 浏览器打开 百度网盘开放平台 (pan.baidu.com/union)；
- 登录你常用的百度网盘个人账号（首次进入点击注册开发者，普通个人账号绑定手机即可免费开通）。
第二步：创建个人开发者应用
- 进入【控制台】-> 点击【创建应用】；
- 应用类别：选择【软件】或【移动/桌面应用】；
- 应用名称：任意输入（例如
ObsidianSync或MyObsidian）； - 开通权限：保持默认的基础网盘读写权限（
basic,netdisk）即可，无需额外特殊申请； - 点击提交创建。
第三步：获取 AppKey 与 AppSecret
- 进入刚创建的应用详情页面，切换到【开发信息】一栏；
- 复制你的 AppKey (Client ID) 与 AppSecret (SecretKey)；
- 打开 Obsidian 插件设置页面，分别粘贴进 AppKey 和 AppSecret 输入框。
第四步：网页授权与换取 Token
- 在插件设置中点击【1. 获取网页授权码】按钮，会自动在浏览器中弹出百度官方授权登录页面；
- 登录账号并点击【允许授权】；
- 授权成功后，页面会展示一段授权码（Code）；
- 复制该 Code 粘贴回插件设置中的输入框，点击【2. 兑换并保存 Token】；
- 提示兑换成功后，点击【测试连通性】，显示你的百度网盘用户名即代表完全就绪！
💡 小贴士：百度网盘 Token 到期前插件会自动无感续期，日常无需手动维护。
多设备快速配对指南（当前仅支持桌面设备）
插件支持桌面设备之间的加密配置迁移。以下配对机制不代表当前版本支持手机或平板：
- 在主设备（电脑端）：
- 进入插件设置 -> 【2. 多设备快速配对与配置迁移】；
- 点击 “📤 导出加密配对码”，设置一个临时保护密码（PIN 码），点击生成并复制配对码（以
BDSYNC:v1:...开头）。
- 在第二台桌面设备：
- 在第二台桌面设备的 Obsidian 安装并启用本插件；
- 进入插件设置，点击 “📥 导入配置配对码”；
- 粘贴配对码，输入你刚设置的保护 PIN 码，点击“解密并应用配置”；
- 导入后拥有同步配置与鉴权凭证，无需在第二台电脑重复申请开发者应用。
🚀 核心架构与功能特性
1. 严格时间顺序（Ordering Guarantee）
- 本地防抖缓冲池（Debounce Manager）：在 Obsidian 中高频键入或自动保存时，通过可配置窗口（默认 3 秒）将多次修改合并为单次有效变更，杜绝打字期间高频发包引起的网络倒序与网盘接口频控。
- 严格 FIFO 串行异步执行队列：确保对于任何文件与元数据，始终按产生的逻辑时间序列单调推进，消除并发交错。
- 全局同步互斥锁（Sync Mutex Lock）：全量比对期间独占锁，防止手动连续点击或定时轮询与正在运行的增量任务重叠。
2. 文件替换、持久化与恢复边界
- 桌面端：使用本地文件系统
rename覆盖目标，不先删除旧文件；替换前对新内容、旧版本备份及事务记录执行写入、重读 MD5 校验和fsync。如果文件系统不支持替换，直接报错，不退化成先删后写。 - 移动端：Obsidian DataAdapter 没有承诺原子覆盖或
fsync，采用校验过的新文件、旧文件副本和事务记录实现可恢复替换。替换期间目标路径可能短暂不存在，不能宣称运行时原子可见。 - 启动恢复：仅处理当前配置目录
plugins/baidu-sync/transactions/内有事务记录的文件。已完成替换则清理；目标缺失则恢复已验证的旧版本（新建文件恢复新内容）。遇到损坏记录、内容不明或恢复失败会停止同步并保留恢复材料。 - 同步基线：
sync-state.json使用同一事务写入机制；恢复先于基线加载，保存失败可重试，损坏的基线不会静默重置。 - 边界：保证的是单文件替换及上述故障模型下的恢复，不是整个知识库、同步基线与百度网盘之间的分布式事务。DataAdapter、底层文件系统、云盘占位文件、设备缓存及目录元数据落盘能力各异，不能承诺任意物理断电下零丢失。外部编辑器或其他设备不受插件进程内锁控制。
- 测试：
npm test覆盖持久化步骤后的重启、写入/删除/重命名故障、损坏临时内容、用户备份保护、基线重试和加密冲突回归；npm run typecheck检查类型。
3. 三方差异冲突防护（3-Way Conflict-Safe Resolution）
基于【当前本地】、【当前网盘】、【上次成功同步基准（Base Snapshot）】进行三方对比：
- 本地修改，远端未变：自动推送（Upload）。
- 远端修改，本地未变：自动拉取（Download）。
- 两端并发修改且哈希不同（真实冲突）：
- 默认策略（安全分支副本）：保留本地编辑内容原封不动，将远端冲突版本拉取并另存为
${文件名}.conflict-${时间戳}.${扩展名}，并在 Obsidian 界面弹出 Notice 提示，保留两个版本供用户检查与合并。 - 可选策略：支持在设置中切换为“以最新时间戳为准（keep_newer）”、“强制本地优先”或“强制远端优先”。
- 默认策略（安全分支副本）：保留本地编辑内容原封不动，将远端冲突版本拉取并另存为
4. 工业级端到端加密（E2EE）
- 采用 Web Crypto API 原生实现的 AES-256-GCM 高级加密标准 + PBKDF2（600,000 次 SHA-256 哈希迭代）派生高强度密钥。
- 文件在离开本地设备前完成加密，网盘端仅存放密文，兼顾大容量同步与笔记隐私保护。
🛠️ 安装与使用
手动安装方式
- 打开你的 Obsidian 知识库目录，进入
.obsidian/plugins/； - 新建文件夹
baidu-sync； - 将仓库构建出的
main.js、manifest.json、styles.css放入该文件夹； - 在 Obsidian “设置 -> 第三方插件” 中刷新并启用 Baidu Sync Safe。
💻 本地构建开发
# 安装依赖
npm install
# 生产环境编译打包
npm run build
# 开发监听模式
npm run dev
📄 开源许可证
本项目基于 MIT License 开源。 特别感谢社区项目 owl234/obsidian-baidu-netdisk-sync。