Baidu Sync Safe

by minlaoge
5
4
3
2
1
Score: 50/100

Description

Obsidian 百度网盘高可靠双向同步插件:严格时间顺序,事务原子性,3-Way 冲突安全保护,支持端到端加密与跨端快速配对

Reviews

No reviews yet.

Stats

2
stars
315
downloads
0
forks
32
days
3
days
3
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
1
total issues
0
open issues
1
closed issues
39
commits

Latest Version

3 days ago

Changelog

2.1.2 — 2026-11-17

  • V2 改用设备独立的滚动日志。正常同步复用同一个文件,最多保留 64 批变更、256 KiB;旧记录原样保留。
  • 大量旧格式记录积压时改用目录分页校验,不再逐条下载已完成的 JSON;未完成记录继续复查,不伪造完成状态。
  • 检测日志断档、回滚和缺失,回退完整目录校验;断网未确认或崩溃后保留旧日志并换用新标识,避免迟到请求覆盖后续日志。
  • 设备标识存放在设备本机存储中;重启后先核对云端内容,避免从旧备份恢复后覆盖较新的日志。
  • 回归覆盖 1,000 次写入限容、2,000 个文件/旧记录的请求计数、日志轮换、异常上传、旧备份恢复、双设备及 Android/iOS 浏览器环境。
  • 升级说明:建议所有设备一起更新。旧版遇到新日志会回退完整校验。本次不删除历史记录、不实现跨设备同文件写锁;不要在多个设备同时修改并同步同一文件,以免发生覆盖。长期未完成任务仍可能增加检查耗时。

验证:npm test、npm run typecheck、npm run build、git diff --check 全部通过。

升级要求:Obsidian 1.14.4+。请各设备更新到同一版本;手动安装仅替换 main.js、manifest.json、styles.css,保留配置、同步状态及备份。

README file from

Github

Baidu Sync Safe — Obsidian 百度网盘安全双向同步插件

安装前请先升级到 Obsidian 1.14.4 或以上。 Obsidian 1.13 等旧客户端可能安装到历史版 Baidu Netdisk Sync,并不代表已安装当前 Baidu Sync Safe 2.1.2。请先升级 Obsidian,再在社区插件页面更新;安装后到本插件设置顶部核对实际版本。手动安装请覆盖发布包中的 main.js、manifest.json、styles.css,保留 data.json、同步状态和备份。旧客户端不再提供历史版本兼容回退;已安装的旧插件不会因此自动升级。


🇨🇳 中文使用指南(置前) | 🌐 English Documentation | 🛠️ 开发者文档 (DEVELOPER.md)


🇨🇳 中文使用指南

🌟 项目设计初衷与核心价值

Obsidian 社区拥有非常丰富优秀的同步方案。每个方案都有其适用的场景,而 Baidu Sync Safe 专注于为广大希望使用百度网盘作为个人云端知识库存储介质的用户,提供原生级、高稳定性的同步体验:

  • 📦 充分利用百度网盘大容量云存储:个人免费拥有 TB 级存储空间,笔记、超大 PDF 文献、长音频与丰富图床附件均可随心备份与同步,无需时刻担忧空间配额。
  • 🚀 国内网络原生极速连通:依托百度网盘全国高质量 CDN 节点与官方 OpenAPI,在国内多网络环境(家用宽带、校园网、移动 4G/5G)下均具备优秀的上传与下载速率。
  • 📱 专为移动端深度优化体验:针对手机设备内存与后台特点,深度定制流式传输与轻量化快筛,确保在移动端拥有轻快、顺畅、省电的使用体验。
  • 🔐 严格的数据完整性与原子保障:引入两阶段提交与本地原子写入,即使在网络突然中断或进程异常退出的情况下,也能确保笔记不被损坏。

