- 快猫星云Flashcat

透過 Lark（飛書海外版）群組自訂機器人（Webhook）將告警以互動式卡片形式推送到 Lark 群組，新手可依步驟逐步完成設定。

概述

Lark 卡片（Lark Card）通知媒介，用來把夜鶯產生的告警事件透過 Lark 群組自訂機器人（Webhook）推送到指定的 Lark 群組，訊息以富文字的互動式卡片呈現——有彩色頭圖、標題、分隔線和內文，triggered 是紅色、recovered 是綠色，比純文字 Markdown 更直觀。

適用情境：使用 Lark（Larksuite，飛書海外版）的團隊，希望告警以精美卡片形式發送到 Lark 群組，並支援按成員 @ 提醒。
你需要準備：一個 Lark 群組，以及對該群組擁有「新增機器人」權限。
整個設定分三步：①在 Lark 群組裡新增機器人 → ②在夜鶯新建 Lark 卡片通知媒介 → ③在通知規則裡填入 token。

第一步：在 Lark 群組裡新增自訂機器人

在目標 Lark 群組中：Group settings → Bots → Add Bot → Custom Bot（中文介面：群組設定 → 群組機器人 → 新增機器人 → 自訂機器人）。
設定機器人名稱（例如 Nightingale Alert）和描述，點擊 “Next”。

安全設定（至少選一種，建議「Custom Keywords」，夜鶯目前只相容下面這兩種）：

方式	說明	適用情境
Custom Keywords（自訂關鍵字）	機器人只接受包含指定關鍵字的訊息，最多 3 個	建議，最簡單。建議填寫告警標題裡一定會出現的字，如 `Alert` 或 `n9e`
IP Allowlist（IP 白名單）	只接受指定 IP 區段發來的請求	適合部署在固定公網出口的情境

Lark 還有一種「Signature Verification」（簽章驗證）安全策略，夜鶯預設請求內容裡不帶 timestamp/sign，選擇加簽後需要你自行在 token 欄位裡填入完整的帶簽章 URL，不建議新手使用。

勾選同意條款，點擊 “Finish”。
複製彈出的 Webhook URL，形如：
```
https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
其中 /hook/ 後面那一串就是後面夜鶯裡要填的 Token（實際是一個 UUID），先儲存好。

Lark 官方限制：單個機器人每分鐘最多發送 100 條訊息，每秒最多 5 條，超過會被限流。如果告警量非常大，建議把告警拆分到多個群組／多個機器人，或者在通知規則裡設定合理的收斂策略。

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

登入夜鶯 → 左側選單 通知 → 通知媒介，進入通知媒介列表頁。
在左側媒介類型面板中點擊 Lark 卡片，進入新建頁面（對應 URL /notification-channels/add?ident=larkcard）。

填寫基礎資訊並儲存，絕大部分欄位系統已經預先填好，只需要改一下「名稱」：

Lark 卡片通知媒介表單

區塊	欄位	是否需要改	說明
基礎設定	名稱	需要	例如 `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`	預設已填好

繼續向下可以看到「請求內容」，這段是卡片訊息的核心邏輯，保持預設即可：

預設請求內容是 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。
點擊左下角儲存，一條類型為「Lark 卡片」的通知媒介就建好了。

說明：夜鶯 v8 已經不再像舊版那樣在媒介本身存 Token，同一個 Lark 卡片媒介可以被多個群組／多個機器人重用，每個通知規則填自己的 token 就行。

第三步：在通知規則裡填入 token

Lark 機器人 Webhook 位址裡 /hook/ 後面的那段 UUID，在通知規則裡填：

左側選單 通知 → 通知規則 → 新增（或編輯既有規則）。
在「通知設定」區域：
- 通知媒介：選擇你剛才建立的 Lark 卡片媒介；
- 訊息範本：選擇 LarkCard（系統自帶；如果沒有，請到「訊息範本」裡匯入預設範本）；
- Token：貼上第一步從 Lark 取得的 Token（只填 /hook/ 後面那一串 UUID，不要帶 URL）；
- Bot Name：可選，填一個方便自己辨識的名字，例如 Nightingale；
- 適用級別／適用時段／適用標籤：按需過濾要推送的事件。
儲存後，點擊「通知測試」即可發送一條測試訊息，正常情況下 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）。