使用场景

关于微光集整个网站的介绍,可以先看 关于本站:微光集。

网站刚开始只有文章,给 Quartz 接一个评论组件,似乎只需要在页面下面放上 Artalk 就可以了。但后来有了 Share 和 Repo,同一个仓库还会切换分支、目录、提交和 Release,评论应该属于哪个页面,就需要先想清楚。

我的处理方式是:Artalk 负责评论,微光集负责把评论接到自己的内容、身份和页面交互里。

评论数据仍由 Artalk 保存,没有另外在本站复制一套评论数据库。主要改造在微光集前端、Go 桥接层和邮件模板中。

实现内容

  • 文章、分享项目、仓库项目使用统一的评论样式。
  • 普通用户直接填写昵称、邮箱发表评论。
  • 本站管理员登录后同步 Artalk 管理员身份。
  • 按内容控制是否允许普通用户评论。
  • 在星枢中管理评论和普通用户。

Video 单独处理:页面读取 Bilibili 评论,发表入口跳到 B 站,不再加载本站 Artalk 编辑器。

对接入口与数据流

普通评论:页面 → Artalk 前端组件 → /artalk/api/v2/… → Artalk
管理功能:星枢 → /api/site/admin/comments/… → Go → Artalk
评论汇总:页面 → /api/comments → Go 筛选、整理 → Artalk

浏览器加载的是 Artalk 的前端资源,公开反代入口使用 /artalk。后端则使用服务接入里配置的 Artalk 地址,与容器内的评论服务通信。

管理员邮箱、密码配置在 星枢 → 服务 → Artalk。这里需要填的是 Artalk 管理员凭据,不是让访问者填写的评论邮箱。

评论跟随内容,不跟随浏览状态

文章使用公开路径作为 pageKey。例如,同一篇文章增加查询参数,不产生另一个评论区。

Repo 的分支、文件、提交和 Release 也共用仓库项目的评论。Share 同样围绕分享项目组织评论,不为每个内部文件建立一套评论记录。

pageKey 是关联评论的身份。把构建文件路径、临时查询参数或当前代码目录直接拿来当页键,后面很容易出现评论分散、汇总跳转错误的问题。

页面交互与身份

普通用户和管理员分开处理

普通用户保留 Artalk 原有的昵称、邮箱输入方式,不需要先注册本站账户。

本站管理员则先登录星枢,再由后端为浏览器建立独立的 Artalk 管理员会话。前端拿到的是这个浏览器会话,后端自己的管理 Token 不直接交出去。

往表单里填上管理员的昵称、邮箱,并不等于管理员登录。 真正的身份仍然要由 Artalk 会话确认,不凭昵称判断权限。

管理员状态下昵称、邮箱锁定,昵称显示红名;退出本站管理员登录时,清理关联的评论身份,避免把管理员信息遗留在访客表单中。

排序、回复和点赞

评论区默认按热门排序,还可以切换最新、最早。排序继续调用 Artalk 原生能力,只局部刷新评论列表;加载时保留区域高度,隐藏中间产生的“暂无评论”状态。

回复入口改成点击评论正文或头像,正文里的链接、图片和选中文字保留各自的操作。原先正文下方的回复按钮不再展示。

点赞放在昵称、时间同一行的右侧。桌面端零赞入口在 hover 或聚焦时显示,触屏端直接可用;点击后仍然交给 Artalk 处理,并根据返回结果更新计数。

评论权限怎么控制

文章通过原本的笔记属性表达权限:

comment: true

允许普通用户评论;设置为 false 时,仅管理员可以评论。没有配置评论的普通文章,则不生成评论组件。

Share、Repo 还可以通过管理员右键菜单切换“允许普通用户评论/禁止普通用户评论”。这里同步的是 Artalk 页面的 admin_only,同时调整前端编辑器,不能只把输入框藏起来。

需要输入密码的文章在解密后再加载评论。加密分享的评论访问也跟随分享权限处理。

评论自动审核

评论多了以后,每条都打开后台点一次通过,也没什么必要。我的处理方式是:新评论先进入待审,由 AstrBot 调用模型判断,再把结果写回 Artalk。 无法确定的内容留给我处理,不因为模型或网络出错就直接放行。

这里没有在微光集的 Go 服务里再写一套审核器,而是使用自己写的 AstrBot 插件 astrbot_plugin_artalk_moderation。Artalk 继续保存评论和审核状态,AstrBot 负责模型调用、审核通知和后续的会话操作。

从待审到公开

访客发表评论 → Artalk 保存为待审 → Webhook 通知 AstrBot
→ 插件入队 → 从 Artalk 读取评论原文 → 模型审核
→ 调用 Artalk API 更新状态或删除 → 向管理员会话发送结果

Webhook 只是触发入口,不直接把回调里的正文交给模型。插件收到评论编号后,会重新调用 GET /api/v2/comments/{id},确认评论属于配置的站点,而且仍然处于待审状态,再执行审核。

收到回调后,成功入队就返回 HTTP 200,不让 Artalk 等模型生成完结果。队列有容量限制,并限制同时执行的模型请求数;队列满时返回 503,没有处理到的待审评论还能通过后面的扫描补入。

Artalk 和 AstrBot 分别配置什么

Artalk 的配置在部署目录 artalk-data/artalk.yml,需要同时开启默认待审、待审通知和 Webhook:

moderator:
  pending_default: true
 
admin_notify:
  notify_pending: true
  webhook:
    enabled: true
    url: "http://astrbot:6185/api/v1/plugins/extensions/astrbot_plugin_artalk_moderation/webhook?api_key=替换为插件权限APIKey"

notify_pending 很关键:评论既然默认待审,如果待审时不发送通知,就无法及时触发这条审核链路。

这里的 astrbot:6185 是 Docker 同网络下的服务地址,需要从 Artalk 容器访问得通。api_key 使用 AstrBot 中具有插件权限的 API Key,包含特殊字符时先做 URL 编码;示例中的占位值需要替换,实际密钥不放进文章或前端。

AstrBot 插件配置则填写 Artalk 地址、站点名、管理员邮箱和密码,以及审核使用的 llm_provider_id。模型复用 AstrBot 已接入的 Provider,不需要再给微光集前端配置一份模型密钥。

其中 artalk_site_name 必须与评论组件的 site 一致;管理员凭据用于插件登录 Artalk 管理 API,与星枢里的服务接入是分别配置的。审核标准通过插件的 moderation_instruction 调整。

模型判断后会做什么

模型的输出固定为两行纯文本:第一行是结论,第二行是简短原因。插件只接受下面四种结论:

结论实际操作
通过is_pending=false、is_collapsed=false,公开评论
折叠is_pending=false、is_collapsed=true,审核通过但折叠保留
拒绝调用 DELETE /api/v2/comments/{id},直接删除评论
待审核is_pending=true、is_collapsed=false,保留人工处理

“拒绝”会删除评论,不是简单地隐藏。 配置审核标准时,需要把删除和保留待审区分清楚。

评论正文作为不可信内容传给模型,提示中明确要求不执行评论里夹带的指令。提交给模型的正文长度默认限制为 3000 个字符,所以这不是把任意长度的评论完整交给模型阅读,也不能把模型结论当作绝对可靠的判断。

模型请求失败、无法判断或返回的首行不符合约定时,评论保留待审,并通知管理员检查。审核结果仍以 Artalk 中的实际状态为准,星枢可以继续人工调整。

漏掉的评论和人工接管

Webhook 之外,插件支持启动时扫描一次待审评论,并定时补扫,默认间隔 1800 秒,最短也是 30 分钟。扫描按配置的站点分页读取待审列表,跳过已折叠的记录,再放入同一个审核队列。

队列在插件进程内,不是微光集的持久任务队列。重启后依靠 Artalk 里仍保存的待审记录重新扫描;本次运行中已通知、仍需人工处理的评论还会做有上限的去重,避免每轮扫描都重复调用模型和通知,重载插件后这份缓存会清空。

管理员 UID 配置在插件的 admin_uids。在要接收审核消息的会话中执行 /artalk_bind,之后可以用 /artalk_status 查看队列、扫描时间和错误,或用 /artalk_scan 手动扫描待审评论。

审核通知还会写入该会话的上下文。开启 Agent Tools 后,可以继续在会话里要求公开、折叠或删除指定评论;工具同样检查管理员 UID 和评论所属站点。也可以直接回到星枢的评论模块处理,不依赖模型继续判断。

使用的 API

下面的 Artalk 路径相对于它自己的服务根地址;经本站公开反代访问时,前面还有 /artalk。

Artalk 接口用途
GET /api/v2/conf读取评论前端配置
GET /api/v2/comments/{id}自动审核前读取评论原文和当前状态
GET /api/v2/comments评论列表、分页、date_desc/date_asc/vote 排序
POST /api/v2/comments发表评论与回复
PUT /api/v2/comments/{id}、DELETE /api/v2/comments/{id}编辑、审核、置顶、折叠、删除
POST /api/v2/votes/comment/{id}/up评论点赞
POST /api/v2/auth/email/login管理员邮箱、密码认证
GET /api/v2/user?email=…查询并确认管理员资料
GET /api/v2/pages、POST /api/v2/pages/pv、PUT /api/v2/pages/{id}查询、按需建立评论页和更新页面权限
GET /api/v2/users/all、GET /api/v2/users/admin管理列表及管理员范围判断
PUT /api/v2/users/{id}、DELETE /api/v2/users/{id}普通用户编辑、删除
本站桥接接口用途
POST /api/site/admin/comments-session已登录本站的管理员取得独立评论会话
GET /api/site/admin/comments/comments、…/users星枢评论、用户列表
PUT /api/site/admin/comments/{comments或users}/{id}、DELETE经本站鉴权后转交管理操作
GET /api/comments?page=1公开评论汇总,每页 20 条
GET /api/comments/avatar-hash?hash=…为头像服务取得对应的 MD5 哈希
GET /api/site/repo-comments?slug=…、PUT /api/site/admin/repo-comments?slug=…读取、调整仓库评论权限

头像、管理页和邮件的改造

头像只对接 Cravatar,找不到远程头像时由前端生成。Artalk 提供 SHA-256 邮箱哈希,Cravatar 使用 MD5,因此后端缓存两种哈希的映射,公开响应不带邮箱。头像在检测、解码完成后展示,主题切换只更新生成头像的配色。

管理员使用固定头像。星枢的用户列表只管理普通用户,所有 Artalk 管理员都排除在这个列表之外;管理接口也拒绝在这里编辑、删除管理员。管理员发表的评论仍能正常管理。

邮件模板放在项目的 artalk/templates/reply.html,只读挂载到容器的 /templates,由 Artalk 的 email.mail_tpl 指向它。表情按正文的两倍高度约束,普通图片另外限制宽度。

模板使用本站配色,亮暗色由邮件客户端决定,支持 prefers-color-scheme 的客户端使用模板的暗色样式。


星轨图