Obsidian Headless

版本说明

Obsidian Headless 于 2026.02.27 发布，支持在无图形界面的环境中运行 Obsidian Sync。

概述

Obsidian Headless 是一个无头客户端，允许你在服务器或自动化环境中运行 Obsidian Sync，无需图形界面。这对于以下场景非常有用：

服务器同步：在服务器上保持仓库同步
自动化工作流：配合 CI/CD 管道使用
定时备份：自动同步和备份笔记
远程同步：作为中转节点同步多个设备

安装

系统要求

yaml

支持平台:
  - Linux (x64, ARM64)
  - macOS (无头模式)
  - Windows (无头模式)

依赖:
  - Node.js 18+ (推荐)
  - 稳定的网络连接

获取客户端

Obsidian Headless 客户端可通过官方渠道获取：

bash

# 下载地址
# 访问 Obsidian 官网获取最新版本
https://obsidian.md/download

# 或通过 CLI 安装
# 需要先安装 Obsidian CLI

配置

基本配置

创建配置文件 headless-config.json：

json

{
  "vault": "/path/to/your/vault",
  "sync": {
    "remoteVaultId": "your-vault-id",
    "email": "your-email@example.com",
    "password": "your-password-or-api-key"
  },
  "options": {
    "syncImages": true,
    "syncAudio": true,
    "syncVideo": false,
    "syncPDFs": true,
    "excludedFolders": [".trash", "templates"]
  }
}

环境变量配置

推荐使用环境变量存储敏感信息：

bash

# .env 文件
OBSIDIAN_EMAIL=your-email@example.com
OBSIDIAN_PASSWORD=your-password
OBSIDIAN_VAULT_ID=your-vault-id
OBSIDIAN_VAULT_PATH=/path/to/vault

高级配置

json

{
  "vault": "/path/to/vault",
  "sync": {
    "remoteVaultId": "${OBSIDIAN_VAULT_ID}",
    "email": "${OBSIDIAN_EMAIL}",
    "password": "${OBSIDIAN_PASSWORD}"
  },
  "schedule": {
    "interval": 300,
    "retryOnFailure": true,
    "maxRetries": 3
  },
  "logging": {
    "level": "info",
    "path": "/var/log/obsidian-headless.log"
  }
}

使用方法

命令行操作

bash

# 启动同步
obsidian-headless sync

# 指定配置文件
obsidian-headless sync --config /path/to/config.json

# 后台运行
obsidian-headless sync --daemon

# 查看状态
obsidian-headless status

# 强制完全同步
obsidian-headless sync --full

定时同步

使用 cron 或 systemd 定时任务：

Cron 配置

bash

# 编辑 crontab
crontab -e

# 每 5 分钟同步一次
*/5 * * * * /usr/local/bin/obsidian-headless sync >> /var/log/obsidian-sync.log 2>&1

# 每小时完全同步
0 * * * * /usr/local/bin/obsidian-headless sync --full >> /var/log/obsidian-full-sync.log 2>&1

Systemd 服务

创建服务文件 /etc/systemd/system/obsidian-headless.service：

ini

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

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username
ExecStart=/usr/local/bin/obsidian-headless sync --daemon
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

启用服务：

bash

sudo systemctl daemon-reload
sudo systemctl enable obsidian-headless
sudo systemctl start obsidian-headless

自动化场景

CI/CD 集成

在 GitHub Actions 中使用：

yaml

# .github/workflows/sync.yml
name: Sync Obsidian Vault

on:
  schedule:
    - cron: '*/30 * * * *'  # 每 30 分钟
  workflow_dispatch:  # 手动触发

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout vault
        uses: actions/checkout@v4
        with:
          path: vault
      
      - name: Setup Obsidian Headless
        run: |
          # 下载并安装 Obsidian Headless
          curl -L https://obsidian.md/download/headless -o obsidian-headless
          chmod +x obsidian-headless
      
      - name: Sync vault
        env:
          OBSIDIAN_EMAIL: ${{ secrets.OBSIDIAN_EMAIL }}
          OBSIDIAN_PASSWORD: ${{ secrets.OBSIDIAN_PASSWORD }}
          OBSIDIAN_VAULT_ID: ${{ secrets.OBSIDIAN_VAULT_ID }}
        run: |
          ./obsidian-headless sync --config config.json
      
      - name: Commit changes
        run: |
          cd vault
          git config user.name "Obsidian Sync"
          git config user.email "sync@obsidian.md"
          git add -A
          git diff --quiet && git diff --staged --quiet || git commit -m "Auto sync $(date)"
          git push

Docker 部署

创建 Dockerfile：

dockerfile

FROM node:18-alpine

WORKDIR /app

# 安装 Obsidian Headless
RUN apk add --no-cache curl && \
    curl -L https://obsidian.md/download/headless -o /usr/local/bin/obsidian-headless && \
    chmod +x /usr/local/bin/obsidian-headless

# 复制配置
COPY config.json /app/config.json
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

VOLUME ["/vault"]

ENTRYPOINT ["/entrypoint.sh"]
CMD ["sync", "--daemon"]

entrypoint.sh：

bash

