Obsidian 自建发布调研

相关规范: 相关私有笔记、相关私有笔记

结论

当前更适合采用 Quartz + 独立 repo + VPS 静态托管。

理由:

• 已倾向单独维护发布 repo，Quartz 的项目边界更清楚。
• 已有 VPS、域名、IP，Quartz build 后产物可以直接由 Nginx 或 Caddy 托管。
• Vault 规则明确不应在 Obsidian vault 内运行 npm、pnpm 或 build；Quartz 可以放在 vault 外部，只同步公开内容。
• Digital Garden 更适合“从 Obsidian 内点按钮发布选中笔记”的工作流，但独立 repo + VPS 部署时反而需要绕开它的默认 GitHub/Vercel 路线。

目标架构

<private-vault>/         # 私有 vault，只写笔记，不运行 build
<notes-site>/            # 独立 Git repo，Quartz 项目
<notes-site>/content/
<notes-site>/public/
VPS:/var/www/notes

原则: vault 是私有知识源，发布 repo 是公开站点源。不要直接部署整个 vault。

Quartz

Quartz 是面向 digital garden 的静态站点生成器。官方文档描述的部署模型是: 将 Markdown 和资源转换成 HTML、CSS、JS，然后把生成目录部署到任意静态文件服务器。

适合点:

• 支持 Obsidian 风格的 wikilinks、backlinks、graph、全文搜索、LaTeX、popover、callouts 等。
• 自托管路径直接: build 出 public/，再复制到服务器。
• 官方 hosting 文档包含 self-hosting，并给出 Nginx、Apache、Caddy 等服务器示例。
• 与“独立 repo + VPS”的目标匹配，CI、rsync、Caddy/Nginx、域名和 HTTPS 都可以独立治理。

代价:

• 需要维护一个 Quartz repo。
• 需要自己设计同步策略，避免把私有笔记或附件带进 content/。
• 如果公开笔记链接到私有笔记，需要决定是保留断链、隐藏链接，还是生成前做链接清理。

Digital Garden 插件

Digital Garden 是 Obsidian 插件路线，更强调从 Obsidian 内选择笔记并发布。它通常用 dg-publish: true 控制发布笔记。

适合点:

• 发布控制贴近 Obsidian 编辑体验。
• 对“只发布少量选中笔记”的流程友好。
• 支持 backlinks、local graph、search、filetree、link preview 等站点能力。

代价:

• 默认工作流偏 GitHub + Vercel。
• 自托管时更像“先本地导出，再自己 build/deploy”，工程边界不如 Quartz 简洁。
• 官方说明中，本地导出模式没有发布状态 tracking 和 diffing。

对比

推荐工作流

1. 在 vault 中只标记允许公开的笔记，例如 publish: true 或维护一个显式公开目录。
2. 在独立 repo 中写同步脚本，只复制 allowlist 笔记和被引用附件。
3. 同步后运行泄露检查，阻止 05 - 工作 Work、01 - 面试 Interviews、私有项目、未授权附件进入发布 repo。
4. 在独立 repo 中运行 Quartz build。
5. 将 public/ 部署到 VPS，例如 rsync 到 /var/www/notes。
6. 用 Caddy 或 Nginx 绑定域名和 HTTPS。

示例命令只应在发布 repo 中运行:

pnpm sync
pnpm build
rsync -az --delete public/ user@example.com:/var/www/notes/

泄露防线

• 默认 denylist: 01 - 面试 Interviews、05 - 工作 Work、99 - 归档 Archive、.obsidian、.git、模板 Templates。
• 默认 allowlist: 只有显式 publish: true 的笔记，或专门的公开目录。
• 附件只复制公开笔记实际引用的文件。
• build 前检查 content/ 中是否出现敏感路径、未授权 frontmatter、私有域名、token、邮箱或工作项目名。
• 不在 vault 内安装依赖、运行 build、生成 node_modules、dist 或缓存。

初始实施计划

1. 在 vault 外创建 notes-site repo。
2. 初始化 Quartz 并配置站点标题、域名、主题、搜索和 graph。
3. 写 scripts/sync-from-vault.mjs，只同步公开笔记和引用附件。
4. 写 scripts/check-no-private-content.mjs，把泄露检查作为 build 前置条件。
5. 在 VPS 上创建 /var/www/notes，配置 Caddy 或 Nginx。
6. 先手动 rsync 部署，再决定是否接入 GitHub Actions 或本机一键脚本。

参考

• Quartz features
• Quartz hosting
• Digital Garden getting started
• Digital Garden hosting alternatives