一、核心原理

为什么能免费？

Cloudflare 提供了一套免费的 Serverless 生态，恰好覆盖了一个博客系统的全部需求：

一个个人博客的流量和存储远低于上述限额，因此完全零成本 24 小时在线。

二、架构设计

整体架构图

用户浏览器
    │
    ▼
┌─────────────────────────────────────────────────┐
│              Cloudflare CDN (全球边缘节点)          │
│                                                   │
│  ┌──────────────────┐    ┌────────────────────┐  │
│  │  静态资源 (SPA)     │    │  API (/api/*)        │  │
│  │  client/dist/     │    │  Pages Functions    │  │
│  │  React + Vite     │    │  Hono Framework     │  │
│  └──────────────────┘    └────────┬───────────┘  │
│                                    │               │
│                            ┌───────┴───────┐      │
│                            │    D1 (SQLite)   │      │
│                            │   blog-db        │      │
│                            └───────────────┘      │
└─────────────────────────────────────────────────┘

为什么是「Pages Functions」而不是「Workers」？

• Pages Functions 和 Pages 项目天然一体，部署时无需分别管理
• 自动处理 SPA 路由回退（所有非 /api/* 请求返回 index.html）
• 部署命令更简单：直接 deploy client/dist，Functions 目录自动关联

技术选型

三、项目结构

blog/
├── client/                    # React SPA 前端
│   ├── src/
│   │   ├── api.js             # API 客户端 (自动注入 JWT token)
│   │   ├── main.jsx           # React 入口 + 路由定义
│   │   ├── App.css            # 全局样式 (CSS 变量 + glassmorphism)
│   │   ├── components/
│   │   │   ├── Layout.jsx         # 整体布局 (顶栏+侧栏+页脚)
│   │   │   ├── PostCard.jsx       # 文章卡片
│   │   │   ├── ProfileCard.jsx    # 个人信息卡片
│   │   │   ├── CommentSection.jsx # 评论组件
│   │   │   ├── KanbanGirl.jsx     # Live2D 看板娘
│   │   │   └── Background.jsx     # 动态壁纸 (5分钟轮换)
│   │   └── pages/
│   │       ├── Home.jsx           # 首页 (文章列表+标签+布局切换)
│   │       ├── Post.jsx           # 文章详情 + 评论
│   │       ├── Search.jsx         # 全文搜索
│   │       ├── Guestbook.jsx      # 留言板
│   │       ├── Login.jsx          # 管理员登录
│   │       └── admin/
│   │           ├── Dashboard.jsx  # 文章管理 (CRUD)
│   │           ├── EditPost.jsx   # 编辑文章
│   │           ├── NewPost.jsx    # 新建文章
│   │           └── ProfileEdit.jsx# 个人设置 (名称/头像/密码)
│   └── vite.config.js         # Vite 配置 (含开发代理)
├── functions/
│   └── api/
│       └── [[path]].ts        # 全部 API 路由 (Hono + Pages Functions)
├── schema.sql                 # D1 建表语句
├── seed-admin.cjs             # 生成管理员 PBKDF2 密码哈希
├── wrangler.toml              # Cloudflare Pages + D1 配置
├── .dev.vars                  # 本地开发环境变量
└── package.json               # 依赖 + 脚本

四、核心技术细节

4.1 API 路由 — Hono on Pages Functions

functions/api/[[path]].ts 是唯一的 API 入口文件，使用 Hono 框架处理所有路由。

关键设计：

// Hono 连接 Pages Functions
import { Hono } from 'hono'
import { handle } from 'hono/cloudflare-pages'

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()

app.get('/api/posts', async (c) => { /* ... */ })
app.post('/api/auth/login', async (c) => { /* ... */ })
app.put('/api/profile', authGuard, async (c) => { /* ... */ })

export const onRequest = handle(app)

为什么使用 [[path]].ts（catch-all 路由）？

