Obsidian同步与部署指南

Obsidian 同步与部署完整方案 - 结合 Git + Quartz + Digital Garden

#resource / obsidian #type / howto #status / evergreen

[!info] related notes

Obsidian 同步与部署指南

目标：在多台设备上同步笔记库，并发布到网站供他人阅读
涉及插件：Obsidian Git + Quartz 4.0 + Digital Garden
难度级别：⭐⭐⭐⭐
推荐度：⭐⭐⭐⭐⭐

📋 快速导航

架构选择

🎯 三个方案的对比

对比项方案 1（完整）方案 2（简化）方案 3（企业）
同步工具Obsidian GitDigital GardenGit + Sync API
部署工具Quartz 4.0Digital GardenQuartz + CDN
设备同步✅ 完全⚠️ 单向✅ 完全
网站定制✅ 高度定制⚠️ 有限✅ 完全定制
学习成本⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
性能⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
成本免费免费免费-付费
推荐人群技术爱好者内容创作者企业/团队

方案 1：完整方案（推荐专业用户）

架构图：

┌─────────────────────────────────────┐
│     Obsidian 库 (本地编辑)           │
│  device-a/vault + device-b/vault     │
└──────────────┬──────────────────────┘
               │ 编辑笔记
               ↓
        ┌─────────────┐
        │ Obsidian    │
        │ Git 插件    │
        └──────┬──────┘
               │ 自动提交 & 推送
               ↓
        ┌─────────────────┐
        │ GitHub 仓库     │
        │ (私有或公开)     │
        └──────┬──────────┘
               │ Pull 更新
         ┌─────┴──────────────────┐
         ↓                        ↓
    ┌────────────┐        ┌──────────────┐
    │ Obsidian   │        │ GitHub Pages │
    │ (多设备)   │        │ (网站托管)    │
    └────────────┘        └──────────┬───┘
                                     │ Quartz
                                     ↓
                          ┌───────────────────┐
                          │ 静态网站          │
                          │ (完全自定义)      │
                          └───────────────────┘

架构说明

流程：

  1. 本地编辑：在 Obsidian 中编辑笔记
  2. 自动提交：Obsidian Git 定时自动提交并推送
  3. 多设备同步：其他设备自动拉取最新笔记
  4. 构建网站：GitHub Actions 自动运行 Quartz 构建
  5. 发布部署：自动部署到 GitHub Pages

优点：

  • ✅ 完整的版本控制历史
  • ✅ 高度自定义网站样式
  • ✅ 支持多设备实时同步
  • ✅ 完全免费（GitHub + Pages）
  • ✅ 所有数据在自己手中

缺点：

  • ❌ 配置相对复杂
  • ❌ 需要理解 Git 基础
  • ❌ Quartz 学习成本较高

详细设置步骤

第一步：初始化 Git 仓库

设备 A（主设备）

# 1. 创建 GitHub 仓库
# 访问 https://github.com/new
# 创建私有仓库 "obsidian-vault"

# 2. 初始化本地仓库
cd /path/to/your/vault
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/obsidian-vault.git
git push -u origin main

第二步：配置 Obsidian Git

在 Obsidian 中：

  1. Settings → Community plugins → Obsidian Git

  2. Authentication：

    GitHub Username: your-username
Personal Access Token: ghp_xxxxx...（见之前的步骤）

  3. Auto：

    Auto backup interval: 10 minutes
Auto pull interval: 5 minutes
Auto push interval: 10 minutes

  4. Commit message：

    {{date}}-{{time}}: {{numFiles}} files changed

第三步：配置 Quartz 部署

克隆或创建 Quartz 项目

# 方式 A：使用模板（推荐）
git clone https://github.com/jackyzha0/quartz.git
cd quartz

# 方式 B：从仓库模板创建
# 访问 https://github.com/jackyzha0/quartz
# 点击 "Use this template"

配置 Quartz

编辑 quartz.config.ts：

const config: QuartzConfig = {
  configuration: {
    pageTitle: "我的知识库",
    baseUrl: "example.com",    // 改为你的域名
    ignorePatterns: [
      "private",
      "drafts",
      ".obsidian",
      "node_modules",
    ],
  },
  // ... 其他配置
}

配置内容源

方案 A：符号链接（推荐，实时同步）

# Windows PowerShell
New-Item -ItemType SymbolicLink -Path "./content" -Target "C:\path\to\vault"

# Mac/Linux
ln -s /path/to/vault ./content

