Backstage 通知如何路由到郵件、Slack 等外部渠道【免費(fèi)下載鏈接】backstageBackstage is an open framework for building developer portals項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ba/backstage在 Backstage 中插件和外部服務(wù)發(fā)送的通知默認(rèn)只顯示在前端 UI 的/notifications頁面。如果你希望通知同時投遞到郵件、Slack 這類外部渠道機(jī)制是NotificationProcessor它會在通知發(fā)出前/后攔截通知可以改寫內(nèi)容也可以把它轉(zhuǎn)發(fā)到外部系統(tǒng)。本文基于 processors 文檔 和兩個內(nèi)置處理器模塊的 README、配置 schema給出把郵件和 Slack 渠道接上并驗(yàn)證的完整路徑。處理器如何接入通知流所有外部渠道都以處理器形式注冊到通知系統(tǒng)。處理器的兩個鉤子分工明確見 processors.mdpreProcess在通知保存到數(shù)據(jù)庫之前調(diào)用適合修改通知內(nèi)容postProcess在通知保存且 signal 發(fā)出之后調(diào)用適合發(fā)送到外部服務(wù)。兩個函數(shù)都是可選的可以只實(shí)現(xiàn)其中一個。最小骨架如下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 投遞到外部服務(wù)例如 nodemailer 發(fā)信 } }把處理器掛進(jìn)通知系統(tǒng)通過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 都是按這個模式實(shí)現(xiàn)的現(xiàn)成模塊下面的章節(jié)介紹它們的接入方式。如果你要接的是其他渠道上面這段就是模板。接入郵件渠道內(nèi)置郵件處理器是backstage/plugin-notifications-backend-module-email支持smtp、ses、azureAzure Communication Services、sendmail以及僅用于調(diào)試的stream五種傳輸方式見 模塊 README。安裝并注冊到 backend# 在 Backstage 倉庫根目錄執(zhí)行 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 服務(wù)器和發(fā)件人地址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各傳輸方式的關(guān)鍵配置項(xiàng)完整字段見 config.d.tstransport必填項(xiàng)說明smtphostname、port可選secure默認(rèn) false、requireTls默認(rèn) false、username、passwordsesregion可選apiVersion默認(rèn) 2010-12-01、accountId、endpointazureendpoint可選accessKey不提供時使用 Managed Identitysendmail無可選path默認(rèn)/usr/sbin/sendmail、newline默認(rèn)unixstream無僅用于調(diào)試實(shí)際不發(fā)送郵件幾個直接影響路由行為的配置broadcastConfig.receiver廣播通知發(fā)給誰取值none跳過、users發(fā)給所有 Backstage 用戶可能有性能影響、config發(fā)給receiverEmails里列出的地址。filter該處理器處理的范圍。minSeverity/maxSeverity限定嚴(yán)重級別excludedTopics列出不發(fā)信的 topicincludedTopics若定義了則只有列出的 topic 會發(fā)信。allowedEmailDomains精確匹配不區(qū)分大小寫、不隱含子域名的允許域列表allowlistEmailAddresses可放行名單外地址denylistEmailAddresses最后生效可覆蓋允許列表。收件地址來自 catalog 中的用戶 profile 數(shù)據(jù)官方 README 建議生產(chǎn)環(huán)境配置域名白名單防止用戶實(shí)體上被寫入惡意地址導(dǎo)致郵件發(fā)往組織外部。配置路徑?jīng)_突提示processors.md 中的示例用的是舊式路徑notifications.email.smtp而模塊 README 和 config.d.ts 定義的結(jié)構(gòu)是notifications.processors.email.transportConfig。以后者為準(zhǔn)。接入 Slack 渠道Slack 處理器是backstage/plugin-notifications-backend-module-slack能發(fā)給用戶和頻道。前置條件是先有一個 Slack App自建或復(fù)用現(xiàn)有的OAuth Permissions 下至少包含這些 scopechat:write、users:read、im:write私信支持如果要向 Bot 未加入的公共頻道發(fā)消息可加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, 默認(rèn)為 Slack App 名稱 concurrencyLimit: 20 # Optional, 每區(qū)間允許的消息數(shù)默認(rèn) 10 throttleInterval: 1m # Optional, 支持 ISO-8601 時長、1m/30s 或 { minutes: 2 }默認(rèn) 1 分鐘slack是一個數(shù)組可以放多個實(shí)例來覆蓋多個 Slack workspace。注意文檔明確說明不支持 Org-Wide App 安裝。按實(shí)體注解路由到具體收件方實(shí)體需要帶slack.com/bot-notify注解其值是 chat.postMessage 支持的任何 Slack ID例如用戶U12345678、頻道C12345678、群組或私信會話。也可以用用戶郵箱或頻道名但 Slack 官方建議使用 ID私有頻道/會話必須使用 ID。廣播通知的 broadcastRoutes想讓不同來源的通知進(jìn)不同頻道時用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 發(fā)到多個頻道 - origin: external:monitoring channel: - ops-team - on-call-alerts路由按以下優(yōu)先級求值第一個匹配的路由生效Origin Topic 同時匹配最具體僅 Origin 匹配僅 Topic 匹配都不匹配時回落到broadcastChannels如果沒有任何路由匹配、也沒有配置broadcastChannels該廣播通知不會發(fā)送到 Slack。channel字段可以是頻道 ID、頻道名或用戶 ID單個字符串或數(shù)組。自定義消息排版可選通過notificationsSlackBlockKitExtensionPoint注冊自定義 Block Kit 渲染器來改變消息在 Slack 里的結(jié)構(gòu)不注冊時使用默認(rèn)渲染器。用戶側(cè)開關(guān)與默認(rèn)設(shè)置每個具備發(fā)送能力的處理器會在用戶通知設(shè)置頁里占一個獨(dú)立渠道行與內(nèi)置的Web渠道并列用戶可以按處理器單獨(dú)啟用或禁用通知也可以按 origin/topic 細(xì)化。各處理器每收到一條新通知時會檢查用戶的這些設(shè)置缺失的設(shè)置按啟用處理。注意兩條邊界來自 BEP-0001廣播通知會忽略用戶設(shè)置直接發(fā)給所有用戶——廣播級別的收斂只能靠處理器自身的配置如郵件的broadcastConfig、Slack 的broadcastRoutes/broadcastChannels。禁用某個 origin/topic 只阻止新通知不會從 UI 里刪除舊通知。前端也可以在app-config.yaml里用notifications.defaultSettings配置渠道/origin/topic 三級默認(rèn)開關(guān)實(shí)現(xiàn) opt-in 策略詳見 notifications Getting Started。如何驗(yàn)證渠道真的在工作文檔給出的核對手段有這些Slack 側(cè)指標(biāo)如果后端接了 OpenTelemetry 指標(biāo)導(dǎo)出Slack 處理器會暴露兩個計數(shù)器——notifications.processors.slack.sent.count發(fā)送成功數(shù)和notifications.processors.slack.error.count發(fā)送失敗數(shù)。兩者能直接回答消息發(fā)出去沒有、有沒有失敗。郵件調(diào)試傳輸把郵件的transportConfig.transport設(shè)為stream處理器會走完整流程但實(shí)際不發(fā)郵件適合先驗(yàn)證收件人解析、廣播配置和過濾器是否正確再切回真實(shí)傳輸。發(fā)信日志郵件處理器在發(fā)送前校驗(yàn)收件地址格式不合法或不在域名白名單內(nèi)的地址會被跳過日志中會打印 warning投遞繼續(xù)給其余有效收件人。排查為什么某人沒收到時先看這里的 warning。限制與邊界廣播通知不受用戶個人設(shè)置約束見上文。Slack 不支持 Org-Wide App 安裝私有頻道/會話必須用 ID。沒有任何路由匹配且沒配broadcastChannels時Slack 廣播靜默丟棄。郵件的域名匹配是精確匹配mail.mycompany.com不會匹配mycompany.com。通知發(fā)送失敗不會阻塞主流程——NotificationService.send設(shè)計上永不拋錯通知被視為非關(guān)鍵的次要功能。想進(jìn)一步了解處理器編寫細(xì)節(jié)可繼續(xù)讀 processors.md郵件與 Slack 各字段含義分別以 郵件 config.d.ts 和 Slack config.d.ts 為準(zhǔn)?！久赓M(fèi)下載鏈接】backstageBackstage is an open framework for building developer portals項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ba/backstage創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考