# 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](LICENSE)。