#审核流程

MODERATION_REQUIRED 控制是否开启人工审核，默认 true。

#开启审核（默认）

评论者提交
  → 蜜罐 / 长度 / 链接数 / 限频
  → Cloudflare Turnstile 校验
  → 整条评论封成加密 + 签名信封
  → 发到博主邮箱
博主点邮件链接
  → 静态审核页只预览（不写入）
  → 点「批准并写入仓库」
  → 复验签名 / 7 天期限 / 来源白名单
  → GitHub Contents API 写入
  → 约 60 秒后博客可见

待审数据不写入任何存储，只存在于审核邮件的 URL fragment 里。

#为什么批准必须是 POST

邮件安全网关会预抓取邮件里的链接。如果批准动作是 GET，扫描器会替你批准。因此链接只打开预览页，真正的写入是页面里的 POST。

#URL fragment 存储

密文放在 #token= 后面而不是查询串里：

• fragment 不会发送到服务器，不进访问日志
• 长度限制几乎不存在（Chrome / Firefox 可承载数 MB）
• 审核页加载后立即用 history.replaceState 清除，防止 Referer 泄露

#凭据规则

• 内容绑定签名（HMAC-SHA256）
• 7 天有效期
• 一次性内容幂等：同 id 同内容重复批准不会重复写入；同 id 不同内容返回 409 且不覆盖

#关闭审核

设置 MODERATION_REQUIRED=false：

评论者提交
  → 蜜罐 / 长度 / 链接数 / 限频
  → Cloudflare Turnstile 校验
  → 直接写入 GitHub
  → 约 60 秒后博客可见

此时：

• 不发任何邮件，MODERATOR_EMAIL 与发件配置不再必填
• widget 成功文案变为「留言已发布，约 1 分钟后可见」
• /api/health 返回 moderation: false 并附警告

风险：Turnstile 一旦失效或被绕过，陌生人可以直接往目标仓库写文件。同仓库模式下后果更严重。若无法承担该风险，请保持审核开启。

#表单知情同意

无论审核是否开启，表单都要求勾选：

我同意昵称和留言经审核后公开，并保留在公开 Git 仓库的历史记录中。

删除评论只能删除当前版本，Git 历史中的记录仍然存在。这一点必须让评论者知情。