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），仅供参考
` 的用法与源码实现解析)
