一个团队里经常同时存在监控告警、CI构建通知、客服工单提醒等多个钉钉机器人。如果这些机器人最终都发到同一个群,逐一维护webhook会变得很繁琐。此时可以考虑把它们聚合到一个出口,由统一服务来转发。但聚合不是简单的“把地址换一下”,需要先判断场景,再看实现细节。
在多机器人场景下,最简单直接的做法不是逐个管理多个webhook,而是统一聚合成一个出口。具体实现时,可以部署一个轻量转发服务,让每个机器人将消息POST到该服务,再由服务转发到钉钉群的自定义机器人。判断是否适合此方案,可以看机器人之间是否共享同一接收人:如果所有消息最终面向同一个钉钉群,聚合才有意义。转发后需要检查消息中的text字段是否被原样保留,因为钉钉对消息类型有严格校验,一旦类型不符就会返回errcode。
什么情况下值得聚合
判断是否需要聚合,主要看消息接收人是否相同。如果所有机器人面向同一个钉钉群,或者几个机器人都是给同一批人发提醒,聚合才有意义。如果每个机器人发往完全不同的群,聚合反而增加了一层单点故障。另外也要看消息量:如果每天只有几十条,逐个管理webhook也够用;如果消息类型多样且数量大,聚合的收益才明显。
聚合的本质是统一出口,但每个机器人保留自己的身份。转发服务只负责把请求透传到对应群的webhook,而不是让所有机器人共用一个token。这样后续权限调整和出问题排查都不会互相牵连。
转发服务的基本设计
转发的核心是异步。先接受请求,再排队发送,避免调用方一直等待。开发时建议按生产消费模式设计:
转发服务建议按生产消费模式设计。接收端暴露一个HTTP接口,把请求体先解析成统一结构,比如提取msgtype、text.content、at信息;然后放入内存队列,由单消费者按顺序发送到钉钉。这里有个常见坑:不要在接口里直接同步调用钉钉接口,否则对方网络抖动会拖垮整个服务。正确做法是接口立刻返回“已接收”,后台异步处理。为便于排查,在队列消息里带上源机器人标识和原始时间戳,发送后在日志中记录钉钉返回的msgId。
这个设计的关键点在于队列里保存的是标准化消息,而不是原始HTTP请求。这样即使钉钉接口暂时不可用,消息也不会在进程重启前丢失。验证方式很简单:先发一条测试消息,看接口是否在几毫秒内返回,再看聚合服务的日志里是否有钉钉返回的msgId。如果日志中能看到msgId,说明转发链路正常。例如检查日志时可以执行:tail -f /var/log/aggregation.log | grep msgId。
限流与去重:别让一个小出口成为瓶颈
多个机器人汇聚到同一个出口,最直接的问题是钉钉侧单个token有时间窗口内发送条数限制。这个限制不在HTTP服务层处理,就会产生大量超频错误。另外,两个机器人可能监控同一资源,产生重复告警,所以去重也值得考虑。这里先说限流,一个通用做法是使用令牌桶算法:
钉钉自定义机器人对单个token有发送频率限制,超出后返回频率超限错误。聚合服务必须自行限流,不能依赖对端重试。推荐使用令牌桶算法,桶容量设为10,每3秒补充一个令牌,发送前消耗一个令牌。如果令牌不足,把消息暂存到待发送队列,而不是直接丢弃。这里要特别留意:如果队列积压超过5分钟,说明限流阈值设置太保守,需要检查是否误把多机器人聚合的QPS算成了单机器人。宁可少量延迟,也不要触发封禁风险。
素材中提到的5分钟积压可以作为一个自查信号。如果积压持续增加,说明桶容量和补充速率(每3秒1个)对于当前机器人数量太慢。需要结合群内实际消息量重新调整参数,不要把聚合服务的并发处理能力当成钉钉的发送能力。
去重不是必须的,但一旦发现重复告警,可以在转发前对text字段取哈希,用带有源标识的缓存键来判断。注意不要对at信息做哈希,否则同一条消息因为@的人不同会生成不同键,达不到去重目的。
失败重试与日志排查
重试机制只能用于临时网络问题,不能替代限流。钉钉接口返回超时或5xx时,需要按幂等规则重试,具体做法如下:
聚合转发时,钉钉接口偶尔会返回超时或内部错误,需要设计重试机制。重试要遵循幂等原则:每条消息生成唯一业务ID,发送请求带上该ID,钉钉服务端会根据ID做去重。如果没这个ID,重试可能导致重复消息。推荐采用指数退避,第一次失败后等2秒,第二次4秒,第三次8秒,最多重试3次。重试仍失败时,不要丢日志,把原始消息存储到本地磁盘,并打印错误码。后续排查时,先比对钉钉后台的机器人回调记录和服务器的发送日志,确认是网络问题还是消息格式问题。
这里的重试间隔和次数是保守建议,具体要看你的服务超时配置和最终用户容忍度。关键在于唯一业务ID必须能在重试时保持稳定,否则第一次请求可能成功,第二次重试又发了一条。排查时不要把目光只放在聚合服务上,钉钉管理后台的机器人回调记录是另一份参照。如果回调里没有记录,说明消息根本没到钉钉;如果回调里有多次记录,说明问题出在幂等ID上。
聚合带来的风险边界
把所有机器人集中到一个服务,风险也随之集中。原来单个机器人故障只影响一类通知,现在转发服务宕机会让所有机器人失联。所以聚合边界要清楚:只聚合消息发送通道,不聚合机器人密钥。每个机器人仍然使用自己的webhook地址,转发服务只做透传,不做身份替换。这样当某个机器人需要停用或更换时,不会影响其他机器人。
钉钉消息体中@人的语法在文本和Markdown等不同消息类型下不一样。聚合服务如果对消息做二次拼接,要小心转义,否则会出现@失效或明文显示手机号。另外,聚合服务的日志不能随意暴露在前端页面,里面很可能出现webhook URL里的access_token,以及内网IP。建议对日志脱敏后再查看。
聚合方案好不好用,最终要看运维者能不能在出现告警时快速定位是哪个源机器人、哪条消息出了问题。做好请求日志和发送日志的关联,这件事就成功了一半。