开源一个AI开发的自用评论系统:Qingniao

Qingniao 评论系统基于 Cloudflare Workers + D1 (SQLite) + KV 构建，专为现代静态博客与网站设计。

来源：

青鸟，不是北大的那个，是传说中西王母的使者、传递信息的仙禽，象征着自由、速度与希望。
青鸟不传云外信，丁香空结雨中愁。
我还喜欢这只鸟：Twitter

开源地址：https://github.com/harry10086/Qingniao

核心特性

• ⚡ 极致性能：依托 Cloudflare 全球边缘网络，配合 D1 SQLite 与 KV Edge 读写缓存，毫秒级极速响应。
• 🛡️ 安全与反垃圾：
  • 动态轻量级数学验证码（防机刷）；
  • 基于 KV 的 IP 级别滑动窗口速率限制（Rate Limiting）；
  • 智能反垃圾规则引擎：过量链接、手机号引流、灌水重复字符自动拦截；
  • 动态敏感词词库：支持后台在线单条/批量添加自定义敏感词，提供 「直接拒绝 (Block)」 与 「转入待审核 (Pending)」 双重处置策略；
  • IP 黑名单与一键封禁：支持手动录入 IP 黑名单，或在管理后台对违规评论 「一键封禁 IP」；
  • 隐私保护：IP 匿名脱敏单向哈希，邮箱安全加密。
• 📝 现代化富文本体验：
  • 内置精简 Markdown 解析引擎（支持加粗、斜体、删除线、行内代码、代码块、引用、链接等）；
  • 分类 Emoji 表情面板，一键点击插入；
  • 500 字数限制与剩余字数动态提醒。
• 💬 强大交互功能：
  • 多层级嵌套评论与回复树；
  • 赞成 👍 与反对 👎 投票机制（带防重复刷票与取消功能）；
  • 支持「最新发布」、「最早发布」、「最多赞成」多维度排序；
  • 置顶评论徽章与博主官方身份高亮徽章。
• 👑 完善的独立管理后台：
  • 单文件轻量 Web 面板，零编译直接使用；
  • 支持多状态筛选（待审核/已通过/已拒绝）；
  • 支持文章链接与页面标题关键词模糊检索；
  • 博主在线一键快捷回复（自动免审展示 + 异步邮件提醒）；
  • 批量通过、批量拒绝、批量删除、一键置顶；
  • 信任机制：已审核通过的用户后续发评自动免审；
  • 全面跨平台一键平滑迁移：内置通用导入引擎，原生支持 WordPress (WXR/XML & JSON)、Typecho、Waline、Artalk、Twikoo 历史数据一键导入（自动递归还原回复树、HTML 智能转 Markdown、文件拖拽与实时诊断预览）与原生 JSON/CSV 导出。
• 📧 邮件异步通知：
  • 集成 Resend API，新评论即时提醒博主，读者被回复时自动通知作者。
• 🎨 精美设计与主题自适应：
  • 现代圆角微阴影设计，CSS 变量轻松定制配色；
  • 完美自适应亮色（Light）与暗色（Dark）模式。

界面

登录：

评论管理：

导入：

评论：

垃圾管理：

该评论系统除了名字由我取之外，全部由 Gemini 开发。目前已开源，可自行修改：Qingniao 评论系统 GitHub 仓库

静态博客中使用

一套完整的青鸟（Qingniao）评论系统包含三部分：

1. 后端服务：运行在 Cloudflare Workers 上（带 D1 数据库与 KV 缓存）；
2. 博客前台：在 Hexo 博客文章底部展示评论框并与后端交互；
3. 管理后台：独立单文件 Web 面板，可直接集成进 Hexo 随博客发布。

准备工作

• 已注册 Cloudflare 账号
• 本地装有 Node.js（推荐 20+ 版本）
• 本地有一个可运行的 Hexo 博客项目

第一阶段：部署后端 (Cloudflare Workers)

1. 进入服务端目录并安装依赖

在本项目根目录打开终端：

cd server
npm install

2. 登录 Cloudflare

npx wrangler login

浏览器会自动弹出授权页面，点击同意即可。

3. 创建 D1 数据库与 KV 命名空间

# ① 创建 D1 数据库
npx wrangler d1 create qingniao-comments

控制台会输出类似：

database_name = "qingniao-comments"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# ② 创建 KV 缓存
npx wrangler kv namespace create qingniaoKV

控制台会输出类似：

id = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

4. 配置 server/wrangler.toml

复制或直接编辑 server/wrangler.toml，将上面输出的 database_id 和 KV id 填入：

name = "qingniao-comments"
main = "src/index.js"
compatibility_date = "2024-04-01"

# 绑定 D1
[[d1_databases]]
binding = "DB"
database_name = "qingniao-comments"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # 替换为你的真实 database_id

# 绑定 KV
[[kv_namespaces]]
binding = "KV"
id = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"             # 替换为你的真实 KV id

