首页 > 专题 > Obsidian知识库 > 文章详情
返回 Obsidian知识库

5、Obsidian Headless 服务器常驻同步方案

2026年05月05日 31 阅读 Obsidian知识库

第5篇｜Obsidian Headless 服务器常驻同步方案

预计阅读时间：25分钟
核心目标：在服务器/树莓派上常驻运行 Obsidian 同步服务，让 Agent 持续维护 Wiki，同时桌面端实时看到更新

5.1 为什么需要 Headless 模式？

典型场景：

[你的开发服务器/树莓派]          [你的 MacBook/PC]
      │                                │
   Agent 持续写入 wiki/           Obsidian 打开 vault
   （用 Hermes 自动维护）           实时看到更新
      │                                │
      └────────── Obsidian Sync ────────┘
                    （云端同步）

好处：

  • 24/7 不间断维护：Agent 可以随时写入 wiki，不用等你打开电脑
  • 数据在本地：不依赖 Notion 等云服务，Obsidian Sync 只做同步通道
  • 多设备同步：手机、平板、办公室/家里电脑都能看到同一份 wiki

5.2 前置条件

| 需求 | 说明 |
|------|------|
| Node.js ≥ 18 | obsidian-headless 基于 Node.js |
| Obsidian Sync 订阅 | $4/月，跨设备同步的核心 |
| 一个 Obsidian 账号 | 用于登录 Sync |

⚠️ obsidian-headless 官方说明需要 Obsidian Sync 订阅（不是免费服务）。如果你不想付费，也可以用 iCloud/ Dropbox/ Git 方案替代同步功能，但无法使用 ob sync --continuous。

5.3 安装 obsidian-headless

5.3.1 Node.js 环境检查

node --version
# v22.x.x ✅
# v16.x.x ❌ 需要升级

如果没有 Node.js：

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

5.3.2 全局安装

npm install -g obsidian-headless

验证：

ob --version
# obsidian-headless v1.x.x ✅

5.4 登录 Obsidian 账号

ob login --email "your@email.com" --password 'your-password'

输出：

✅ Login successful
   Vault sync enabled
   Email: your@email.com

⚠️ 密码包含特殊字符时用单引号包裹，避免 shell 转义问题。

5.5 创建远程 Vault 并连接

5.5.1 方式一：新建远程 Vault

# 创建一个名为 "llm-wiki" 的远程 vault
ob sync-create-remote --name "llm-wiki"

输出：

✅ Remote vault created
   Vault ID: vault-a1b2c3d4e5f6
   Name: llm-wiki

5.5.2 方式二：关联已有本地 Vault

如果你已经有本地 Vault（比如 ~/wiki），直接进入那个目录初始化：

cd ~/wiki
ob sync-setup --vault "vault-a1b2c3d4e5f6"

这会在 ~/wiki/.obsidian/sync.json 里写入同步配置。

5.6 首次同步

cd ~/wiki
ob sync

首次运行会：

  1. 扫描所有本地文件
  2. 上传元数据到 Obsidian Sync
  3. 等待远程 vault 的确认
🔄 Syncing...
   Uploaded: 247 files
   Downloaded: 0 files
✅ Sync complete (took 12s)

5.7 持续同步（后台常驻）

5.7.1 前台运行（测试用）

cd ~/wiki
ob sync --continuous

会看到实时输出：

🔄 Continuous sync enabled
   Watching for changes...
   [2026-05-04 14:23:01] + new file: concepts/attention.md
   [2026-05-04 14:25:33] ~ modified: entities/gpt4.md
   [2026-05-04 14:30:00] + new file: entities/openai.md

按 Ctrl+C 停止。

5.7.2 systemd 服务（推荐用于服务器）

在服务器上，前台运行会在 SSH 断开后终止。用 systemd 管理才能常驻。

创建服务文件

mkdir -p ~/.config/systemd/user

# ~/.config/systemd/user/obsidian-wiki-sync.service
[Unit]
Description=Obsidian LLM Wiki Sync
After=network-online.target
Wants=network-online.target
# 如果想在网络差的环境工作可以去掉 network 依赖

