11 月 16 日,我给 WebTG Robot 加了 Telegram 群管理。这次挑入群验证这一块,记一下代码里的处理方式。
功能看起来很短:新人进群,先禁言,发一道算术题,答对后恢复发言。真正需要多写代码的地方,是题目之外的事:机器人重启了怎么办?禁言成功但题目没发出去怎么办?用户答题的同时,管理员又把他禁言了怎么办?
这些情况都涉及同一件事:本地记录的状态,和 Telegram 上已经发生的操作,并不总能一起成功。
先把验证过程存下来
如果只用 setTimeout 等待验证超时,进程一退出,定时器就没有了。Telegram 上的禁言却仍然存在。
现在的实现把验证记录放在 SQLite 的 group_verifications 表里。除了答案和截止时间,还保存这些字段:
| 字段 | 用途 |
|---|---|
id |
区分每一次验证,避免旧按钮影响新任务 |
group_id、user_id |
确定对应的群和成员 |
status |
当前处于哪个阶段 |
prompt_id |
清理验证消息时使用 |
original_permissions |
验证前的权限快照 |
original_until、original_restricted |
原来的限制期限,以及是否已被限制 |
penalty |
创建任务时确定的超时处理方式 |
retry_at |
下次允许后台处理的时间 |
这里专门留了一个 preparing 状态。顺序是先写记录,再调用 Telegram 禁言,然后发送验证题。拿到消息 ID 后,才把状态改为 pending。
因此,“已经准备验证”和“题目已经成功发出”是两回事。如果只保存一个 pending,重启后就很难判断用户到底有没有收到题。
主要路径可以写成:
1 | preparing → pending → passed |
这张图省略了异常重试分支,完整逻辑在 backend/services/groupModeration.js。
重启后按状态处理,不重新计时
后台的 tick() 会从数据库取出可处理的任务,每批最多 100 条。查询范围包含 pending、preparing 和 penalized,并受 retry_at 控制。
它们的处理方式不同:
pending:比较保存的expires_at和当前时间,已过期才执行超时处理。preparing:按未完整发出题目的任务处理,尝试恢复权限并取消验证。penalized:到了处罚结束时间,再处理权限恢复。
网络调用失败时,记录错误,并把下一次尝试推迟 30 秒。普通轮转则会向后推迟 5 秒,避免同一批尚未过期的任务一直占住查询前面的名额。
这种做法可以让重启后的程序接着处理数据库里的任务,但不能保证本地数据库和 Telegram 操作原子提交。例如 Telegram 已经接受了请求,本地还没写入结果就断电,恢复后仍可能再次尝试。因此每个分支都需要考虑重复执行,不能把“已持久化”等同于“恰好执行一次”。
答对之后,也不能直接全部解禁
恢复权限是这里容易写错的地方。
假设某个成员原来就被限制发图片,验证期间群管理员又关闭了全群的发链接权限。如果答对后把权限全部设成 true,就可能越过这两层限制。
当前实现先判断原来的个人限制是否仍然有效;有效时使用原权限,否则使用当前群默认权限。最后逐项求交集:
1 | const restored = Object.fromEntries( |
其中 previous 是前一步选出的权限,permissions 是此时从 Telegram 查询到的群权限。这段代码只展示权限合并,调用 restrictChatMember 时还要处理原来的限制期限。
另外,管理员在验证期间手动调整成员权限,会取消旧验证任务。否则成员再点一次正确答案,机器人可能把管理员刚设置的禁言解除。这里需要同时处理后台操作和 Telegram 的成员状态更新。
回答按钮和超时任务会撞在一起
用户在截止时间附近点击答案时,回调与后台扫描可能同时开始。
代码按 groupId:userId 维护一个 Promise 队列,让同一成员的相关操作在当前进程内依次执行。进入队列后重新读取数据库状态,再判断是不是当前验证、是否仍为 pending、是否已经过期。
这个顺序有两个作用:重复点击不能反复通过验证;晚到的正确答案也不能越过截止时间。按钮里的验证 ID 则负责拦住退群、重新入群后留下的旧消息。
这个锁只存在于进程内。它适合目前单实例的运行方式,不是分布式锁。以后如果拆成多个消费进程,还需要数据库中的条件更新、任务认领等机制,不能直接把服务副本数加上去。
验证题之外的两个细节
群消息过滤需要检查 text 和 caption,也需要检查 entities、caption_entities。只在正文里匹配网址,会漏掉图片说明和显示为普通文字的隐藏链接。
刷屏计数也不能简单地“一次更新算一条”。Telegram 的相册会带来多条消息,当前实现用 media_group_id 合并计数;没有这个字段时才使用 message_id。这样一组图片不会直接消耗掉多条发送额度。
另外,Web 页面展示的是机器人观察到的成员。Bot API 没有提供一个可以直接拉取完整群成员名册的接口,页面上的数量不能当作群的总人数。过滤规则也只能处理 Telegram 实际推送给机器人的消息。
用什么场景检查这段逻辑
仓库里的 tests/groupModeration.test.cjs 使用内存数据库、模拟 Telegram API 和可控制的时间,覆盖了重启后超时、题目发送失败、原有限制保留、管理员覆盖、过期答案、相册计数等分支。
这类测试不需要真的等三分钟,也不会向真实群发消息。不过它不能代替实际环境中的权限检查:机器人是否为管理员、能否删除消息、群是否支持成员限制,都要在接入时确认。
这次整理下来,我更在意的是每个未完成状态有没有后续处理。发题和验答案都很短,恢复逻辑才决定了服务重启之后,群里会留下什么。
本文对应 2026-11-16 的提交 7d11bbd。相关源码:群管理服务、测试用例。