Quartz 静态知识库部署与 Cloudflare Pages 构建 SOP
本卡片记录知识库静态发布引擎 Quartz (v4/v5) 的本地构建、配置规范以及在 Cloudflare Pages 上实现零成本自动化 CI/CD 部署的完整 SOP 指南。
一、 架构设计与方案对比
1. 为什么选择 Quartz + Cloudflare Pages
- 零服务器开销：替代昂贵的自托管图形 Web 版 Obsidian（如已废弃的 Ignis 容器），无需在服务器驻留进程或消耗内存。
- 极致加载速度：底层基于 Node.js/TypeScript 构建，生成的纯 HTML/CSS 部署至 Cloudflare 边缘 CDN，毫秒级响应。
- Git 驱动与 CI/CD：只需在本地或 Agent 端编辑 Markdown，向 GitHub 执行
git push即可自动触发边缘云端增量构建与发布。
二、 本地环境与目录结构
Quartz 安装在知识库根目录 ~/wiki/ 下，核心结构如下：
~/wiki/
├── content/ # Markdown 核心内容源目录 (对应知识库卡片)
│ ├── concepts/ # 概念与技术 SOP
│ ├── entities/ # 实体与档案
│ └── index.md # 知识库首页与双链主目录
├── quartz/ # Quartz 框架核心解析组件与插件配置
├── public/ # 编译生成的最终静态网页目录
├── quartz.config.ts # 核心样式、主题、语言及插件配置文件
├── package.json # 项目依赖定义文件
└── wrangler.toml # (可选) Cloudflare 部署配置文件三、 Cloudflare Pages 自动化构建配置
在 Cloudflare Dashboard 中创建 Pages 项目，连接至 GitHub 仓库 HermesAgent/wiki，具体构建参数配置如下：
1. 基础构建设置 (Build Settings)
- Framework preset：
None(或选择Quartz) - Build command：
git fetch --unshallow && npx quartz build - Build output directory：
public - Root directory：
/(留空)
2. 环境变量 (Environment Variables)
NODE_VERSION:20(或22.x)
四、 本地与 Cloudflare 常见构建报错与防坑指南 (Pitfalls)
1. 致命报错：duplicated mapping key (YAML 标头重复)
- 现象：构建在解析 Markdown 时抛出
ERROR: Failed to process markdown ... duplicated mapping key并退出（Exit Code 1）。 - 根因：Markdown 顶部的 Frontmatter 中存在相同的 YAML 键（例如重复定义了两行
title:）。 - 规避方案：任何编辑 Markdown 头部的自动化脚本或模版，必须确保 Frontmatter 格式严谨且无重复键：
--- title: 正确的唯一标题 created: 2026-07-31 type: concept ---
2. 知识库全局去重与脱敏规范
在部署上线公网知识库前，必须强制执行防泄漏检查：
- 脱敏规则：
- 公网 IP 地址：一律隐去前三段，保留最后一段方便识别（如
*.*.*.114）。 - 姓名与特定园区：统一采用通用代称（如
老大、海外园区）。 - 密钥与凭证：绝对禁止落盘至 Markdown，必须统一替换为
[REDACTED]。
- 公网 IP 地址：一律隐去前三段，保留最后一段方便识别（如
五、 本地手动编译与调试命令
在对 ~/wiki 进行了本地批量卡片新增或修改后，可通过以下命令测试编译：
cd ~/wiki
# 1. 本地增量编译测试 (验证 Markdown 语法与 YAML Frontmatter)
npx quartz build
# 2. 提交更改并触发 Cloudflare 自动部署
git add -A
git commit -m "docs: update wiki cards"
git push origin main相关链接
- 知识库目录规范与创作指南 — 查阅卡片写作与目录结构标准。
- Debian系统安全加固与优化 — 服务器基础防护规程。