✨ 核心功能亮点

  1. ⚡ 零 I/O 快速指纹剪枝 (Fast-path 毫秒级比对)
    • 针对包含数千篇笔记的大型知识库,采用 mtime + size 内存快速指纹比对机制。
    • 未改动的文件直接在内存中完成判定,不读盘、不占闪存 I/O、不算 MD5,耗时 0 毫秒。2,800+ 篇文件的全库核对缩短至 50 毫秒以内,大幅降低移动端 CPU 占用与发热。
  2. 🛡️ HTTP Range 4MB 分片流式拉取(移动端大文件顺畅传输)
    • 针对包含 50MB~100MB+ 大文件(如 PDF 扫描件或音视频),底层采用基于 HTTP Range 的 4MB 分片流式拉取技术。
    • 分片数据随拉取随释放,严格控制内存占用,保障手机与平板设备在处理大附件时平稳顺畅。
  3. 🔄 相同内容 MD5 自动对齐与冗余副本清理
    • 当检测到两端文件存在微小时间戳偏差,但实际内容 MD5 100% 一致时,引擎会自动认定为相同版本并对齐基准线,静默清理多余的 .conflict 副本,减少人工维护负担。
  4. 🎨 桌面端与移动端统一实时进度 UI
    • 桌面端自适应固定于窗口右下角(380px 卡片式悬浮),移动端贴合在底部操作栏上方。
    • 实时呈现当前传输阶段、文件进度条、耗时、正在处理的文件名以及上传/下载/跳过统计计数。
  5. 🎛️ 独立配置上传与下载并发数(1~5 并发)
    • 上传通道与下载通道均支持在 15 之间自由调节(1 适合弱网省电,3 为标准推荐,45 适合宽带极速传输)。
    • 下载写入前自动执行本地哈希复核,排队期间本地若被编辑立即升级为冲突保护,绝不静默覆盖最新笔记。
  6. 🔐 AES-256-GCM 端到端可选加密与一键配对码导出
    • 允许用户设置独立密码开启客户端 AES-256 加密,上传到网盘的均为主机加密后的密文。
    • 支持主设备一键生成加密配对码(BDSYNC:v1:...),副设备粘贴配对码输入 PIN 即可一键导入全部配置,无需在手机上重复申请开发者应用。

📖 保姆级长篇使用教程

第一步:安装插件
方式 A:从 GitHub Releases 离线安装(推荐)
  1. 访问本项目的 GitHub Releases 最新发布页面;
  2. 桌面端(Windows / macOS / Linux):下载 main.js、manifest.json、styles.css 三个文件,在你的知识库目录中创建文件夹 <知识库>/.obsidian/plugins/baidu-sync/,将这三个文件放入其中;
  3. 安卓端(Android 手机 / 平板):下载离线压缩包 baidu-sync-2.0.2-mobile.zip,解压后将 baidu-sync 文件夹整体复制到手机知识库路径下的 .obsidian/plugins/ 目录;
  4. 打开 Obsidian,进入「设置」→「第三方插件」,关闭安全模式,找到 Baidu Sync Safe 并开启启用。
方式 B:通过 BRAT 插件管理器安装
  1. 安装并启用社区插件 BRAT;
  2. 在 BRAT 设置中点击「Add Beta plugin」;
  3. 输入仓库地址:minLaoGe/obsidian-baidu-netdisk-sync,点击确认即可完成安装,并可在后续享受新版本自动更新。

第二步:创建百度网盘开发者应用(仅需电脑端操作一次)

[!NOTE] 百度网盘开放平台个人开发者申请完全免费,使用个人手机号即可快速完成认证,无需企业资质。

  1. 登录开放平台:在电脑浏览器中访问 百度网盘开放平台控制台;
  2. 完成开发者认证:登录你常用的百度网盘账号,按照页面提示完成个人开发者认证;
  3. 创建应用:
    • 点击「创建应用」;
    • 应用类别:选择「软件」或「移动 / 桌面应用」;
    • 应用名称:自定义填写(例如 MyObsidianSync 或 知识库同步);
    • 开通权限:勾选默认的基础网盘读写权限(basic, netdisk)即可;
    • 点击提交创建。
  4. 获取密钥:进入刚创建的应用,点击「开发信息」标签页,复制两项关键信息:
    • AppKey (Client ID)
    • AppSecret (SecretKey)

