- 快猫星云Flashcat

指令稿執行處理器 — 透過自訂 Shell 指令稿靈活處理與轉換告警事件。

概述

Script 事件處理器是一個強大的告警事件處理元件，允許您透過自訂指令稿對告警事件進行靈活的處理與轉換。該處理器會將告警事件以 JSON 格式傳遞給您的指令稿，指令稿處理後可以傳回修改後的事件資料。

設定參數

逾時時間（必填）

參數名稱：逾時時間
單位：毫秒（ms）
預設值：10000（10 秒）
說明：指令稿執行的最大時間限制。如果指令稿執行時間超過此值，將被強制終止並傳回原始事件。

指令稿內容（必填）

參數名稱：指令稿內容
格式：Shell 指令稿
說明：您要執行的自訂指令稿程式碼，用於處理告警事件。

工作原理

事件輸入：處理器將目前告警事件轉換為 JSON 格式，透過標準輸入（stdin）傳遞給指令稿
指令稿處理：您的指令稿從 stdin 讀取事件 JSON，進行自訂處理
結果輸出：指令稿將處理後的事件 JSON 輸出到標準輸出（stdout）
事件更新：處理器解析指令稿輸出，更新原始事件

常見處理場景

修改告警等級
新增自訂標籤
修改告警描述

注意事項

1. 指令稿要求

指令稿必須能夠從 stdin 讀取 JSON 資料
指令稿必須向 stdout 輸出有效的 JSON 格式

2. 錯誤處理

如果指令稿執行失敗或逾時，將傳回原始未處理的事件
如果指令稿輸出為空或無效 JSON，將傳回原始事件

3. 效能考量

合理設定逾時時間，避免指令稿執行時間過長影響告警處理效能
避免在指令稿中執行過於複雜的操作

4. 安全建議

謹慎處理指令稿中的外部輸入
避免在指令稿中執行不安全的系統指令
定期審查指令稿內容

測試建議

使用測試功能：在儲存設定前，使用頁面上的「測試」按鈕驗證指令稿功能
本機測試：可以在本機環境中模擬事件 JSON 進行指令稿測試
逐步除錯：從簡單的指令稿開始，逐步增加複雜的處理邏輯

範例指令稿

範例 1：基礎事件透傳

#!/bin/bash

# 读取输入事件
event_json=$(cat)
echo "$event_json"

範例 2：根據標籤升級告警等級

#!/bin/bash
event_json=$(cat)

# 用 jq 检查标签里有没有 critical
is_critical=$(echo "$event_json" | jq -r '.tags_map.env // empty')

if [ "$is_critical" = "prod" ]; then
  # 把 prod 环境的告警级别提升到 1（S1）
  echo "$event_json" | jq '.severity = 1'
else
  echo "$event_json"
fi

範例 3：新增自訂標籤

#!/bin/bash
event_json=$(cat)
echo "$event_json" | jq '.tags_map.processed_by = "ops-script-v2" | .tags_map.processed_at = (now | tostring)'

常見問題

Q1：指令稿可以呼叫外部指令嗎（curl / kubectl / aws-cli）？

A：可以 — 指令稿執行環境是 n9e-server 所在主機的標準 Shell。前提：

所需指令已經裝在 server 主機上；
指令稿程序的使用者權限夠（n9e 預設用啟動 server 的帳號執行）；
指令的網路可達（如 kubectl 需要 kubeconfig 設定好）。

強烈建議單獨裝到 server 部署機，不要假設指令一定有。

Q2：指令稿執行失敗怎麼除錯？

A：

用頁面上的「測試」按鈕（輸入範例事件 JSON）；
看執行記錄裡的 stderr 輸出；
在指令稿裡加 echo "DEBUG: xxx" >&2 輸出除錯資訊到 stderr（不會影響 stdout 的 JSON）；
本機用 cat sample.json | bash your-script.sh 模擬。

Q3：如果指令稿輸出的不是 JSON 或者損壞了，會怎樣？

A：處理器會忽略指令稿輸出，使用原始事件繼續後續流程。所以指令稿損壞不會讓告警遺失，但也意味著你的修改完全沒生效。務必測試覆蓋。

Q4：指令稿支援 Python / Node.js 嗎？

A：技術上可以，只要 shebang 行（如 #!/usr/bin/env python3）指向 server 主機上能執行的解譯器。注意效能：每次告警都 fork 一次解譯器開銷不小，慢的話逾時會導致指令稿被 kill。簡單邏輯首選 bash + jq。

概述