README file from
GithubWebDAVrSync
WebDAVrSync — lightweight, dependency-free two-way WebDAV sync for Obsidian.
Author: 撞强 · [email protected] · https://github.com/xztjhs
English
WebDAVrSync synchronizes your Obsidian vault with any standard WebDAV server
(Nextcloud, ownCloud, SFTPGo, Apache mod_dav, nginx-dav, …). It is a single
main.js file: no build step, no third-party runtime dependency, MIT licensed.
Highlights
- Two-way sync — upload, download and delete between the vault and the server.
- Append-only trash archive —
.trashis backed up and is never deleted by emptying your local trash. If a copy disappears from the server it is restored from the local vault, so the recycle bin works as a real safety net for deleted content. - Encrypted plugin config and secrets backup — collects every plugin's
data.json,manifest.jsonand other configuration files, plus Copilot's API keys from the Obsidian Keychain, encrypts them with AES-256-GCM + PBKDF2-SHA256 (210,000 iterations) and uploads a.wdrsbackupfile to.webdavrsync-backups/on your WebDAV server. - Conflict safety — both versions are kept by default, as
name (conflict YYYYMMDD-HHMMSS device).ext. A "keep newest" strategy is also available. - Selective sync — optional
.obsidianconfiguration sync, optional mirroring of empty directories, and glob-based ignore rules. - Byte-level verification of same-size files on the first sync, so identical files on both sides are not reported as conflicts.
- Flexible triggers — manual, interval, on start, and a few seconds after you stop editing. The status bar shows progress and can be clicked to sync now.
- Config export / import with or without the WebDAV password, to set up another machine quickly.
Install
- Open Settings → Community plugins → Browse, search for WebDAVrSync, install and enable it.
- Open the plugin settings and fill in the WebDAV URL, username and password.
- Click Test connection, then Sync now.
Manual install: download main.js and manifest.json from the
latest release, put them in
<vault>/.obsidian/plugins/webdavrsync/ and enable the plugin in
Settings → Community plugins.
Requirements
- Obsidian 1.4.0 or newer.
- A WebDAV server that supports
PROPFIND,PUT,GET,MKCOL,DELETEand HTTP Basic Auth. - Desktop only for now. Mobile support depends on whether the mobile
requestUrlimplementation allows custom methods such asPROPFIND; it has not been verified yet.
Notes
- Your WebDAV password is stored in plain text in this plugin's own
data.json. That folder is always excluded from sync. - The plugin does not implement a cross-device lock. Avoid editing the same file on two devices at the same time; the default "keep both" strategy preserves both versions.
Contact
- Author: 撞强
- Email: [email protected]
- Issues and feature requests: https://github.com/xztjhs/WebDAVrSync/issues
Licensed under the MIT License.
中文说明
一个轻量、开源、免费的 Obsidian 双向同步插件。只使用 WebDAV,不依赖 S3、Dropbox、OneDrive 等任何专有服务。
作者:撞强 · [email protected] · https://github.com/xztjhs
重要: 如果本仓库仍启用了 Remotely Save 或其他同步插件,请先停用它们。 两个同步插件同时写同一批文件会造成冲突。
- 无构建步骤、无第三方运行时依赖:
main.js即可直接运行。 - 支持 SFTPGo、Nextcloud、ownCloud、Apache mod_dav、nginx-dav 等标准 WebDAV 服务。
- 保留完整源码,MIT 许可证,可自由修改、分发、商用。
功能
- 本地仓库 ↔ WebDAV 双向同步(上传、下载、删除)。
- 手动同步、定时同步、启动时同步、编辑停止后自动同步。
- 冲突默认“保留双方”:较新版本保留原文件名,较旧版本保存为
文件名 (conflict 20261025-143000 设备名).扩展名。 - 可切换为“仅保留较新版本”。
- 关闭“删除同步”后,删除不会传播,已删除的一侧会从另一侧恢复。
- 可选择是否同步
.obsidian配置;本插件目录始终排除(避免密码上传)。 - 回收站(
.trash)默认一并备份,且是只增不删的存档:清空本地回收站不会删掉 远端备份;远端缺了会用本地补回。可随时关闭。 - 可选择是否在 WebDAV 上建立空目录,让浏览器端的目录结构与本地仓库一致。
- 首次同步或双方同时修改时,可逐字节校验同尺寸文件,减少误报冲突。
- 中文、空格、特殊字符路径按 URL 编码处理。
- 状态栏显示同步进度,点击状态栏可立即同步。
- 配置导出 / 导入:可导出含密码或不含密码的 JSON,在另一台机器快速恢复设置。
- 加密插件配置与密钥备份:包含所有插件
data.json、其他配置文件、Copilot Keychain API Key,以及其他插件明文 token/key。 - 详细图文步骤见 使用手册.md。
安装
方法一:复制文件夹(推荐)
把整个 webdavrsync 文件夹放到目标仓库:
<你的 Obsidian 仓库>/.obsidian/plugins/webdavrsync/
确保目录中有 manifest.json 和 main.js,然后:
- 打开 Obsidian → 设置 → 第三方插件(Community plugins)。
- 关闭“安全模式”(如果尚未关闭)。
- 在“已安装插件”中找到 WebDAVrSync,启用。
- 打开插件设置,填写 WebDAV 地址、用户名、密码、远程根目录。
- 点击“测试连接”,成功后点击“立即同步”。
方法二:PowerShell 安装脚本
在插件目录中运行:
.\install.ps1 -VaultPath "D:\我的Obsidian仓库"
如需连同本机配置(含密码)一起复制:
.\install.ps1 -VaultPath "D:\我的Obsidian仓库" -WithConfig
加 -Enable 会把插件写入目标仓库的 community-plugins.json(需要重启 Obsidian):
.\install.ps1 -VaultPath "D:\我的Obsidian仓库" -Enable
如果 Obsidian 正在运行,复制或启用后请重启 Obsidian,或执行命令面板中的 “Reload app without saving”。
把插件文件夹复制到另一台机器时,
data.json中的“文件对照表”属于原机器。 建议删除data.json后重新填写账号,或在插件设置中点击一次“重置同步状态”。
配置说明
| 设置 | 说明 |
|---|---|
| WebDAV 地址 | 例如 https://dav.example.com,可省略 http:// |
| 用户名 / 密码 | HTTP Basic Auth 凭据 |
| 远程根目录 | / 表示账号根目录;/obsidian 表示同步到该子目录(不存在会自动创建) |
| 设备名称 | 仅用于冲突文件名,例如 PC、Laptop |
| 同步间隔 | 分钟;0 表示关闭定时同步 |
| 启动时自动同步 | Obsidian 启动后约 4 秒执行一次 |
| 文件变更后自动同步 | 停止编辑约 8 秒后执行 |
| 删除同步 | 是否把删除传播到另一端 |
| 冲突处理 | 保留双方 / 仅保留较新版本 |
| 同步 .obsidian 配置 | 默认关闭;本插件目录始终排除 |
| 同步回收站(.trash) | 默认开启;开启时为“只增不删”的存档,关闭后回收站不参与同步 |
| 同步空目录 | 默认开启;关闭后不在 WebDAV 上建立空目录 |
| 内容校验 | 同尺寸文件逐字节比较,较慢但更安全 |
| 忽略规则 | 每行一个 glob:* 匹配一层,** 匹配任意层,# 注释 |
配置导出 / 导入
在插件设置最下方:
- 导出配置(含密码):生成
webdavrsync-config-YYYYMMDD-HHMMSS-with-password.json, 包含地址、账号、密码和全部同步设置,可直接在另一台机器导入。文件含明文密码, 请勿公开分享。 - 导出配置(不含密码):适合备份或分享;导入到已有配置时保留当前密码。
- 导入配置:选择导出的 JSON,也可以直接选择本插件目录下的
data.json。
导入时会弹窗显示目标服务器、远程根目录和密码处理方式,确认后才会应用。导入不会 自动同步,也不会导入“文件对照表”:
- 服务器或远程根目录发生变化 → 清空文件对照表,下次同步重新比较两端文件;
- 服务器和根目录未变化 → 保留现有文件对照表,只更新设置。
导入后请先点“测试连接”,确认无误再点“立即同步”。
插件配置与密钥备份(加密)
普通的 .obsidian 同步会复制各插件的 data.json,但 Copilot 的模型 API Key
不在 data.json 里:当前 Copilot 使用 Obsidian 的 OS Keychain / SecretStorage,
data.json 只保存 apiKeyKeychainId 引用。因此新增一个独立的加密备份功能。
在插件设置最下方“插件配置与密钥备份(加密)”中:
- 立即创建加密备份
- 读取所有插件(不含 WebDAVrSync 自己)的
data.json、manifest.json, 以及.json/.yaml/.toml/.ini/.conf/.env/.txt等配置文件; - 其他插件明文写在
data.json里的 token / key 会随配置文件一起进入备份; - 读取 Copilot 在 Obsidian Keychain 中的密钥,包括 provider 的
apiKeyKeychainId和copilot-v<vaultId>-...形式的模型/旧版密钥; - 可选“备份时包含插件代码”(
main.js、styles.css等); - 使用 AES-256-GCM + PBKDF2-SHA256(210,000 次) 加密;
- 备份文件同时下载到本机,并上传到 WebDAV 的
.webdavrsync-backups/文件夹(可在设置中修改,默认保留最近 10 个); - 密码不会保存;忘记密码无法恢复。
- 读取所有插件(不含 WebDAVrSync 自己)的
- 从本地文件恢复
- 选择
.wdrsbackup文件,输入密码,恢复插件配置和 Copilot 密钥。
- 选择
- 从 WebDAV 恢复
- 列出远端备份文件夹中的
.wdrsbackup,选择后输入密码恢复。
- 列出远端备份文件夹中的
恢复时会:
- 覆盖对应插件的
data.json/ 其他配置文件;如果备份包含插件代码,也会覆盖manifest.json和代码文件(不包含代码时不恢复manifest.json,避免版本不一致); - 覆盖前在每个文件旁生成
.pre-restore-*.bak(该模式已加入同步忽略,不会上传); - 把 Copilot 密钥写回 Obsidian Keychain;
- 备份中会记录
community-plugins.json/core-plugins.json供参考, 但恢复时不覆盖这两个启用列表,避免改变当前 Obsidian 的插件启用状态; - 完成后建议重启 Obsidian。
本功能不包含:
- WebDAVrSync 自己的
data.json(用“配置导出”备份它); - 其他插件使用 SecretStorage / IndexedDB / localStorage 保存、且未在
data.json中留下引用的密钥; - 插件之外的数据(笔记本身仍由普通同步处理;Copilot 保存成 Markdown 的聊天记录 也属于笔记)。
不包含插件代码时,目标机器应先安装相同或兼容版本的插件;需要完整迁移插件版本时, 可开启“备份时包含插件代码”。
备份密码只存在于你的记忆中。忘记密码时,备份文件无法解密。 备份文件虽然经过加密,仍建议放在可信的 WebDAV 服务器上,并使用 HTTPS。
注意: 加密备份不会改变普通
.obsidian同步的行为。当前syncConfig开启时, 各插件的data.json仍会以明文同步到 WebDAV。如果不希望明文上传插件配置, 请关闭“同步 .obsidian 配置”,或把.obsidian/plugins/*/data.json加入忽略规则, 然后使用本加密备份恢复插件配置和密钥。
同步逻辑
插件在 data.json 中维护一份“文件对照表”,记录每个文件上次同步时的:
- 本地修改时间与大小;
- 远端修改时间、大小与 ETag。
每次同步:
- 扫描本地文件(通过 Obsidian
DataAdapter,包括.obsidian等隐藏路径)。 - 通过 WebDAV
PROPFIND递归扫描远端文件。 - 按路径合并三份数据:本地、远端、上次同步状态。
- 只有一侧变化 → 传输该侧版本。
- 两侧都变化 → 按冲突策略处理。
- 一侧删除、另一侧未变化 → 按“删除同步”设置传播或恢复。
- 仅一侧存在、且没有历史状态 → 视为新文件,上传或下载。
- 首次遇到两侧同路径文件 → 比较大小;大小相同且开启内容校验时逐字节比较, 内容相同则直接标记为已同步。
冲突副本会同时保留在本地和远端,因此两台设备最终都能看到两个版本。
不会同步的内容
- 本插件目录
.obsidian/plugins/webdavrsync/(无论是否同步.obsidian)。 - 匹配“忽略规则”的路径。
- 默认忽略:
.obsidian/workspace.json、.obsidian/workspace-mobile.json、.webdavrsync-backups/、*.pre-restore-*.bak、任意层级的.git/与node_modules/、.DS_Store、Thumbs.db、*.tmp。 - 回收站
.trash/:默认会同步,并且只增不删(保证删除的内容仍有备份), 可在设置里关闭“同步回收站”。该开关优先于忽略规则里的.trash写法。 开启时清空本地回收站不会删除远端副本,远端的.trash相当于一份删除内容存档。 - 目录软链接本身不作为文件上传;它在远端对应的历史残留会被清理。
常见错误排查
| 现象 | 可能原因 |
|---|---|
无法连接 WebDAV ... 目标计算机积极拒绝 |
端口没有监听或被防火墙拦截。SFTPGo 在 Docker 中时,除了在 SFTPGo 里设置 WebDAV 端口,还必须在 Unraid/Docker 容器模板里发布同样的端口(例如 1080:1080/TCP)。 |
认证失败(HTTP 401) |
用户名或密码错误;SFTPGo 用户被禁用。 |
HTTP 405 Method Not Allowed |
地址指向了 SFTPGo 管理界面或其他 HTTP 服务,而不是 WebDAV 端口。 |
HTTP 404 |
远程根目录不存在且自动创建失败,检查账号权限。 |
| 能连接但同步报错 | 查看 Obsidian 开发者工具 Console 中的 [WebDAVrSync] 日志。 |
SFTPGo 默认 WebDAV 端口是 10080,管理界面默认是 8080。如果修改过端口,请同时检查
Docker 端口映射;只改 SFTPGo 内部端口而不同步修改容器映射,宿主机仍然无法访问。
安全说明
- 密码以明文形式保存在本插件目录的
data.json中。本插件目录已被强制排除同步。 - 发布源码或分享插件文件夹前,请删除
data.json;仓库中的.gitignore已忽略它。 - 建议只在可信局域网使用 HTTP;跨公网请使用 HTTPS 反向代理并配置强密码。
- 本插件不实现跨设备互斥锁。请避免两台设备在同一时刻修改同一个文件; 默认“保留双方”策略会把两个版本都留下。
已知限制
- 空目录不同步。
- 远端文件的修改时间是服务器
Last-Modified(通常是上传时间),不是原始本地 mtime;选择“仅保留较新版本”时可能受此影响。默认“保留双方”不受影响。 - 不做大小写不敏感文件系统的路径合并;Windows/macOS 上请避免仅大小写不同的文件名。
- 首次同步大仓库、且开启内容校验时,会比较同尺寸文件,耗时较长。
- WebDAV 服务必须支持
PROPFIND、PUT、GET、MKCOL、DELETE和 HTTP Basic Auth。 - 插件主要面向桌面版 Obsidian;移动版能否使用取决于该平台的
requestUrl是否允许PROPFIND等自定义方法。
开发与测试
插件是纯 CommonJS JavaScript,不需要打包。修改 main.js 后重启 Obsidian 即可。
测试使用 Bun:
cd <插件目录>
bun test tests/sync.test.js
测试会启动一个内存 WebDAV 服务器和一个模拟的 Obsidian DataAdapter,
覆盖上传、下载、冲突、删除、忽略规则、中文路径、配置导出导入、加密备份/恢复等场景。
版本历史
- 1.2.3(2026-11-14):文档合规版——README 改为英文在前、中文在后,新增
CONTRIBUTING.md;插件行为与 1.2.2 一致。 - 1.2.2(2026-10-29):回收站改为“只增不删”的存档——清空本地回收站不再删除远端 备份,远端缺失时用本地补回;另一台设备新放进回收站的文件照常下载。
- 1.2.1(2026-10-26):修复回收站内容不参与同步导致删除后无法找回; 修复目录软链接造成的远端残留卡死;修复本地 mtime 精度导致的重复上传; 新增“同步空目录”;加密备份上传后自动回读校验;新增命令面板备份入口。
- 1.2.0(2026-10-26):新增加密插件配置与密钥备份;包含 Copilot Keychain API Key、 其他插件明文 token/key;支持本地/WebDAV 恢复。
- 1.1.0(2026-10-26):新增配置导出 / 导入;连接失败提示更明确;补充使用手册。
- 1.0.0(2026-10-25):首个版本,双向同步、冲突副本、定时/自动同步、忽略规则。
完整记录见 CHANGELOG.md。
仓库与版本
- GitHub 仓库:https://github.com/xztjhs/WebDAVrSync
- Releases 页面提供每个版本的
main.js、manifest.json与说明: https://github.com/xztjhs/WebDAVrSync/releases - 版本标签:
1.0.0、1.1.0、1.2.0、1.2.1、1.2.2、1.2.3
安装(其他机器):
- 新建
<仓库>/.obsidian/plugins/webdavrsync/; - 从 Releases 下载
main.js和manifest.json(如果发布里有styles.css也一并下载)放进去; - 重启 Obsidian,在“第三方插件”里启用 WebDAVrSync。
也可以直接克隆源码:
git clone https://github.com/xztjhs/WebDAVrSync.git
# 把仓库内容复制到 <仓库>/.obsidian/plugins/webdavrsync/
源码仓库包含全部历史版本与 tests/sync.test.js(需要 Bun 运行)。
联系作者
- 作者:撞强
- 邮箱:[email protected]
- GitHub:https://github.com/xztjhs
问题反馈、功能建议欢迎提 Issue,或直接发邮件。
许可证
MIT,见 LICENSE。
文档与代码同样使用 MIT 许可证。英文说明见上方的 English 一节。