Lark 群聊卡片机器人

概述

Lark 卡片（Lark Card）通知媒介，用于把夜莺产生的告警事件通过 Lark 群自定义机器人（Webhook）推送到指定的 Lark 群，消息展示为富文本的交互式卡片——有颜色头图、标题、分隔线和正文，triggered 是红色、recovered 是绿色，比纯文本 Markdown 更直观。

• 适用场景：使用 Lark（Larksuite，飞书海外版）的团队，希望告警以精美卡片形式发到 Lark 群，并支持按成员 @ 提醒。
• 你需要准备：一个 Lark 群，以及对该群有"添加机器人"的权限。
• 整个配置分三步：①在 Lark 群里添加机器人 → ②在夜莺新建 Lark 卡片通知媒介 → ③在通知规则里填入 token。

第一步：在 Lark 群里添加自定义机器人

1. 在目标 Lark 群中：Group settings → Bots → Add Bot → Custom Bot（中文界面：群设置 → 群机器人 → 添加机器人 → 自定义机器人）。

2. 设置机器人名称（例如 Nightingale Alert）和描述，点击 “Next”。

3. 安全设置（至少选一种，推荐"Custom Keywords"，夜莺当前只兼容下面这两种）：

   方式	说明	适用场景
   Custom Keywords（自定义关键词）	机器人只接受包含指定关键词的消息，最多 3 个	推荐，最简单。建议填写告警标题里一定会出现的词，如 Alert 或 n9e
   IP Allowlist（IP 白名单）	只接受指定 IP 段发来的请求	适合部署在固定公网出口的场景

   Lark 还有一种"Signature Verification"（签名校验）安全策略，夜莺默认请求体里不带 timestamp/sign，选签名后需要你自行在 token 字段里填完整的带签名 URL，不建议新人使用。

4. 勾选同意条款，点击 “Finish”。

5. 复制弹出的 Webhook URL，形如：

   https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   

   其中 /hook/ 后面那一串就是后面夜莺里要填的 Token（实际是一个 UUID），先保存好。

Lark 官方限制：单个机器人每分钟最多发送 100 条消息，每秒最多 5 条，超过会被限流。如果告警量非常大，建议把告警拆分到多个群/多个机器人，或者在通知规则里配置合理的收敛策略。

第二步：在夜莺新建 Lark 卡片通知媒介

1. 登录夜莺 → 左侧菜单 通知 → 通知媒介，进入通知媒介列表页。

2. 在左侧的媒介类型面板中点击 Lark 卡片，进入新建页面（对应 URL /notification-channels/add?ident=larkcard）。

   

3. 填写基础信息并保存，绝大部分字段系统已经预置好，只需要改一下"名称"：

   

   区块	字段	是否需要改	说明
   基础配置	名称	需要	例如 Lark 群卡片机器人，在通知规则里选媒介时看到的就是这个名字
   基础配置	启用	保持开启	关闭后该媒介不会被发送
   变量配置	联系方式	可不填	用于 @ 指定用户；选择后会把用户配置的"Lark open_id/手机号/邮箱"注入到消息体中
   变量配置	参数配置	保持默认，不要删	已预置 token、bot_name 两个参数，真正的 Token 在第三步通知规则里填
   HTTP 配置	URL	保持默认	https://open.larksuite.com/open-apis/bot/v2/hook/{{$params.token}}，{{$params.token}} 会被通知规则里填的值替换
   HTTP 配置	请求方法	POST	Lark Webhook 只接受 POST
   HTTP 配置	请求头	Content-Type: application/json	默认已填好

4. 继续向下可以看到"请求体"，这段是卡片消息的核心逻辑，保持默认即可：

   

   默认请求体是 Lark 的交互式卡片结构（msg_type: interactive），关键点：

   {
     "msg_type": "interactive",
     "card": {
       "config": { "wide_screen_mode": true },
       "header": {
         "title": { "content": "{{$tpl.title}}", "tag": "plain_text" },
         "template": "{{if $event.IsRecovered}}green{{else}}red{{end}}"
       },
       "elements": [
         { "tag": "markdown", "content": "{{$tpl.content}}" }
       ]
     }
   }
   

   • header.title.content 取自"消息模板"里 LarkCard 模板的 title 字段，一般是 🔔 告警规则名；
   • header.template 根据事件的 IsRecovered 自动变色：恢复绿色 / 触发红色，一眼就能看出状态；
   • elements[0].content 取自 LarkCard 模板的 content 字段，就是卡片正文的 Markdown。