• /api/posts → [[path]].ts 处理
• /api/profile → 同文件处理
• 所有 /api/* 请求统一路由，避免为每个端点创建单独文件

为什么可以在同一个文件里处理所有路由？

• Hono 内部实现了路由树匹配，app.get('/api/posts', ...) 和 app.get('/api/profile', ...) 互不干扰
• 这是 Hono/Express/Koa 风格的标准做法，不是 hack

4.2 JWT 认证

// 签发 token
const token = await sign({ username: user.username }, secret, 'HS256')

// 验证 token
const payload = await verify(token, secret, 'HS256')

• 使用 hono/jwt 的 sign() 和 verify()
• 必须显式指定 'HS256' 算法，否则 verify 会失败（与 jsonwebtoken 库不同）
• Token 无过期时间（管理员登录长期有效）
• authGuard 中间件拦截所有写操作（文章/POST/DELETE、评论删除、留言删除、个人资料修改）

4.3 认证流程

1. POST /api/auth/login { username, password }
2. 服务端查 users 表 → PBKDF2 密码验证
3. 验证通过 → sign({ username }, JWT_SECRET, 'HS256') → 返回 token
4. 客户端 localStorage.setItem('token', token)
5. 后续请求自动在 Authorization 头注入 Bearer token
6. authGuard 中间件 verify() 验证 token

4.4 数据库 — D1

D1 是 Cloudflare 的边缘 SQLite 数据库，语法与 SQLite 完全兼容。

数据表设计：

• posts — 博客文章 (title, content, summary, timestamps)
• tags — 标签 (name, UNIQUE)
• post_tags — 文章-标签多对多关联
• comments — 文章评论 (author, content, post_id FK)
• guestbook — 留言板 (author, content)
• profile — 个人资料单例 (id=1, name, bio, avatar, layout)
• users — 管理员账户 (username, password_hash)

头像存储： 直接存 base64 数据 URL 在 profile 表的 avatar 列，无需文件存储。适合小尺寸头像（<100KB）。

4.5 SPA 路由回退

生产环境中，所有非 /api/* 的请求都应该返回 index.html，由 React Router 处理客户端路由。

• Cloudflare Pages 自动处理 SPA 回退
• 后端无需任何 _redirects 或 catch-all 规则（Pages Functions 不匹配的路径自动走静态文件）
• 开发模式下由 Vite 处理

4.6 前端 API 客户端

client/src/api.js 统一封装：

const API_BASE = '/api'  // 相对路径，生产环境走同源

async function request(path, options = {}) {
  const token = localStorage.getItem('token')
  const headers = {
    'Content-Type': 'application/json',
    ...(token && { Authorization: `Bearer ${token}` })
  }
  const res = await fetch(`${API_BASE}${path}`, { ...options, headers })
  const data = await res.json()
  if (!res.ok) throw new Error(data.error)
  return data
}

• 所有请求走同源 /api/...，无需 CORS 配置
• Token 自动注入，401 时前端提示重新登录

五、迁移路线图

原始架构 vs 目标架构

迁移步骤

第一步：剥离后端（最关键的改造）

原始代码中，Express 服务器同时负责 API 和静态文件托管：

server/src/index.js → Express app
  ├── /api/* 路由
  ├── 静态文件托管 client/dist/
  └── SPA fallback

需要拆分为两层：

Cloudflare Pages
  ├── Pages Functions (/api/*)  → 替代 Express 路由
  └── 静态文件 (client/dist/)   → 替代 Express 静态托管

主要挑战：

1. Express → Hono 重写

   • Express req.body → Hono c.req.json()
   • Express req.params → Hono c.req.param('key')
   • Express res.json() → Hono return c.json()
   • Express res.status() → Hono c.json({...}, 400)
   • Express 中间件签名 (req, res, next) → Hono 中间件签名 (c, next)

2. bun:sqlite → D1

   • db.query('SELECT * FROM posts').all() → c.env.DB.prepare('SELECT * FROM posts').all()
   • db.run() → c.env.DB.prepare().run()
   • 参数绑定：? 占位符在 D1 中同样支持

3. 文件上传 → base64

   • 原始用 multer 中间件处理 multipart/form-data
   • 改为前端将图片转为 base64 data URL，通过 JSON body 发送
   • 好处：无需文件存储，无需处理 FormData

4. jsonwebtoken → hono/jwt

   • jwt.sign() → sign() (hono/jwt)
   • jwt.verify() → verify() (hono/jwt)
   • 关键差异： hono/jwt 的 verify 必须传入算法参数 'HS256'，否则静默失败

5. Bun PBKDF2 → Web Crypto PBKDF2

   • Bun.password.hash() / Bun.password.verify() → Web Crypto API crypto.subtle.deriveBits()
   • 原因：Pages Functions 运行在 V8 Isolate 中，没有 Bun 的密码 API

6. Schema 迁移

   • 从 server/data/blog.db 提取 SQLite schema
   • 写出 schema.sql
   • 通过 wrangler d1 execute --remote --file=schema.sql 应用到 D1

第二步：前端适配

前端改造相对简单：

• API_BASE 从 http://localhost:3000/api 改为 /api（同源请求）
• 移除 FormData 上传，改用 base64
• 其他代码基本不变（React Router、组件、样式全部保留）

第三步：部署配置

1. 创建 wrangler.toml，绑定 D1 数据库
2. 创建 .dev.vars，配置本地开发环境变量
3. 设置 package.json 脚本（dev/build/deploy）

第四步：生产部署

bun run build                              # Vite 构建前端
bunx wrangler pages deploy client/dist     # 部署到 Cloudflare Pages

六、本地开发

开发架构

┌─────────────────────────────┐
│   Vite Dev Server :5173      │
│   (React HMR + 代理)         │
│                              │
│   /api/* → localhost:8788 ───┼──┐
└──────────────────────────────┘  │
                                   ▼
┌─────────────────────────────┐
│   Wrangler Dev :8788         │
│   (Pages Functions + D1)     │
│                              │
│   本地 D1 模拟 (SQLite)       │
│   数据目录: .wrangler/state/  │
└─────────────────────────────┘

开发命令

bun install                    # 安装依赖
bun run db:local               # 初始化本地 D1 并建表
bun run dev                    # 同时启动 Vite + Wrangler

Vite 配置中 proxy: { '/api': 'http://localhost:8788' } 将 API 请求转发到 Wrangler 模拟的 Pages Functions。

环境变量

本地开发环境变量在 .dev.vars 中定义，Pages Functions 在本地运行时会自动加载（无需 dotenv）。

七、为什么这样设计

函数入口的单文件模式

functions/api/[[path]].ts 是整个 API 的唯一入口，而不是每个端点一个文件（如 functions/api/posts.ts、functions/api/profile.ts）。

原因：

• Hono 路由树：Hono 在单个 app 实例中管理所有路由，路由匹配效率高
• 共享中间件和工具函数：认证中间件、密码哈希、数据库操作都在同一个文件中，无需跨文件导入
• 部署简单：只有一个 Function 入口，冷启动后所有路由共享同一个 V8 Isolate 实例
• 符合 Cloudflare 最佳实践：Workers 官方推荐使用 Hono/Itsy 等框架，而不是每个路由一个文件

为什么不用 Workers + KV？

• Workers 单独部署 意味着要管理两个独立项目（Pages + Workers），并处理跨域
• Pages Functions 与 Pages 一体，部署时无需额外配置
• D1 比 KV 更适合关系型数据：文章、标签、评论需要 JOIN 和关联查询
• KV 适合键值缓存（如 URL 重定向），不适合复杂查询

头像为什么用 base64 而不是文件上传？

• Pages Functions 本身不提供持久化文件存储
• 使用 R2（Cloudflare 的对象存储）会增加架构复杂度
• base64 直接存数据库，读写简单，适合小尺寸头像
• 避免 FormData 解析和 multipart 处理

八、费用分析

假设月均 PV 50,000 次：

结论：个人博客完全不需要付费。

九、常见问题

Q: 为什么不直接用 GitHub Pages？

A: GitHub Pages 只能托管静态文件，无法运行服务端代码。博客需要后端 API（文章管理、认证、评论等），必须使用能运行服务端逻辑的平台。

Q: Pages Functions 冷启动慢吗？

A: Hono 框架极轻量（约 12KB），冷启动通常在 50-200ms。相比 Express（约 2MB），Hono 在 Serverless 场景有明显优势。

Q: D1 数据库丢失了怎么办？

A: D1 自动多副本存储，且有自动备份。可通过 wrangler d1 backup 手动创建备份。

Q: 如何绑定自定义域名？

A: 在 Cloudflare Dashboard → Workers & Pages → 项目 → 自定义域中添加。要求域名的 DNS 托管在 Cloudflare 上，HTTPS 证书自动颁发。

Q: Token 过期了怎么办？

A: 当前 JWT 没有设置过期时间。登出时清除 localStorage 即可。如果需要过期机制，在 sign() 时添加 exp 负载即可。

十、总结

这套架构的本质是：

将传统 VPS 上的 monolithic 应用拆分为 Cloudflare Serverless 生态的标准架构：Pages（静态）+ Pages Functions（API）+ D1（数据库）。

核心改造点：

1. Express → Hono（适配 Pages Functions 运行时）
2. bun:sqlite → D1（切换到边缘 SQLite）
3. jsonwebtoken → hono/jwt（无 Node.js 依赖的 JWT）
4. 文件上传 → base64（避免文件存储）
5. Bun PBKDF2 → Web Crypto PBKDF2（兼容 V8 Isolate）

改造完成后实现：

• 零成本 运行，无需付费计划
• 全球 CDN 加速，延迟更低
• 零运维，无需管理服务器、证书、进程
• 自动扩展，流量增长无需干预

这是我的第一篇博客文章。