kmenta 使用文档

快速开始

把评论区接到你自己的页面，只需要两步：放一个挂载点，再引入一段脚本。样式自动注入，服务器地址自动识别。

最简接入（自动挂载）

<div id="kcomment"></div>
<script src="https://api.example.com/widget/comment-widget.js"></script>

脚本加载后自动寻找 #kcomment 节点并挂载。挂载点缺省用 location.pathname 作为页面 Key，同一篇文章保持同一个评论区。

手动初始化

需要多个评论区、或想精确控制参数时，用 kcomment.init()。脚本仍以普通 script 引入，初始化代码放在其后即可。

<div id="kcomment"></div>
<script src="/widget/comment-widget.js"></script>
<script>
  kcomment.init({
    el: '#kcomment',
    server: 'https://api.example.com',  // 缺省自动识别
    pageKey: '/post/hello-world',       // 缺省用 location.pathname
    theme: 'teal'                          // 缺省 'default'
  });
</script>

属性配置（零 JS）

不想写初始化代码？直接在 script 标签上放属性即可，效果与 init() 参数一一对应。

<div id="kcomment"></div>
<script
  src="https://api.example.com/widget/comment-widget.js"
  data-server="https://api.example.com"
  data-page-key="/post/42"
  data-theme="crimson"
  defer></script>

主题

内置 5 套主题，在评论区右上角即可即时切换（选择会记忆在访客本地）。也可以初始化时指定，或用 CSS 变量整站换色。

所有主题都通过 .kc-widget 上的 --kc-* CSS 变量实现。想微调某个颜色，覆盖变量即可：

