Backstage 通知系统（Notifications Signals）接入指南：安装、配置与 Scaffolder 集成实战

Backstage 通知系统Notifications Signals接入指南安装、配置与 Scaffolder 集成实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读Backstage 通知系统Notifications System为插件和外部服务提供了一条向 Backstage 用户发送通知的标准通道通知可以展示在前端专用的/notifications页面中也可以由前端插件按具体场景自行消费还可以通过插件内实现的 processors 转发到外部渠道如 Email。本文以 docs/notifications/index.md 为核心主线结合本仓库中 notifications 系列插件的真实源码与配置定义完整讲解后端/前端插件安装、侧边栏入口、可选 Signals 实时推送、用户级与全局默认通知设置、自动清理机制以及通过 Scaffolder 模板动作发送通知的完整实战帮助你在自己的 Backstage 应用中快速落地一套可用的通知体系。本文面向使用新前端系统New Frontend System也是新版 Backstage 应用的默认前端系统的读者。如果你的应用仍在使用旧前端系统请参阅 旧前端系统版本指南旧版指南采用Root.tsx、App.tsx手动挂载路由与SignalsDisplay /的接入方式核心概念与配置部分完全一致。通知系统是什么通知Notifications是发送给单个用户或用户组的消息其定位非常明确不用于任何形式的进程间通信inter-process communication。需要异步任务编排、事件总线之类能力的场景应使用其他机制如 events-backend、signals 等。通知分为两种基本类型Broadcast广播发送给 Backstage 的所有用户。适用于系统级公告、全局告警等场景。Entity实体定向投递给特定实体列表如 User、Group。适用于面向组件所有者、订阅者或目录中特定实体的定向消息。典型使用场景包括系统级公告或告警Broadcast面向组件所有者的通知例如构建失败、部署成功、新漏洞Entity面向个人的通知例如你订阅的更新、新的必修培训课程Entity与目录中某个实体相关的通知例如一条通知同时适用于某个实体及其负责团队Entity在此基础上通知系统可以可选地与 Signals 插件配合使用。Signals 提供一套推送机制确保用户无需轮询即可立即收到新通知显著改善实时性体验。版本要求与升级为保证你使用的 Backstage 版本包含全部 notifications 与 signals 相关功能建议先升级到最新版本。官方提供的 Backstage upgrade helper 是升级过程中核对所有必要变更的常用工具在仓库内可以参考 docs/getting-started/keeping-backstage-updated.md 了解常规升级流程。注意从 Backstage1.42.0版本开始Notifications 与 Signals 已经作为默认backstage/create-app实例的组成部分被内置安装因此无需再手动执行下面的安装步骤。唯一例外是你仍需要手动添加 Notifications 侧边栏入口以及可选在 用户设置页添加 Notifications 标签页。安装 Notifications 后端如果你的应用版本早于1.42.0或未内置该插件先添加后端依赖包yarn --cwd packages/backend add backstage/plugin-notifications-backend然后在后端入口 packages/backend/src/index.ts 中注册插件const backend createBackend(); // ... backend.add(import(backstage/plugin-notifications-backend));从源码结构看该后端插件见 plugins/notifications-backend/src/plugin.ts由createBackendPlugin定义其初始化时依赖coreServices.auth、coreServices.httpAuth、coreServices.userInfo、coreServices.httpRouter、coreServices.logger、coreServices.database、coreServices.rootConfig、coreServices.scheduler以及signalsServiceRef、catalogServiceRef、actionsRegistryServiceRef等服务。它主要完成四件事注册notificationsProcessingExtensionPoint供其他模块注入 Notification Processor 与 Recipient Resolver通过createRouter挂载 REST API 路由同时将/health路由设为允许未认证访问用于健康检查创建NotificationCleaner并启动定时清理任务通过createNotificationsActions向 Scaffolder 动作注册表注入通知相关动作见下文 Scaffolder 集成。安装 Notifications 前端添加前端依赖包yarn --cwd packages/app add backstage/plugin-notifications安装完成后通过默认的 feature discovery 机制通知插件会自动在应用中生效并提供位于/notifications的通知页面通知 API供前端插件调用。更多安装方式与细节参见 安装插件。添加 Notifications 侧边栏入口通知插件目前不内置导航项需要手动把NotificationsSidebarItem组件加入侧边栏。如果你通过NavContentBlueprint自定义了侧边栏在该组件中加入即可import { NotificationsSidebarItem } from backstage/plugin-notifications; // Inside your NavContentBlueprint component: Sidebar SidebarGroup labelMenu icon{MenuIcon /} {/* ... other items ... */} /SidebarGroup SidebarGroup labelSettings icon{SettingsIcon /} to/settings NotificationsSidebarItem / /SidebarGroup /Sidebar;旧前端系统下则需要手动在Root.tsx挂载NotificationsSidebarItem并在App.tsx中为/notifications添加Route参见 docs/notifications/index--old.md。可选接入 Signals 实现实时推送Signals 的使用是可选的但它通过实时推送更新显著改善用户体验。其原理可参考仓库中的 signals、signals-backend、signals-node、signals-react 等包后端通过signalsServiceRef与 notifications 后端协作前端则通过 signals 客户端建立长连接通知到达后立即推送到浏览器。可选Signals 后端yarn --cwd packages/backend add backstage/plugin-signals-backendconst backend createBackend(); // ... backend.add(import(backstage/plugin-signals-backend));可选Signals 前端yarn --cwd packages/app add backstage/plugin-signals安装完成后signals 插件通过默认 feature discovery 自动生效无需额外配置。只要 signals 插件被正确配置notifications 插件会自动发现并使用它——这一点在 notifications-backend/src/plugin.ts 中可以看到后端在初始化时显式声明了对signalsServiceRef的依赖将实时推送能力直接接入通知处理链路。用户级通知设置通知插件为用户提供了管理通知设置的能力。通过SubPageBlueprint创建一个挂载到 user-settings 插件的设置标签页即可启用。首先创建设置页面组件packages/app/src/modules/NotificationSettingsPage.tsximport { Content } from backstage/core-components; import { UserNotificationSettingsCard } from backstage/plugin-notifications; export function NotificationSettingsPage() { return ( Content UserNotificationSettingsCard originNames{{ plugin:scaffolder: Scaffolder }} / /Content ); }然后定义前端模块packages/app/src/modules/notificationSettings.tsximport { createFrontendModule } from backstage/frontend-plugin-api; import { SubPageBlueprint } from backstage/frontend-plugin-api; export const notificationSettingsModule createFrontendModule({ pluginId: user-settings, extensions: [ SubPageBlueprint.make({ name: notifications, params: { path: notifications, title: Notifications, loader: () import(./NotificationSettingsPage).then(m ( m.NotificationSettingsPage / )), }, }), ], });最后把该模块安装到应用中将其加入createApp的 features 数组如果你的应用开启了默认 feature discovery也可以通过该机制自动加载。两点自定义说明来源origin名称定制通过originNames传入一个对象键为 origin来源标识值为希望在界面中展示的名称。例如{ plugin:scaffolder: Scaffolder }会把 Scaffolder 插件来源在界面上显示为 Scaffolder。按处理器粒度开关每个通知处理器notification processor都会在设置页面拥有独立的一行用户可分别启用或禁用来自该处理器的通知。旧前端系统下的等价做法是在App.tsx的UserSettingsPage /路由中加入SettingsLayout.Route并渲染UserNotificationSettingsCard详见 旧版指南。全局默认通知设置app-config.yaml除了让用户自行设置你还可以在app-config.yaml中为所有用户配置默认通知设置。这在需要全局统一偏好的场景下非常有用例如默认禁用某些渠道或来源从而实施opt-in默认关闭而非opt-out默认开启策略。配置结构由 notifications-backend/config.d.ts 定义整体为notifications.defaultSettings.channels[]每个 channel 可包含origins[]每个 origin 又可包含topics[]。下面按粒度从粗到细逐一说明。渠道级Channel-level默认值可为整个渠道设置默认启用状态。当设为false时该渠道采用 opt-in 策略通知默认禁用除非用户显式开启或针对特定来源显式开启。notifications: defaultSettings: channels: - id: Web enabled: false # Opt-in 策略渠道默认关闭 - id: Email enabled: true # Opt-out 策略渠道默认开启默认行为来源级Origin-level默认值也可以为渠道内的特定来源origin配置默认值notifications: defaultSettings: channels: - id: Web enabled: true # 渠道默认开启 origins: - id: plugin:scaffolder enabled: false # 默认关闭 scaffolder 的通知 - id: plugin:catalog enabled: true # 默认开启 catalog 的通知从 config.d.ts 的注释可以看到origin 的 id 形如plugin:catalog、external:jenkins——plugin:前缀表示来自某个 Backstage 插件external:前缀表示来自外部服务。主题级Topic-level默认值需要更细粒度控制时可以为来源内的特定主题topic设置默认值notifications: defaultSettings: channels: - id: Email enabled: false # Email 默认 opt-in origins: - id: plugin:catalog enabled: true # 但 catalog 的通知是开启的 topics: - id: entity:validation:error enabled: false # 唯独校验错误类主题关闭topic 的 id 形如entity-refresh、build-failure见 config.d.ts。重要规则与 config.d.ts 中的实现说明一致若渠道的enabled标志未设置则默认视为true以保持向后兼容当渠道设置为enabled: false时该渠道内所有来源默认均为关闭状态除非显式开启。通知自动清理机制为防止数据库无限增长、保持界面整洁通知会在存储一段时间后被自动删除。默认保留期为 1 年即超过该期限的通知会被自动清理。保留期可通过app-config.yaml中的notifications.retention配置notifications: retention: 1y若将retention设为false则通知不会被自动删除。从源码层面看这一机制的实现位于 plugins/notifications-backend/src/service/NotificationCleaner.ts默认保留期在构造时初始化为{ years: 1 }第 27 行且默认启用第 28 行配置解析逻辑第 42-54 行若notifications.retention存在且为布尔值false则直接禁用清理任务否则通过readDurationFromConfig读取持续时间配置任务调度第 62-67 行使用cron: 0 0 * * *每天午夜执行超时 1 小时初始延迟 1 小时作用域为global保证多实例部署下只有一个清理任务运行实际清理第 82-96 行调用database.clearNotifications({ maxAge: retention })并按deletedCount记录删除数量。该清理器在 plugin.ts 中随后端插件一并初始化其相关单元测试可参考 NotificationCleaner.test.ts。Scaffolder Action在软件模板中发送通知除了插件/外部服务直接调用 API 发送通知通知系统还提供了一个Scaffolder 动作可以在软件模板Software Template执行流程中发送通知。注意从 Backstage1.42.0版本开始该动作也已作为默认backstage/create-app实例的一部分被内置无需手动安装可直接跳到下方的 基础示例。如需手动安装先添加后端依赖包yarn --cwd packages/backend add backstage/plugin-scaffolder-backend-module-notifications然后在 packages/backend/src/index.ts 注册const backend createBackend(); // ... backend.add( import(backstage/plugin-scaffolder-backend-module-notifications), );从 module.ts 的源码可以看到该模块以createBackendModule定义插件 ID 为scaffolder模块 ID 为notifications初始化时同时依赖notificationService来自backstage/plugin-notifications-node与scaffolderActionsExtensionPoint将createSendNotificationAction注册为 Scaffolder 动作。基础示例下面是在软件模板中使用该动作的示例。更多细节与示例可以在你 Backstage 实例的Installed actions界面中查看该动作的示例定义见 sendNotification.examples.ts测试见 sendNotification.test.ts。steps: - id: notify name: Notify action: notification:send input: recipients: entity entityRefs: - user:default/guest title: Template executed info: Your template has been executed severity: normal上述示例会向 Guest 用户user:default/guest发送一条通知。action 输入参数详解根据 sendNotification.ts 中定义的输入 schemanotification:send支持以下参数参数类型必填说明recipientsenum(broadcast \| entity)是接收者类型。选择entity时必须同时提供entityRefsentityRefsstring[]条件必填接收通知的实体引用列表recipients: entity时必填titlestring是通知标题infostring否通知描述文本linkstring否通知附带链接severityenum(low \| normal \| high \| critical)否通知严重级别源码实现中normal为默认值见 types.ts 与 constants.tsscopestring否通知作用域标识topicstring否通知主题标识可与全局默认设置中的 topic 级配置联动optionalboolean否为true时通知发送失败不会导致模板步骤失败几个值得注意的实现细节实体校验当recipients entity但未提供entityRefs时若optional不为true动作会直接抛出Entity references must be provided错误第 83-88 行幂等支持动作内部通过ctx.checkpoint({ key: send.notification.title })包裹发送逻辑第 104-112 行这与本仓库中 Scaffolder 任务幂等性设计 的思路一致可避免模板重试时重复发送通知底层发送链路notificationService.send()的实现见 DefaultNotificationService.ts会先通过discovery.getBaseUrl(notifications)解析 notifications 后端地址再以auth.getPluginRequestToken获取服务间调用令牌最后POST到该地址从而实现插件到后端、后端到后端如外部服务的统一发送入口。后端插件如何发送通知进阶对于希望在自己的后端插件中发送通知的开发者推荐使用backstage/plugin-notifications-node提供的notificationServiceNotificationService的实例并通过notificationsProcessingExtensionPoint注册处理器。相关参考实现就在本仓库内通知服务与收件人解析plugins/notifications-node/src/service含 NotificationService.ts、DefaultNotificationService.ts以及收件人解析相关的 DefaultNotificationRecipientResolver.ts后端 API 与存储plugins/notifications-backend/src路由在 service/router.ts存储层在 databaseOpenAPI 定义在 schema/openapi.yaml公共类型与常量plugins/notifications-common/src含NotificationPayload、NotificationSeverity等类型定义见 types.ts收件人类型NotificationRecipients支持{ type: entity, entityRef, excludeEntityRef? }与{ type: broadcast }两种形态见 DefaultNotificationService.ts其中excludeEntityRef可用于排除当前操作用户避免用户执行了操作却收到自己操作的通知处理器Processor与扩展点扩展点定义位于 plugins/notifications-node/src/extensions.ts后端在 plugin.ts 中实现该扩展点addProcessor收集所有处理器setNotificationRecipientResolver仅允许设置一次解析器。相关源码参考本仓库中 notifications 与 signals 系列的全部相关包plugins/notifications — 通知前端插件页面、侧边栏项、用户设置卡片plugins/notifications-backend — 通知后端插件REST API、存储、清理任务、动作注册plugins/notifications-common — 通知公共类型与常量plugins/notifications-node — 后端通知服务与扩展点plugins/scaffolder-backend-module-notifications — Scaffolder 的notification:send动作模块plugins/signals — Signals 前端插件plugins/signals-backend — Signals 后端插件plugins/signals-node — Signals 后端服务定义plugins/signals-react — Signals React 客户端库接入完成后你可以在/notifications页面查看广播与定向通知在用户设置页为各处理器单独配置开关并通过 Signals 获得实时到达体验同时结合全局默认设置与自动清理机制即可构建一套低成本、可运维、体验完整的 Backstage 通知体系。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考