README file from
GithubWebDAV nas
一个轻量的 Obsidian WebDAV 同步插件 —— 桌面（Windows / macOS / Linux）与移动端（iOS / iPadOS / Android）通用。
基于 Obsidian 官方 requestUrl，不依赖任何第三方库。像连你家 NAS 一样直接同步笔记：不经过中转服务器，数据只在你自己的设备与存储之间流动。
目录
特性
| 能力 | 说明 |
|---|---|
| 三种方向 | 只上传 / 只下载 / 双向 |
| 两种传送方式 | 只传变动（增量，省时间） / 全部对齐（全量，强制一致） |
| 删除跟随方向 | 没有孤立的"删除开关"，删除行为由方向决定 |
| 自动同步 | 本地改动约 10 秒后自动跑；可选定时轮询（可关） |
| 无变化静默 | 没活干时一声不吭，绝不打扰写作 |
| 右上角通知 | 进度只走通知，不弹框打断 |
| 预览 | 动手前先看清要传/删哪些文件 |
| 防误删 | 删除占比超过阈值自动中止（阈值可调） |
| 诊断连接 | 一键生成报告（实际 URL / 原始返回 / 三方数值），换服务器排错利器 |
| 地址/目录自动去重 | 地址里已含文件夹名时不再重复拼接（群晖常见坑） |
| 密码密文保存 | 不以明文落盘，可随配置同步，换设备免手输 |
| 桌面 + 移动 | isDesktopOnly: false，手机端同样可用 |
安装
方式一：手动拷贝（推荐，零依赖）
- 下载本项目的三个文件：
main.js、manifest.json、styles.css - 放进你的库：
<你的库>/.obsidian/plugins/webdav-nas/
├── main.js
├── manifest.json
└── styles.css
- 打开 Obsidian →
设置→第三方插件→ 刷新 → 启用 WebDAV nas
方式二：BRAT（适合手机端 / 自动更新）
- 先从社区插件市场安装 BRAT
- BRAT 设置 →
Add a beta plugin→ 填入本仓库地址 - 自动安装并启用
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。