飞书群聊卡片机器人

通过飞书群自定义机器人（Webhook）将告警以交互式卡片形式推送到飞书群，新人可按步骤直接完成配置。

概述

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

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

如果你希望发送到单聊、按飞书 open_id/user_id @ 指定成员，或在卡片中嵌入告警截图（仅群机器人嵌入截图属于进阶用法，见本页最后一节），请参考飞书应用。本文只讲最常用、最简单的群机器人方式。

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

在目标飞书群中：群设置 → 群机器人 → 添加机器人 → 自定义机器人。
设置机器人名称（例如 夜莺告警）和描述，点击"下一步"。

安全设置（至少选一种，推荐"自定义关键词"，夜莺当前只兼容下面这两种）：

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

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

勾选"我已阅读并同意《自定义机器人使用协议》"，点击"完成"。
复制弹出的 Webhook 地址，形如：
```
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
其中 /hook/ 后面那一串就是后面夜莺里要填的 Access Token（实际是一个 UUID），先保存好。

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

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

登录夜莺 → 左侧菜单 通知 → 通知媒介，进入通知媒介列表页。
在左侧的媒介类型面板中点击 飞书卡片，进入新建页面（对应 URL /notification-channels/add?ident=feishucard）。

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

飞书卡片通知媒介表单

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

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

默认请求体是飞书的交互式卡片结构（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 取自"消息模板"里 FeishuCard 模板的 title 字段，一般是 🔔 告警规则名；
- header.template 根据事件的 IsRecovered 自动变色：恢复绿色 / 触发红色，一眼就能看出状态；
- elements[0].content 取自 FeishuCard 模板的 content 字段，就是卡片正文的 Markdown。
点击左下角保存，一条类型为"飞书卡片"的通知媒介就建好了。

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

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

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

左侧菜单 通知 → 通知规则 → 新增（或编辑已有规则）。
在"通知配置"区域：
- 通知媒介：选择你刚才创建的飞书卡片媒介；
- 消息模板：选择 FeishuCard（系统自带；如果没有，请到"消息模板"里导入默认模板）；
- Access Token：粘贴第一步从飞书拿到的 Token（只填 /hook/ 后面那一串 UUID，不要带 URL）；
- Bot Name：可选，填一个方便自己辨识的名字，比如 夜莺监控；
- 适用级别 / 适用时段 / 适用标签：按需过滤要推送的事件。
保存后，点击"通知测试"即可发送一条测试消息，正常情况下飞书群里会立刻收到一张告警卡片。

一个飞书卡片媒介 + 多个机器人

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

常见问题

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

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

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

A：飞书机器人选了"签名校验"模式，而夜莺默认发送不带 sign/timestamp 字段。建议改用"自定义关键词"方式；如果一定要用签名，请在通知规则的 access_token 里直接填完整的带签名的 URL（以 https://open.feishu.cn/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：飞书官方限制单机器人 100 条/分钟、5 条/秒。建议：