问题:为什么静态站点要自己造轮子?

墨点博客从 Halo 迁移到 Astro + Cloudflare Pages 后,面临一个经典问题:静态站点没有后端,用户评论怎么存?

市面上成熟的评论方案很多——Disqus、Giscus、Cusdis……但我需要的方案必须符合三个条件:

  1. 数据自主:评论要存在我自己手里,不能因为第三方服务停摆就消失
  2. 零成本:个人博客不能产生订阅费
  3. 防滥用:既能防垃圾评论,又不给真实用户添麻烦

权衡之后,我选择了 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)

几个设计要点:

  1. 使用 Unix 毫秒时间戳:Date 对象在 D1 中实际是字符串,统一用 INTEGER 存储毫秒数
  2. 分层设计:parent_id 支持回复功能
  3. 三级状态:pending(待审核)→ approved(已通过)→ spam(垃圾)
  4. 复合索引:高频查询路径都需要索引支撑

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.

排查过程:

  1. 验证账户权限:wrangler whoami 返回正常
  2. 检查 D1 套餐:需要免费的 “Workers Paid” 计划
  3. 升级订阅:在 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"

排查过程:

  1. 检查绑定名称:前后端必须一致
  2. 部署时绑定:需要 --binding 参数
  3. 部署命令: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()

这是多环境开发的典型问题。容器重启会丢失所有未挂载的数据。

性能考量

  1. D1 读性能:毫秒级响应,适合博客评论场景
  2. 缓存策略:评论不常变,可以前端缓存 5 分钟
  3. 分页方案:个人博客评论量小,一次性全量加载可行
  4. 备用方案:D1 不可用时降级到 localStorage 暂存,待恢复后同步

防滥用措施小结

  1. 三层验证:蜜罐(前端)+ 频率限制(API)+ 关键词过滤(后端)
  2. IP 信誉:利用 Cloudflare 的 cf.threat_score
  3. 审核流:新用户前 2 条评论进入 pending,老用户自动 approved
  4. 监控报警:评论异常增长时邮件通知

部署命令

完整的部署流程需要三步:

# 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/月 无限 ✅

结论:完全在免费额度内。

经验总结

  1. 数据自主是第一原则:第三方评论服务随时可能停止
  2. 从最简单的方案开始:sqlite + 几个 API 接口就能满足需求
  3. 防滥用比功能重要:没人评论比全是垃圾评论好
  4. 工具链要完整:建库、部署、管理、监控都需具备
  5. 文档就是运维手册:写下每一步,半年后还能复现

静态站点的评论系统不必复杂,但必须可靠。这套方案已经在墨点博客稳定运行 30 天,经受住了真实流量的考验。

下一篇,我将分享在 Astro 内容集合中遇到的 Date 对象类型陷阱。