第三步:在 Obsidian 插件中一键授权与测试
  1. 打开 Obsidian,进入「设置」→「Baidu Sync Safe」;
  2. 将复制好的 AppKey 与 AppSecret 填入对应输入框;
  3. 点击 「1. 获取网页授权码」 按钮,系统会自动在默认浏览器打开百度官方授权页面;
  4. 登录账号并点击「允许授权」,授权成功后页面会生成一段授权码(Code);
  5. 复制这段 Code,回到 Obsidian 粘贴进输入框,点击 「2. 兑换并保存 Token」;
  6. 点击下方 「测试连通性」,页面提示 连接成功!网盘用户名:xxx 即代表云端通信完全正常!

第四步:多设备极速配对(电脑 → 手机 / 副电脑)

主设备配置成功后,其他设备完全不需要再重复申请开发者账号或扫码,直接使用加密配对码即可一键同步凭据:

  1. 在主电脑上:
    • 进入插件设置,滚动至「多设备快速配对与配置迁移」区块;
    • 点击 「📤 导出加密配对码」,设置一个临时的 6 位数 PIN 码;
    • 插件将自动生成一段加密字符串(以 BDSYNC:v1: 开头),点击复制到剪贴板;
  2. 在手机或另一台电脑上:
    • 在新设备的 Obsidian 中安装并启用本插件;
    • 进入插件设置,点击 「📥 导入配置配对码」;
    • 粘贴配对码,输入刚才设置的保护 PIN 码,点击「解密并应用配置」;
    • 导入完成!所有鉴权凭据与远程目录配置自动就绪,立即可以开始双向同步。

第五步:日常同步与最佳配置推荐
  • 自动同步间隔:推荐设置为 600 ~ 900 秒(10~15 分钟),插件也支持最短 10 秒的高频自动同步。
  • 编辑防抖延迟:默认为 3 秒(最低支持 3 秒),等待用户一段文字输入停顿后由 Obsidian 正常完成物理写盘,避免打字期间高频发起网络请求。
  • 全量同步防频繁冷却:系统内置 10 秒冷却保护,短时间内连续点击状态栏不会重复触发全量扫描。
  • 移动端(Android / iOS)使用建议:
    • 手机端首次同步包含几千篇笔记时,请在 Obsidian 前台保持亮屏,避免系统锁屏休眠切断网络;
    • 建议将 Obsidian 加入手机系统的“电池优化白名单”(允许后台运行),保障同步顺畅。

第六步:冲突管理与可视化合并

如果两台设备在离线状态下编辑了同一篇笔记且内容不同,同步引擎会触发安全冲突保护机制,绝不武断覆盖任何一边的修改:

  1. 查看冲突:点击状态栏图标或进度卡片,打开「待处理冲突」列表;
  2. 比较并合并:点击进入双向 Diff 对比界面,支持直观查看逐行增删,并在下方编辑器中按需手动合并;
  3. 批量接受:也支持勾选多个文件,一键选择“全部接受本地版本”或“全部接受网盘版本”;
  4. 自动对齐:如果检测到两边实质内容文字完全相同,插件会在同步启动时自动消解冲突,无需手动干预。

❓ 常见问题排查 (FAQ)

remote-index.json 是当前设备的网盘目录缓存,不是笔记,也不是保存同步基线和待处理冲突的 sync-state.json。上次完整校验超过 24 小时、手动执行完整校验、缓存校验失败、账号或路径发生变化,或远端变更记录异常时,插件会重新扫描并更新索引缓存。更新缓存不意味着笔记或同步基线被删除。远端变更记录多时,首次核对可能需要较久;请保持手机亮屏前台,查看进度中的记录数。不要手动删除这些文件来加速同步。

