#API 参考

所有响应均为 JSON。错误体统一：

{ "error": "invalid_post", "message": "post is invalid" }

#GET /api/comments

读取某篇文章的已发布评论。

GET /api/comments?post=hello-world

成功 200：

{
  "post": "hello-world",
  "updatedAt": "2026-10-30T05:00:00.000Z",
  "comments": [
    {
      "id": "8c8f3690-7bb7-4add-901d-c829b337417e",
      "parentId": null,
      "name": "Alice",
      "content": "写得好。",
      "createdAt": "2026-10-30T04:12:00.000Z"
    }
  ]
}

• 文件不存在时返回 200 与空数组，便于新文章首次评论前正常渲染
• 邮箱字段永不出现
• 响应头：Cache-Control: public, s-maxage=60, stale-while-revalidate=600
• CORS 只回命中 ALLOWED_ORIGINS 的 Origin

错误：400 invalid_post、403 origin_not_allowed、502 git_unavailable、503 service_unavailable

#POST /api/submissions

请求体必须包含 action。

#action: challenge

{
  "action": "challenge",
  "post": "hello-world",
  "name": "Alice",
  "content": "写得好。",
  "parentId": null
}

成功 200：

{ "ok": true, "siteKey": "...", "turnstileAction": "submit", "cData": "..." }

服务端会先校验来源、蜜罐、长度、链接数、父评论，再派生 Turnstile 的 cData（内容摘要）。widget 用返回的 siteKey 与 cData 渲染验证组件。

#action: submit

challenge 的字段，外加：

{
  "turnstileToken": "...",
  "email": "alice@example.com",
  "website": ""
}

website 是蜜罐，必须为空。

成功且开启审核：{ "ok": true, "pending": true } 成功且关闭审核：{ "ok": true, "pending": false, "id": "..." }

错误：400 turnstile_failed、400 invalid_submission、400 spam_rejected、403 origin_not_allowed、429 rate_limited、502 mail_send_failed、502 git_write_failed、503 mail_not_configured

#action: preview

{ "action": "preview", "token": "<envelope>" }

只解封、验签、验期限，返回可展示字段，不写入任何内容。扫描器访问审核页只会走到这里。

成功 200：post、name、content、parentId、createdAt、hasEmail、exp

错误：400 token_invalid、400 token_expired

#action: approve

{ "action": "approve", "token": "<envelope>" }

复验后再写入。成功 200：

{ "ok": true, "id": "...", "created": true }

created 为 false 表示该评论此前已被批准，本次为幂等命中。

错误：400 token_invalid、400 token_expired、403 origin_not_allowed、409 conflict、502 git_write_failed

#GET /api/health

无需鉴权，不返回任何密钥。

{
  "status": "ok",
  "git": { "repo": "owner/repo", "branch": "main", "path": "comments", "readable": true, "writable": true },
  "sameRepo": false,
  "sameRepoWarning": null,
  "moderation": true,
  "moderationWarning": null,
  "mail": { "provider": "resend", "configured": true },
  "issues": [],
  "timestamp": "2026-10-30T05:00:00.000Z"
}

配置不完整时 status 为 degraded，HTTP 状态码为 503。