Obsidian Stats logoObsidian Stats

MeshSync

by 此沐
5
4
3
2
1
Score: 50/100
Install Code

Description

無伺服器區域網同步：自動發現、加密傳輸、亞秒更新。Server-free LAN sync with discovery, encryption, and sub-second updates.

Reviews

No reviews yet.

Stats

0
stars
24
downloads
0
forks
4
days
1
days
1
days
1
total PRs
0
open PRs
0
closed PRs
1
merged PRs
0
total issues
0
open issues
0
closed issues
7
commits

Latest Version

0.5.0
2 days ago

Changelog

See all version on GitHub

README file from

Github

Obsidian MeshSync

無伺服器的 Obsidian 局域網同步：自動發現設備，加密傳輸，變更後亞秒同步。

Server-free Obsidian sync over your LAN: automatic peer discovery, encrypted transfer, and sub-second change propagation.

核心功能 / Core features

  • 局域網直連 / LAN peer-to-peer: Mac、Windows 與手機直接互聯，無需雲端或中繼服務。Mac, Windows, and mobile devices connect directly without a cloud service or relay.
  • 自動發現 / Automatic discovery: 使用經過簽名的 UDP 組播訊息尋找同一局域網內的設備；組播被系統或 VPN 阻擋時會改用 Wi-Fi 定向廣播。Finds peers using signed UDP multicast, with physical-LAN directed broadcast fallback when multicast is blocked by the OS or a VPN.
  • 快速同步 / Fast sync: Obsidian 建立或修改檔案後，經 80 ms 防抖立即推送。Pushes file creates and changes after an 80 ms debounce.
  • 加密傳輸 / Encrypted transfer: 透過持久 TCP 連線傳輸，訊息使用 AES-256-GCM 加密。Uses persistent TCP connections with AES-256-GCM encrypted messages.
  • 離線追趕 / Catch-up: 手機離開網路期間可以繼續修改；回到電腦所在局域網並恢復 Obsidian 後，自動重連並補齊較新的檔案。A phone can be edited while away, then reconnect and catch up newer files after returning to the desktop LAN and resuming Obsidian.
  • 可視化狀態 / Visible status: 獨立面板顯示掃描、TCP 連接、加密驗證、已連設備、同步方向、檔案進度與版本決策。A dedicated panel shows discovery, TCP connection, authentication, connected devices, transfer direction, file progress, and version decisions.
  • 閱讀狀態 / Reading state: 捲動位置與標題／清單展開收起狀態可在裝置間同步；離線裝置重新連線後會自動補齊。Scroll positions and heading/list fold states sync between devices and catch up after reconnecting.
  • 可靠續傳 / Reliable resume: 接收端逐檔確認，失敗自動重試三次；重新連線後跳過已一致的檔案，進度保留完整總數。The receiver acknowledges every file, failed files retry up to three times, and reconnects skip matching files while preserving whole-job progress.
  • 白名單與黑名單 / Include and exclude filters: 可只同步選定的單一檔案或資料夾，也可排除任意檔案或資料夾。Synchronize only selected files or folders, and exclude any file or folder from both directions.

目前範圍 / Current scope

目前支援 macOS、Windows、Android 與 iOS 的 Obsidian 插件入口。電腦會提供手機橋接服務；QR 配對會帶入電腦在目前局域網的位址、Port 與 Sync Key。首次配對先以電腦建立一次安全基線，完成後自動進入雙向同步。後續修改按每個檔案的修改時間選擇較新版本；刪除以帶時間的墓碑傳播，對端舊檔會移入可恢復隔離區。衝突副本、手機背景常駐及手機間直連仍在規劃中。

The plugin entrypoint supports Obsidian on macOS, Windows, Android, and iOS. A desktop provides the mobile bridge, while QR pairing supplies its current LAN address, port, and sync key. The first pairing loads one safe desktop baseline and then enables two-way sync automatically. Later changes are resolved per path by modification time. Timestamped deletion tombstones move stale counterparts into a recoverable quarantine. Conflict copies, mobile background operation, and phone-to-phone connections remain planned work.

手機設定 / Mobile setup

  1. 在電腦與手機開啟同名 vault，安裝並啟用相同版本的 MeshSync。0.5.0 使用閱讀狀態協議 6，會拒絕舊協議。
  2. 電腦打開 MeshSync 狀態面板，點 Pair mobile，手動選擇首次同步以電腦或手機為最新基準，再顯示 QR code。
  3. 手機使用系統相機掃描，再在 Obsidian 點 Pair safely。Vault、電腦 IP、Port 和 Sync Key 會一次套用。
  4. 首次配對時面板會顯示你指定的基線方向與逐檔結果。基線完成後，插件自動切換成雙向同步；後續無需手動選方向。

如果手機相機不直接打開 obsidian://，在電腦點 Copy pairing link，透過你信任的方式傳到手機後點擊。QR 和連結包含 Sync Key，只應在可信環境中展示或傳送。

When the phone leaves the LAN, edits remain in its local vault. After the phone returns to the desktop network and Obsidian is opened or resumed, MeshSync reconnects and exchanges manifests automatically.

MeshSync 會排除 VPN 與虛擬網卡，將電腦端探索、TCP 傳輸、手機橋接和 QR 位址綁定到實體 Wi-Fi／Ethernet 的私有 IP。電腦切換網路後會自動重新綁定。手機開啟全域 VPN 時，請在 VPN 設定中允許區域網路；行動端 WebSocket 使用系統網路棧，外掛無法改寫系統 VPN 路由。

MeshSync excludes VPN and virtual adapters and binds desktop discovery, TCP transfer, the mobile bridge, and QR addresses to the private IP of physical Wi-Fi/Ethernet. It automatically rebinds after a desktop network change. With a full-tunnel phone VPN, enable local-network access in the VPN settings because the mobile WebSocket follows the system network route.

隱私與網路 / Privacy and network use

  • 插件只與目前局域網內的設備通訊，不使用雲端、中繼、分析、廣告或遙測。The plugin communicates only with peers on the current LAN and uses no cloud service, relay, analytics, advertising, or telemetry.
  • 桌面發現封包的 IPv4 multicast TTL 為 1；手機橋接使用局域網 WebSocket；檔案清單與內容均以 AES-256-GCM 加密。Desktop discovery uses IPv4 multicast with a TTL of 1; the mobile bridge uses a LAN WebSocket; manifests and contents are encrypted with AES-256-GCM.
  • 插件只讀寫目前開啟的 vault，並排除 Obsidian 設定目錄、垃圾桶、Git metadata 與自身狀態目錄。It reads and writes only the open vault, excluding Obsidian's settings directory, trash, Git metadata, and its own state directory.
  • 發現封包包含設備名稱與經驗證的 vault identifier，不包含 vault 內容或同步密鑰。Discovery packets contain a device name and authenticated vault identifier, never vault contents or the shared sync key.

開發 / Development

npm install
npm run check

Obsidian Release 附件為 main.js、manifest.json 與 styles.css；versions.json 保留在倉庫中供版本相容性記錄使用。

The Obsidian release attachments are main.js, manifest.json, and styles.css; versions.json remains in the repository as the compatibility record.

授權 / License

MeshSync 依照 GNU General Public License v3.0 發佈。

MeshSync is released under the GNU General Public License v3.0.

Sponsors