[Service]
ExecStart=/usr/local/bin/ob sync --continuous
WorkingDirectory=/home/YOUR_USER/wiki
Restart=on-failure
RestartSec=10
# 日志输出到 journalctl
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

💡 用 which ob 确认路径，可能是 /usr/bin/ob 或 ~/.npm-global/bin/ob。

启用服务

# 重载 systemd 配置
systemctl --user daemon-reload

# 开机自启
systemctl --user enable --now obsidian-wiki-sync.service

# 检查状态
systemctl --user status obsidian-wiki-sync.service

输出：

● obsidian-wiki-sync.service - Obsidian LLM Wiki Sync
     Loaded: loaded (/home/user/.config/systemd/user/obsidian-wiki-sync.service; enabled)
     Active: active (running) since Mon 2026-05-04 14:00:00 CST; 2h 30min ago
   Main PID: 12345 (ob)
     CGroup: /user.slice/user-1000.slice/user@1000.service/obsidian-wiki-sync.service
             └─12345 /usr/local/bin/ob sync --continuous

✅ 绿色 active (running) 说明正常运行中。

常用运维命令

# 查看实时日志
journalctl --user -u obsidian-wiki-sync.service -f

# 重启服务
systemctl --user restart obsidian-wiki-sync.service

# 停止服务
systemctl --user stop obsidian-wiki-sync.service

# 查看服务是否开机自启
systemctl --user list-dependencies obsidian-wiki-sync.service

开机自启生效条件

systemd user 服务的开机自启依赖于 logind 的 linger 机制：

# 开启 linger（必须执行，否则 SSH 断开后服务会停止）
sudo loginctl enable-linger $USER

5.8 无网络时的行为

Obsidian Headless 在网络中断时的行为：

| 场景 | 行为 |
|------|------|
| 网络临时断开 | 等待重试，每 10 秒一次 |
| 文件在离线期间被修改 | 下次连接后自动 merge（Obsidian Sync 的冲突处理）|
| --continuous 期间 SSH 断开 | systemd 保持服务运行，网络恢复后继续同步 |
| 长时间离线（>30天）| Obsidian Sync 可能会提示需要手动确认 |

5.9 与 Git 方案对比

除了 Obsidian Sync，还有一些免费替代方案：

| 方案 | 优点 | 缺点 |
|------|------|------|
| Obsidian Sync（官方） | 原生集成，冲突处理好 | $4/月 |
| iCloud Drive | 免费，macOS 原生 | 只适合 Apple 全家桶 |
| Git (git-grain/obsidian-git) | 免费，版本控制强 | 需手动提交/推送 |
| Syncthing | 免费，P2P 局域网 | 跨网络需要公网 relay |

如果你已经在用 Git 管理 wiki，可以用 obsidian-git 插件 + CI/CD 自动推送，但 ob sync --continuous 的实时性更好。

5.10 桌面端查看同步状态

Obsidian 桌面端会自动同步，不需要额外操作。状态栏显示：

🔄 Syncing...  (灰色 = 同步中)
✅ All files synced  (绿色 = 同步完成)
⚠️ Offline  (红色 = 离线)

只要你的桌面端和服务器登录的是同一个 Obsidian 账号，vault 内容会实时保持一致。

5.11 小结

  • obsidian-headless 让服务器/树莓派能常驻运行 Obsidian 同步
  • ob sync --continuous 实时监控文件变化并同步
  • systemd + linger 实现开机自启和断网恢复
  • Obsidian Sync 是唯一支持 --continuous 的同步方式（付费 $4/月）
  • Git/iCloud/Syncthing 是免费替代方案，但功能折损

下一篇预告：第6篇我们将讲解 Agent 自动化 Ingest 工作流——如何让 AI Agent 自动完成来源灌入、实体抽取、wikilinks 生成，以及如何设计批量处理管道避免 wiki 爆炸。

Obsidian