钉钉群机器人推送渠道配置指南
本教程将指导你如何在 MagicPush（魔法推送）中配置钉钉群机器人推送渠道，实现向钉钉群聊发送文本和 Markdown 消息。
概述
什么是钉钉群机器人？
钉钉群机器人是钉钉内置的群聊机器人功能，可以在群中自动发送消息通知。通过 Webhook 地址即可推送，无需复杂的鉴权配置。
| 特点 | 说明 |
|---|---|
| 推送目标 | 钉钉群聊 |
| 鉴权方式 | Webhook URL（可选加签 Secret） |
| 配置复杂度 | 低，仅需粘贴 Webhook 地址 |
| 消息格式 | text、markdown |
| 频率限制 | 20条/分钟/机器人 |
前置条件
- 拥有钉钉账号，且是某个群的管理员或群成员
- 已部署并登录 MagicPush 管理后台
第一步：在钉钉群中获取机器人 Webhook 地址
1.1 添加群机器人
- 打开钉钉，进入需要添加机器人的群聊
- 点击右上角 「群设置」 图标（齿轮图标）
- 找到并点击 「机器人」
- 点击 「添加机器人」 → 「自定义」
- 点击 「添加」 按钮
- 填写机器人信息：
- 机器人名称：如
MagicPush 通知 - 安全设置：选择一种安全方式（推荐「加签」，安全性更高）
- 自定义关键词：消息必须包含指定关键词才能发送
- 加签：使用 Secret 对消息进行签名校验（推荐）
- IP地址（段）：限制调用 IP
- 机器人名称：如
- 点击 「完成」
1.2 获取 Webhook 地址和 Secret
添加成功后，会显示机器人的 Webhook 地址：
https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxxxxxx📌 关键信息：
- Webhook 地址：上述完整 URL，复制后粘贴到 MagicPush
- Secret（加签密钥）：如果选择了「加签」安全设置，点击机器人详情页的 「设置」 可以查看 Secret 值
如果选择了「加签」方式，需要同时记录：
| 配置项 | 示例值 | 来源 |
|---|---|---|
| Webhook 地址 | https://oapi.dingtalk.com/robot/send?access_token=... | 机器人添加成功页面 |
| Secret 密钥（可选） | SECxxxxxxxxxxxxxxxxxxxx | 机器人详情 → 设置 → 查看 Secret |
💡 提示：如果不需要加签验证，Secret 留空即可，但安全性较低，建议生产环境使用加签。
第二步：在 MagicPush 中添加渠道
2.1 进入渠道管理
- 登录 MagicPush 管理后台（默认地址
http://<服务器IP>:3000） - 点击左侧导航 「渠道管理」
- 点击右上角 「+ 绑定渠道」 按钮
2.2 选择渠道类型
在弹出的对话框中，从渠道类型下拉列表中选择 「钉钉」。
2.3 填写配置信息
根据第一步获取的信息，填写以下配置字段：
| 字段 | 说明 | 示例 |
|---|---|---|
| Webhook 地址 | 钉钉机器人的完整 Webhook 地址 | https://oapi.dingtalk.com/robot/send?access_token=... |
| Secret 密钥（可选） | 加签方式的密钥，留空则不校验签名 | SECxxxxxxxxxxxxxxxxxxxx |
💡 安全设置说明：
- 如果钉钉机器人安全设置选择了「加签」，必须填写 Secret，否则消息发送会被拒绝
- 如果选择了「自定义关键词」，确保发送的消息内容包含关键词
- 如果选择了「IP地址」，确保 MagicPush 服务器 IP 在白名单中
填写完成后，给渠道起一个易于辨识的名称（如「研发告警群」），点击 「保存」。
2.4 测试连通性
渠道创建成功后，在渠道卡片右侧的下拉菜单中，点击 「测试」 按钮。
- ✅ 如果钉钉群中收到「这是一条来自魔法推送的测试消息」，说明配置成功
- ❌ 如果测试失败，请参考下方常见问题排查
第三步：使用推送
3.1 通过 API 推送
bash
curl -X POST http://<服务器IP>:3000/api/push/<渠道ID> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <你的API Token>" \
-d '{
"title": "服务异常告警",
"content": "生产环境 API 响应时间超过 5 秒，请排查",
"type": "markdown"
}'支持的消息类型（type 参数）：
| type 值 | 说明 |
|---|---|
text | 纯文本消息（默认） |
markdown | Markdown 格式消息 |
3.2 Markdown 消息示例
钉钉支持相对丰富的 Markdown 语法：
markdown
### 服务异常告警
**环境**：生产环境
**服务**：api-gateway
**告警内容**：响应时间超过 5 秒
> 时间：2024-06-01 14:00:00
> 触发条件：连续 3 次超过阈值
[查看详情](https://monitor.example.com/alert/12345)支持的格式：
- 标题（
#~###） - 加粗（
**text**） - 引用（
> text） - 链接（
[text](url)） - 图片（
） - 有序/无序列表
技术细节
消息长度限制
- 文本消息：最长不超过 5000 字符
- Markdown 消息：最长不超过 5000 字符
频率限制
钉钉群机器人限制：每个机器人最多 20 条消息/分钟。
签名机制（加签）
如果配置了加签，MagicPush 会自动：
- 使用当前时间戳 + Secret 计算 HMAC-SHA256 签名
- 将 timestamp 和 sign 参数附加到 Webhook URL 上
- 发送签名后的请求
你无需手动处理签名，MagicPush 已自动完成。
常见问题
Q: 发送消息返回 300001 错误码？
原因：Webhook 地址格式不正确，或 access_token 无效。
解决：
- 检查 Webhook 地址是否完整复制，没有多余空格
- 确认地址以
https://oapi.dingtalk.com/robot/send开头 - 重新从钉钉机器人管理页复制 Webhook 地址
Q: 发送消息返回 300002 错误码？
原因：消息内容未通过安全校验。
解决：
- 如果设置了「自定义关键词」：确保消息内容包含至少一个关键词
- 如果设置了「加签」：确保 Secret 填写正确
- 如果设置了「IP 白名单」：确保 MagicPush 服务器 IP 在白名单中
Q: 发送消息返回 frequency limit 错误？
原因：触发了频率限制（20条/分钟）。
解决：
- 降低推送频率，合并消息
- 创建多个机器人分散推送
Q: Markdown 消息中的图片无法显示？
原因：图片 URL 需要是公网可访问的地址，且钉钉支持的图片格式有限。
解决：
- 确保图片 URL 是
https://开头 - 图片大小不超过 500KB
- 支持的格式：JPG、PNG
Q: 如何发送到多个群？
解决：每个钉钉群需要单独添加一个机器人，每个机器人对应一个 MagicPush 渠道。也可在钉钉中将一个机器人添加到多个群（该机器人的消息会同时发到所有已添加的群）。