方案 B：复制笔记

cp -r /path/to/vault/* ./content/

第四步：设置 GitHub Actions 自动部署

创建工作流文件 .github/workflows/deploy.yml

name: Deploy Quartz

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm install
      
      - name: Build Quartz
        run: npm run build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          cname: example.com  # 可选：自定义域名

第五步：同步到第二台设备

设备 B（辅助设备）

# 1. 克隆库
git clone https://github.com/username/obsidian-vault.git
cd obsidian-vault

# 2. 在 Obsidian 中打开此文件夹
#    (Settings → Vault → Open vault location)

# 3. 安装 Obsidian Git 插件
#    (同步配置自动继承)

# 完成！设备 B 现在会自动同步设备 A 的更新

工作流示例

日常操作：

周一 (设备 A - Mac)
├─ 14:00 编辑 note-1.md
├─ 14:15 Obsidian Git 自动提交并推送
└─ GitHub 仓库更新

周一 (设备 B - Windows)
├─ 14:20 自动拉取最新版本
├─ note-1.md 更新完成
└─ 继续编辑并添加 note-2.md

同时
├─ GitHub Pages 自动运行 Quartz 构建
├─ 网站在 ~2 分钟内自动部署
└─ https://example.com 更新完成

冲突处理

场景：同时在两台设备编辑同一文件

设备 A 编辑 note.md:
    Line 5: Content by A

设备 B 编辑 note.md:
    Line 5: Content by B

设备 B 拉取时产生冲突

自动解决（推荐配置）

// quartz.config.ts
configuration: {
  git: {
    syncMethod: "merge",        // 自动合并
    conflictResolution: "ours", // 保留本地版本
  }
}

手动解决

# Git 面板显示冲突文件
# 打开冲突文件，解决标记
<<<<<<< HEAD
Content by B
=======
Content by A
>>>>>>> branch-name

# 保留需要的内容，删除标记，保存
Content merged by hand

# 提交解决
git add .
git commit -m "Resolved conflict"
git push

方案 2：简化方案（推荐新手）

架构图：

┌─────────────────────────────┐
│   Obsidian 库 (本地编辑)    │
│   (单个设备或云盘同步)       │
└──────────────┬──────────────┘
               │ 编辑笔记
               ↓
        ┌──────────────────┐
        │ Digital Garden   │
        │ 插件 (一键发布)   │
        └──────────┬───────┘
                   │ 发布
                   ↓
        ┌──────────────────┐
        │ GitHub 仓库      │
        │ (自动创建)       │
        └──────────┬───────┘
                   │
                   ↓
        ┌──────────────────┐
        │ GitHub Pages     │
        │ (自动部署网站)   │
        └──────────────────┘

优点与缺点

优点：

  • ✅ 极简配置（5 分钟内完成）
  • ✅ 无需 Git 知识
  • ✅ 一键发布，无需构建流程
  • ✅ 适合内容创作者

缺点：

  • ❌ 网站定制选项有限
  • ❌ 设备同步需要额外工具（云盘）
  • ❌ 版本控制功能有限

详细设置步骤

第一步：安装 Digital Garden 插件

Settings → Community plugins → Browse → “Digital Garden” → Install & Enable

第二步：创建 GitHub Token

  1. https://github.com/settings/tokens
  2. Generate new token (classic)
  3. 勾选 repo + workflow
  4. 复制 token

第三步：配置插件

在 Obsidian 中：

Settings → Community plugins → Digital Garden → Options

GitHub Username: your-username
GitHub Repository: digital-garden
GitHub Token: ghp_xxxxx...

第四步：发布笔记

方式 A：单个笔记

---
title: "我的第一篇笔记"
published: true
---

内容...

命令面板 → “Digital Garden: Publish single note”

方式 B：批量发布

---
published: true
---

命令面板 → “Digital Garden: Publish all notes”

第五步：设备同步（可选）

使用云盘同步库文件夹：

iCloud Drive / Google Drive / OneDrive / 阿里云盘
    ↓
  Obsidian
    ↓
  Digital Garden 发布

工作流示例

编辑笔记 (iPhone/iPad)
    ↓
iCloud 自动同步到 Mac
    ↓
Mac 中 Obsidian 刷新
    ↓
标记 published: true
    ↓
Publish single note
    ↓
网站自动更新（2 分钟内）

方案 3：企业方案（推荐团队）

适用场景：

  • 多人团队协作
  • 需要权限管理
  • 需要版本跟踪
  • 需要高可用性

架构：

┌─────────────────────────────┐
│  Obsidian Enterprise (团队)  │
│  + Obsidian Sync (官方同步)  │
└──────────────┬──────────────┘
               │
               ↓
        ┌──────────────────┐
        │ Git (Gitea/GitLab) │
        │ (企业内部部署)      │
        └──────────┬───────┘
                   │
    ┌──────────────┼──────────────┐
    ↓              ↓              ↓
┌────────┐  ┌────────┐  ┌────────┐
│ 设备 A  │  │ 设备 B  │  │ 设备 C  │
│(同步)  │  │(同步)  │  │(同步)  │
└────────┘  └────────┘  └────────┘

    同时同步到 Web 服务器
    ↓
    ┌──────────────────┐
    │  企业知识库网站   │
    │  (内部 / 公网)    │
    └──────────────────┘

需要工具：

  • Obsidian Sync（官方服务，$96/年）
  • 企业 Git 服务（Gitea、GitLab、Bitbucket）
  • CI/CD 流程（Jenkins、GitLab CI）
  • 团队权限管理

设置步骤（简化版）：

1. 订阅 Obsidian Sync
   ├─ 所有设备自动同步
   └─ 版本回滚功能

2. 创建企业 Git 仓库
   ├─ 团队成员权限控制
   └─ 分支管理

3. 配置 CI/CD
   ├─ 自动构建（Quartz 或 Hugo）
   └─ 自动部署到网站

4. 权限管理
   ├─ 谁可以编辑
   ├─ 谁可以发布
   └─ 谁可以访问网站

常见同步场景

场景 1：在线编辑 + 离线备份

使用 Obsidian Sync（在线）
+ Obsidian Git（离线备份到 GitHub）

配置：
- Obsidian Sync: 实时云同步
- Obsidian Git: 每天自动备份到 GitHub

优点：
✅ 云端备份，丢不了
✅ 本地 Git 历史
✅ 多设备实时同步

场景 2：家里电脑 + 外出手机

iOS/Android:
  ↓
Obsidian for Mobile
  ↓
iCloud / Google Drive (云盘同步)
  ↓
家里 Mac/Windows
  ↓
Obsidian Git (推送到 GitHub)
  ↓
网站发布 (Quartz / Digital Garden)

场景 3：团队协作

成员 A ──┐
成员 B ──┤─ Git 仓库 ─┬─ Obsidian (共享库)
成员 C ──┘           │
                     ├─ 网站发布 (Quartz)
                     │
                     └─ 权限管理 (GitHub/GitLab)

故障排查

问题 1：Obsidian Git 自动推送失败

错误：fatal: could not read Password

解决：

# 使用 SSH 密钥替代密码认证
ssh-keygen -t ed25519 -C "your@email.com"

# 添加公钥到 GitHub
cat ~/.ssh/id_ed25519.pub
# 复制到 GitHub Settings → SSH Keys

# 修改远程地址为 SSH
git remote set-url origin git@github.com:username/vault.git

问题 2：多设备冲突频繁

原因：两台设备同时编辑同一文件

解决：

✅ 启用自动合并
❌ 避免同时编辑
✅ 定期 Pull
❌ 不要长时间离线

问题 3：网站构建失败

错误：GitHub Actions 显示”Build failed”

解决步骤：

  1. 检查 GitHub Actions 日志
  2. 查看 Quartz 配置是否正确
  3. 检查笔记中是否有 Quartz 不支持的语法
  4. 尝试本地运行 npm run build 测试

问题 4：大文件导致推送慢

优化：

# 使用 Git LFS 处理大文件
git lfs track "*.pdf"
git lfs track "*.mp4"

# 清理历史
git gc --aggressive

# 浅克隆（减小下载大小）
git clone --depth=1 https://github.com/username/vault.git

📊 对比总结

需求方案 1方案 2方案 3
多设备同步✅ 完全⚠️ 依赖云盘✅ 完全
网站定制✅ 高度定制⚠️ 有限✅ 完全定制
团队协作⚠️ 可行❌ 不支持✅ 完全支持
学习成本⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
成本免费免费$96-400/年

推荐选择：

  • 个人用户、技术爱好者 → 方案 1
  • 内容创作者、博主 → 方案 2
  • 企业、团队 → 方案 3

📚 相关文档

创建于 2025/12/8 更新于 2026/5/27