跳至主要内容
版本:0.4 · 現行版

設定 Slack 通知

操作指南審閱日期:2026年10月11日
適用於:Excubius 0.4角色: 實體管理員
方案Free · Core · Pro · Enterprise部署自行託管

Excubius 會在 Slack 中發出警報通知:警報開啟時、嚴重程度上升時,以及警報解決時。你可以按實體選擇頻道,其下的每個實體都會繼承這些頻道,直到它設定自己的頻道為止。本指南說明如何一次性連接 Slack 應用程式、為實體新增頻道、測試頻道,以及訊息如何路由。

開始之前​

  • 若要新增頻道,你需要在該實體上具備 Entity admin 角色。
  • 若要建立 Slack 應用程式,你需要有權在 Slack 工作區中安裝應用程式。
  • 若要把應用程式的權杖提供給 Excubius,你需要能夠存取伺服器:在伺服器上具備 sudo 權限,或持有安裝程式套件。

連接 Slack 應用程式​

每次安裝只需要執行一次。

  1. 前往 https://api.slack.com/apps,選取 Create New App,選擇 From scratch,為它取一個團隊容易辨認的名稱,並選擇你的工作區。

  2. 在 OAuth & Permissions 下,新增機器人權杖範圍 chat:write。Excubius 不需要其他範圍。

  3. 選取 Install to Workspace 並允許。複製以 xoxb- 開頭的 Bot User OAuth Token。

  4. 在伺服器上,以 sudo -iu excubius 切換為服務帳戶,並在 /opt/excubius/.env 中設定權杖:

    SLACK_BOT_TOKEN=xoxb-…
    SLACK_DEFAULT_CHANNEL=#alerts

    SLACK_DEFAULT_CHANNEL 會接收所有「在其上層任何位置都沒有自己頻道」的實體的警告及嚴重警報。省略時預設為 #alerts。

  5. 重新啟動平台:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

安裝程式也會詢問 Slack 機器人權杖及預設頻道;sudo ./install.sh --reconfigure 會再次詢問。在設定權杖之前,Settings › Notifications 會顯示 Slack is not configured on the server,而且不會傳送任何訊息。

為實體新增頻道​

  1. 在 Slack 中,開啟頻道(例如 #ciguapa-alerts),並邀請應用程式加入,例如使用 /invite @Monitoring。應用程式只能在它所屬的頻道中發佈訊息。
  2. 在 Excubius 中,開啟 Settings › Notifications,並在選擇器中選擇實體,例如桃花島物流。
  3. 選取 Add Slack channel。
  4. 填寫欄位:
    • Name:給你的團隊使用的名稱,例如桃花島警報。
    • Slack channel:小寫的 #name,或頻道 ID,例如 C0123456789。
    • Minimum:發佈的最低嚴重程度,即 Info、Warning 或 Critical。低於此程度的警報不會發佈。
    • Message language:English 或 Español。西班牙文需要功能 ui.i18n;沒有該功能時,欄位會說明訊息使用英文。
  5. 選取 Add Slack channel。
  6. 在新頻道上選取 Test。

Slack 頻道中會出現一則測試訊息,而 Excubius 會顯示 Test message sent。如果 Slack 拒絕該訊息,錯誤會指出原因,例如 not_in_channel:請邀請應用程式加入頻道、檢查頻道名稱,然後再次測試。

來自桃花島物流及其下所有項目的警報,現在都會傳送到該頻道。一個實體可以有多個頻道,例如一個用於警告,另一個只用於嚴重警報。

關閉、變更或移除頻道​

在頻道的列上:

  • 使用其開關可以關閉頻道而不移除它,之後可再開啟。當實體的所有頻道都關閉時,該實體會使用從上層繼承的頻道。
  • 選取 Edit 可以變更任何欄位,然後選取 Save。
  • 選取 Remove 可以停止向它傳送。頻道本身仍保留在 Slack 中。

訊息如何找到它的頻道​

頁面會在 Where alerts go 之下顯示所選實體的結果:它自己的頻道,或繼承而來的頻道及其來源實體,或伺服器的預設頻道。

情況警報的去向
警報所屬的實體有已啟用的頻道它自己的頻道,每個頻道各自以其 Minimum 篩選
它沒有頻道,但上層實體有最近一個有頻道的上層實體的頻道
路徑上沒有任何實體有頻道SLACK_DEFAULT_CHANNEL,只傳送警告及嚴重警報
沒有頻道,也沒有預設頻道不會傳送到任何地方;頁面會說明這一點

每則訊息都包含資源及其實體路徑、檢查、數值與閾值的比較及該閾值的設定位置、狀況已持續多久、檢查目錄中有的話則附上建議的處理方式,以及警報的連結。訊息從不提及產品名稱。

讓頻道保持安靜的機制:

  • 每個狀況一個警報。 重複出現只會更新警報,不會傳送任何訊息。
  • 靜默期。 除非嚴重程度上升,否則每個狀況每 10 分鐘最多傳送一則訊息。伺服器設定 EXCUBIUS_NOTIFY_QUIET_MINUTES 可以變更這段時間。
  • 根本原因。 當資源無法連線時,只會傳送一個嚴重的 Cannot reach 警報,該資源的其他警報會等到它解決後才傳送。
  • 靜音及維護時段。 在它們持續期間不會傳送任何訊息;頻道尚未收到的內容,會在它們結束時發出(如果仍然適用)。
  • 不發送降級通知。 從嚴重降為警告只會記錄在警報的時間軸中,不會傳送。只有在開啟時已傳送通知,才會傳送解決通知。
  • 已關閉的功能。 功能已關閉的模組所產生的警報永遠不會傳送,安全建議也一樣。

Slack 絕不會妨礙監控:結果會先儲存並評估,訊息隨後才會發出,並由每 15 秒一次的背景掃描發出。傳送失敗會記錄在警報的時間軸中,並由之後的掃描重試,合共三次嘗試。

使用 API 操作​

工作要求
查看實體的頻道及其有效路由GET /api/v1/entities/{id}/channels
新增頻道POST /api/v1/entities/{id}/channels
變更、關閉或開啟PATCH /api/v1/channels/{id},可帶有 name、config、min_severity、locale、enabled 的任何一項
移除DELETE /api/v1/channels/{id}
傳送測試訊息POST /api/v1/channels/{id}/test。回應 {"ok": true},或回應 {"ok": false, "error": "not_in_channel"} 並附上 Slack 提供的原因
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'