#!/bin/sh
obsidian-headless "$@"

运行容器：

bash

docker build -t obsidian-headless .

docker run -d \
  --name obsidian-sync \
  -v /path/to/vault:/vault \
  -e OBSIDIAN_EMAIL=your-email \
  -e OBSIDIAN_PASSWORD=your-password \
  -e OBSIDIAN_VAULT_ID=your-vault-id \
  obsidian-headless

备份脚本

bash

#!/bin/bash
# backup-vault.sh

VAULT_PATH="/path/to/vault"
BACKUP_PATH="/backup/obsidian"
DATE=$(date +%Y%m%d_%H%M%S)

# 同步最新内容
obsidian-headless sync

# 创建备份
tar -czf "$BACKUP_PATH/vault_$DATE.tar.gz" -C "$VAULT_PATH" .

# 保留最近 7 天的备份
find "$BACKUP_PATH" -name "vault_*.tar.gz" -mtime +7 -delete

echo "Backup completed: vault_$DATE.tar.gz"

安全最佳实践

凭证管理

yaml

推荐做法:
  - 使用环境变量存储敏感信息
  - 不要在配置文件中硬编码密码
  - 使用 API Key 而非密码（如果支持）
  - 定期轮换凭证

网络安全

yaml

安全措施:
  - 使用 HTTPS 连接
  - 限制服务器访问 IP
  - 配置防火墙规则
  - 使用 VPN 或私有网络

访问控制

bash

# 设置文件权限
chmod 600 ~/.obsidian/headless-config.json
chmod 700 ~/.obsidian/

# 使用专用用户运行
sudo useradd -r -s /bin/false obsidian
sudo -u obsidian obsidian-headless sync

日志和监控

日志配置

json

{
  "logging": {
    "level": "debug",
    "path": "/var/log/obsidian-headless.log",
    "maxSize": "10MB",
    "maxFiles": 5
  }
}

日志格式

[2026-03-31 10:30:45] INFO  Starting sync for vault: my-vault
[2026-03-31 10:30:46] INFO  Connected to remote vault
[2026-03-31 10:30:48] INFO  Synced 5 files (2.3 MB)
[2026-03-31 10:30:48] INFO  Sync completed successfully

监控脚本

bash

#!/bin/bash
# check-sync.sh

LOG_FILE="/var/log/obsidian-headless.log"
ALERT_THRESHOLD=3600  # 1 小时无同步

LAST_SYNC=$(grep "Sync completed" "$LOG_FILE" | tail -1)
LAST_SYNC_TIME=$(date -d "$(echo $LAST_SYNC | cut -d']' -f1 | tr -d '[')" +%s)
CURRENT_TIME=$(date +%s)

if [ $((CURRENT_TIME - LAST_SYNC_TIME)) -gt $ALERT_THRESHOLD ]; then
    echo "Warning: No sync in the last hour"
    # 发送告警通知
    exit 1
fi

故障排除

常见问题

连接失败

yaml

症状: 无法连接到 Obsidian Sync 服务器

检查步骤:
  1. 确认网络连接正常
  2. 验证凭证是否正确
  3. 检查防火墙设置
  4. 确认 Obsidian Sync 订阅有效

解决方案:
  - 检查 obsidian.md 系统状态
  - 重新配置凭证
  - 使用 --verbose 查看详细日志

同步冲突

yaml

症状: 文件同步出现冲突

处理方法:
  1. 检查版本历史
  2. 手动解决冲突
  3. 使用 --force 覆盖（谨慎使用）

预防措施:
  - 避免多设备同时编辑
  - 使用定时同步而非实时同步

性能问题

yaml

症状: 同步速度慢或超时

优化建议:
  - 排除大型附件文件夹
  - 启用增量同步
  - 调整同步间隔
  - 检查服务器资源使用

调试模式

bash

# 启用详细日志
obsidian-headless sync --verbose

# 调试模式
obsidian-headless sync --debug

# 测试连接
obsidian-headless test-connection

Obsidian Headless ​

概述 ​

安装 ​

系统要求 ​

获取客户端 ​

配置 ​

基本配置 ​

环境变量配置 ​

高级配置 ​

使用方法 ​

命令行操作 ​

定时同步 ​

Cron 配置 ​

Systemd 服务 ​

自动化场景 ​

CI/CD 集成 ​

Docker 部署 ​

备份脚本 ​

安全最佳实践 ​

凭证管理 ​

网络安全 ​

访问控制 ​

日志和监控 ​

日志配置 ​

日志格式 ​

监控脚本 ​

故障排除 ​

常见问题 ​

连接失败 ​

同步冲突 ​

性能问题 ​

调试模式 ​

相关资源 ​

Obsidian Headless

概述

安装

系统要求

获取客户端

配置

基本配置

环境变量配置

高级配置

使用方法

命令行操作

定时同步

Cron 配置

Systemd 服务

自动化场景

CI/CD 集成

Docker 部署

备份脚本

安全最佳实践

凭证管理

网络安全

访问控制

日志和监控

日志配置

日志格式

监控脚本

故障排除

常见问题

连接失败

同步冲突

性能问题

调试模式

相关资源