<style>
.kc-widget{ --kc-accent:#3a6ea5; --kc-radius:6px; }
</style>

前台能力

• 发表 / 回复：楼中楼回复，最长 1000 字，实时字数统计（接近上限变红提醒）。
• @提及：点「回复」自动填入 @昵称，对方一眼看清是对谁说话。
• 表情：工具栏内置表情选择器，点击在光标处插入，正文即所见。
• 最新 / 最热：评论区右上角一键切换排序——「最新」按时间倒序，「最热」按点赞排序，置顶始终在最上。
• 匿名发言：勾选后真实昵称不下发，对外只显示系统分配的脱敏昵称。
• 点赞：访客端随机指纹去重，同一访客只计一次，刷新页面不会重复。
• 举报：把不当评论标记给管理员处理。
• 头像：填邮箱则用邮箱哈希生成确定性几何头像，不依赖任何第三方头像服务。
• 本地记忆：昵称 / 邮箱 / 主题 / 点赞状态存在访客自己的 localStorage，不上传。

图片上传

图片上传是后台开关控制的。后台「设置 → 图片上传」里可随时开启 / 关闭，并调整单张大小上限（默认 2048KB）。

• 关闭后，评论区输入框不显示 📷 按钮，已上传的图片仍正常显示。
• 图片存于 Cloudflare R2，经 /api/image?key=… 代理访问，不暴露存储域名。
• 单条评论最多 3 张，支持 png / jpg / gif / webp。

人机验证

后台「设置 → 人机验证」开启后，评论发布前必须先通过人机验证，否则提交会被拦截（接口返回「请先完成人机验证」）。服务端校验由 kmenta 完成，你只需要在前端页面提供一个东西：对应服务商的站点密钥（sitekey / AppKey）——验证脚本的加载、验证组件的渲染、评论提交时令牌的携带，都由评论区组件自动完成。

前端需要做的

在引入 comment-widget.js 的 script 标签上加 data-captcha-sitekey="你的站点密钥"（使用 kcomment.init() 时，在参数里传 captcha: { sitekey: '…' } 也可以）：

<div id="kcomment"></div>
<script
  src="https://api.example.com/widget/comment-widget.js"
  data-captcha-sitekey="你的站点密钥"
></script>

Cloudflare Turnstile

在 Turnstile 控制台创建站点，会得到一对密钥：Site Key（前端）与 Secret Key（服务端）。后台「人机验证」填入 Secret Key，前端把 Site Key 填到 data-captcha-sitekey 上即可。

hCaptcha

在 hCaptcha 控制台注册一个站点，会得到 Site Key 与 Secret Key。后台填入 Secret Key，前端把 Site Key 填到 data-captcha-sitekey 上即可。

阿里云验证码

在阿里云「验证码 2.0」控制台创建验证码配置，会得到 AppKey。服务端校验与前端渲染使用同一个 AppKey：后台「人机验证」填入 AppKey，前端把同一个 AppKey 填到 data-captcha-sitekey 上即可（具体字段以阿里云控制台说明为准）。

验证是否生效

• 开启后刷新页面，评论区输入框下方应出现验证组件。
• 不做验证直接点「发布」，会被提示「请先完成人机验证」。
• 验证令牌一次性使用：一条评论发布成功后，下一条需要重新验证。
• 没填 data-captcha-sitekey 时，组件会提示「前端未配置站点密钥」，属正常现象——补上即可。

移动端适配

评论区与官网都为手机做了专门优化：

• 触控友好：点赞 / 回复 / 表情按钮尺寸适中，图片可点击放大查看。
• 布局自适应：窄屏下字段纵向排列、头部精简，不挤、不溢出。
• 官网移动端：顶部导航在窄屏隐藏，页面底部有醒目的「不明白？查看文档」入口，一键直达本文档。
• 主题记忆：访客在手机上选的主题同样会记住，下次回来保持一致。

管理后台

入口 /admin/。全站不采集 IP/UA，管理员只能看到昵称、内容、时间与状态。

初始化

首次打开后台进入安装向导：设置管理员账号、可选配置 AI 审核（OpenAI 兼容接口）、选择审核策略（是否预审）、是否开放图片上传。初始化完成后，后续都能在「设置」里修改。

评论管理

「评论」页按状态切换（待审 / 展示中 / 已拒绝 / 全部），支持关键词搜索与分页。每条评论可单独通过 / 待审 / 拒绝 / 删除，也可勾选多条做批量操作。

页面 / 置顶

• 页面列表：按 page_key 分组统计，可一键清空某页全部评论。
• 置顶：把重要评论置顶，展示在评论区最上方（对应前台支持置顶排序）。
• 导出：一键导出全部评论 JSON，方便迁移备份。
• 违禁模式库：添加「命中即拒绝」的文本模式，并查看拦截日志（不记 IP）。
• 管理员：添加 / 删除协管员，修改自己的密码。

设置

• 预审核：新评论先进待审队列，人工通过才展示。
• AI 审核：调用 OpenAI 兼容接口自动判断，失败自动放行不丢评论。
• 图片上传：开关 + 单张大小上限。
• 人机验证：开关 + 服务商（Cloudflare Turnstile / hCaptcha / 阿里云验证码）+ 服务端校验密钥。开启后需在前端补对应站点密钥，见 人机验证。

部署与自托管

kmenta 完全自托管，数据始终在你自己的账号下。推荐部署在 Cloudflare Pages，整站只需三个托管资源：

• Pages：静态站点与 Pages Functions（评论 / 点赞 / 举报 / 图片代理 / 后台 API）。
• D1：SQLite 数据库，存评论、点赞去重、举报、管理员、设置与违禁模式库。
• R2：对象存储，存放评论图片，经 /api/image 代理读取。

本地初始化数据库并部署：

# 1. 建表（本地方便，--remote 才影响线上库）
wrangler d1 execute kcomment --file=./schema.sql --remote

# 2. 部署站点（自动带上 D1 / R2 绑定）
wrangler pages deploy site --project-name kcomment

# 3. 绑定你自己的域名（可选）
wrangler pages project update kcomment --project-name kcomment
# 或在 Cloudflare 控制台「自定义域」里添加 example.com

数据备份与迁移

后台「导出 JSON」可一键导出全部评论（含回复、图片 Key、点赞数、状态），文件里不含 IP / UA / 邮箱明文。导出后即可备份，或作为迁移到其他实例的原始数据。

• 导出为单个 kcomment-export.json，字段自解释。
• 评论图片存于 R2，导出的是对象 Key；如需图片一并迁移，可在 R2 中整桶复制。
• 删除数据：在后台「页面列表」可按页清空，或直接对 D1 执行 SQL。

隐私说明

• IP / UA 根本不进库：数据库与接口里都没有这两列。不是「存了但脱敏」，是压根没有。
• 邮箱只存哈希：仅用于生成头像，绝不存明文、绝不对外。
• 匿名是真匿名：匿名评论对外只下发脱敏昵称，抓包也验证不出原身份。
• 点赞去重不依赖 IP：使用访客端随机指纹（仅存哈希，不可溯源）。
• 无埋点：不使用统计脚本、不写入 Cookie、无第三方请求。

API 参考

前台（公开）

管理（Bearer Token）

版本历史

常见问题

数据存哪里？

本部署存于你自己的 Cloudflare D1（SQLite）。自托管版则是本地单文件 SQLite。评论数据始终在你自己的控制下。

可以同时给多篇文章用吗？

可以。每篇文章用一个不同的 page_key，各挂载点互相独立。后台「页面列表」可统一查看。

图片上传关了会怎样？

输入框不再显示 📷 按钮，访客发不了新图；历史已上传的图片仍可正常查看。

AI 审核挂了会影响评论吗？

不会。AI 服务不可用时自动放行，保证评论不丢。违禁模式库始终生效，是秒拒的第一道闸。

为什么我看到的昵称和我填的不一样？

你勾选了匿名。匿名评论对外只下发系统分配的脱敏昵称，这是设计如此。

「最热」是怎么排的？

按评论点赞数从高到低排序，置顶评论始终在最上方。切换只影响当前页面的展示顺序，不改动数据。

表情和 @提及 需要额外配置吗？

不需要，组件内置。@昵称 是回复时自动填写的普通文本，提交即随正文入库展示。

后台打开为什么有登录？

管理入口受保护：本站用 Cloudflare Access 做了一层账号登录，你登录后即可进入后台安装向导。这是给站点管理员的额外一道门。

怎么迁移到别的服务器？

后台「导出 JSON」导出全部评论，再到新实例导入即可。图片在 R2 中整桶复制，Key 保持不变。