钉钉群机器人接入Zabbix,比较适合告警接收方集中在钉钉、需要群内多人同步处理告警的团队。和邮件相比,机器人消息少了“查看收件箱”这一步,和电话告警相比,它不会因为深夜连续拨打而打扰太多人。如果团队日常用钉钉办公,并且告警群成员固定,这个方案比自建一套消息网关更省事,但也意味着Zabbix需要具备出网能力,脚本得运行在Zabbix Server或指定Proxy上。不同版本的Zabbix在媒介类型里对脚本参数的宏名称可能存在差异,这一点需要结合你实际使用的版本确认。
创建机器人:权限和webhook地址完整性
在钉钉群中添加自定义机器人前,请先确认群成员权限。打开群设置,选择智能群助手,再点击添加机器人。如果找不到自定义选项,通常是因为群主关闭了机器人添加功能,需要联系群主开放权限。创建时选择自定义(webhook)方式,钉钉会生成一个以 https://oapi.dingtalk.com/robot/send?access_token= 开头的地址。复制该地址时注意不要截断,建议先粘贴到文本编辑器里核对完整性。添加成功后,建议立即在群里发一条测试消息,确认webhook可用。
添加成功后,webhook地址相当于发送凭证,任何拿到这个地址的人都能向群里发消息。建议把它当成敏感信息保存,不要出现在截图、日志、公共代码仓库里。如果担心泄露,可以借助钉钉的安全设置做一道限制,这就是下面要说的关键字或加签。另外,Zabbix脚本里也要用到这个地址,所以先确认Zabbix Server能正常访问外网。内网部署的Zabbix,通常需要配置代理服务器或放通出网策略,否则后续所有排查都会卡在“发送超时”上。可以用curl命令手动请求一次webhook,观察返回结果,而不是直接改完配置才去试:
curl -H "Content-Type: application/json" -d '{"msgtype":"text","text":{"content":"test"}}' https://oapi.dingtalk.com/robot/send?access_token=xxx如果返回errcode为0,说明网络链路和webhook地址都没问题。这样可以提前发现网络不通或token失效的问题。安全设置:关键字与加签的取舍
钉钉自定义机器人的安全设置中,关键字是最常用的校验方式。Zabbix发送的告警内容必须包含至少一个你设置的关键字,否则机器人会拒绝消息并返回错误码310000。如果告警标题同时包含多个变量,建议将关键字设置成固定字符串,例如“ZABBIX”或“告警”。注意,关键字是区分大小写的,钉钉只做包含匹配,不做分词判断。若使用加签方式,则需要把时间戳和密钥拼接后计算HMAC-SHA256,并作为sign参数附加到webhook地址中,这种方式更安全但配置稍复杂。
从实际使用来看,关键字适合告警内容字段可控的场景,比如在告警标题里固定放一个“ZABBIX-告警”前缀,这样设置起来简单,后续改标题模板时也容易维护。加签方式把密钥和webhook绑定,安全性更好,但代价是脚本里需要额外计算签名参数。如果团队里有人维护脚本,加签的配置工作量并不大;如果脚本长期没人动,关键字方案倒是更省心。返回310000时,先用实际发送的告警原文去核对关键字设置,而不是急着改webhook。确认方法很简单:在Zabbix动作里把消息模板改成只包含固定关键字,发一次测试消息,如果成功,再逐步加回变量。
Zabbix媒介与脚本参数顺序
进入Zabbix的“管理”-“媒介类型”,点击“创建媒介类型”。名称填写“钉钉”,类型选择“脚本”,脚本名称自定义为“dingtalk.py”或“send_dingtalk.sh”。在脚本参数中,需要按顺序传递三个变量:{ALERT.SENDTO}(机器人webhook地址)、{ALERT.SUBJECT}(告警标题)、{ALERT.MESSAGE}(告警内容)。注意,Zabbix的宏在触发时会被替换为实际值,但脚本参数中一定不要加引号,否则脚本内接收时会带有多余引号导致解析失败。
媒介建好后,需要把媒介分配给对应用户,并且在用户媒介配置里填上实际使用的webhook地址,否则Zabbix动作触发时找不到发送目标,动作日志里只会显示发送失败,不会有具体原因。这一步容易漏,建议在“用户”-“报警媒介”里检查一遍。不同Zabbix版本对媒介脚本的超时时间设置不一样,如果脚本执行时间较长,可能需要把超时时间调大,这个也要看具体版本。
发送脚本的常见坑
脚本负责将Zabbix传来的标题和内容组装成钉钉要求的JSON结构。钉钉机器人接口只接受键为msgtype、text、title、content等字段。使用Python时,建议用json库构造字典,然后通过requests.post发送。一个容易踩的坑是钉钉对消息内容长度有限制,超过20000字节会报错,所以在脚本里可以对{ALERT.MESSAGE}做截断处理。另外,Zabbix默认的消息中包含换行符,直接放入JSON的content字段会导致格式错误,需要先转义 。脚本执行完成后,需要打印结果,但注意Zabbix会把stdout和stderr都记录到日志,尽量不要在脚本中输出敏感信息。
标题和内容都建议先做strip处理,再判断长度。requests模块不是Zabbix Server自带的,有些最小化安装的系统上需要单独安装python3-requests,这一步通常会被忽略,等到Zabbix执行脚本时才发现模块缺失。给脚本加上可执行权限,并用Zabbix运行用户手动执行一次,确认输出。手动执行时,直接从命令行传入webhook、标题、内容三个参数,观察返回JSON里的errcode。errcode为0表示钉钉已接收,之后再回到Zabbix的动作日志里看是否标记为已发送。如果命令行正常但Zabbix不触发,多半是媒介分配或用户权限问题。
验证手段与常见报错判断
配置完成后,先确认两件事:动作日志里有没有触发记录,以及钉钉群里有没有消息。动作日志显示“已发送”不代表钉钉真的收到了,还需要看脚本实际返回的结果。常见错误码可以这样判断:返回310000是消息内容没包含安全关键字,返回310001是webhook地址不对,返回40035则是JSON格式不正确。如果脚本里没做日志,建议先临时写入/tmp下的日志文件,记录请求URL和响应码,确认问题后把日志清理掉,避免泄露webhook地址。另外,如果脚本文件是在Windows上编辑再传到Linux,很可能因为换行符或编码问题执行失败,脚本文件需要确保UTF-8编码,且换行符为LF。整个链路里,最容易出问题的不是脚本逻辑,而是媒介分配、webhook地址拼接这类配置环节。建议在改动作模板前,先用脚本手动发一条固定内容,确认连通性,再处理Zabbix侧的动作配置。