Backstage 通知如何路由到郵件、Slack 等外部渠道【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage在 Backstage 中插件和外部服務發送的通知默認只顯示在前端 UI 的/notifications頁面。如果你希望通知同時投遞到郵件、Slack 這類外部渠道機制是NotificationProcessor它會在通知發出前/后攔截通知可以改寫內容也可以把它轉發到外部系統。本文基于 processors 文檔 和兩個內置處理器模塊的 README、配置 schema給出把郵件和 Slack 渠道接上并驗證的完整路徑。處理器如何接入通知流所有外部渠道都以處理器形式注冊到通知系統。處理器的兩個鉤子分工明確見 processors.mdpreProcess在通知保存到數據庫之前調用適合修改通知內容postProcess在通知保存且 signal 發出之后調用適合發送到外部服務。兩個函數都是可選的可以只實現其中一個。最小骨架如下import { Notification } from backstage/plugin-notifications-common; import { NotificationProcessor } from backstage/plugin-notifications-node; class MyNotificationProcessor implements NotificationProcessor { async preProcess(notification: Notification): PromiseNotification { if (notification.origin plugin-my-plugin) { notification.payload.icon my-icon; } return notification; } async postProcess(notification: Notification): Promisevoid { // 在這里把 notification 投遞到外部服務例如 nodemailer 發信 } }把處理器掛進通知系統通過notificationsProcessingExtensionPoint依賴拿到注冊入口import { notificationsProcessingExtensionPoint } from backstage/plugin-notifications-node; export const myPlugin createBackendPlugin({ pluginId: myPlugin, register(env) { env.registerInit({ deps: { notifications: notificationsProcessingExtensionPoint, }, async init({ notifications }) { notifications.addProcessor(new MyNotificationProcessor()); }, }); }, });郵件和 Slack 都是按這個模式實現的現成模塊下面的章節介紹它們的接入方式。如果你要接的是其他渠道上面這段就是模板。接入郵件渠道內置郵件處理器是backstage/plugin-notifications-backend-module-email支持smtp、ses、azureAzure Communication Services、sendmail以及僅用于調試的stream五種傳輸方式見 模塊 README。安裝并注冊到 backend# 在 Backstage 倉庫根目錄執行 yarn --cwd packages/backend add backstage/plugin-notifications-backend-module-email// packages/backend/src/index.ts const backend createBackend(); // ... backend.add(import(backstage/plugin-notifications-backend-module-email));然后在app-config.yaml中配置。這是 模塊 README 給出的示例占位值需要替換成你自己的 SMTP 服務器和發件人地址notifications: processors: email: # Transport config, see options at config.d.ts transportConfig: transport: smtp hostname: my-smtp-server port: 587 secure: false username: my-username password: my-password # The email sender address sender: sendermycompany.com replyTo: no-replymycompany.com # Who to send email for broadcast notifications broadcastConfig: receiver: users各傳輸方式的關鍵配置項完整字段見 config.d.tstransport必填項說明smtphostname、port可選secure默認 false、requireTls默認 false、username、passwordsesregion可選apiVersion默認 2010-12-01、accountId、endpointazureendpoint可選accessKey不提供時使用 Managed Identitysendmail無可選path默認/usr/sbin/sendmail、newline默認unixstream無僅用于調試實際不發送郵件幾個直接影響路由行為的配置broadcastConfig.receiver廣播通知發給誰取值none跳過、users發給所有 Backstage 用戶可能有性能影響、config發給receiverEmails里列出的地址。filter該處理器處理的范圍。minSeverity/maxSeverity限定嚴重級別excludedTopics列出不發信的 topicincludedTopics若定義了則只有列出的 topic 會發信。allowedEmailDomains精確匹配不區分大小寫、不隱含子域名的允許域列表allowlistEmailAddresses可放行名單外地址denylistEmailAddresses最后生效可覆蓋允許列表。收件地址來自 catalog 中的用戶 profile 數據官方 README 建議生產環境配置域名白名單防止用戶實體上被寫入惡意地址導致郵件發往組織外部。配置路徑沖突提示processors.md 中的示例用的是舊式路徑notifications.email.smtp而模塊 README 和 config.d.ts 定義的結構是notifications.processors.email.transportConfig。以后者為準。接入 Slack 渠道Slack 處理器是backstage/plugin-notifications-backend-module-slack能發給用戶和頻道。前置條件是先有一個 Slack App自建或復用現有的OAuth Permissions 下至少包含這些 scopechat:write、users:read、im:write私信支持如果要向 Bot 未加入的公共頻道發消息可加chat:write.public。然后把Bot User OAuth Token保存下來供配置使用。安裝并注冊yarn --cwd packages/backend add backstage/plugin-notifications-backend-module-slack// packages/backend/src/index.ts const backend createBackend(); // ... backend.add(import(backstage/plugin-notifications-backend-module-slack));app-config.yaml中的配置token替換為你的xoxb-開頭的 Bot Tokennotifications: processors: slack: - token: xoxb-XXXXXXXXX broadcastChannels: # Optional, 用于支持廣播通知 - C12345678 username: Backstage Bot # Optional, 默認為 Slack App 名稱 concurrencyLimit: 20 # Optional, 每區間允許的消息數默認 10 throttleInterval: 1m # Optional, 支持 ISO-8601 時長、1m/30s 或 { minutes: 2 }默認 1 分鐘slack是一個數組可以放多個實例來覆蓋多個 Slack workspace。注意文檔明確說明不支持 Org-Wide App 安裝。按實體注解路由到具體收件方實體需要帶slack.com/bot-notify注解其值是 chat.postMessage 支持的任何 Slack ID例如用戶U12345678、頻道C12345678、群組或私信會話。也可以用用戶郵箱或頻道名但 Slack 官方建議使用 ID私有頻道/會話必須使用 ID。廣播通知的 broadcastRoutes想讓不同來源的通知進不同頻道時用broadcastRoutes按 origin 和/或 topic 路由完整示例見 processors.mdnotifications: processors: slack: - token: xoxb-XXXXXXXXX # Legacy option - 作為沒有路由匹配時的兜底 broadcastChannels: - general-notifications # Route broadcasts based on origin and/or topic broadcastRoutes: # 最具體同時匹配 origin 和 topic - origin: plugin:catalog topic: alerts channel: catalog-alerts # 只匹配 origin - origin: plugin:catalog channel: catalog-updates # 只匹配 topic - topic: security channel: security-team # 一個 origin 發到多個頻道 - origin: external:monitoring channel: - ops-team - on-call-alerts路由按以下優先級求值第一個匹配的路由生效Origin Topic 同時匹配最具體僅 Origin 匹配僅 Topic 匹配都不匹配時回落到broadcastChannels如果沒有任何路由匹配、也沒有配置broadcastChannels該廣播通知不會發送到 Slack。channel字段可以是頻道 ID、頻道名或用戶 ID單個字符串或數組。自定義消息排版可選通過notificationsSlackBlockKitExtensionPoint注冊自定義 Block Kit 渲染器來改變消息在 Slack 里的結構不注冊時使用默認渲染器。用戶側開關與默認設置每個具備發送能力的處理器會在用戶通知設置頁里占一個獨立渠道行與內置的Web渠道并列用戶可以按處理器單獨啟用或禁用通知也可以按 origin/topic 細化。各處理器每收到一條新通知時會檢查用戶的這些設置缺失的設置按啟用處理。注意兩條邊界來自 BEP-0001廣播通知會忽略用戶設置直接發給所有用戶——廣播級別的收斂只能靠處理器自身的配置如郵件的broadcastConfig、Slack 的broadcastRoutes/broadcastChannels。禁用某個 origin/topic 只阻止新通知不會從 UI 里刪除舊通知。前端也可以在app-config.yaml里用notifications.defaultSettings配置渠道/origin/topic 三級默認開關實現 opt-in 策略詳見 notifications Getting Started。如何驗證渠道真的在工作文檔給出的核對手段有這些Slack 側指標如果后端接了 OpenTelemetry 指標導出Slack 處理器會暴露兩個計數器——notifications.processors.slack.sent.count發送成功數和notifications.processors.slack.error.count發送失敗數。兩者能直接回答消息發出去沒有、有沒有失敗。郵件調試傳輸把郵件的transportConfig.transport設為stream處理器會走完整流程但實際不發郵件適合先驗證收件人解析、廣播配置和過濾器是否正確再切回真實傳輸。發信日志郵件處理器在發送前校驗收件地址格式不合法或不在域名白名單內的地址會被跳過日志中會打印 warning投遞繼續給其余有效收件人。排查為什么某人沒收到時先看這里的 warning。限制與邊界廣播通知不受用戶個人設置約束見上文。Slack 不支持 Org-Wide App 安裝私有頻道/會話必須用 ID。沒有任何路由匹配且沒配broadcastChannels時Slack 廣播靜默丟棄。郵件的域名匹配是精確匹配mail.mycompany.com不會匹配mycompany.com。通知發送失敗不會阻塞主流程——NotificationService.send設計上永不拋錯通知被視為非關鍵的次要功能。想進一步了解處理器編寫細節可繼續讀 processors.md郵件與 Slack 各字段含義分別以 郵件 config.d.ts 和 Slack config.d.ts 為準。【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Backstage 通知如何路由到郵件、Slack 等外部渠道？
Backstage 通知如何路由到郵件、Slack 等外部渠道【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage在 Backstage 中插件和外部服務發送的通知默認只顯示在前端 UI 的/notifications頁面。如果你希望通知同時投遞到郵件、Slack 這類外部渠道機制是NotificationProcessor它會在通知發出前/后攔截通知可以改寫內容也可以把它轉發到外部系統。本文基于 processors 文檔 和兩個內置處理器模塊的 README、配置 schema給出把郵件和 Slack 渠道接上并驗證的完整路徑。處理器如何接入通知流所有外部渠道都以處理器形式注冊到通知系統。處理器的兩個鉤子分工明確見 processors.mdpreProcess在通知保存到數據庫之前調用適合修改通知內容postProcess在通知保存且 signal 發出之后調用適合發送到外部服務。兩個函數都是可選的可以只實現其中一個。最小骨架如下import { Notification } from backstage/plugin-notifications-common; import { NotificationProcessor } from backstage/plugin-notifications-node; class MyNotificationProcessor implements NotificationProcessor { async preProcess(notification: Notification): PromiseNotification { if (notification.origin plugin-my-plugin) { notification.payload.icon my-icon; } return notification; } async postProcess(notification: Notification): Promisevoid { // 在這里把 notification 投遞到外部服務例如 nodemailer 發信 } }把處理器掛進通知系統通過notificationsProcessingExtensionPoint依賴拿到注冊入口import { notificationsProcessingExtensionPoint } from backstage/plugin-notifications-node; export const myPlugin createBackendPlugin({ pluginId: myPlugin, register(env) { env.registerInit({ deps: { notifications: notificationsProcessingExtensionPoint, }, async init({ notifications }) { notifications.addProcessor(new MyNotificationProcessor()); }, }); }, });郵件和 Slack 都是按這個模式實現的現成模塊下面的章節介紹它們的接入方式。如果你要接的是其他渠道上面這段就是模板。接入郵件渠道內置郵件處理器是backstage/plugin-notifications-backend-module-email支持smtp、ses、azureAzure Communication Services、sendmail以及僅用于調試的stream五種傳輸方式見 模塊 README。安裝并注冊到 backend# 在 Backstage 倉庫根目錄執行 yarn --cwd packages/backend add backstage/plugin-notifications-backend-module-email// packages/backend/src/index.ts const backend createBackend(); // ... backend.add(import(backstage/plugin-notifications-backend-module-email));然后在app-config.yaml中配置。這是 模塊 README 給出的示例占位值需要替換成你自己的 SMTP 服務器和發件人地址notifications: processors: email: # Transport config, see options at config.d.ts transportConfig: transport: smtp hostname: my-smtp-server port: 587 secure: false username: my-username password: my-password # The email sender address sender: sendermycompany.com replyTo: no-replymycompany.com # Who to send email for broadcast notifications broadcastConfig: receiver: users各傳輸方式的關鍵配置項完整字段見 config.d.tstransport必填項說明smtphostname、port可選secure默認 false、requireTls默認 false、username、passwordsesregion可選apiVersion默認 2010-12-01、accountId、endpointazureendpoint可選accessKey不提供時使用 Managed Identitysendmail無可選path默認/usr/sbin/sendmail、newline默認unixstream無僅用于調試實際不發送郵件幾個直接影響路由行為的配置broadcastConfig.receiver廣播通知發給誰取值none跳過、users發給所有 Backstage 用戶可能有性能影響、config發給receiverEmails里列出的地址。filter該處理器處理的范圍。minSeverity/maxSeverity限定嚴重級別excludedTopics列出不發信的 topicincludedTopics若定義了則只有列出的 topic 會發信。allowedEmailDomains精確匹配不區分大小寫、不隱含子域名的允許域列表allowlistEmailAddresses可放行名單外地址denylistEmailAddresses最后生效可覆蓋允許列表。收件地址來自 catalog 中的用戶 profile 數據官方 README 建議生產環境配置域名白名單防止用戶實體上被寫入惡意地址導致郵件發往組織外部。配置路徑沖突提示processors.md 中的示例用的是舊式路徑notifications.email.smtp而模塊 README 和 config.d.ts 定義的結構是notifications.processors.email.transportConfig。以后者為準。接入 Slack 渠道Slack 處理器是backstage/plugin-notifications-backend-module-slack能發給用戶和頻道。前置條件是先有一個 Slack App自建或復用現有的OAuth Permissions 下至少包含這些 scopechat:write、users:read、im:write私信支持如果要向 Bot 未加入的公共頻道發消息可加chat:write.public。然后把Bot User OAuth Token保存下來供配置使用。安裝并注冊yarn --cwd packages/backend add backstage/plugin-notifications-backend-module-slack// packages/backend/src/index.ts const backend createBackend(); // ... backend.add(import(backstage/plugin-notifications-backend-module-slack));app-config.yaml中的配置token替換為你的xoxb-開頭的 Bot Tokennotifications: processors: slack: - token: xoxb-XXXXXXXXX broadcastChannels: # Optional, 用于支持廣播通知 - C12345678 username: Backstage Bot # Optional, 默認為 Slack App 名稱 concurrencyLimit: 20 # Optional, 每區間允許的消息數默認 10 throttleInterval: 1m # Optional, 支持 ISO-8601 時長、1m/30s 或 { minutes: 2 }默認 1 分鐘slack是一個數組可以放多個實例來覆蓋多個 Slack workspace。注意文檔明確說明不支持 Org-Wide App 安裝。按實體注解路由到具體收件方實體需要帶slack.com/bot-notify注解其值是 chat.postMessage 支持的任何 Slack ID例如用戶U12345678、頻道C12345678、群組或私信會話。也可以用用戶郵箱或頻道名但 Slack 官方建議使用 ID私有頻道/會話必須使用 ID。廣播通知的 broadcastRoutes想讓不同來源的通知進不同頻道時用broadcastRoutes按 origin 和/或 topic 路由完整示例見 processors.mdnotifications: processors: slack: - token: xoxb-XXXXXXXXX # Legacy option - 作為沒有路由匹配時的兜底 broadcastChannels: - general-notifications # Route broadcasts based on origin and/or topic broadcastRoutes: # 最具體同時匹配 origin 和 topic - origin: plugin:catalog topic: alerts channel: catalog-alerts # 只匹配 origin - origin: plugin:catalog channel: catalog-updates # 只匹配 topic - topic: security channel: security-team # 一個 origin 發到多個頻道 - origin: external:monitoring channel: - ops-team - on-call-alerts路由按以下優先級求值第一個匹配的路由生效Origin Topic 同時匹配最具體僅 Origin 匹配僅 Topic 匹配都不匹配時回落到broadcastChannels如果沒有任何路由匹配、也沒有配置broadcastChannels該廣播通知不會發送到 Slack。channel字段可以是頻道 ID、頻道名或用戶 ID單個字符串或數組。自定義消息排版可選通過notificationsSlackBlockKitExtensionPoint注冊自定義 Block Kit 渲染器來改變消息在 Slack 里的結構不注冊時使用默認渲染器。用戶側開關與默認設置每個具備發送能力的處理器會在用戶通知設置頁里占一個獨立渠道行與內置的Web渠道并列用戶可以按處理器單獨啟用或禁用通知也可以按 origin/topic 細化。各處理器每收到一條新通知時會檢查用戶的這些設置缺失的設置按啟用處理。注意兩條邊界來自 BEP-0001廣播通知會忽略用戶設置直接發給所有用戶——廣播級別的收斂只能靠處理器自身的配置如郵件的broadcastConfig、Slack 的broadcastRoutes/broadcastChannels。禁用某個 origin/topic 只阻止新通知不會從 UI 里刪除舊通知。前端也可以在app-config.yaml里用notifications.defaultSettings配置渠道/origin/topic 三級默認開關實現 opt-in 策略詳見 notifications Getting Started。如何驗證渠道真的在工作文檔給出的核對手段有這些Slack 側指標如果后端接了 OpenTelemetry 指標導出Slack 處理器會暴露兩個計數器——notifications.processors.slack.sent.count發送成功數和notifications.processors.slack.error.count發送失敗數。兩者能直接回答消息發出去沒有、有沒有失敗。郵件調試傳輸把郵件的transportConfig.transport設為stream處理器會走完整流程但實際不發郵件適合先驗證收件人解析、廣播配置和過濾器是否正確再切回真實傳輸。發信日志郵件處理器在發送前校驗收件地址格式不合法或不在域名白名單內的地址會被跳過日志中會打印 warning投遞繼續給其余有效收件人。排查為什么某人沒收到時先看這里的 warning。限制與邊界廣播通知不受用戶個人設置約束見上文。Slack 不支持 Org-Wide App 安裝私有頻道/會話必須用 ID。沒有任何路由匹配且沒配broadcastChannels時Slack 廣播靜默丟棄。郵件的域名匹配是精確匹配mail.mycompany.com不會匹配mycompany.com。通知發送失敗不會阻塞主流程——NotificationService.send設計上永不拋錯通知被視為非關鍵的次要功能。想進一步了解處理器編寫細節可繼續讀 processors.md郵件與 Slack 各字段含義分別以 郵件 config.d.ts 和 Slack config.d.ts 為準。【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考