渠道消息进来之后:幂等、限流、防自环、身份映射四道关
渠道接通的那天我们挺高兴,第二天就被打回来了。
反馈有三条:同一个问题机器人答了两遍;群里两个机器人互相 @,刷了一屏;还有人问"为什么我 @ 它,它说我没绑定?"
前两条是治理没做够,第三条是治理做对了但没人告诉他。这篇就讲 BizBuddy 里的这四道关。
一、重复消息
为什么一定会重复
平台不是你想象中"一条消息只投一次":
- 你没在时限内 ACK,平台会重投;
- 长连接是集群模式,同一事件可能被分派到不同连接;
- 连接重连期间,事件可能补投。
所以幂等不是"防御性编程",是必需品。
拿平台自己的事件 id 当键
每个平台都给了全局唯一的事件标识,直接用它做幂等键最省事:飞书是 event_id,钉钉是 msgId。
java
private void onFeishuPayload(JsonNode payload) {
Optional<String> eventId = FeishuInboundMapper.extractEventId(payload);
if (eventId.isPresent() && !idempotency.firstSeen(channelCode + "|" + eventId.get())) {
return; // 重复事件,丢掉
}
// ... 继续处理
}三个细节注意一下。
键要带渠道前缀。不同渠道的事件 id 各自独立编号,万一同号就会把正常消息误丢掉。
幂等状态必须写 Redis。放进程内存里,多副本、重启一次就失真了。
事件 id 缺失时不要阻断(所以我写了 eventId.isPresent() 才校验)。宁可偶尔重复处理一次,也别因为解析不到 id 就把消息丢了——丢消息比重复处理严重得多。
二、渠道级限流(也是防自环)
机器人怎么自己转起来的
- 机器人回的消息,可能又被当成新消息投回来;
- 群里两个机器人互相 @,能一直转下去;
- 也真有人写脚本刷。
所以限流不只是防刷,主要是防自环:
java
if (!rateLimiter.allow(channelCode, message.peer().key())) {
log.warn("触发防自环限流:channelCode={}, peer={}", channelCode, message.peer().key());
return;
}两个点:维度是"渠道 + 会话对端"(channelCode + peer),不是全局——某个群刷屏不该影响别的群;状态同样走 Redis,理由跟幂等一样,限流是集群级的事,不是单机的。
三、身份映射:这是唯一真正的安全关
四道关里只有这一道是安全性质的,也最容易在上线第一天被当成 Bug。
外部标识既不是手机号,也不是昵称
钉钉给你的是 senderStaffId(企业内的 userId,有时候就是一串数字),飞书给的是 open_id。这些都不能直接当平台账号用,必须先有一张"外部标识 → 平台账号"的映射表。
没绑定就拒绝,绝不回退默认身份
渠道入站被拒(外部身份未映射):channelCode=dd_robot, externalUserId=xxxxxxxx这条日志看起来像故障,其实它在正常工作。外部消息的能力,等于被绑定那个账号的权限。
设想一下"没绑定就回退到超级管理员"会发生什么:群里任何人 @ 一下机器人,就等于拿到了管理员权限,能操作平台全部数据和配置。这是个典型的越权漏洞。
那"回退到一个只读游客账号"呢?外部渠道的访问就跟平台权限体系脱钩了,谁在群里说了什么、以谁的身份做的,审计全对不上。
所以正确做法只有一条:拒绝,并明确告诉对方去哪儿绑定。每个人各绑一条,这张映射表本身就是访问控制。
顺手把脏活做成功能
管理员配映射时最烦的不是"怎么填",是"填什么"——标识既不是手机号也不是昵称。所以我们把它做进了产品:渠道列表行内一个图标,输手机号查出该成员的外部标识,一键预填到绑定表单。
两个地方是刻意的:
平台账号不由查询接口决定。查出标识后还是要管理员自己选绑谁——"标识绑到哪个账号"是权限决策,不该自动化。
能力边界如实暴露。企业微信(那个接口要通讯录同步的独立 secret)和 GitHub(没有手机号概念)不支持这个查询,界面上直接不显示图标,而不是做成"点了报错"。
四、会话映射
外部世界和平台世界对"会话"的理解不一样:外部一个群、一条私聊线程,对应到平台是一个带上下文、消息、工具记录的 AI 会话。
所以要有一层映射(我们落成 ai_channel_thread)把外部线程绑到平台会话:
- 第一次收到消息:新建平台会话并绑定;
- 同一个线程再来消息:续接原会话,上下文不丢;
- 会话归档之后再发消息:新建并重绑,免得把上一个话题带进来。
这么做的额外好处是,平台侧的会话管理、工具调用明细、链路追踪,在渠道来源的会话上全都生效——运维在后台看到的,跟网页端对话完全一致。
五、还有一条:渠道链路是无人值守的
渠道消息边上没人点确认。所以能力上做了一次收口:
渠道来源的会话,只读放开,写类工具一律拒绝。
这不是技术限制,是产品判断:一个可能被任何人触发的入口,不该有直接改数据的能力。真要写数据,走有人确认的对话链路。
六、串起来看
外部消息
→ 幂等 重复投递只处理一次(Redis,事件 id 去重)
→ 限流 / 防自环 渠道 + 对端维度,超限丢弃(Redis)
→ 身份映射 没绑定就拒绝,能力 = 被绑账号的权限
→ 会话映射 外部线程 ↔ 平台会话,能续接、能重绑
→ 无人值守执行 只读放开,写操作拒绝最后
如果你的渠道接入只做到"能收发消息",那只是个功能。把这四道关补上,才是能让企业安全团队点头的系统。
尤其提醒第三条:"没绑定就拒绝"这条规则,上线前一定要跟客户和同事讲明白。你不讲,第一天就会有人来问"机器人说我没绑定,是不是坏了"。提前说清楚它是加分项,事后补救就成了事故。
下一篇换个角度,讲排障:《钉钉与飞书机器人接入排障实录》。
关于 BizBuddy
BizBuddy 是一个全量开源的企业级智能体平台(MIT License):开源中后台底座(Spring Boot 4.1.1 / JDK 21)做底座,AgentScope Java Harness 做智能体内核,纯 Java 全栈、不含 Python,权限、审计、配额、多渠道接入等能力全部随仓库开源。
欢迎 Star、Issue 与共建。