如何用Node.js开发钉钉企业内部机器人

文章导读
拿到一个钉钉企业内部机器人的开发任务,我通常先打开钉钉开放平台的后台,把回调模式和 stream 模式的选择确认下来。这两者的差别决定了后续代码怎么写。你只需要回答一个实际问题:部署机器人的服务器,是否有一个稳定的公网 HTTPS 地址。有,就配 webhook;没有,就用 stream 模式。如果选择 stream 模式,重连逻辑得提前写好,否则长连接断掉后,机器人不会主动报错,只是收不到消息,
📋 目录
  1. 壹 先确认接收方式
  2. 贰 签名验证:不能只比 sign 字段
  3. 叁 消息类型不能默认是文本
  4. 肆 本地调试:先打通链路,再加上业务
  5. 伍 部署:权限和密钥分开处理
  6. 陆 建议的处理顺序
A A

先确认接收方式

拿到一个钉钉企业内部机器人的开发任务,我通常先打开钉钉开放平台的后台,把回调模式和 stream 模式的选择确认下来。这两者的差别决定了后续代码怎么写。你只需要回答一个实际问题:部署机器人的服务器,是否有一个稳定的公网 HTTPS 地址。有,就配 webhook;没有,就用 stream 模式。如果选择 stream 模式,重连逻辑得提前写好,否则长连接断掉后,机器人不会主动报错,只是收不到消息,排查起来很被动。

签名验证:不能只比 sign 字段

回调请求到达第一个节点是签名验证。这个环节容易误判,但也是安全底线。

钉钉机器人的回调请求会携带timestamp和sign等参数。在Node.js中验证签名时,不要只对比sign字段,要先判断请求头中的timestamp是否在合理时间范围内,例如偏差超过30分钟应该直接拒绝。然后把timestamp、密钥和请求体拼接后做HMAC-SHA256,结果转为Base64后再和sign比较。常见坑是异步读body后忘记把原始字符串缓存下来,导致签名验证时用了解析后的对象,造成不匹配。

这里有一个常见的坑:在读取请求体时要保存原始字符串。验证签名用的请求体应当和收到时的原文一致,如果用了解析后的 JSON 再重新序列化,字段顺序变了,签名必然不匹配。我习惯在路由里先拿到 rawBody,再交给 bodyParser 去解析,这样两边都能拿到。

const crypto = require('crypto');
const signStr = timestamp + '\n' + secret;
const expectedSign = crypto
  .createHmac('sha256', signStr)
  .update(rawBody)
  .digest('base64');
if (expectedSign !== sign || Math.abs(Date.now() - timestamp * 1000) > 30 * 60 * 1000) {
  // 拒绝请求
}

消息类型不能默认是文本

签名通过后,进入业务逻辑之前,先看消息类型。

收到用户消息后,需要根据消息内容决定回复逻辑。钉钉内部机器人的文本消息事件里,text.content是用户输入的纯文本,而其他类型的消息(如图片、链接)在content字段中会是JSON字符串。处理时要先做类型判断,不能默认所有消息都是文本。回复消息时,使用机器人发送消息接口,必须使用当前企业的access_token,且要注意token的获取和失效刷新。如果是异步任务,回调接口要尽快返回200,避免超时重试导致重复处理。

这里的处理顺序是:先判断 eventType,再判断 msgtype,再使用对应的 content。把文本、图片、链接分开处理,后续加卡片消息才不混乱。另外,机器人主动发消息时用的 access_token 和接收回调是不同的两套,只申请发送消息权限就够了,别为了图省事把通讯录管理权限也带上。

如何用Node.js开发钉钉企业内部机器人

本地调试:先打通链路,再加上业务

本地调试时,无法直接接收到钉钉的回调。建议使用内网穿透工具生成公网地址,然后配置到钉钉开放平台。但要注意,穿透工具的免费版本可能会随机变化域名,导致回调地址失效。更稳妥的方式是先用一个简单的HTTP Server打印收到的所有请求体,确认签名验证通过后,再逐步添加业务逻辑。另外,钉钉管理后台可以启用调试模式,查看机器人推送日志,这个也是排查问题的常用入口。

ngrok http 3000

把 ngrok 生成的公网地址填到钉钉后台的回调 URL 里,临时写一个接口,只打印原始请求体和 headers,先确认钉钉能推过来、签名能通过。确认无误后再把业务逻辑接上。这个步骤能省下大量“为什么收不到回调”的排查时间。

部署:权限和密钥分开处理

部署上线我建议把回调路由和发送消息的 API 拆开。回调路由只做验签和事件响应,发送消息走另一个模块。企业机器人使用的 appKey 和 appSecret 要从环境变量读,不要写进代码里,更不要放在前端页面。如果密钥泄露,攻击者可以伪造请求,也能冒充机器人发消息,所以除了环境变量,还要在钉钉后台配置 IP 白名单,把回调来源限制在钉钉的出口 IP 范围内。

同时,企业内部机器人可以调用通讯录等 API,但权限要按需申请。不要用管理员账号的 token 运行机器人,应使用应用自身的 appKey 和 appSecret。如果机器人对话中涉及敏感信息,比如手机号、工号,代码里必须做脱敏处理,并且保留操作日志,方便追溯。

建议的处理顺序

如果是从零开始,我倾向按下面这个顺序做:第一步,先做本地调试环境,配置好内网穿透和签名验证,用临时服务器打印收到的原始请求体。第二步,在本地把消息类型处理写好,只处理文本消息,其他类型直接返回空响应。第三步,接上 access_token 缓存和发送消息接口,先用一个固定接收人测试。第四步,再部署到服务器,配置 HTTPS 回调或 stream 模式,切换到正式环境。最后才申请额外权限,比如通讯录或审批事件。每一步都观察日志,确认没有报错再进入下一步。

钉钉机器人开发本身不复杂,复杂的是回调链路里的细节。签名验证、消息类型、token 缓存这三件事处理稳妥,大部分问题都能在两小时内定位。