给静态博客添加评论系统:从零搭建 Cloudflare D1 + Pages Functions 实战
问题:为什么静态站点要自己造轮子?
墨点博客从 Halo 迁移到 Astro + Cloudflare Pages 后,面临一个经典问题:静态站点没有后端,用户评论怎么存?
市面上成熟的评论方案很多——Disqus、Giscus、Cusdis……但我需要的方案必须符合三个条件:
- 数据自主:评论要存在我自己手里,不能因为第三方服务停摆就消失
- 零成本:个人博客不能产生订阅费
- 防滥用:既能防垃圾评论,又不给真实用户添麻烦
权衡之后,我选择了 Cloudflare D1 + Pages Functions 这条技术路线。
D1 数据库设计
D1 是 Cloudflare 的关系型数据库,本质上是 SQLite。表结构设计是评论系统的核心:
-- 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,
author_website TEXT,
content TEXT NOT NULL,
created_at INTEGER DEFAULT (unixepoch() * 1000),
parent_id INTEGER,
status TEXT CHECK(status IN ('pending', 'approved', 'spam')) DEFAULT 'pending'
);
-- 索引策略
CREATE INDEX idx_post_slug ON comments(post_slug);
CREATE INDEX idx_created_at ON comments(created_at DESC);
CREATE INDEX idx_status ON comments(status);
-- 同一 IP 在 24 小时内最多 5 条评论(需配合 Pages Functions 的 ctx.request.cf)
几个设计要点:
- 使用 Unix 毫秒时间戳:Date 对象在 D1 中实际是字符串,统一用
INTEGER存储毫秒数 - 分层设计:
parent_id支持回复功能 - 三级状态:
pending(待审核)→approved(已通过)→spam(垃圾) - 复合索引:高频查询路径都需要索引支撑
API 设计与 Pages Functions
在 Cloudflare Pages 项目中创建 functions/api/comments.ts:
interface Env {
DB: D1Database;
}
export const onRequestPost: PagesFunction<Env> = async (context) => {
const { request } = context;
const slug = new URL(request.url).searchParams.get('slug');
// 1. 基础校验
if (!slug) {
return new Response(
JSON.stringify({ error: '缺少文章标识' }),
{ status: 400, headers: { 'Content-Type': 'application/json' } }
);
}
// 2. 从数据库中获取文章评论
const comments = await context.env.DB.prepare(`
SELECT id, author_name, author_website, content, created_at, parent_id
FROM comments
WHERE post_slug = ? AND status = 'approved'
ORDER BY created_at ASC
`).bind(slug).all();
return new Response(
JSON.stringify({
ok: true,
comments: comments.results || []
}),
{ headers: { 'Content-Type': 'application/json' } }
);
};
发表评论的 API 需要更多防御:
export const onRequestPost: PagesFunction<Env> = async (context) => {
const ip = context.request.headers.get('cf-connecting-ip') || 'unknown';
const country = context.request.headers.get('cf-ipcountry') || 'unknown';
// 1. 蜜罐检测
const data = await context.request.json<SubmitData>();
if (data.website2 && data.website2.trim() !== '') {
// 机器人填了隐藏字段,直接丢弃
return Response.json({ ok: true, message: '评论已接收' });
}
// 2. 频率限制
const lastHour = await context.env.DB.prepare(`
SELECT COUNT(*) as cnt FROM comments
WHERE (
author_email = ? OR
(cf_ip = ? AND cf_ip != 'unknown')
) AND created_at > ?
`).bind(data.email, ip, Date.now() - 3600000).first<{ cnt: number }>();
if (lastHour?.cnt && lastHour.cnt >= 3) {
return Response.json({ error: '发言频率过快,请稍后再试' }, { status: 429 });
}
// 3. 关键词过滤
const badWords = ['赌场', '现金', '贷款', '色情'];
const contentLower = data.content.toLowerCase();
if (badWords.some(word => contentLower.includes(word))) {
await context.env.DB.prepare(`
INSERT INTO comments (post_slug, author_name, author_email, content, status)
VALUES (?, ?, ?, ?, 'spam')
`).bind(data.slug, data.author, data.email, data.content).run();
return Response.json({ ok: true, message: '评论已接收' });
}
// 4. 保存评论
const result = await context.env.DB.prepare(`
INSERT INTO comments (
post_slug, author_name, author_email, author_website,
content, parent_id, cf_ip, cf_country
) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
`).bind(
data.slug, data.author, data.email, data.website,
data.content, data.parentId || null, ip, country
).run();
return Response.json({
ok: true,
message: '评论已提交,待管理员审核后显示',
id: result.meta.last_row_id
});
};
前端实现与 XSS 转义
前端组件 (Comments.astro) 的核心挑战是 XSS 防护。用户输入的评论内容必须安全转义:
---
<script>
function esc(html: string): string {
const div = document.createElement('div');
div.textContent = html;
return div.innerHTML;
}
async function loadComments(slug: string) {
const raw = await fetch(`/api/comments?slug=${encodeURIComponent(slug)}`);
const { comments } = await raw.json();
const container = document.querySelector('#comment-list');
container.innerHTML = comments.map(c => `
<div class="comment">
<div class="author">${esc(c.author_name)}</div>
<div class="content">${esc(c.content)}</div>
<div class="time">${formatTime(c.created_at)}</div>
</div>
`).join('');
}
</script>
<section class="comments">
<div id="comment-list">加载中...</div>
<form @submit.prevent="submitComment">
<!-- 蜜罐字段 -->
<input type="text" name="website2" style="display: none;" autocomplete="off">
<input name="author" required placeholder="昵称">
<input name="email" type="email" placeholder="邮箱(不公开)">
<textarea name="content" required placeholder="评论内容"></textarea>
<button type="submit">发表评论</button>
</form>
</section>
管理后台的朴素实现
静态站点没有传统后台,我用 Python 写了个简单的管理脚本:
#!/usr/bin/env python3
# manage_comments.py
"""
评论管理工具
用法:
python3 manage_comments.py list [pending|approved|spam]
python3 manage_comments.py approve <id>
python3 manage_comments.py delete <id>
"""
import json
import sys
import secrets
TOKEN = open('/path/to/.secrets/cf_token.txt').read().strip()
ACCOUNT = 'your-account-id'
DB_UUID = open('/path/to/.secrets/d1_uuid.txt').read().strip()
def d1_query(sql, params=None):
"""调用 Cloudflare D1 API"""
import urllib.request
url = f"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/d1/database/{DB_UUID}/query"
body = {"sql": sql}
if params:
body["params"] = params
req = urllib.request.Request(
url,
data=json.dumps(body).encode(),
headers={
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json",
},
method="POST",
)
resp = urllib.request.urlopen(req, timeout=30)
result = json.loads(resp.read())
return result.get("result", [{}])[0].get("results", [])
def list_comments(status="pending"):
rows = d1_query(
"SELECT id, post_slug, author, content, created_at FROM comments WHERE status = ? ORDER BY created_at DESC LIMIT 50",
[status]
)
for r in rows:
print(f"#{r['id']} {r['author']} @ {r['post_slug']}")
print(f" {r['content'][:80]}...")
# 后续命令:approve, delete, stats
遇到的真实问题与解决
问题1:D1 数据库创建失败
最初尝试用 wrangler d1 create blog-comments 创建数据库,但报错:
Error: Failed to create D1 database: Your account does not have D1 databases enabled.
排查过程:
- 验证账户权限:
wrangler whoami返回正常 - 检查 D1 套餐:需要免费的 “Workers Paid” 计划
- 升级订阅:在 Cloudflare Dashboard → Workers & Pages → Plan 改为 Workers Paid(免费)
解决方法:
# 1. 升级订阅
# 2. 重新创建
wrangler d1 create blog-comments
# ✅ Database created: blog-comments (UUID: xxxx)
问题2:Pages Functions 无法连接 D1
配置了 wrangler.toml 但运行时提示 DB is undefined:
# wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "blog-comments"
database_id = "xxxx"
排查过程:
- 检查绑定名称:前后端必须一致
- 部署时绑定:需要
--binding参数 - 部署命令:
wrangler pages deploy --project-name=my-project ./dist --binding DB=blog-comments
解决方法:
# 正确的部署命令
wrangler pages deploy ./dist \
--project-name=mydian-blog \
--branch main \
--commit-hash $(git rev-parse HEAD) \
--env-binding DB=blog-comments
问题3:时区混乱
用户提交的评论时间在页面上显示为 UTC 时间:
// ❌ 错误:显示 "Fri Nov 22 2024 08:00:00 GMT+0000"
const date = new Date(created_at);
console.log(date.toString());
// ✅ 正确:转换为本地时间
const local = new Date(created_at).toLocaleString('zh-CN', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
hour12: false
});
console.log(local); // "2024-11-22 16:00"
问题4:dsh 容器没挂载导致文件写进容器内
在测试管理脚本时,我发现日志文件不见了。排查后发现脚本的配置读取路径有问题:
# ❌ 错误:容器内路径
TOKEN = open('/secrets/cf_token.txt').read()
# ✅ 正确:挂载路径
TOKEN = open('/mnt/-1/halo/.secrets/cf_token.txt').read()
这是多环境开发的典型问题。容器重启会丢失所有未挂载的数据。
性能考量
- D1 读性能:毫秒级响应,适合博客评论场景
- 缓存策略:评论不常变,可以前端缓存 5 分钟
- 分页方案:个人博客评论量小,一次性全量加载可行
- 备用方案:D1 不可用时降级到 localStorage 暂存,待恢复后同步
防滥用措施小结
- 三层验证:蜜罐(前端)+ 频率限制(API)+ 关键词过滤(后端)
- IP 信誉:利用 Cloudflare 的
cf.threat_score - 审核流:新用户前 2 条评论进入
pending,老用户自动approved - 监控报警:评论异常增长时邮件通知
部署命令
完整的部署流程需要三步:
# 1. 创建数据库
wrangler d1 create blog-comments
# 2. 初始化表结构
wrangler d1 execute blog-comments --file=./schema.sql
# 3. 部署 Pages Functions
wrangler pages deploy ./dist \
--project-name=mydian-blog \
--env-binding DB=blog-comments
成本统计
| 项目 | 用量 | 免费额度 | 状态 |
|---|---|---|---|
| D1 读操作 | ~100/天 | 100万/天 | ✅ |
| D1 写操作 | ~10/天 | 10万/天 | ✅ |
| Pages Functions | ~100次/天 | 10万次/天 | ✅ |
| Pages 带宽 | ~50MB/月 | 无限 | ✅ |
结论:完全在免费额度内。
经验总结
- 数据自主是第一原则:第三方评论服务随时可能停止
- 从最简单的方案开始:
sqlite+ 几个 API 接口就能满足需求 - 防滥用比功能重要:没人评论比全是垃圾评论好
- 工具链要完整:建库、部署、管理、监控都需具备
- 文档就是运维手册:写下每一步,半年后还能复现
静态站点的评论系统不必复杂,但必须可靠。这套方案已经在墨点博客稳定运行 30 天,经受住了真实流量的考验。
下一篇,我将分享在 Astro 内容集合中遇到的 Date 对象类型陷阱。
分享到微信
在微信里打开这篇文章,点右上角「···」→「分享到朋友」
手机扫码打开
加载中…