NocoBase 通知管理Notification Manager完整指南多渠道配置、工作流触发与自定义渠道扩展【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase导读NocoBase 的通知管理nocobase/plugin-notification-manager是一个集成多渠道通知方式的中心化服务为站内信、电子邮件、企业微信等通知渠道提供统一的渠道配置、发送管理与日志记录能力并允许通过插件机制按需扩展短信、App 推送、钉钉、飞书等任意第三方通知渠道。本文以 通知管理概述 为主线结合渠道文档与源码实现完整讲解渠道管理、通知日志、工作流通知节点以及从registerChannelType到send()的底层调用链帮助你既能在界面上快速落地通知能力也能基于扩展 API 开发属于自己的通知渠道插件。通知管理是什么通知管理是 NocoBase 中负责“把消息可靠地送达用户”的中心化服务模块。它不直接绑定任何单一的通知技术而是抽象出统一的**渠道Channel**概念渠道负责“怎么发”通知管理负责“发给谁、何时发、发完记什么账”。整体架构可以分为三层通知管理内核提供统一的管理服务涵盖渠道配置、发送编排、日志记录等功能通知渠道类型本身可扩展内置渠道站内信In-App Message开箱即用支持用户在 NocoBase 应用内实时接收消息扩展渠道电子邮件Email基于 SMTP、企业微信WeCom等由对应插件提供激活后即可在通知管理中统一使用。从源码上看服务端核心类NotificationManager见 manager.ts通过一个Registry维护所有已注册的渠道类型构造器public channelTypes new Registry{ Channel: NotificationChannelConstructor; useQueue: boolean }();每个渠道类型只要在注册时提供Channel构造器继承自BaseNotificationChannel即可被统一调度。这意味着通知管理天然是“渠道可插拔”的新增一种通知方式不需要改动内核只需要新增一个渠道插件。渠道管理界面操作在 NocoBase 管理后台进入“通知管理”可以看到渠道列表页面。点击新增按钮即可从已注册的渠道类型中选择并创建渠道站内信内置渠道无需安装创建时只需填写渠道名称与描述电子邮件预置插件nocobase/plugin-notification-email需先在插件管理页激活渠道配置中目前仅支持 SMTP 传输方式需要填写 SMTP 服务器地址、端口、账号、密码、发件人等企业微信通过nocobase/plugin-auth-wecom与用户认证联动只有经过企业微信登录的系统用户才能通过企业微信接收系统通知。需要扩展更多渠道如短信、App 推送时参考 渠道扩展 文档。渠道的数据模型渠道在数据库中存储为notificationChannels集合定义见 channel.ts其核心字段如下字段类型说明nameuid渠道唯一标识主键支持字母、数字、下划线必须以字母开头创建时随机生成、可修改titlestring渠道显示名称用于在界面与日志中辨识notificationTypestring通知类型即注册的渠道类型标识如in-app-message、email创建渠道时选择optionsjson渠道配置参数由对应渠道类型提供的ChannelConfigForm决定如 SMTP 的 host/port/account/password/frommetajson渠道元信息descriptiontext渠道描述其中notificationType的下拉选项enum由notificationTypeOptions动态注入即界面上能选到哪些渠道类型完全取决于当前已注册的渠道类型库——这正是“渠道可扩展”的直接体现。通知日志发送全过程的留痕每条通知发送后都会在notificationSendLogs集合中生成一条日志记录字段定义见 messageLog.ts用于分析和故障排查字段类型说明iduuid日志主键channelName/channelTitlestring发送所用渠道的名称与显示名称notificationTypestring渠道类型triggerFromstring触发来源如工作流触发的workflow、API 批量触发的sendToUsersstatusselectsuccess/failure界面中以绿/红颜色区分messagejson发送的消息内容含接收人reasontext失败原因createdAt/updatedAtdate创建与更新时间在服务端日志的落库发生在 manager.ts 的sendNow中无论渠道发送成功还是抛出异常都会调用createSendingRecord写入日志并记录compileMs消息模板编译耗时、findChannelMs渠道查询耗时、channelSendMs渠道实际发送耗时等埋点。当单次发送总耗时超过 500msSLOW_SEND_THRESHOLD_MS时还会输出一条notification send is slow的 warn 日志方便定位慢通知。工作流通知节点通知管理内置于工作流生态通过nocobase/plugin-workflow-notification插件提供一个“通知”指令节点实现见 NotificationInstruction.ts你可以在任意工作流中插入通知节点选择之前创建好的通知渠道配置消息内容内容表单支持消费工作流上下文变量如发起人、业务数据字段节点执行时工作流处理器调用通知管理内核的send()完成下发。节点支持ignoreFail配置默认false当设置为true时即使通知发送失败工作流节点也按成功处理、继续流转适合“通知失败不影响主流程”的场景。源码中configSchema定义如下configSchema Joi.object({ channelName: Joi.string(), ignoreFail: Joi.boolean().default(false), });在执行阶段指令会通过this.workflow.pm.get(NotificationsServerPlugin)拿到通知管理服务端插件实例再调用其send()方法发送结果为success时工作流节点置为RESOLVED成功否则置为FAILED/ERROR。此外工作流节点还实现了test()方法用于在配置界面“测试发送”测试走的是sendNow()直发路径不经消息队列。内置渠道与扩展渠道站内信In-App Message由内置插件nocobase/plugin-notification-in-app-message提供无需安装即可在通知管理中新增“站内信”渠道。创建后用户可以在 NocoBase 应用内实时收到消息消息按渠道名称分组展示支持按已读/未读状态筛选并可通过“查看”按钮跳转到配置的链接页面进一步处理。典型场景示例——“营销线索跟进”在渠道管理中创建名为Marketing Clue的站内信渠道 → 在工作流中增加通知节点、选择该渠道并配置消息内容 → 当新的营销线索产生时自动触发 → 相关人员实时收到站内信并按需跟进。该流程完整覆盖了“渠道配置 → 工作流触发 → 应用内接收 → 消息管理与跟踪”四个环节。电子邮件Email由预置插件nocobase/plugin-notification-email提供需先在插件管理页激活。目前仅支持 SMTP 传输方式渠道配置中填写 SMTP 服务器host、port、secure是否 TLS、账号account、密码password、发件人from等信息。从源码实现看见 mail-server.ts邮件渠道基于nodemailer实现并做了连接池复用优化以host:port:account作为 transporter 的缓存键同一 SMTP 配置复用同一个连接池pool: true通过isConfigChanged对比host/port/secure/account/password/from六个字段仅在配置发生变化时才关闭旧 transporter 并重建新连接避免频繁建连。邮件接收人支持两种方式NocoBase 站内用户 IDuserId或直接填写邮箱地址channel-self-defined。企业微信WeCom由nocobase/plugin-auth-wecom提供。使用前需先在用户认证中配置企业微信认证器参考 用户认证 - 企业微信只有通过企业微信登录的系统用户才能接收通知。添加通知渠道时选择该认证器工作流通知节点中可选择三种消息类型文本卡片、Markdown、模版卡片。编程式发送服务端send()与sendToUsers()除了通过工作流节点发送通知管理内核还暴露了服务端 API可在任意插件代码中直接下发通知。服务端插件类为PluginNotificationManagerServer实现见 plugin.ts核心方法如下。send()单渠道下发签名与示例源自 API 参考send({ channelName: in-app-message, message: { receivers: [1, 2, 3], receiverType: userId, content: 站内信测试, title: 站内信测试标题, }, triggerFrom: workflow, });发送参数SendOptions定义见 types.ts说明属性类型描述channelNamestring渠道标识渠道表中的namemessageobject消息对象支持模板变量发送前会结合data编译triggerFromstring触发来源会记录到日志如workflow、sendToUsersreceivers?ReceiversType接收人目前支持两种格式data?object用于编译消息模板的上下文数据transaction?Transaction可选传入事务时将在事务提交后再触发发送接收人ReceiversType仅支持两种格式type ReceiversType | { value: number[]; type: userId } // NocoBase 站内用户 ID | { value: any; type: channel-self-defined; channelType: string }; // 渠道自定义格式如邮箱地址sendToUsers()多渠道批量下发当需要同时通过多个渠道通知同一批用户时可直接调用sendToUsers见 manager.tsawait notificationServer.sendToUsers({ userIds: [1, 2, 3], channels: [in-app-message, email], message: { title: 公告, content: 系统将于今晚升级 }, data: {}, });其内部会为每个渠道分别构造send()调用triggerFrom固定为sendToUsers并通过Promise.all并行下发。发送链路队列、直发与日志从 manager.ts 的实现可以梳理出完整的发送编排逻辑事务感知若调用方传入了事务且事务尚未提交则注册afterCommit回调事务提交后才真正触发发送保证“业务成功才通知”队列判定通过shouldUseQueue检查渠道类型注册时的useQueue标记默认true决定走消息队列异步发送还是sendNow直发入队/直发走队列时调用app.eventQueue.publish发布到${pluginName}.send通道直发时调用sendNow统一留痕sendNow中完成消息模板编译compile、渠道实例化new Channel(app)、instance.send()调用与日志写入发送结果统一为{ status: success | failure, reason?, message }。需要说明的是渠道类型注册时的useQueue默认开启且若渠道不存在也会回退到队列模式当调用方需要立即得到发送结果如工作流节点的“测试发送”时可使用sendNow()。扩展自定义通知渠道短信 / App 推送 / 钉钉 / 飞书NocoBase 支持按需扩展通知渠道类型例如为系统接入短信网关、App 推送等。完整开发流程见 扩展通知渠道类型这里梳理其核心步骤。第一步创建插件执行创建插件命令yarn pm add nocobase/plugin-notification-example第二步客户端开发配置表单客户端需要为渠道提供两个表单组件ChannelConfigForm渠道配置表单收集渠道参数例如短信平台的 API key 与 secret。组件基于SchemaComponent以 JSON Schema 形式描述表单字段MessageConfigForm消息配置表单配置接收人receivers与消息内容content组件接收variableOptions变量参数通常需要消费工作流节点变量接收人输入框使用Variable.Input内容使用Variable.RawTextArea。然后在插件load()中调用客户端内核的registerChannelType注册import PluginNotificationManagerClient from nocobase/plugin-notification-manager/client; class PluginNotificationExampleClient extends Plugin { async load() { const notification this.pm.get(PluginNotificationManagerClient); notification.registerChannelType({ title: Example SMS, // 渠道类型显示标题 type: example-sms, // 渠道类型标识 components: { ChannelConfigForm, // 渠道配置表单 MessageConfigForm, // 消息配置表单 }, }); } }客户端注册参数registerTypeOptions完整说明type registerTypeOptions { title: string; // 渠道显示标题 type: string; // 渠道标识 components: { ChannelConfigForm?: ComponentType; // 渠道配置表单组件 MessageConfigForm?: ComponentType{ variableOptions: any }; // 消息配置表单组件含接收人 ContentConfigForm?: ComponentType{ variableOptions: any }; // 内容配置表单组件仅消息内容不含接收人 }; meta?: { // 渠道配置元信息 createable?: boolean; // 是否支持新增渠道 editable?: boolean; // 渠道配置是否可编辑 deletable?: boolean; // 渠道配置是否可删除 }; };第三步服务端开发发送逻辑服务端核心是继承抽象类BaseNotificationChannel并实现send方法import { BaseNotificationChannel } from nocobase/plugin-notification-manager; export class ExampleSever extends BaseNotificationChannel { async send(args): Promiseany { // 这里实现调用第三方短信网关的真正发送逻辑 console.log(ExampleSever send, args); return { status: success, message: args.message }; } }BaseNotificationChannel的抽象定义源自 API 参考export abstract class BaseNotificationChannelMessage any { constructor(protected app: Application) {} abstract send(params: { channel: ChannelOptions; message: Message; }): Promise{ message: Message; status: success | fail; reason?: string }; }随后在服务端插件load()中调用内核的registerChannelType注册服务端实现import PluginNotificationManagerServer from nocobase/plugin-notification-manager; import { Plugin } from nocobase/server; import { ExampleSever } from ./example-server; export class PluginNotificationExampleServer extends Plugin { async load() { const notificationServer this.pm.get(PluginNotificationManagerServer) as PluginNotificationManagerServer; notificationServer.registerChannelType({ type: example-sms, Channel: ExampleSever }); } }注册签名registerChannelType({ type, Channel, useQueue? }: { type: string; Channel: BaseNotificationChannel; useQueue?: boolean })其中useQueue表示是否通过消息队列异步发送默认true见 types.ts。第四步注册启用并验证yarn p add nocobase/plugin-notification-example # 注册插件 yarn pm enable nocobase/plugin-notification-example # 启用插件完成后即可在通知管理的渠道页面看到新渠道类型如Example SMS新增渠道 → 新增工作流并配置通知节点 → 触发工作流执行此时服务端控制台会输出send方法中的日志验证整个链路已打通。小结NocoBase 通知管理以“渠道”为核心抽象将渠道配置、发送编排、日志记录沉淀为统一内核向下对接站内信、SMTP 邮件、企业微信等具体渠道向上通过工作流通知节点与编程式send()/sendToUsers()两种方式供业务调用对开发者而言通过继承BaseNotificationChannel并调用registerChannelType即可在半小时内接入任意第三方通知服务。无论是普通业务用户还是插件开发者都可以从本文对应的三份文档入手深入实践渠道使用总览、API 参考、渠道扩展指南。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考