墨点博客迁移记:从 Halo Docker 到 Cloudflare Pages 的完整实践
为什么迁移?
墨点博客最初基于 Halo 2.x 运行在我的家庭服务器上,通过 Docker 部署,Caddy 提供 HTTPS 反代。这个架构运行了一年多,稳定性不错,但也暴露了几个问题:
- 家宽网络的不稳定性:虽然配置了 DDNS 和端口映射,但国际链路质量时好时坏
- 维护成本:需要维护 Docker 容器、数据库、备份系统
- 扩展性问题:想尝试一些前沿技术(如边缘函数、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 插件生态系统
- 实时预览
- 用户管理
经验总结
值得做的事
- 渐进式迁移:不是一次性切换,而是逐步转移功能
- 保留编辑体验:内容创作工具的重要性不亚于发布平台
- 利用免费资源:Cloudflare 的免费套餐足够个人博客使用
- 自动化一切:手动操作越少,维护成本越低
可以改进的地方
- 同步延迟:目前有最长6小时的同步延迟,可考虑实时 webhook
- 功能完整性:搜索、站内统计等高级功能需要重新实现
- 主题定制:Cloudflare Pages 的主题定制不如 Halo 灵活
后续计划
- 实时同步:开发 Halo webhook 插件,实现秒级同步
- 增强搜索:集成 Algolia 或 Meilisearch
- 数据分析:使用 Cloudflare Analytics 和 Web Analytics
- 边缘实验:尝试 Durable Objects、Queues 等新特性
工具与资源
结语
这次迁移让我深刻体会到:架构的选择本质上是取舍的艺术。Halo 提供了完整的 CMS 体验,Cloudflare Pages 提供了极致的性能与扩展性。我的混合架构试图兼顾两者,虽然增加了复杂性,但获得了更大的灵活性和更好的用户体验。
对于个人博客来说,最重要的是持续创作。工具应该服务于这个目标,而不是成为负担。这次迁移后,我可以更专注于内容本身,而将运维复杂性交给 Cloudflare。
迁移时间:2026年11月 当前状态:正常运行,持续优化中 问题反馈:欢迎通过评论或邮件交流迁移经验
分享到微信
在微信里打开这篇文章,点右上角「···」→「分享到朋友」
手机扫码打开
加载中…