mirror of
https://github.com/sotashimozono/obsidian-remote-ssh.git
synced 2026-07-22 06:52:07 +00:00
docs: fix shadow-vault "mirrors/syncs" claims in index + first-connect (#429)
Two more docs carried the same misconception the compat guide did: - architecture/index.md: "local vault that mirrors remote", "creates a real vault and syncs files", and a "local storage grows / LRU evicts files not opened in N days" cost note (the ReadCache is in-memory and capped, not a growing on-disk mirror). - getting-started/first-connect.md: the connect explanation said it "mirrors the remote vault's files" and "watches both sides and syncs them" — restated as direct-to-remote, virtual notes, remote→local fs.watch only. Found by a full docs/en audit (architecture+api / user-facing / guides+ops+migration). Everything else verified accurate — notably architecture/shadow-vault.md §6.5 already described fs-direct readers as broken and the local mirror as a deferred (never-built) enhancement, which is the source of truth the drifted docs contradicted. Refs #429 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
52c1c5d5ba
commit
81dd966dbb
2 changed files with 8 additions and 8 deletions
|
|
@ -11,7 +11,7 @@ Design specs for the major subsystems — the **why** behind decisions, not just
|
|||
|
||||
| Doc | What it covers |
|
||||
|---|---|
|
||||
| [[shadow-vault\|Shadow vault]] | The "local Obsidian vault that mirrors remote" model — shadow lifecycle, file routing, sync events |
|
||||
| [[shadow-vault\|Shadow vault]] | The shadow-vault model (a local vault whose patched adapter serves the remote virtually) — lifecycle, file routing, change events |
|
||||
| [[perf\|Performance]] | Sync latency budget, perf bench, the per-merge baseline tracking on `perf-baseline` branch |
|
||||
| [[collab\|Collaboration]] | Multi-client editing, conflict handling, the per-client `.obsidian/user/<id>/` workspace partition |
|
||||
| [[release-pipeline\|Release & deploy pipeline]] | Two-channel release model, `release.yml` signing flow, sync workflow, branch-aware lint/version-check, plugin-side deploy lifecycle |
|
||||
|
|
@ -28,9 +28,9 @@ The daemon is the only thing that touches the actual vault files. The plugin nev
|
|||
|
||||
### "Shadow vault is a real local vault"
|
||||
|
||||
Obsidian's plugin API is opinionated about vault paths. Rather than forking Obsidian's vault layer to be remote-aware (a multi-month investment), the shadow vault model just creates a real vault on your local disk and syncs files. Every Obsidian feature works without modification.
|
||||
Obsidian's plugin API is opinionated about vault paths. Rather than forking Obsidian's vault layer to be remote-aware (a multi-month investment), the shadow vault model creates a real local vault but patches its adapter so every file op goes to the remote — the notes are never copied to local disk (only `.obsidian/` lives there). Every Obsidian feature works without modification.
|
||||
|
||||
The cost: storage on your local machine grows with what you have opened. The plugin keeps a hot cache of recently-touched files; LRU eviction frees space for files not opened in N days.
|
||||
The cost: file ops need the remote reachable and pay per-op SSH/RPC latency. An in-memory cache (capped) speeds re-reads of recently-touched files.
|
||||
|
||||
### v1.x stability promises
|
||||
|
||||
|
|
|
|||
|
|
@ -8,13 +8,13 @@ description: "What happens when you click Connect: SSH handshake, daemon auto-de
|
|||
|
||||
## The shadow vault model
|
||||
|
||||
obsidian-remote-ssh does not edit your remote files directly through Obsidian's vault layer. Instead it:
|
||||
obsidian-remote-ssh doesn't keep a synced copy of your vault — the remote is the single source of truth. Instead it:
|
||||
|
||||
1. Creates a **local shadow vault** under `~/.obsidian-remote/vaults/<profile-id>/`. This is a real Obsidian vault on your local disk.
|
||||
2. Mirrors the remote vault's files into that shadow vault (lazily — large files are fetched on first open).
|
||||
3. Watches both sides for changes and syncs them through the SSH-tunneled daemon RPC.
|
||||
1. Creates a **local shadow vault** under `~/.obsidian-remote/vaults/<profile-id>/` — a real Obsidian vault dir, but only `.obsidian/` config lives on disk.
|
||||
2. Patches that vault's file adapter so every read/write goes **directly to the remote** over the SSH-tunneled daemon (or SFTP). Your notes are served virtually — never copied to local disk.
|
||||
3. The daemon's `fs.watch` pushes remote changes back, so the file explorer and open editors update live (~1 s).
|
||||
|
||||
Result: Obsidian thinks it's editing a local vault. All Obsidian features (Dataview, Templater, Excalidraw, …) work because they ARE working against a local vault. The "remote-ness" lives in the sync layer, invisible to most plugins.
|
||||
Result: Obsidian thinks it's editing a local vault, so all features (Dataview, Templater, Excalidraw, …) work — but every file op actually hits the remote. (Plugins that bypass the vault API and use Node `fs` directly are the exception — see #429.)
|
||||
|
||||
See [[shadow-vault|Shadow vault architecture]] for the full design.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue