使用场景
网站有了告警中心、问题反馈和友链申请后,总不能每次都打开星枢,挨个看看有没有需要处理的内容。
我本来就在用 AstrBot,希望这些事情能直接出现在聊天里。收到通知后,可以接着问具体原因,确认后再让机器人处理,而不是收到消息,又回到后台重新找记录。
整体介绍见 关于本站:微光集,网站结构见 微光集模块构成与实现思路。
微光集负责业务判断、状态和邮件,AstrBot 负责通知与对话,LLM 通过限定工具执行管理员明确要求的操作。
实现内容
| 功能 | 实现方式 |
|---|---|
| 告警通知 | 新告警、级别升级及任务/队列异常进入通知链路 |
| 问题反馈 | 新反馈及处理状态变化时通知,支持查询原文、标记已解决 |
| 友链处理 | 自动审核通过、失败达到阈值时通知,支持通过、失败邮件与弃用 |
| 任务重试 | 查询任务状态、日志和队列,按需重试失败或中断的任务 |
| 通知模板 | 告警、反馈、友链分别配置文本模板 |
| 对话上下文 | 可把通知记入绑定会话,方便后续追问 |
| 投递记录 | 本站记录向插件投递的结果,插件记录向聊天平台发送的结果 |
通知由 Go 主动推送。插件只在管理员查询或操作时请求本站 API。
对接入口与数据流
通知:
业务事务 → MySQL notification_outbox → Go 投递工作器
→ AstrBot 插件 Web API → SQLite 收件箱 → 绑定会话
处理:
管理员提出操作 → LLM 选择 MicroLight 工具
→ 插件校验管理员 UID → 本站受限 API
→ Go 校验业务条件 → 更新数据/邮件入队插件仓库:astrbot_plugin_microlight。通过 AstrBot SDK 的 register_web_api 注册通知入口,由 AstrBot 统一提供 HTTP 服务。
默认接收地址:
http://astrbot:6185/api/v1/plugins/extensions/astrbot_plugin_microlight/webhook这是 Go 容器访问 AstrBot 的内部地址。换部署方式时,需要调整主机名和端口。
插件反向访问本站使用网站根地址,例如 https://goblincwl.site,具体接口由客户端拼到 /api/microlight/v1/ 下。
两种密钥分别做什么
| 凭据 | 来源 | 用途 |
|---|---|---|
| AstrBot 插件 API Key | AstrBot 创建,授予插件权限 | Go 请求 AstrBot,使用 X-API-Key |
| MicroLight API Token | 星枢 → 账户 → 本站 API 生成 | 插件调用本站使用 Bearer;接收通知时使用 X-MicroLight-Token 校验来源 |
AstrBot 的 API Key 复用星枢「服务 → AstrBot → 插件 API Key」,对应 api.astrbot.token。
本站 Token 生成后只显示一次,复制到插件的 api_token。本站在数据库中加密保存,重置后旧 Token 失效,插件需要同步更新。
AstrBot API Key 让请求进入插件接口,MicroLight Token 确认双方使用的是同一套本站接入配置。。
本站 Token 只能访问固定开放的接口。
配置步骤
- 安装并加载
astrbot_plugin_microlight。 - 在星枢账户中生成本站 API Token,填写到插件
api_token。 - 插件
microlight_url填本站根地址,admin_uids填允许管理的平台 UID。 - 创建具有插件权限的 AstrBot API Key,填入星枢已有的 AstrBot 服务配置。
- 在星枢账户的本站 API 区域配置接收地址,开启通知类型及告警最低级别。
- 在目标会话发送
/microlight_bind,绑定接收位置。 - 发送
/microlight_check检查 API 连接。
接收地址对应 notify.astrbot.url。总开关是 notify.astrbot.enabled,分类开关分别为 notify.astrbot.alerts、notify.astrbot.feedback、notify.astrbot.friends,最低级别为 notify.astrbot.minLevel。
| 命令 | 用途 |
|---|---|
/microlight | 查看启用状态、会话与发送队列,不显示密钥 |
/microlight_check | 检查本站连接、鉴权和接口版本 |
/microlight_bind | 绑定当前通知会话 |
/microlight_retry | 重新排队插件中已达到重试上限的失败通知 |
这些命令同样检查 admin_uids,不是任意聊天用户都能绑定通知或执行管理操作。
通知投递
业务操作与通知事件在同一个数据库事务中保存,提交后由 Go 工作器读取 notification_outbox 投递。
插件校验事件后写入 notifications.sqlite3,返回事件 ID,Go 随后更新投递状态。同一事件重试时 ID 不变,插件按 ID 去重。
投递记录分为两处:
- 星枢:Go 向插件投递的结果。
- 插件:向聊天会话发送的结果。
两边各自最多尝试 10 次,从 30 秒开始指数退避,最长等待一小时。达到上限后,可以在星枢重试投递,或通过 /microlight_retry 重试消息发送。
通知模板与上下文
告警、反馈、友链分别配置纯文本模板,支持换行,留空使用默认格式。
| 变量 | 含义 |
|---|---|
{title} | 事件标题 |
{summary} | 内容摘要,友链失败附具体原因 |
{status} | 业务状态 |
{recordId} | 业务记录标识 |
{occurredAt} | 北京时间,格式 yyyy-MM-dd HH:mm:ss |
{category} | 中文通知分类 |
{level} | 中文告警级别 |
{id} | 通知事件 UUID |
{kind} | 原始类型:alerts、feedback、friends |
recordId 用于查询和操作业务记录,id 用于通知去重。友链卡片编号与内部 UUID 分开保存,操作时通过查询工具取得 UUID。
模板在发送时应用,修改后对尚未发送的通知生效。
通知默认记入绑定会话的上下文,方便后续追问。record_context 可以关闭记录。
LLM 操作
插件通过 AstrBot 注册 LLM 工具,调用时检查发送者的 admin_uids。
| 工具 | 功能 |
|---|---|
microlight_records | 查询告警、反馈、友链、任务列表或详情 |
microlight_delete_alert | 删除单条告警 |
microlight_approve_friend | 人工审核通过友链 |
microlight_abandon_friend | 发送失败邮件并删除友链 |
microlight_send_friend_failure_mail | 只发送失败邮件 |
microlight_resolve_feedback | 标记反馈已解决,发送处理邮件 |
microlight_auto_review_friends | 提交回链自动审核 |
microlight_retry_task | 重试失败或中断的任务 |
收到通知后,可以直接接着处理:
看一下这条友链失败的原因
弃用这条友链
这条反馈已经解决了,标记一下
重试刚才失败的任务插件先查询记录,再调用对应接口。弃用和发送失败邮件需要管理员明确确认,通知内容本身不作为操作指令。
角色工具配置
如果 AstrBot 角色设置了工具白名单,在 tool_persona 中填写角色名称。插件加载时通过 PersonaManager 追加 MicroLight 工具,保留原有工具;留空则不修改角色。
友链审核与巡检
友链有两组状态:
- 已审/待审:审核状态,通过后进入公开列表。
- 已验/未验:回链验证标记,可独立切换。
审核
自动审核先检查首页、头像和配置的 RSS,再检查回链页面中的本站首页链接。通过后设为已审、已验,发送成功邮件和 AstrBot 通知。
回链检查读取服务器返回的 HTML。通过 JavaScript 动态加载的友链暂时需要人工审核。
星枢点击待审,会提交一次人工检查队列。首页、头像、RSS 全部通过后设为已审、未验,失败则保留待审。插件的 microlight_approve_friend 用于直接通过已完成前置检查的记录。
申请失败
待审核申请失败后累计次数,由周期任务继续处理。默认从第 5 次开始,每次失败都通知 AstrBot,阈值可配置。通知包含失败原因。
收到通知后,可以选择:
- 发送失败邮件,保留申请。
- 弃用申请,发送失败邮件并删除记录。
手动弃用要求达到失败阈值,并有通知邮箱。邮件任务与删除记录在同一事务中提交。
已收录友链巡检
已通过的友链检查首页、头像和 RSS。只有首页失败累计巡检失败天数,北京时间同一天计一次,成功不清零。
默认累计 3 天置灰、7 天移除,均可在任务模块配置。头像和 RSS 刷新失败时沿用已有数据。
移除时发送邮件。没有邮箱的友链仍移除,并记录无法发送邮件的告警。
友链队列并行数量可设为 1–8,默认 1;头像压缩最多同时两个。
反馈处理与邮件
标记反馈已解决时,Go 将处理邮件写入队列。重复标记不重复发送,重新打开后再次解决会发送新的处理结果。
插件调用本站接口,SMTP 和邮件模板由本站维护。评论邮件见 Artalk评论系统对接,反馈与友链分别使用各自的邮件模板。
任务重试
先查询任务 key、日志和 retryable,再提交重试。支持失败或中断的任务,运行中或已排队的任务不能重复提交。
| 操作 | 使用工具 |
|---|---|
| 全站友链巡检失败后重试 | microlight_retry_task,任务 key 为 friends-refresh |
| 自动审核待审核申请 | microlight_auto_review_friends |
| 查看执行结果 | microlight_records |
使用的 API
接口根路径为 /api/microlight/v1,请求头使用 Authorization: Bearer <MicroLight API Token>。
| 方法与路径 | 用途 |
|---|---|
GET /status | 连接、版本及权限检查 |
GET /alerts、/alerts/{id} | 告警列表和详情 |
GET /feedback、/feedback/{id} | 反馈列表和详情 |
GET /friends、/friends/{id} | 友链及待审申请 |
GET /tasks、/tasks/{key} | 任务、日志及重试条件 |
DELETE /alerts/{id} | 删除单条告警 |
POST /friends/{id}/approve | 人工通过已满足前置条件的友链 |
POST /friends/auto-review、/friends/{id}/auto-review | 批量或单条回链自动审核 |
POST /friends/{id}/failure-mail | 发送失败邮件 |
POST /friends/{id}/abandon | 邮件入队并删除友链 |
POST /feedback/{id}/resolve | 标记已解决,发送处理邮件 |
POST /tasks/{key}/retry | 提交任务重试 |
排查
| 情况 | 检查位置 |
|---|---|
| 没有投递记录 | 通知开关、分类、最低级别及通知时机;新增友链不通知 |
| 本站投递失败 | 容器网络、插件加载状态、两种 Token |
| 插件已接收但没消息 | 绑定会话、插件发送队列 |
| 模型无法调用工具 | admin_uids、角色工具白名单、tool_persona |
| 工具调用失败 | 记录详情、审核条件、失败阈值、通知邮箱、任务状态 |
| 有回链却未通过 | 服务器返回的 HTML 是否包含链接 |