xHalo Blog：从 Hexo 博客到 Cloudflare 原生开源 CMS 的演进

发表于 分类于 Waline：

xHalo Blog 的目标不是简单替换一个博客主题，也不是把传统 CMS 原样搬到云端，而是把 Hexo 的静态站点生态、GitHub 的审查协作模型、Cloudflare 的边缘计算能力 组合成一个更适合长期维护、开源复用和自动化扩展的博客/CMS 框架。

它从 ranbeis.com 的真实 Hexo 博客迁移需求出发，逐步抽象出通用能力：内容仍然保留在 Git 仓库中，发布仍然经过 Pull Request 审核，运行时服务则由 Cloudflare Workers、Queues、D1、R2、Pages 等能力承担。这样既保留了静态博客的稳定性，也为后台管理、异步任务、AI 工作流、审计日志和多站点部署留下了扩展空间。

一、为什么需要 xHalo Blog

传统 Hexo 博客的优势非常明确：结构简单、生成速度快、主题生态成熟、内容天然 Git 化。但当一个博客开始具备在线编辑、后台管理、自动化发布、评论审核、媒体资源处理、AI 内容辅助、任务队列和多站点部署时，单纯的本地 Hexo 命令已经难以覆盖全部需求。

xHalo Blog 的设计出发点是：不破坏 Hexo 已有内容结构，不绕过 GitHub 审查流程，在 Cloudflare 上补足现代化博客系统所需的动态能力。

换句话说，xHalo Blog 不是要抛弃 Hexo，而是把 Hexo 从“本地静态生成工具”扩展为“可审计、可托管、可自动化、可开源复用的现代内容平台”。

二、项目定位

xHalo Blog 可以被理解为三层结构：

  1. Hexo-compatible content layer：继续使用 source/_posts/、frontmatter、分类、标签、静态生成等 Hexo 习惯。
  2. Cloudflare-native service layer：用 Workers 提供 API，用 Queues 处理异步任务，用 D1 记录任务与审计，用 R2 承载未来媒体资产。
  3. GitHub PR-only governance layer：所有真实内容发布先生成 draft branch 和 Pull Request，由 owner 人工审核后决定 merge 或 close。

这种定位让 xHalo Blog 同时具备个人博客、开源项目模板和轻量 CMS 的特征。

三、核心优势

1. 保留 Hexo 生态，不强行迁移内容模型

xHalo Blog 首先尊重现有 Hexo 项目。文章仍然是 Markdown，frontmatter 仍然使用标题、日期、标签、分类等字段，目标路径仍然是 source/_posts/<slug>.md。

这意味着旧博客可以逐步迁移，不需要一次性重写主题、URL、内容结构或历史文章。

2. GitHub Pull Request 成为发布边界

xHalo Blog 的生产发布不是“一键写入 main”，而是：

1
Admin UI -> API Worker -> Queue Worker -> draft branch -> GitHub Pull Request -> owner manual review

自动化系统只负责创建草稿分支和 PR，不负责合并。最终发布权仍然留在 owner 手中。

这种 PR-only 模型带来的好处是：

  • 每次变更都有清晰 diff；
  • 误生成内容可以直接 close；
  • 所有发布都能留下审计记录；
  • 不需要给自动化系统 direct main 权限；
  • 适合开源项目协作和多人审核。

3. Cloudflare 原生架构，减少服务器运维负担

xHalo Blog 的运行时能力优先放在 Cloudflare 上：

  • Pages：托管 Hexo 静态站点；
  • Workers：承载 Admin API、Webhook、发布入口；
  • Queues：异步处理 GitHub PR 创建、构建状态同步等任务；
  • D1：记录任务状态、审计日志和未来的轻量索引；
  • R2：为未来图片、附件和媒体资产提供对象存储；
  • Turnstile / Access：用于后台和写入入口的额外防护。

这让系统可以减少传统 VPS 维护，同时保留边缘计算和全局部署能力。

4. 默认安全边界清晰

xHalo Blog 的默认生产基线是保守的：

1
2
3
4
5
6
LIVE_WRITES_ENABLED=false
No direct main write
No auto-merge
No unattended batch publish
No D1 direct production publish
No R2 live write without separate approval

即使后台界面具备创建 PR 的能力，真实写入窗口也需要 owner 明确批准。写入完成后必须恢复 LIVE_WRITES_ENABLED=false。

5. Admin MVP 不追求“一键发布”，而是服务审核流

Admin MVP 的目标不是跳过 GitHub，而是让内容准备过程更高效：

  • 编辑标题、slug、摘要、分类、标签；
  • 编辑 Markdown 正文；
  • 预览 frontmatter；
  • 预览 Markdown；
  • 生成 GitHub plan；
  • 创建 Review PR；
  • 展示 task status、branch、error、retry count、updated time 和 PR URL。

它解决的是“如何更好地准备 PR”，而不是“如何绕过 PR”。

四、整体架构图

上图展示了 xHalo Blog 的核心数据流。内容从 Admin UI 进入 API Worker，经过鉴权、校验和任务队列，再由 Queue Worker 创建 GitHub draft branch 和 Pull Request。静态站点仍由 Hexo 构建，最终部署到 Cloudflare Pages。

这种架构的关键点在于：动态能力在 Cloudflare，内容权威在 GitHub，最终发布由 owner 手动决定。

五、开发过程与阶段路线图

xHalo Blog 的开发过程并不是一次性重构，而是按风险逐步推进。

