为什么迁移?

墨点博客最初基于 Halo 2.x 运行在我的家庭服务器上,通过 Docker 部署,Caddy 提供 HTTPS 反代。这个架构运行了一年多,稳定性不错,但也暴露了几个问题:

  1. 家宽网络的不稳定性:虽然配置了 DDNS 和端口映射,但国际链路质量时好时坏
  2. 维护成本:需要维护 Docker 容器、数据库、备份系统
  3. 扩展性问题:想尝试一些前沿技术(如边缘函数、D1 数据库)时受限于架构

今年初,我决定将博客迁移到 Cloudflare Pages,这标志着从传统 CMS 到现代 Jamstack 架构的转变。

迁移方案设计

原架构回顾

访客 → Cloudflare(443) → Origin Rule 回源 8443 → 爱快端口映射
     → Caddy(Let's Encrypt) → Halo:8091 → PostgreSQL 16

新架构(Cloudflare Pages + 部分原功能保留)

访客 → Cloudflare Pages(SaaS)
     ↓
评论系统 → Cloudflare D1 数据库
     ↓
管理后台 → 原 Halo Docker(仅后台,不对外)
     ↓
内容同步 → GitHub Actions + 自定义发布脚本

为什么不是”一刀切”?

完全放弃 Halo 意味着失去友好的后台编辑体验。我的折中方案是:

  • 前台静态化:文章通过 Halo 后台编辑,自动同步到 Cloudflare Pages
  • 动态功能分离:评论系统独立用 D1 实现
  • 后台保留:Halo 仅在本地网络访问,作为内容管理系统

实施步骤

1. Halo 数据导出与处理

首先需要从 Halo 导出所有内容。Halo 2.x 提供了完整的 API:

# 获取所有文章
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts?page=0&size=1000" \
  | jq '.items[] | {title, slug, content, categories: [.categories[].spec.displayName]}' > articles.json

然后编写转换脚本,将文章内容转换为 Markdown 格式,并添加 Front Matter:

def halo_to_markdown(article):
    front_matter = f"""---
title: {article['title']}
slug: {article['slug']}
categories: {', '.join(article['categories'])}
date: {article['create_time']}
---\n\n"""
    return front_matter + article['content']

2. Cloudflare Pages 配置

Cloudflare Pages 支持 Hugo、Hexo 等静态生成器,但我选择了更简单的方案:纯 HTML + 预渲染。原因是我需要保留原主题样式,且迁移时间有限。

# wrangler.toml
name = "md-blog"
main = "src/index.js"
compatibility_date = "2024-09-30"

[[routes]]
pattern = "/*"
script = "render"

Pages Functions 负责根据请求路径渲染对应文章:

export async function onRequest(context) {
  const url = new URL(context.request.url);
  const slug = url.pathname.slice(1);
  
  if (slug === '' || slug === 'index.html') {
    // 返回首页
    return renderIndex();
  }
  
  // 从 KV 或 D1 获取文章内容
  const article = await getArticle(slug);
  if (!article) {
    return new Response('Not Found', { status: 404 });
  }
  
  return renderArticle(article);
}

3. 评论系统迁移到 D1

原来使用 Halo 内置评论,现在用 Cloudflare D1 + Pages Functions:

-- schema.sql
CREATE TABLE IF NOT EXISTS comments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  post_slug TEXT NOT NULL,
  author_name TEXT NOT NULL,
  author_email TEXT,
  content TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  parent_id INTEGER,
  status TEXT DEFAULT 'pending' -- pending/approved/spam
);

CREATE INDEX idx_post_slug ON comments(post_slug);
CREATE INDEX idx_created_at ON comments(created_at DESC);

API 端点设计:

  • GET /api/comments?slug=:slug - 获取文章评论
  • POST /api/comments - 提交新评论
  • POST /api/comments/preview - 评论预览(避免 Spam)

4. 自动化发布流程

最关键的部分:如何在 Halo 后台编辑文章后,自动同步到 Cloudflare Pages?

我设计了两个同步方案:

方案A:实时同步(通过 Halo 插件) 编写 Halo 插件监听文章发布事件,调用 Cloudflare API 更新内容。但 Halo 插件开发门槛较高。