[vars]
CORS_ORIGIN = "https://yourblog.com"                # 换成你的博客域名（本地测试可先填 "*"）
SITE_NAME = "我的博客"
SITE_URL = "https://yourblog.com"
ADMIN_EMAIL = "admin@yourblog.com"                  # 博主邮箱（接收提醒、前台博主认证）

5. 初始化数据库表结构与设置 Secret

# ① 线上数据库建表
npm run db:init:remote

# ② 设置验证码加盐秘钥 (必填，随意输入一段随机复杂字符)
npx wrangler secret put CAPTCHA_SECRET

# ③ (可选) 如果需要邮件通知，配置 Resend API Key
npx wrangler secret put RESEND_API_KEY

6. 部署后端 Worker

npm run deploy

部署成功后，命令行会输出分配的 API 地址，例如：
https://qingniao-comments.yourname.workers.dev（记录此地址为 API_URL）。

7. 初始化管理员账号

执行以下命令创建管理员（将 URL 与密码替换为您自己的）：

curl -X POST https://qingniao-comments.yourname.workers.dev/api/admin/init \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword123"}'

返回 {"success":true,"message":"管理员创建成功"} 即表示后端完全部署就绪！

---

第二阶段：在 Hexo 博客中集成评论前台

方案 A：Butterfly 主题集成（推荐）

如果您的 Hexo 博客使用的是 Butterfly 主题：

1. 放置静态资源文件：
   将本项目 client/qingniao.js 复制到博客的 source/js/qingniao.js；
   将本项目 client/qingniao.css 复制到博客的 source/css/qingniao.css。

2. 复制模板文件：
   将本项目 integrations/hexo-butterfly/layout/ 整个目录覆盖复制到博客的 themes/butterfly/layout/ 下。

3. 在 Butterfly 中注册 Qingniao：
   在 themes/butterfly/layout/includes/third-party/comments/index.pug 的 case comment 分支下添加：

   case theme.comments.use[0]
     when 'Qingniao'
       include ./qingniao.pug

   并在 themes/butterfly/layout/includes/third-party/comments/js.pug 下同样加上：

   case theme.comments.use[0]
     when 'Qingniao'
       include ./qingniao.pug

4. 配置主题配置文件 _config.butterfly.yml：

   comments:
     use:
       - Qingniao
     lazyload: true
     count: true
   
   qingniao:
     apiUrl: https://qingniao-comments.yourname.workers.dev  # 你的 Worker 地址
     option:
       placeholder: 蓬山此去无多路，青鸟殷勤为探看...
       adminBadge: 博主
       masterEmail: admin@yourblog.com                       # 与后端填写的博主邮箱一致

---

方案 B：通用 Hexo 主题接入（适用于 Next / Fluid / 任意其他主题）

如果使用的是其他主题，只需利用 Hexo 的自定义 HTML/注入机制：

1. 拷贝文件：
   将 client/qingniao.js 放到博客 source/js/，client/qingniao.css 放到博客 source/css/。

2. 在文章模板（或主题自定义 injection 代码块）底部添加：

   <!-- 引入样式 -->
   <link rel="stylesheet" href="/css/qingniao.css">
   
   <!-- 评论容器 -->
   <div id="qingniao-wrap"></div>
   
   <!-- 引入脚本并初始化 -->
   <script src="/js/qingniao.js"></script>
   <script>
     Qingniao.init({
       el: '#qingniao-wrap',
       apiUrl: 'https://qingniao-comments.yourname.workers.dev', // 你的 Worker 地址
       placeholder: '说点什么吧...',
       adminBadge: '博主',
       masterEmail: 'admin@yourblog.com'
     });
   </script>

第三阶段：部署管理后台 (博主管理端)

无需额外买服务器，直接将管理后台静态页放进 Hexo 静态博客中随站发布：

1. 在 Hexo 博客的 source/ 目录下新建 comment-admin 文件夹：

   hexo-blog/
   └── source/
       └── comment-admin/
           └── index.html

2. 将本项目 admin/index.html 复制并重命名为 source/comment-admin/index.html。
3. 在该文件的最上方加入 front-matter，防止 Hexo 渲染器破坏 HTML：

   ---
   layout: false
   ---

   (如果文件开头已有此标记则无需重复添加)
4. 执行 Hexo 构建与发布：

   hexo clean && hexo g && hexo d

5. 部署后，访问：
   https://yourblog.com/comment-admin/
   在页面中输入您的 Worker API 地址、管理员账号 admin 与密码即可登录。

第四阶段：验证测试

1. 打开 Hexo 任意一篇文章底部，能看到青鸟评论框；
2. 输入昵称、邮箱、评论内容，计算图形验证码，点击发表评论；
3. 打开 https://yourblog.com/comment-admin/，可看到刚才提交的评论；
4. 点击该评论下方的 💬 回复，输入回复内容并点击 发送回复，前台即时同步展示带博主标识的嵌套回复。