Metabase 通知后端深度解析Notification 统一模型、投递管道与 GraalJS 渲染管线【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase本文以 Metabase 仓库中的通知后端专家文档.claude/agents/notifications-backend-expert.md为主线结合src/metabase/notification/、src/metabase/channel/等真实源码系统梳理 Metabase 通知系统的完整技术栈统一 Notification 模型payload subscriptions handlers、遗留 Pulse 系统及其迁移路径、Email/Slack/HTTP 三类投递通道、基于 GraalJS 在 JVM 内渲染图表的管线以及 Quartz 驱动的时区感知调度基础设施。读完后你能够独立定位“订阅邮件缺少图表”“通知集中触发压垮 SMTP”这类典型问题并理解新增投递通道所需的完整改造面。1. 通知系统的总体架构Metabase 的通知体系由三套相互配合的子系统构成metabase.notification— 现代统一通知框架Alert、卡片通知、系统事件通知metabase.pulse— 遗留 Pulse 系统目前主要承担 Dashboard 订阅dashboard subscriptionmetabase.channel— 投递通道抽象层与渲染管线邮件、Slack、HTTP webhook。src/metabase/notification/README.md给出了最基础的数据流图------------------- | Subscription | - 何时触发cron / 系统事件 ------------------- | | || NOTIFICATION | | || Execute (payload) v | - 执行查询生成 payload | | || CHANNEL | | || Template Engine v | - 渲染成通道消息 || Destination v | - 投递到收件人 一个 Notification 由三个核心组件构成Payload要发送的实际数据内容Handlers决定 payload 如何渲染、投递到哪里通道 可选模板 收件人列表Subscriptions决定何时发送cron 调度或系统事件触发。README 中还给出了最小可运行的 REPL 示例来自 src/metabase/notification/README.md(require [metabase.notification.test-util :as notification.tu]) (require [metabase.notification.core :as notification]) (notification.tu/with-card-notification [notification {:card {:dataset_query (mt/mbql-query users)} :subscriptions [{:type :notification-subscription/cron :cron_schedule 0 0 0 * * ?}] :handlers [{:channel_type :channel/slack :recipients [{:type :notification-recipient/raw-value :details {:value #general}}]} {:channel_type :channel/email :recipients [{:type :notification-recipient/user :user_id (mt/user-id :crowberto)}]}]}] (notification/send-notification! notification :notification/sync? true))这条语句创建了一个带 1 个 cron 订阅、2 个 handlerSlack 邮件的卡片通知并同步发送是理解整个数据流的最佳入口。2. 统一模型Notification 的五张表从 src/metabase/notification/models.clj 的源码结构看Notification 实体被拆分为五张数据库表全部通过 Toucan2 模型访问模型表名职责:model/Notificationnotification主体持有payload_type、payload_id、active:model/NotificationSubscriptionnotification_subscription触发条件cron 或系统事件:model/NotificationHandlernotification_handler投递通道 可选模板引用:model/NotificationRecipientnotification_recipient收件人:model/NotificationCardnotification_card卡片型 payload 的发送条件2.1 Payload 类型models.clj中定义的合法 payload 类型集合为(def notification-types #{:notification/system-event :notification/dashboard :notification/card ;; for testing only :notification/testing})每种 payload 的执行实现在src/metabase/notification/payload/impl/下card.clj执行卡片查询、dashboard.clj执行仪表盘上所有卡片、system_event.clj系统事件。src/metabase/notification/payload/core.clj 中的payload多方法按:payload_type分派执行执行结果再被notification-payload函数装饰上:creator创建人姓名/邮箱和:context应用名、logo、按钮样式等模板上下文后交给各 handler。对于大型查询结果payload 层提供临时存储payload/temp_storage.clj把结果落盘避免在内存中搬运大结果集。值得注意的是send.clj中的一处注释“:notification/dashboardis still on pulse”——即仪表盘订阅目前仍走遗留 Pulse 代码路径metabase.pulse.send这与专家文档中“Dashboard 订阅是挂在仪表盘上的 Pulse”的描述一致。2.2 Subscription 类型与 Quartz 联动订阅支持两种类型subscription-types:notification-subscription/croncron 表达式调度由 Quartz 调度器管理每个订阅对应一个独立的 trigger详见第 6 节:notification-subscription/system-event系统事件触发如评论创建、Slack 事件、transform 失败等必须携带event_name。模型层通过 Toucan2 的 insert/update/delete 钩子把模型变更与 Quartz trigger 同步define-after-insert/define-before-update调用update-subscription-trigger!删除时调用delete-trigger-for-subscription!均以requiring-resolve动态解析 src/metabase/notification/task/send.clj 以避免循环依赖。另外当 Notification 的:active字段变更时会批量更新或删除其所有 cron 订阅对应的 trigger——这意味着停用一条通知会立即从调度器中摘除其触发器。2.3 Recipient 类型收件人有四种类型notification-recipient-types:notification-recipient/user具体用户user_id:notification-recipient/group权限组permissions_group_id:notification-recipient/raw-value原始值如 Slack 频道名#general或外部邮箱地址details.value:notification-recipient/template模板化收件人details.pattern可选is_optional支持按结果行动态生成收件人。details字段通过transform-encrypted-json加密存储。企业版还在此处叠加了subscription-allowed-domains域名白名单校验validate-raw-value-email-domain!任何写入路径包括未认证的取消订阅恢复端点都无法绕过。2.4 卡片发送条件Alert 条件检查专家文档提到的“alert 风格条件检查”在源码中有两层实现NotificationCard的send_conditionsrc/metabase/notification/models.clj 中定义为#{:has_result :goal_above :goal_below}——卡片查询结果与目标线goal line比较决定“是否发送”默认:send_condition :has_result、:send_once false在 insert 钩子中自动补齐。metabase.notification.conditionsrc/metabase/notification/condition.clj——一个通用的数组表达式求值器支持and/or/not、比较运算符 ! 、context数据访问与count/min/max函数例如[and [, [count, [context, rows]], 0] [, [context, user_id], 1]]需要说明的是该命名空间的文档字符串表明它“原本为 notification conditions 开发目前保留给未来使用”。从源码结构看当前线上 Alert 的实际条件判断主要依赖send_condition枚举值条件表达式求值器是为此保留的可复用基础设施。理解这一点有助于在排查“条件不生效”时正确定位代码路径。3. 发送管道重试、优先级队列与并发控制src/metabase/notification/send.clj 是整条投递管道的核心。入口函数send-notification!接受:notification/sync?选项同步路径直接调用send-notification-sync!异步路径则进入 dispatcher 队列。3.1 同步发送的主流程send-notification-sync!依次完成孤儿 payload 防御卡片通知若其NotificationCard记录已被级联删除则删除该 notification 并抛错避免触发无意义的查询执行收件人域名校验企业版 allow-list执行 payloadnotification.payload/notification-payload生成带上下文的 payload随后notification.payload/skip-reason决定是否跳过如发送条件不满足逐 handler 渲染与发送对每个 handler 调用channel/render-notification多方法按[channel-type payload-type]双键分派得到消息序列再对每条消息调用带重试的channel-send-retrying!任务历史与指标全程包裹task-history/with-task-history与 analytics 指标send-ok/send-error/channel-send-ok/channel-send-error、send-duration-ms、concurrent-tasks等。3.2 通道发送重试策略channel-send-retrying!使用metabase.util.retry实现指数退避重试默认配置default-retry-config为{:max-retries (if config/is-dev? 1 6) ;; dev 环境 1 次生产 6 次 :initial-interval-millis 500 :multiplier 2.0 :jitter-factor 0.1 :max-interval-millis 30000}两个值得注意的细节不可重试错误:slack/invalid-token与:slack/channel-not-found被明确列入unretriable-errorsabort-if会立即终止重试——无效 token 重试 6 次毫无意义重试报告落盘每次重试的错误消息与时间戳累积进retry_errors最终合并进 task history 的task_details这是排查“Slack 间歇性上传失败”的关键审计数据。3.3 双 Dispatcher去重优先级队列 vs 简单阻塞队列异步发送时dispatch!按 payload 类型选择两个不同的线程池 dispatcherdedup-priority-dispatcher卡片/仪表盘通知底层是DedupPriorityQueue——一个按 deadline 排序、按notification id去重的线程安全优先级队列。同一 id 的通知重复入队时只保留最新版本最新的 creator、active 状态、handler 信息更可靠。deadline 由subscription-deadline依据 cron 频率计算平均触发间隔小于 1 分钟的订阅只给 5 秒宽限小于 5 分钟的给 10 秒小于 30 分钟给 15 秒小于 1 小时给 30 秒其余给 60 秒——触发频率越高的通知越容易被判定“过期”而被更新版本顶替避免过期的高频订阅占住工作线程simple-blocking-dispatcher系统事件通知普通ArrayBlockingQueue容量 1000FIFO 处理。线程池大小由 src/metabase/notification/settings.clj 中的 Setting 控制Setting默认值说明notification-thread-pool-size3常规通知发送线程数官方文档建议若长查询堵死通知队列导致 Alert 停发可尝试调大此值notification-system-event-thread-pool-size5系统事件通知线程数notification-temp-file-size-max-bytes1048576010 MiBpayload 落盘临时文件的最大字节数设 0 可禁用限制此外send-notification!会记录:notification/triggered-at-ns元数据同步发送前若触发到实际执行之间产生了等待会通过wait-duration-ms指标上报——这是观察“Quartz 触发 → 队列消化”延迟的直接手段。4. 通道层可插拔的投递抽象src/metabase/channel/core.clj 定义了通道协议的三个多方法命名空间注释标明“API 仍在开发中可能变更”(defmulti can-connect? 检查能否用 details 连接到 channel-type失败时返回/抛出 {:errors {字段 错误信息}} 以便 UI 展示字段级错误。 (fn [channel-type _details] channel-type)) (defmulti render-notification 给定 notification payload返回该 handler 的消息序列 消息格式必须与 send! 期望的格式一致。 (fn [channel-type notification-payload _handler] [channel-type (:payload-type notification-payload)])) (defmulti send! 向通道发送一条消息。 (fn [channel _message] (:type channel)))render-notification用[channel-type payload-type]二元组分派意味着每个通道都要针对每种 payload 类型实现各自的渲染。现有实现在 src/metabase/channel/impl/Emailimpl/email.clj配合channel/email.cljSMTP 发送、HTML 渲染、内联图片CID 引用、CSV/XLSX 附件消息构造集中在channel/email/messages.cljHandlebars 模板位于 src/metabase/channel/email/如dashboard_subscription.hbs、notification_card.hbs、broken_subscription_notification.hbs、card_notification_archived.hbs等 30 余个.hbs文件Slackimpl/slack.clj配合channel/slack.cljSlack API 集成含频道/用户缓存、token 管理、OAuth 流程图表以文件上传方式投递缓存由后台任务 src/metabase/channel/task/refresh_slack_channel_user_cache.clj 周期性刷新HTTP webhookimpl/http.clj把通知 payload 投递到任意 HTTP 端点。模板渲染基于 Handlebarssrc/metabase/channel/template/core.clj、handlebars.clj、handlebars_helper.clj深链回跳地址由channel/urls.clj生成。4.1 新增一个投递通道的检查清单专家文档给出的 7 步流程对照源码结构可细化为在channel/impl/channel.clj中实现can-connect?、render-notification每种 payload 类型各一个方法、send!三组多方法处理认证OAuth、API key 等认证失败时抛出带:error-type的异常以参与重试判定参考 Slack 的:slack/invalid-token模式;按通道格式约束适配渲染输出如 Slack 对附件大小的限制处理图片/附件投递与清理Slack 上传的文件、邮件 CID 内联图都有生命周期问题在channel/settings.clj体系中登记通道配置项接入notification与pulse两条发送管道仪表盘订阅仍走 Pulse不能只接 Notification 一侧用含大仪表盘20 卡片意味着 20 次查询执行与 20 次图表渲染的真实 payload 做压测。对应的测试可参考 test/metabase/channel/ 下的impl/、render/、email_test.clj、slack_test.clj等既有用例。5. 渲染管线从查询结果到 HTML/PNGmetabase.channel.rendersrc/metabase/channel/render/负责把查询结果转换为可视化输出是“邮件里图表丢失”类问题的第一排查现场render/body.clj按可视化类型表格、柱状图、折线图、标量、进度条、漏斗、地图等分派到 HTML 或图片渲染render/table.cljtable_data.clj结果集 → 带样式的 HTML 表格含列格式化、截断、行数上限render/js/GraalJS 图表渲染JVM 内执行与浏览器相同的 static-viz JS 代码产出 SVG 再栅格化为 PNGrender/image_bundle.cljrender/png.clj为邮件内嵌与 Slack 上传准备图表图片包render/preview.clj通知配置 UI 的预览渲染render/style.clj渲染输出的 CSS 与样式。5.1 GraalJS 沙箱池化上下文与共享引擎src/metabase/channel/render/js/graal.clj 是该管线技术上最有趣的部分。其命名空间文档精确描述了当前设计在 JVM 进程内运行 static-viz JS使用最多 3 个沙箱化 GraalVM 上下文的池dirigiste Pool 管理在标准 JDK 上以解释模式运行不启用 Graal 编译器并通过引擎级选项engine.WarnInterpreterOnlyfalse静默警告池中所有上下文共享同一个Engine与同一份已解析的 bundleSource引擎随第一个上下文创建、随最后一个上下文关闭每个上下文把共享 source 求值进自己的 realm。因此无论池扩到几个上下文解析后的 bundle 只保留一份——“把池上限从 1 提到 2 或 3 只需改一行”池的最小值为 0空闲时收缩到 0 并关闭引擎GraalVM 不会在 GC 时回收 context/engine空闲后的首次渲染会重建每次渲染独占一个上下文因此同一上下文上的渲染是串行的。沙箱强度从create-context可见allowHostAccess HostAccess/NONE、类查找谓词恒返回falseno-host-class-lookup、allowIO false——JS 无法触碰宿主类、文件系统所有数据必须以 JSON 字符串传入并在 JS 侧解析。这解释了专家文档的告诫GraalJS 是渲染瓶颈——复杂可视化可能超时或内存吃紧图表渲染失败往往是 JS 上下文问题而非投递问题应先在render/preview.clj层面隔离测试渲染。6. 调度基础设施Quartz Trigger 与时区感知src/metabase/notification/task/send.clj 展示了 Quartz 集成细节Trigger 命名约定每个 cron 订阅对应 key 为metabase.task.notification.trigger.subscription.id的 CronTrigger全部挂在一个持久化的SendNotificationJob 下Job 通过DisallowConcurrentExecution语义与job-data中的subscription-id传递上下文时区send-notification-timezone按优先级取driver/report-timezone报告时区 Setting→ 系统时区 →UTC。报告时区变更时update-send-notification-triggers-timezone!会遍历全部 trigger 并对时区不一致者reschedule-trigger!对应events/report_timezone_updated.clj事件。这正对应专家文档强调的“通知必须在用户时区的正确时刻触发而不是服务器时区”Misfire 策略with-misfire-handling-instruction-fire-and-proceed——即使上次触发错过了如实例重启窗口也要补发一次再继续正常调度Trigger 生命周期管理update-subscription-trigger!按“类型变更 → 删除非 cron → 忽略不存在 → 创建cron 表达式变化 → 删除后重建”的顺序收敛模型层的增删改钩子与它联动启动期自愈InitNotificationTriggers任务在每次实例启动时运行init-send-notification-triggers!对“现有 trigger 集合”与“数据库中 active 的 cron 订阅集合”做 diff删除多余 trigger、补建缺失 trigger。其文档字符串解释了背景Alert 从 Pulse 迁移到 Notification 之后v53.2024-12-12T08:05:00迁移需要在启动时为存量订阅补齐 trigger而由于无法保证“只运行一次”的迁移只好每次启动都跑一遍对账Job 执行日志SendNotificationJob 记录完整的 Quartz 上下文scheduled fire time、实际 fire time、recovering、refire count、scheduler id配合task-history可回答“某次触发为什么晚了/漏了”。task-history体系src/metabase/task_history/为每一次通知执行留存带计时、成败与输出的记录是调试交付失败的第一站。7. 遗留 Pulse 系统与迁移metabase.pulsesrc/metabase/pulse/是通知系统的前身Pulse 模型pulse/models/卡片的定时通道投递Dashboard 订阅即挂在仪表盘上的 Pulsepulse/send.cljtask/按调度执行 Pulse 的发送管道迁移src/metabase/app_db/custom_migrations/pulse_to_notification.clj 将遗留 Pulse 转换为 Notification 记录。从该文件源码看迁移的核心难点之一是调度表达式的转换Pulse 的旧式调度以{seconds minutes hours day-of-month month day-of-week year}键值对 framefirst/last 星期结构存储迁移逻辑负责把星期名映射为 Quartz cron 的1-7sun→1 … sat→7并支持“每月第一个周一”1#1、“每月最后一个周五”6L这类 cron 惯用法。专家文档提醒的迁移边界案例在源码中得到印证多通道 Pulse、每通道独立 schedule、特殊收件人配置都需要逐一映射为 handler recipient 结构同时如第 2 节所述send-notification-sync!对“Pulse 转换来的通知”携带:payload而非:payload_id有专门的孤儿 payload 判定豁免。产品文档侧Dashboard 订阅见 docs/dashboards/subscriptions.mdAlert 见 docs/questions/alerts.md。8. 调试路径与工程实践综合专家文档的调查方法Investigation Approach与源码结构推荐的标准排障顺序是先分辨系统是metabase.notification路径Alert/卡片/系统事件还是metabase.pulse路径Dashboard 订阅notification.send/hydrate-notification对:notification/dashboard的分支处理是两条路径并存的直接证据沿管道定位触发 → payload 执行 → 条件检查 → 通道渲染 → 发送逐段核对 task history 记录notification-trigger、notification-send、channel-send三种 task 各有独立记录渲染问题单独隔离缺图表、格式错误通常与投递无关先用预览渲染render/preview.clj或 REPL 单独渲染该可视化确认是否 GraalJS 上下文超时/内存问题检查外部服务SMTP 日志、Slack API 返回码、webhook 超时注意重试日志中retry_errors的累积报告与“不重试”的 warn 日志无效 token / 频道不存在会直接终止重试调度问题看 Quartztrigger 是否被创建启动 diff 对账、时区是否正确报告时区 Setting、misfire 是否补发。代码质量方面专家文档要求遵循 Metabase 的 Clojure 规范、为可靠性构建重试、错误跟踪、优雅降级、处理外部服务不可用SMTP 宕机、Slack 限流需退避、测试真实 payload、尽可能保证幂等。相关测试入口包括 test/metabase/notification/send_test.clj、models_test.clj、condition_test.clj与 test/metabase/channel/ 下的通道与渲染用例仓库 README 与 docs/developers-guide/devenv.md 描述了开发环境搭建方式可用于在本地 REPL 中复现 payload 执行、单图渲染与 Quartz trigger 状态检查。9. 已知坑位清单Important Caveats专家文档末尾列出的“重要注意事项”几乎都能在源码中找到对应实现可作为设计评审时的对照清单坑位源码对应GraalJS 渲染慢、吃内存复杂可视化可能超时src/metabase/channel/render/js/graal.clj 的池化/解释模式设计邮件 HTML 需要“回到 1990 年代”Outlook/Gmail/Apple Mail 渲染各异必须内联 CSS、用 table 做布局src/metabase/channel/email/ 各.hbs模板Slack 批量发送会撞 API 限流需要正确退避channel-send-retrying!的指数退避 不可重试错误短路Pulse → Notification 迁移的边界案例多通道、分通道 schedule、异常收件人src/metabase/app_db/custom_migrations/pulse_to_notification.clj时区感知调度必须用用户/报告时区而非服务器时区send-notification-timezone与 trigger 时区重建逻辑大仪表盘订阅 N 次查询 N 次图表渲染资源密集去重优先级队列 频率化 deadline 设计图表图片生命周期Slack 上传文件需清理邮件内联图依赖 CID 引用render/image_bundle.clj与 email 附件逻辑小结Metabase 通知后端是一套典型的“模型层Toucan2 多表 malli 校验→ 调度层Quartz per-subscription trigger→ 管道层去重优先级队列 指数退避重试 task history 全量审计→ 通道层三多方法协议 分通道渲染→ 渲染层Handlebars 模板 GraalJS 沙箱图表渲染”的分层架构。其工程亮点在于per-subscription 的 Quartz trigger 让调度变更与模型写操作强一致按 cron 频率动态计算的 deadline 与按 id 去重的优先级队列使高频订阅不会饿死彼此GraalJS 共享 Engine 池化 Context 的设计在内存与并发渲染之间取得了平衡。理解这套结构后无论是修复“邮件缺图”、改造 Slack 通道还是设计新的投递渠道如 Microsoft Teams都有清晰的代码入口与测试参照。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考