Phase 1：真实博客迁移与兼容盘点

第一阶段重点是确认现有 Hexo 博客的结构，包括主题、插件、搜索、分类、标签、文章资源、构建脚本和部署链路。目标不是立即改造，而是弄清哪些能力必须保留，哪些能力可以被抽象成开源模板。

Phase 2：开源项目边界拆分

第二阶段开始区分 hexo-blog 和 xhalo-blog 的职责。前者保留生产内容和站点源码，后者逐步沉淀为 Cloudflare-native 的通用框架。这个阶段的核心是避免把生产私有配置、历史内容和开源框架混在一起。

Phase 3：Cloudflare Scaffold 与 Admin 原型

第三阶段建立 Workers API、Admin Panel、D1 migration、Queue scaffold、R2 prototype、Webhook scaffold 等基础模块。此时重点是让各模块可运行、可测试、可扩展，而不是马上进入生产发布。

Phase 4：异步发布与 Staging 验证

第四阶段引入 Queue Worker，把发布动作从同步 API 中拆出来。这样可以记录 task、重试状态、失败原因和异步执行结果。此阶段主要验证 staging 环境、只读检查、secret scan 和 schema validation。

Phase 5：生产边界验证

第五阶段是最关键的安全阶段。系统依次完成 dry-run、shadow-mode、PR trial、controlled live-write trial。每一步都要求 owner approval、单次执行、记录证据，并严格禁止 direct main 和 auto-merge。

测试生成的 PR 可以证明链路可用，但测试内容不应直接发布。PR-only 模式的价值也在这里体现：即使自动化生成了内容，owner 仍然可以 close without merge。

Phase 6：Admin PR-only Publishing MVP

第六阶段把验证过的 PR-only 链路接入 Admin MVP。它增加了文章编辑、frontmatter preview、Markdown preview、GitHub plan、Create Review PR、task status panel 等能力。

随后又完成 PR-only safety alignment：移除 D1 live 主入口，增加 owner-approved write window checkbox，把 D1 direct publishing 明确排除在 Admin PR-only MVP 之外。

Phase 7：第一篇真实文章的受控 PR 创建

第七阶段才适合创建第一篇真实文章 PR。它仍然不是自动发布，而是创建一个真实内容的 draft branch 和 Pull Request。owner 需要在 GitHub 手动审核，确认内容、frontmatter、路径和 diff 后再决定 merge 或 close。

Phase 8：Release Candidate 与开源可用版本

后续阶段会继续完善：

  • .env.example；
  • wrangler.toml.example；
  • Cloudflare 部署文档；
  • GitHub App 权限说明；
  • Admin 使用说明；
  • PR-only publishing runbook；
  • 多站点配置；
  • 开源项目介绍页；
  • demo deployment；
  • changelog 和版本发布。

六、PR-only 发布流程

一次标准的真实文章发布应该是：

1
2
3
4
5
6
7
8
9
10
1. Owner 明确批准一个写入窗口
2. Operator 准备文章标题、slug、summary、categories、tags、body
3. Admin UI 生成 preview 和 GitHub plan
4. 临时开启 LIVE_WRITES_ENABLED=true
5. 发送 exactly one live request
6. Queue Worker 创建 draft branch 和 PR
7. 立即恢复 LIVE_WRITES_ENABLED=false
8. 验证后续写入被 403 阻断
9. Owner 在 GitHub 手动审核 PR
10. Owner 手动 merge 或 close

这套流程刻意把“生成 PR”和“发布到 main”拆成两件事。自动化系统只能完成前半段，发布决策由人完成。

七、和传统 CMS 的差异

传统 CMS 通常把数据库作为内容权威来源，后台保存即发布。xHalo Blog 则选择 Git 作为内容权威来源，后台只是生成变更提案。

这种设计更适合以下场景：

  • 个人长期维护博客；
  • 希望保留 Markdown 与 Git 历史；
  • 需要 Cloudflare 部署但不想长期维护 VPS；
  • 希望将项目开源给社区复用；
  • 希望未来接入 AI，但不允许 AI 自动直接发布；
  • 希望所有内容变更都能 code review。

它牺牲了一些传统 CMS 的即时性，换来了更好的可审计性、可回滚性和生产安全边界。

八、下一步重点

xHalo Blog 接下来最重要的工作不是继续堆功能，而是把第一篇真实文章发布流程跑通，并把成功或关闭的 owner decision 记录下来。

在完成第一篇真实文章的受控 PR 创建后，还需要继续完善：

  1. 真实文章 owner decision audit；
  2. release candidate 文档；
  3. 开源部署说明；
  4. Cloudflare 一键部署路径；
  5. Admin UX hardening；
  6. 多站点和自定义主题配置；
  7. AI workflow 模块化接入；
  8. 社区贡献规则和安全策略。

九、总结

xHalo Blog 的优势不在于“更快发布”，而在于“更安全地自动化”。它用 Cloudflare 提供运行时能力，用 GitHub PR 保留审核边界，用 Hexo 继续承载成熟的静态博客生态。

这条路线更适合长期项目：先保守地保证不破坏生产，再逐步引入后台管理、异步任务、AI 工作流和开源部署能力。

当一个博客系统既能保持 Markdown + Git 的透明性，又能拥有现代 Admin、Queue、API、审计和边缘部署能力时，它就不再只是一个静态博客，而是一个可持续演进的开源内容平台。