5. 点击左下角 保存，一条类型为"Lark 卡片"的通知媒介就建好了。

说明：夜莺 v8 已经不再像旧版那样在媒介本身存 Token，同一个 Lark 卡片媒介可以被多个群/多个机器人复用，每个通知规则填自己的 token 就行。

第三步：在通知规则里填入 token

Lark 机器人 Webhook 地址里 /hook/ 后面的那段 UUID，在通知规则里填：

1. 左侧菜单 通知 → 通知规则 → 新增（或编辑已有规则）。

2. 在"通知配置"区域：

   

   • 通知媒介：选择你刚才创建的 Lark 卡片媒介；
   • 消息模板：选择 LarkCard（系统自带；如果没有，请到"消息模板"里导入默认模板）；
   • Token：粘贴第一步从 Lark 拿到的 Token（只填 /hook/ 后面那一串 UUID，不要带 URL）；
   • Bot Name：可选，填一个方便自己辨识的名字，比如 Nightingale；
   • 适用级别 / 适用时段 / 适用标签：按需过滤要推送的事件。

3. 保存后，点击"通知测试"即可发送一条测试消息，正常情况下 Lark 群里会立刻收到一张告警卡片。

一个 Lark 卡片媒介 + 多个机器人

如果不同业务线希望推送到不同的群，无需新建媒介，只要在"通知规则"里新增一条规则、填写不同的 token 即可。

常见问题

Q1：提示 "msg":"Key Words Not Found" / "code":19024（关键词不匹配）？

A：Lark 机器人启用了"Custom Keywords"安全策略，但告警标题/内容里没有出现任一关键词。解决办法：把你配的关键词放到告警规则名称里，或在 Lark 机器人里增加更宽松的关键词（如 Alert）。

Q2：提示 "code":19021 / "msg":"sign match fail"（签名错误）？

A：Lark 机器人选了"Signature Verification"模式，而夜莺默认发送不带 sign/timestamp 字段。建议改用"Custom Keywords"方式；如果一定要用签名，请在通知规则的 token 里直接填完整的带签名的 URL（以 https://open.larksuite.com/open-apis/bot/v2/hook/xxx?timestamp=yyy&sign=zzz 形式）。

Q3：卡片颜色一直是红色，恢复事件也不变绿？

A：卡片颜色由模板里的 {{if $event.IsRecovered}}green{{else}}red{{end}} 决定。请检查告警规则是否设置了恢复条件；如果是聚合告警同时包含 triggered 与 recovered，可以把 red 改成 {{if $event.IsRecovered}}green{{else if ...}}orange{{else}}red{{end}} 自行定制。

Q4：消息太多被限流？

A：Lark 官方限制单机器人 100 条/分钟、5 条/秒。建议：

• 开启告警收敛 / 告警聚合；
• 按业务拆分到多个群；
• 仅把一级/二级告警发到 Lark，三级告警改用邮件等异步渠道。

Q5：larkcard 和 feishucard 怎么选？

A：两者是同一套卡片协议，区别只在域名：

• feishucard → open.feishu.cn，国内飞书；
• larkcard → open.larksuite.com，海外 Lark。

按你实际使用的版本选择即可，表单字段完全一致。

Q6：能不能在卡片里嵌入告警截图？

A：群机器人方式默认不带截图。如需在卡片中嵌入图片，需要走 Lark 应用方式：申请 Lark 自建应用 → 在 Lark 卡片媒介中填入 app_id/app_secret → 夜莺会自动调用 https://open.larksuite.com/open-apis/im/v1/images 上传图片并把 image_key 注入到卡片中。具体流程参考 飞书应用 文档（仅域名/凭据替换为 Larksuite）。

参考资料

• Lark Open Platform · Custom Bot Guide
• Lark Open Platform · Message Card
• Lark Open Platform · Upload Image