Quartz - Obsidian 笔记发布方案

目标

在 Obsidian 中维护完整私人 Vault，只把显式设置 publish: true 的笔记及其实际引用附件导出到独立 GitHub 仓库，再由 Quartz 构建并部署到 Cloudflare Pages。

网站定位

网站定位为以 Linux、容器、网络和系统运维实践为主体，以 AI 自动化为特色的个人技术知识库。

• 主线内容：Linux、容器与 Kubernetes、网络与 Web 服务、数据库、可观测性、自动化与 DevOps、故障排查。
• 特色内容：AI Agent、浏览器自动化、模型接入和个人工作流实践。
• 内容原则：优先发布实际操作过、可以复用、适用条件明确的技术记录，不追求覆盖所有技术主题。
• 暂不公开：日记、简历、待办、账号配置、生产环境敏感信息、事故细节和来源不明确的转载文章。

数据边界

• 完整 Vault：保留在本地和 OneDrive。
• GitHub：只保存公开笔记、公开附件、Quartz 源码和站点配置。
• Cloudflare Pages：只保存 Quartz 生成的 HTML、CSS、JavaScript 和公开附件。
• 不使用 D1、KV 或 R2；单个附件超过 Pages 限制时再单独评估 R2。

发布规则

• 只有 YAML frontmatter 中布尔值为 publish: true 的 Markdown 才能发布。
• 指向未公开笔记的普通双链转换为显示文本。
• 嵌入未公开或不存在的笔记会阻止发布。
• 只复制公开笔记实际引用的附件；缺失附件会阻止发布。
• .obsidian/、.git/、AGENTS.md、密钥、证书和环境变量文件永不导出。
• 发布前扫描疑似私钥、Token 和密码；高风险命中阻止发布，普通 IP、域名和邮箱只警告。

首页与导航

• 新建独立的公开首页，由本地配置将其映射为 content/index.md，不直接使用现有的内部索引或 README.md。
• 首页首先用两至三句话说明知识库定位。
• “从这里开始”区域人工维护三至五篇具有代表性的精选文章。
• 主题导航包括：Linux 与系统运维、容器与 Kubernetes、网络与 Web 服务、数据库与可观测性、自动化与 DevOps、AI Agent 实践、故障排查记录。
• 自动生成“全部笔记”页面，按原一级目录分组。
• 保留 Quartz 的目录树、全文搜索、反向链接和关系图谱。
• 首页不依赖 Dataview，只使用 Quartz 和 Obsidian 均可识别的普通双链。
• 首页包含内容说明，提醒读者关注文章所注明的软件版本和运行环境。

发布流程

1. 在 Vault 中编辑笔记并添加 publish: true。
2. 运行预览命令，导出到临时目录并执行隐私检查。
3. 使用 Quartz 本地服务器检查页面。
4. 运行正式发布命令，原子更新独立 Quartz 项目的 content/。
5. 检查 Git 差异并确认提交、推送。
6. Cloudflare Pages 从 GitHub 自动执行 npx quartz build，部署 public/。

Cloudflare Pages 配置

• Framework preset：None
• Production branch：v4
• Build command：npx quartz build
• Build output directory：public
• 初期使用 *.pages.dev，确认稳定后再设置自定义域名和 Quartz baseUrl。

安全原则

• 发布器对 Vault 只读。
• 所有输出先写入临时目录，通过验证后才替换公开内容。
• 任一检查失败时不修改公开仓库、不提交、不推送。
• GitHub 是公开内容的版本源，Cloudflare Pages 只是构建和托管层。