新版在 .baidu-sync-index-v1/v2/ 中复用 device-<随机标识>.json:正常情况下每台设备、每个仓库使用一个日志文件,最多保存最近 64 批变更,且不超过 256 KiB(长路径或大批次可能提前轮换)。笔记开始写入前登记变更,操作结束后更新完成状态;多个设备使用不同文件,同一设备的日志写入按顺序执行。设备标识保存在 Obsidian 的本机存储中,复制 .obsidian 配置目录不会复制标识。

  • 旧的 *.begin.json / *.done.json 原样保留,新版不再为正常同步新增这些文件。已有文件数量不会自动减少,兼容旧设备时仍需枚举它们。
  • 单轮遇到超过 128 条需要下载的旧记录时,改用目录分页校验:扫描前已完成的成对记录直接作为边界,不逐个下载 JSON。如果仍有大量未完成记录,则本轮完整校验且不推进索引游标,后续继续检查实际目录,避免遗漏迟到写入。
  • 在线设备继续增量检查;离线太久、日志缺失或回滚时,会完整校验实际目录。过大的单批变更也会明确要求完整校验,不会截断路径后继续使用不完整索引。
  • 完整校验重新核对目录,不等于重新下载所有文件。原有同步基线、冲突和文件内容仍按同步规则处理。
  • 上传结果无法确认或写入中途崩溃时,会保留原日志并改用新标识,避免迟到请求覆盖新日志。这类异常、清除本机存储或新增设备可能留下额外文件;未完成记录继续复查,不自动删除。
  • 建议所有设备一起更新。旧版不能解析新日志时会回退完整目录校验,无法享受这项优化。新格式快照使用独立版本号,旧版不会误用缺少后续变更的缓存。

日志保存的是受影响路径,不是文件内容历史。这项优化不提供跨设备的同文件写锁,也不改变现有冲突处理规则。

界面中的文件检查数量不等于网络请求次数:目录查询每页最多返回 1,000 项,完整校验按目录、按页请求;文件状态在本地逐项比较。实际文件传输和传输前的远端复核另有请求,不包含在索引查询次数中。

不会全量重传。

  • 插件采用两阶段提交事务机制,断网只会让未传完的那一个文件失败并记录到日志中;
  • 之前已经传完的文件基准完好无损;
  • 网络恢复后再次同步时,引擎在 50ms 内快速完成比对,仅对刚才失败的那一个文件进行断点重传,不会重新上传未修改的文件。

这是插件的智能冲突自动对齐机制:

  • 双方文件都存在且内容 MD5 相同时,新一轮比较不会仅因修改时间不同而判为冲突。
  • 已登记的冲突在自动清理时,还会核对秒级修改时间;无法确认安全的副本会保留。
  • 如果一端文件不存在,则无法比较两端内容哈希。完整校验发现删除时会保留另一端并要求人工确认,避免误删。

主要有两个排查方向:

  1. 手机息屏休眠:移动设备在锁屏或切到后台后,系统电池策略可能会休眠网络。建议同步大批文件时保持前台亮屏;
  2. 代理分流或网络波动:检查是否有代理规则阻断了百度网盘开放平台域名,或在手机设置中将“专用 DNS (Private DNS)”暂时关闭后重试。

不需要。 插件内置了 OAuth 2.0 自动续期机制。在 Token 到期前,后台会自动携带 Refresh Token 换取新的凭据并静默保存,日常使用无需手动维护。


🌐 English Documentation

🌟 Project Mission & Core Values

The Obsidian community has many wonderful synchronization tools. Baidu Sync Safe is specifically designed for users who wish to use Baidu Netdisk as their primary cloud knowledge base storage, offering a native, robust, and safe synchronization experience:

  • 📦 Generous Free Cloud Storage: Utilize TB-scale storage on Baidu Netdisk for notes, large PDF research papers, audio recordings, and image attachments without storage anxiety.
  • 🚀 High-Speed Native Connectivity: Benefiting from high-speed domestic CDN nodes and the official Baidu Netdisk OpenAPI, uploads and downloads remain fast and stable across various network environments.
  • 📱 Tailored for Mobile Stability: Specially tuned for mobile hardware constraints, featuring chunked streaming and lightweight memory-first auditing to ensure smooth, responsive, and battery-friendly operation.
  • 🔐 Strict Data Integrity & Atomicity: Built with two-phase atomic write semantics to guarantee that unexpected network drops or process exits never corrupt user notes.

