Hotdry.
归档
systems

Obsidian Sync 无头客户端：CLI 同步与自动化部署参数

Obsidian Sync headless client 实现无 GUI 的 Markdown 笔记同步，提供安装步骤、CLI 参数、连续同步配置及生产监控要点。

Obsidian Sync 无头客户端（obsidian-headless）是 Obsidian 官方推出的开源工具，允许在命令行环境中直接同步 Markdown 笔记库，而无需运行桌面 GUI 应用。这对于服务器自动化、CI/CD 管道、AI 代理访问知识库等场景尤为实用。它利用 Obsidian Sync 的核心引擎，提供端到端加密（E2EE）、高速度和隐私保护，支持 headless 环境如 Linux 服务器或 Docker 容器。

安装与环境准备

首先，确保系统安装 Node.js 22 或更高版本。使用 nvm 或官方包管理器安装，例如在 Ubuntu 上：

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

全局安装客户端：

npm install -g obsidian-headless

验证安装：ob --version，应输出版本号。该工具体积轻量，仅依赖核心 sync 模块，无需 Electron 或浏览器。

认证与 Vault 初始化

认证是第一步。交互式登录：

ob login

系统会提示输入 Obsidian 账户邮箱、密码及 MFA 码（若启用）。登录成功后，可用 ob login 查看账户信息。为非交互环境（如 CI），设置环境变量：

export OBSIDIAN_AUTH_TOKEN="your-auth-token"

列出远程 vault：

ob sync-list-remote

输出 JSON 格式，包括 vault ID、名称、共享状态和加密类型。选择一个 vault 初始化本地同步：

cd /path/to/local/vault
ob sync-setup --vault "My Vault Name" --device-name "server-sync" --config-dir ".obsidian"

此命令创建本地 .obsidian/sync 配置，输入 E2EE 密码（若适用）。首次 setup 会下载远程变更，确保本地目录为空或备份现有文件。

基本同步与参数优化

单次同步：

ob sync --path /path/to/vault

默认检测当前目录。添加 --continuous 实现文件监视模式：

ob sync --continuous

此模式使用 fs.watch 监听变更，每 5 秒轮询一次（可通过 NODE_ENV 调整）。生产中，推荐 Docker 部署：

FROM node:22-alpine
RUN npm install -g obsidian-headless
WORKDIR /vault
CMD ["ob", "sync", "--continuous"]

构建镜像，挂载卷 -v /host/vault:/vault，环境变量注入 token。同步参数包括冲突策略：--conflict-strategy merge 优先合并 Markdown 变更，避免覆盖。文件类型过滤：

ob sync-config --file-types "image,pdf" --excluded-folders "attachments/temp"

仅同步图片和 PDF，排除临时文件夹。配置同步范围：

ob sync-config --configs "core-plugin,community-plugin"

仅同步插件数据，减少带宽。

连续同步与自动化清单

为实现高可用，结合 cron 或 systemd 服务运行。systemd 示例 /etc/systemd/system/obsidian-sync.service：

[Unit]
Description=Obsidian Sync Headless
After=network.target

[Service]
Type=simple
User=obsidian
WorkingDirectory=/vault
Environment=OBSIDIAN_AUTH_TOKEN=xxx
ExecStart=/usr/local/bin/ob sync --continuous
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

启用：systemctl enable --now obsidian-sync。监控要点：

  • 健康检查：ob sync-status 输出 last-sync 时间、pending changes。若 >30min 未更新，重启服务。
  • 日志：ob sync --continuous > /var/log/obsidian-sync.log 2>&1，grep "conflict|error"。
  • 阈值：pending changes >50 触发警报；带宽 >10MB/min 视为异常。
  • 回滚：ob sync-unlink 断开，恢复 git 备份。

脚本示例（aggregate daily notes）：

#!/bin/bash
ob sync
# 处理 daily notes
find . -name "2026-03-01.md" -exec cat {} \; > weekly-summary.md
ob sync

Cron 每日 00:01 执行。

生产部署参数与风险控制

关键参数：

  • --device-name：唯一标识，版本历史中追踪变更源。
  • --region：指定 sync 服务器区域，降低延迟（默认自动）。
  • E2EE 密码：使用 Vaultwarden 或 AWS SSM 存储，避免硬编码。

风险：

  1. Beta 阶段，可能冲突解析不完善。限制造成 git 作为 fallback，每日全量备份。
  2. Token 泄露：使用最小权限账户，定期轮换（ob logout）。
  3. 资源：连续模式 CPU <5%，内存～50MB。Docker 限 256MB。

监控集成 Prometheus：暴露 /metrics 端点，自定义 exporter 刮取 sync-status。

用例落地：AI 代理访问。将 vault 同步到 server，暴露 REST API 查询笔记。团队共享：多设备 --device-name 区分，冲突用 merge。

此工具填补 Obsidian 在 headless 场景空白，结合 Sync 优势，实现可靠笔记自动化。

资料来源

（正文约 950 字）

查看归档