宝塔面板对接企业微信钉钉告警推送故障

为什么你的宝塔面板告警推送到企业微信或钉钉总失败？

很多人在宝塔面板中配置了企业微信机器人或钉钉机器人，但告警消息就是发不出去。
本文结合实际操作经验，从配置源头到网络环境，帮你一步步定位并解决告警推送故障。
无论你是刚接触服务器运维的新手，还是被这个问题困扰已久，都可以按顺序操作。

第一步：确认基础环境与必要信息

在动手排查之前，请先确保以下三项准备已完成：

• 宝塔面板版本：建议升级到最新稳定版（7.9+），部分低版本对第三方推送支持不完整。
• 企业微信机器人：在企业微信中创建一个群聊 -> 添加群机器人 -> 复制 Webhook 地址（形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx）。
• 钉钉机器人：在钉钉中创建一个群聊 -> 添加自定义机器人 -> 选择「加签」安全方式 -> 复制 Webhook 地址（形如 https://oapi.dingtalk.com/robot/send?access_token=xxx）。

注意：钉钉机器人的安全设置如果选择了「IP 地址（段）」，则需要将宝塔面板所在服务器的公网 IP 添加到白名单，否则请求会被拒。

第二步：宝塔面板告警配置的关键路径

1. 登录宝塔面板后台，点击左侧菜单 「面板设置」。
2. 向下滚动找到 「告警推送」 或 「通知设置」（不同版本名称略有差异）。
3. 点击 「添加推送」，选择类型为「企业微信」或「钉钉」。
4. 将第一步复制的 Webhook 地址完整粘贴到输入框，注意不要有多余空格或换行。
5. 点击 「发送测试」 按钮，观察是否收到测试消息。

如果点击测试后显示「发送成功」但你实际没收到，请检查机器人是否被群管理员禁用、或你在群内被@的权限问题。

第三步：针对推送失败的常见故障排查

1. Webhook 地址拼接错误

这是最高频的踩坑点。
钉钉的 webhook 地址中 access_token=xxx 部分不能省略，企业微信的 key=xxx 也不能缺失。
复制时务必带上完整 URL，不要手动输错字符。

2. 网络不通或端口被防火墙拦截

宝塔面板服务器需要能访问以下域名：

• 企业微信：qyapi.weixin.qq.com
• 钉钉：oapi.dingtalk.com

可以在服务器终端使用 ping 或 curl 测试连通性：

# 测试企业微信
curl -I https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your_key
# 测试钉钉
curl -I https://oapi.dingtalk.com/robot/send?access_token=your_token

如果返回 Connection refused 或超时，请检查服务器安全组（阿里云、腾讯云等）是否放行了 HTTPS（443端口）出方向；
同时检查宝塔面板内的系统防火墙是否对出站做了限制。

3. 钉钉自定义机器人「加签」安全设置导致的签名错误

如果钉钉机器人开启了「加签」方式，则需要额外配置一个密钥。
但宝塔面板当前版本（7.9）的钉钉推送接口不支持加签模式。解决办法：在钉钉机器人安全设置中选择「自定义关键词」或「IP地址（段）」，避免使用「加签」。
这是宝塔官方尚未完全兼容的已知情况。

4. 企业微信机器人被限制发送频率

企业微信机器人对单个 Webhook 有每分钟 20 条消息的频率限制。
如果告警规则过多，短时间内触发大量推送，后续会被限流。
建议在告警规则中设置聚合（如 5 分钟内同一事件只发送一次）。

5. 宝塔面板告警推送配置未生效（特别是面板重启后）

部分用户反馈，修改了推送配置后必须重启宝塔面板服务才能生效。
操作路径：在面板首页点击「重启」按钮，或通过 SSH 执行 bt 1 重启面板。

第四步：效果验证与日志检查

配置调整后，不要只点一次「发送测试」，建议手动触发一个真实告警来验证。
例如将磁盘使用率设置到 1% 触发阈值，或直接模拟一个网站故障。

如果告警仍然收不到，可以查看宝塔面板的推送日志：

• 路径：/www/server/panel/logs/request.log（部分版本 /www/server/panel/logs/error.log）
• 搜索 webhook 或 dingtalk 关键词，看是否有返回错误码。

常见错误码说明：

• 企业微信返回 60020：表示请求来源 IP 不在白名单内（可登录企业微信管理后台，在「应用管理」->「机器人」中添加服务器 IP）。
• 钉钉返回 errcode: 310000：表示 access_token 无效或密钥错误。

避坑要点总结

• 钉钉机器人 不要开启加签模式，宝塔暂时不支持。
• 如果使用自定义关键词安全方式，记得在消息内容中包含该关键词（宝塔默认告警消息中包含「报警」二字，你需在钉钉机器人设置中添加关键词「报警」）。
• 企业微信机器人没有关键词限制，但要注意频率限制。
• 配置完成后，建议重启一次宝塔面板，确保新设置生效。
• 如果服务器有多个公网 IP，确保出站 IP 在机器人 IP 白名单中。

遇到其他异常怎么办？

如果以上步骤都检查无误，但告警推送依然失败，可以在宝塔论坛或官方 QQ 群搜索类似问题，附上你的推送日志片段寻求帮助。
也可以尝试在服务器上使用 curl 手动模拟发送一条消息给 Webhook 地址，看是否能成功：

# 企业微信示例
curl -X POST -H "Content-Type: application/json" -d '{"msgtype":"text","text":{"content":"测试消息"}}' https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的key

如果能正常收到，说明问题出在宝塔面板内部配置；
如果收不到，则问题在网络或机器人侧。

希望本教程能帮你顺利解决宝塔面板对接企业微信和钉钉告警推送的故障。
如果你在操作中遇到其他问题，欢迎留言交流。