✨ Key Features

  1. ⚡ Zero-I/O Fast-Path Metadata Auditing
    • Utilizes in-memory mtime + size fingerprints. Unmodified notes require zero disk reads and zero hash calculations.
    • Auditing 2,800+ notes takes less than 50 milliseconds, keeping mobile devices cool with negligible CPU usage.
  2. 🛡️ HTTP Range 4MB Chunked Streaming (Smooth Mobile Large-File Transfers)
    • Downloads large attachments (PDFs, media files) in 4MB chunks via HTTP Range requests.
    • Limits transient memory consumption within safe bounds, ensuring smooth downloads on mobile devices.
  3. 🔄 Identical-Content Auto-Alignment & Duplicate Copy Cleanup
    • Automatically detects files with matching content hashes despite timestamp discrepancies, aligns the baseline, and silently cleans up redundant .conflict-... copies.
  4. 🎨 Unified Real-time Progress UI across Desktop & Mobile
    • Floating status card anchored at the bottom-right corner on desktop (380px), and bottom tab bar on mobile.
    • Displays current phase, progress bar, elapsed time, active filenames, and live transfer counts.
  5. 🎛️ Independent Upload & Download Concurrency (1–5 Workers)
    • Independently tune concurrency pools for upload and download (1 for conservative power saving, 3 for standard recommended, 4–5 for high-speed networks).
    • Pre-commit hash checks protect files edited while queued from accidental overwrite.
  6. 🔐 Optional AES-256-GCM End-to-End Encryption & One-Click Device Pairing
    • Enables client-side AES-256 encryption before uploading to cloud storage.
    • Export an encrypted pairing string (BDSYNC:v1:...) on desktop and import on mobile in seconds without repeating developer registration.

📖 Step-by-Step Setup Guide

Step 1: Installation
  • From GitHub Releases: Download main.js, manifest.json, and styles.css from the Latest Release and place them in <vault>/.obsidian/plugins/baidu-sync/. On Android, extract baidu-sync-2.0.2-mobile.zip directly into the plugins folder.
  • Via BRAT: Add minLaoGe/obsidian-baidu-netdisk-sync in the BRAT community plugin.
  • Enable Baidu Sync Safe in Obsidian Community Plugins.
Step 2: Register Baidu Developer Application (One-time on PC)
  1. Open the Baidu Netdisk Open Platform Console;
  2. Sign in with your Baidu account and complete free individual developer verification;
  3. Click "Create Application", choose "Software" / "Mobile/Desktop", and pick default basic permissions (basic, netdisk);
  4. Under "Development Info", copy your AppKey (Client ID) and AppSecret (SecretKey).
Step 3: Authorize & Connect
  1. In Obsidian settings, paste AppKey and AppSecret;
  2. Click "1. Get Web Auth Code", log in via browser, grant permissions, and copy the authorization code;
  3. Paste back into Obsidian, click "2. Exchange & Save Token";
  4. Click "Test Connectivity" to confirm your account is connected!
Step 4: Quick Multi-Device Pairing (PC → Mobile)
  1. On your primary PC: Go to plugin settings → "Export Encrypted Pairing Code", set a 6-digit PIN, and copy the string;
  2. On your mobile / second device: In plugin settings, click "Import Pairing Code", paste the code, enter your PIN, and click apply. Configuration and authentication tokens sync instantly!

🛠️ Developer & Internal Architecture Documentation

For complete technical specifications, crash-recovery protocols, and automated test suites, please refer to: 👉 DEVELOPER.md — 开发者与底层技术文档


📄 License & Acknowledgements

2.0.2:同步提示与文件时间

  • 点击同步立即显示“等待开始同步”,拿到执行机会后显示实际进度;后台任务不会自动打开窗口。
  • 无失败、无待处理冲突时,进度窗口在完成后 3 秒自动关闭;出现失败或剩余冲突时保留窗口。冲突全部处理后,空冲突窗口也会在 3 秒后关闭。进度中的冲突数是当前待处理数,日志保留本轮历史统计。
  • 新上传/重新上传的文件提交 local_mtime 和 local_ctime;下载优先恢复上传端的修改时间。网盘时间精度为秒,原始毫秒可能被截断。创建时间通过 Obsidian 写入选项尽力保留,受系统和适配器限制,不能保证 Finder/资源管理器的创建日期完全一致。
  • 历史云端文件如果没有保存过客户端时间,只能回退到网盘服务器修改时间。升级不会为了补时间重传所有内容,也无法恢复此前已经丢失的原始时间。