- 快猫星云Flashcat

透過飛書群組自訂機器人（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 條/秒。建議：