Skip to content

README.md

Latest commit

 

History

History
107 lines (72 loc) · 4.65 KB

README.md

File metadata and controls

107 lines (72 loc) · 4.65 KB

Secure WebDAV Images / 安全 WebDAV 图片

Obsidian plugin that stores note images in a dedicated WebDAV folder and syncs the rest of the vault to a separate remote notes folder using three-way comparison version sync.

将笔记图片存储到独立的 WebDAV 图片目录，并通过三向对比版本同步将其他 vault 内容同步到独立的远端笔记目录。

Features / 功能

  • Image separation / 图片分离：本地图片上传到远端图片目录后自动删除，笔记中以 secure-webdav 代码块引用远端图片
  • Three-way comparison sync / 三向对比同步：基于 local × remote × prevSync 状态矩阵的增量版本同步，覆盖创建、修改、删除、重命名、移动等全部操作
  • Automatic sync / 自动同步：可配置定时自动同步间隔
  • Image compression / 图片压缩：可配置的 JPEG 压缩参数（质量、最大尺寸、阈值）
  • One-time migration / 一次性迁移：将旧笔记中的 ![](...) 和 ![[...]] 本地图片引用批量转为远端引用
  • Conflict backup / 冲突备份：双端同时修改时自动创建 .sync-conflict-* 本地副本，保留双方内容供人工合并

Storage Model / 存储模型

远端目录 用途
Image remote folder / 图片远端目录 存储上传的图片文件
Remote notes folder / 笔记远端目录 存储 Markdown 笔记和非图片附件
  • 图片上传成功后，本地图片文件被删除，笔记中替换为 secure-webdav 代码块
  • 笔记同步采用全量本地 + 远端双向同步模式，本地保留完整笔记内容

Sync Mechanism / 同步机制

采用与 remotely-save V3 一致的三向对比算法：

  1. collectEntities — 收集本地文件、远端文件、上次同步记录（prevSyncRecords）
  2. computeDecision — 4×4 决策矩阵覆盖 16 种状态组合（LOCAL_NEW/DELETED/MODIFIED/UNCHANGED × REMOTE_NEW/DELETED/MODIFIED/UNCHANGED）
  3. executeDecisions — 执行推送/拉取/删除/冲突备份
  4. persistPrevSyncRecords — 持久化本轮同步状态作为下次对比基线

文件身份由内容哈希（SHA-256 前 16 位 hex）确定，签名格式为 mtime:size:contentHash16。

所有同步入口（手动、自动、ribbon）统一调用 syncVaultContent 方法。

Settings / 设置

Connection / 连接

  • WebDAV Base URL — WebDAV 服务器地址
  • Username / 用户名
  • Password / 密码
  • Image Remote Folder / 图片远端目录
  • Remote Notes Folder / 笔记远端目录
  • Excluded Sync Folders / 排除同步目录 — 不同步到远端的本地目录

Sync / 同步

  • Auto Sync Interval / 自动同步频率 — 分钟数，设为 0 禁用自动同步
  • Naming Strategy / 命名策略 — 远端图片文件命名方式（hash / 保留原名）

Image Compression / 图片压缩

  • Compress Images / 压缩图片
  • Compress Threshold / 压缩阈值（KB）
  • Max Image Dimension / 最大图片尺寸（px）
  • JPEG Quality / JPEG 质量（1-100）

Other / 其他

  • Auto Update Check Interval / 自动更新检查间隔（小时）
  • Language / 语言（auto / en / zh-cn）
  • Max Retry Attempts / 最大重试次数
  • Retry Delay / 重试间隔（秒）

One-time Tools / 一次性工具

  • Run Migration / 执行迁移 — 将旧笔记中的 Obsidian 本地图片引用批量迁移为远端引用

Commands / 命令

命令 说明
Upload local images in current note to WebDAV / 上传当前笔记中的本地图片到 WebDAV 仅转换当前笔记的图片引用
Test WebDAV connection / 测试 WebDAV 连接 执行 PUT / GET / DELETE 链路验证
Sync vault content to WebDAV / 同步内容到 WebDAV 手动触发全量三向对比同步

Ribbon 图标（🔄）点击执行同步。

Installation / 安装

From GitHub Releases / 从 GitHub Releases 安装

  1. 从 Releases 页面下载最新版 main.js、manifest.json、styles.css
  2. 将三个文件复制到 vault 的 .obsidian/plugins/secure-webdav-images/ 目录
  3. 在 Obsidian 设置中启用插件

From Source / 从源码构建

npm install
npm run build
npm run release:local   # 同步到本地 Obsidian 插件目录（需设置 OBSIDIAN_PLUGIN_DIR 环境变量）

Security Notes / 安全说明

  • data.json 包含 WebDAV 凭据（密码明文），切勿提交到 Git
  • 图片上传使用内容哈希命名可避免文件名碰撞和信息泄露
  • WebDAV 连接使用 Basic Auth，建议通过 HTTPS 连接服务器

License / 许可

MIT