WebDAV nas

一个轻量的 Obsidian WebDAV 同步插件 —— 桌面（Windows / macOS / Linux）与移动端（iOS / iPadOS / Android）通用。

基于 Obsidian 官方 requestUrl，不依赖任何第三方库。像连你家 NAS 一样直接同步笔记：不经过中转服务器，数据只在你自己的设备与存储之间流动。

---

目录

• 特性
• 安装
• 配置
• 同步方向 × 传送方式
• 常见场景怎么操作
• 支持的服务器与地址填法
• 关于密码
• 排错
• 自建环境
• 开发与发布
• 许可

---

特性

能力	说明
三种方向	只上传 / 只下载 / 双向
两种传送方式	只传变动（增量，省时间） / 全部对齐（全量，强制一致）
删除跟随方向	没有孤立的"删除开关"，删除行为由方向决定
自动同步	本地改动约 10 秒后自动跑；可选定时轮询（可关）
无变化静默	没活干时一声不吭，绝不打扰写作
右上角通知	进度只走通知，不弹框打断
预览	动手前先看清要传/删哪些文件
防误删	删除占比超过阈值自动中止（阈值可调）
诊断连接	一键生成报告（实际 URL / 原始返回 / 三方数值），换服务器排错利器
地址/目录自动去重	地址里已含文件夹名时不再重复拼接（群晖常见坑）
密码密文保存	不以明文落盘，可随配置同步，换设备免手输
桌面 + 移动	isDesktopOnly: false，手机端同样可用

---

安装

方式一：手动拷贝（推荐，零依赖）

1. 下载本项目的三个文件：main.js、manifest.json、styles.css
2. 放进你的库：

<你的库>/.obsidian/plugins/webdav-nas/
├── main.js
├── manifest.json
└── styles.css

3. 打开 Obsidian → 设置 → 第三方插件 → 刷新 → 启用 WebDAV nas

方式二：BRAT（适合手机端 / 自动更新）

1. 先从社区插件市场安装 BRAT
2. BRAT 设置 → Add a beta plugin → 填入本仓库地址
3. 自动安装并启用

iOS / iPadOS 提示：系统「文件」App 没有"显示隐藏文件"开关，.obsidian 是隐藏目录。推荐用 BRAT，或用电脑操作（macOS：⌘⇧G 跳转到 iCloud 里 Obsidian 的容器目录）。

---

配置

设置 → WebDAV nas：

字段	说明	示例
服务器地址	WebDAV 的入口地址	https://nas.example.com:5006/WebDAV
用户名	WebDAV 账号	your-name
密码	WebDAV 密码（以密文保存）	••••••
远端目录	要同步到的子目录，留空 = 地址指向的根	知识库
同步方向	只下载 / 只上传 / 双向	只上传
「立即同步」的方式	手动点同步时按哪种方式传	全部对齐
删除保护阈值(%)	一次同步里删除占比超此值就中止	30
本地改动后自动同步	改动约 10 秒后自动跑一次	开
定时轮询间隔（分钟）	额外定时兜底；0 = 关闭	0
同步 .obsidian 配置目录	是否连带同步插件/主题配置（默认关）	关
排除规则	逗号分隔的目录名或路径前缀	.trash, 私人

---

同步方向 × 传送方式

方向决定数据往哪流（删除也跟着它）；传送方式决定"只动变动的"还是"整体对齐"。两者组合出 6 种清晰行为：

	只传变动（更新）	全部对齐（全量）
只下载	只把云端改过的拉到本地 （本地改写的不会被覆盖）	云端全部覆盖本地 （本地改乱了 → 一键还原）
只上传	只把本地改过的推上去	本地全部刷新到云端 （缺的新增、有的更新）
双向	两边各自增量合并	每个文件取较新的一方

删除行为（跟随方向）

方向	云端删了	本地删了
只下载	删本地	从云端补回
只上传	从本地补传	删云端
双向	删本地	删云端

自动同步永远用「只传变动」——只增不覆盖，绝不打扰你正在写的内容。 **手动点「立即同步」**用设置里的方式（默认「全部对齐」）。

---

常见场景怎么操作

你的情况	怎么设置
主电脑写作，同步到云端	方向【只上传】，自动同步会把改动推上去
辅助设备只读，不想动云端	方向【只下载】+ 方式【只传变动】
辅助设备改乱了，想恢复云端版本	点「立即同步」（默认全部对齐）或「强制对齐」
云端被清空了，想从本地恢复	方向【只上传】→ 点「立即同步」，会补传回去
换了新设备，要全量拉取	方向【只下载】→ 点「强制对齐」
只想先看看会动什么	命令面板 →「预览（不修改文件）」

---

支持的服务器与地址填法

规则：插件把「地址 + 远端目录」拼起来当根，所以别填重了（插件会自动识别并去重，但规范填法更清晰）。

服务	地址	远端目录	实际访问
飞牛 fnOS	https://nas.example.com:5006/WebDAV	知识库	.../WebDAV/知识库 ✅
群晖 DSM	https://nas.example.com:5006/WebDAV	obsidian	.../WebDAV/obsidian ✅
Nextcloud	https://cloud.example.com/remote.php/dav/files/<用户名>	obsidian	.../files/<用户名>/obsidian ✅
通用	地址填到你想同步的父目录	填子目录名（或留空）	—

⚠️ 中文目录名的坑：部分服务器/反向代理不解码 URL 中的 %XX 中文路径（例如群晖某些配置），会导致 404。若遇到，把服务器上的文件夹改成英文名即可。 插件在 404/409 时会直接提示这一点。

---

关于密码

密码以密文保存在 data.json 里（不是明文），因此你可以把配置文件一起同步到云端，换设备后直接能用，无需重新输入。

⚠️ 安全边界：解密密钥内置在插件源码中，所以这属于「防明文暴露」级别，不是密码学意义上的强加密。 它能做到：明文密码不会出现在云端文件列表/日志里；密钥或密文被改动时能被检测出来。 它做不到：防住同时拿到「插件源码 + data.json」的人，也不能防止他人复制本插件。

如果你希望更强的保护，建议：不要把 data.json 放进不可信的同步盘，或使用独立的 WebDAV 子账号（最小权限）。

---

排错

现象	原因 / 处理
401	用户名/密码不对（注意大小写、全角字符、末尾空格）
404 / 409	「远端目录」拼错、填重，或服务器不解码中文路径（改用英文目录名）
424 / 207 异常	反向代理配置问题（检查 proxy_pass 尾部斜杠、放行 PROPFIND 等方法）
提示"地址里已包含 XX，已自动忽略"	地址与远端目录填重了，插件已自动处理，可无视
明明改了却不同步	跑一次「诊断」看【同步判定诊断】的 L/R/S 三方数值；必要时点「重置基线」
想看清到底发了什么请求	设置 → 「诊断」，报告可一键复制
手机端看不到 .obsidian	iOS 无"显示隐藏文件"开关；用 BRAT 安装，或用电脑操作

---

自建环境

本插件在以下自建环境实测通过：

• 飞牛 fnOS + 内置 WebDAV（https://域名:5006/WebDAV）
• 群晖 DSM + WebDAV Server 套件（建议英文目录名）
• 通用 WebDAV（Nginx 反代亦可，注意放行 PROPFIND / PROPPATCH / MKCOL / COPY / MOVE / LOCK / UNLOCK）

---

许可

MIT License —— 详见 LICENSE。