方案B:定时同步(选择此方案)

# GitHub Actions workflow
name: Sync Halo to Cloudflare Pages

on:
  schedule:
    - cron: '0 */6 * * *'  # 每6小时同步一次
  workflow_dispatch:  # 手动触发

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Fetch from Halo
        run: |
          python3 sync_halo.py \
            --halo-url http://10.0.0.3:8091 \
            --api-token ${{ secrets.HALO_TOKEN }}
      
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          projectName: md-blog
          directory: ./output

实际中我使用了更简单的方案C:本地脚本同步:

# publish_site.sh 的一部分
curl -s http://127.0.0.1:8091/apis/api.console.halo.run/v1alpha1/posts \
  | python3 /mnt/-1/halo/tools/convert.py \
  | wrangler pages deploy ./dist --project-name=md-blog

迁移中的挑战与解决

1. 样式兼容性问题

Halo 主题与 Cloudflare Pages 的路径结构不同。解决方法:

  • 使用相对路径而非绝对路径
  • 将静态资源(CSS/JS/图片)上传到 R2
  • 编写路径重写规则

2. 评论数据迁移

旧评论需要从 PostgreSQL 导出,转换格式后导入 D1。使用中间脚本:

# 数据格式转换
def convert_comment(old_comment):
    return {
        'post_slug': old_comment['post_slug'],
        'author_name': old_comment['author'],
        'content': old_comment['content']['raw'],
        'created_at': old_comment['createTime'],
        'status': 'approved' if old_comment['approved'] else 'pending'
    }

3. 搜索功能

Halo 有全文搜索,Cloudflare Pages 无服务端搜索。解决方案:

  • 生成搜索索引 JSON 文件
  • 客户端使用 JavaScript 实现搜索
  • 使用 Fuse.js 或 MiniSearch 库

迁移效果对比

性能指标

指标 原架构 (Halo Docker) 新架构 (Cloudflare Pages)
TTFB 1-3秒 200-500毫秒
费用 电费+服务器成本 Cloudflare 免费额度内
可用性 依赖家宽网络 全球边缘节点
维护 需维护 Docker/DB 仅需维护内容

功能对比

保留的功能:

  • 文章发布与编辑(通过 Halo 后台)
  • 分类与标签
  • 基础主题样式

新增的功能:

  • 全球 CDN 加速
  • D1 数据库(评论系统)
  • Pages Functions(自定义逻辑)
  • 更好的开发者体验

暂时缺失的功能:

  • Halo 插件生态系统
  • 实时预览
  • 用户管理

经验总结

值得做的事

  1. 渐进式迁移:不是一次性切换,而是逐步转移功能
  2. 保留编辑体验:内容创作工具的重要性不亚于发布平台
  3. 利用免费资源:Cloudflare 的免费套餐足够个人博客使用
  4. 自动化一切:手动操作越少,维护成本越低

可以改进的地方

  1. 同步延迟:目前有最长6小时的同步延迟,可考虑实时 webhook
  2. 功能完整性:搜索、站内统计等高级功能需要重新实现
  3. 主题定制:Cloudflare Pages 的主题定制不如 Halo 灵活

后续计划

  1. 实时同步:开发 Halo webhook 插件,实现秒级同步
  2. 增强搜索:集成 Algolia 或 Meilisearch
  3. 数据分析:使用 Cloudflare Analytics 和 Web Analytics
  4. 边缘实验:尝试 Durable Objects、Queues 等新特性

工具与资源

结语

这次迁移让我深刻体会到:架构的选择本质上是取舍的艺术。Halo 提供了完整的 CMS 体验,Cloudflare Pages 提供了极致的性能与扩展性。我的混合架构试图兼顾两者,虽然增加了复杂性,但获得了更大的灵活性和更好的用户体验。

对于个人博客来说,最重要的是持续创作。工具应该服务于这个目标,而不是成为负担。这次迁移后,我可以更专注于内容本身,而将运维复杂性交给 Cloudflare。


迁移时间:2026年11月 当前状态:正常运行,持续优化中 问题反馈:欢迎通过评论或邮件交流迁移经验