#故障排查

#/api/health 显示 degraded

issues 数组列出缺失或非法的字段。常见原因：

• COMMENTS_SECRET 少于 32 字节
• ALLOWED_ORIGINS 为空
• MODERATION_REQUIRED 不是严格的 true / false
• 开启了审核但没有完整的发件配置

#评论读不到

1. 检查 git.readable 是否为 true
2. 检查 COMMENTS_REPO 拼写与大小写
3. 检查 PAT 是否勾选了该仓库
4. 私有仓库同样可以读，只要 PAT 有 Contents: Read

#批准后评论不出现

读路径有缓存，最多约 60 秒。等待一分钟后刷新。若仍未出现：

1. 打开评论仓库，确认 comments/<slug>.json 是否已更新
2. 检查 post 是否一致（widget 的 location.pathname 与服务端规范化结果）
3. 检查浏览器缓存

#批准失败 403

• origin_not_allowed：评论提交时的来源已从 ALLOWED_ORIGINS 移除
• GitHub 403：PAT 权限不足或仓库不匹配
• 检查 token 是否被撤销

#批准失败 409

同一 id 的评论已存在且内容不同。系统不会覆盖已有评论。若确认要替换，请在仓库中手动编辑该文件。

#提交返回 429

同一 IP 在 10 分钟内提交超过 5 次。等待窗口结束后再试。这是为了防止邮件额度被打爆。

#人机验证一直失败

• 检查 TURNSTILE_SITE_KEY 与 TURNSTILE_SECRET 是否成对且来自同一 Turnstile 站点
• 检查博客域名是否已加入该 Turnstile 站点的允许域名列表
• Turnstile token 是一次性的，重复提交需重新获取

#收不到审核邮件

1. 检查发件域名是否完成 DNS 验证
2. 查看发件平台（Resend / MailPort）后台日志
3. 检查垃圾邮件箱
4. 若用 MailPort，确认审核邮箱域名在收件白名单内

#审核链接提示已过期

链接 7 天有效。过期后只能让评论者重新提交。

#同仓库模式下频繁重新部署

参考 存储位置 配置平台的跳过构建规则，排除 comments/ 目录。

#密钥轮换后旧链接失效

这是预期行为。COMMENTS_SECRET 一旦更换，所有未使用的审核链接立即失效。已写入的加密邮箱仍可通过指纹识别，旧钥可临时保留用于解密。