Novu 3.19.0 介绍与选型指南

目标：讲清开源通知基础设施平台 Novu 的定位、架构、功能与选型方法，并给出与同类产品的对比结论。本文版本信息于 2026-10-21 通过 GitHub releases 实查（最新平台稳定版 v3.19.0，2026-08-07 发布），并在 Ubuntu 22.04 服务器上以官方 Docker Compose 发行形态部署 3.19.0 版实测通过（部署细节见 《Docker Compose 部署 Novu 指南》）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• 实测组件：Novu v3.19.0（官方 Docker Compose 发行形态，镜像 ghcr.io/novuhq/novu/api:3.19.0 等 4 个业务镜像 + mongo:8.0.17 + redis:alpine）
• 依赖服务：MongoDB 8.0、Redis（alpine 最新）、S3 兼容存储（官方 compose 默认留空，按需自备）
• 版本实查方法：curl -sS -x http://192.168.1.62:7897 -L https://github.com/novuhq/novu/releases.atom，查询日期 2026-10-21
• 参考站内文档：《Docker Compose 部署 Novu 指南》、《Novu 3.19.0 配置参数详解》、《Novu 3.19.0 API 使用详解》

二、软件概述

2.1 Novu 是什么

Novu（GitHub novuhq/novu，主仓库以 TypeScript/Node.js 编写）是一个开源的通知基础设施平台（Notification Infrastructure），而非单一推送服务。它解决的核心问题是：应用系统需要同时对接 Email、SMS、Push、Chat（Slack/Discord 等）、In-App 收件箱等多种通知渠道，每接一个渠道就要写一遍服务商适配、模板管理、用户偏好、频控与重试逻辑。Novu 把这一整层抽象成平台能力：

• Workflow 引擎：把一次「通知」定义成多步骤工作流（In-App → Digest → Email 的编排序列），步骤间可插入延时、摘要合并、节流等控制节点；
• 多渠道 Provider 体系：内置 SendGrid/Mailgun/SMTP、Twilio/Vonage、FCM/APNs、Slack/MS Teams 等数十个渠道服务商适配，切换服务商只改集成配置不改业务代码；
• Subscriber / Preferences / Tenant 模型：订阅者、偏好设置（全局与按工作流粒度的渠道开关）、多租户上下文都是一等公民，用户级「不想收营销邮件」这类需求由平台承接；
• In-App 收件箱（Inbox）：自带应用内通知中心组件（@novu/react 提供 Inbox React 组件）与配套 feed/已读/归档 API，配合 WebSocket（ws 服务）实时推送；
• REST API 与 Web 管理台：所有能力既可通过 API 调用，也可在 Dashboard 上以可视化方式编辑 workflow。

💡 技术拓展：「通知基础设施」与「推送服务」的区别不止是功能多少。业界同类产品可分三类，定位差异直接决定选型——

类型	代表产品	解决的问题	典型场景
单一推送服务	Gotify、ntfy	把一条消息推到一个手机/桌面/群组	个人服务器告警推送、家庭自动化通知
通知编排平台	Novu、Courier、Knock	面向应用的多渠道通知编排、模板与用户偏好管理	SaaS 产品的用户通知中心、电商订单通知
消息队列/事件总线	RabbitMQ、NATS	进程间异步消息传递	系统解耦、事件驱动架构

Novu 属第二类：它站在「业务系统 → 终端用户」这一层，而 Gotify/ntfy 站在「系统事件 → 接收端」这一层。

2.2 许可与商业模式

Novu 采用 GPL-3.0 许可（服务端） 的 open-core 模式：社区版（Community）可自由自托管全部核心能力；商业版（Novu Cloud/企业版）额外提供 SSO、RBAC、邮件打开率追踪、合规认证等。自托管版与云版使用同一套 API Reference，差异仅在把 API 地址指向自己部署的域名。自托管社区版不支持 GitHub/Google 等社交登录，账号需用邮箱+密码（官方 self-hosting 文档明确说明）。部分云版独有功能（如部分 Inbox 高级特性）在自托管环境不可用，官方提供 Community 与 Cloud 的功能对照页。

2.3 版本演进与查询方法

Novu 0.x 时代（2022-2023）以 @novu/node 单包形态流行；2024 年重构后进入 1.x/2.x，2025 年发布 v3 系列。v2/v3 与 v0 的 API 与数据模型差异很大（v0 的 /v1/events/trigger 带 name+payload 的旧契约在 v2 中大部分端点迁移到 /v2 前缀、模板变量改用 {{payload.xxx}} 命名空间），网上旧教程不可直接照搬。

版本实查命令（2026-10-21 实测回显）：

# 拉取官方 releases atom 源并提取平台级 tag（npm 子包发布如 @novu/framework@vX 不算平台版）
curl -sS -x http://192.168.1.62:7897 -L https://github.com/novuhq/novu/releases.atom | grep -oE '<title>v[0-9.]+</title>' | head -3

<title>v3.19.0</title>
<title>@novu/react@v3.19.2</title>
<title>@novu/nextjs@v3.19.2</title>

结果说明：截至 2026-10-21，平台级最新 release 为 v3.19.0（发布时间 2026-08-07，重点方向为 AI Agent/MCP 接入、富文本 Chat 卡片、Slack token 轮换等），其后仅有 @novu/react、@novu/nextjs 等前端子包独立发版。本文与同批各篇均以 v3.19.0 为版本基准。

2.4 官方发行形态

Novu 官方自托管发行形态是 Docker Compose 全家桶：api（REST API）、worker（任务执行）、ws（WebSocket 实时推送）、dashboard（Web 管理台）4 个业务服务 + mongodb + redis 2 个依赖服务，官方 setup 脚本从仓库 next 分支拉取 docker-compose.yml 与 .env.example 一键部署。官方文档同时给出 Kubernetes（Helm Chart）方案与多 VM 拓扑建议。完整的部署过程、端口规划与验证命令见 《Docker Compose 部署 Novu 指南》。

三、核心架构

3.1 服务拓扑

官方 Compose 形态下，Novu 由 6 个容器服务组成，实测 docker compose ps 拓扑如下（服务名、镜像与健康状态均为 3.19.0 实测）：

api         ghcr.io/novuhq/novu/api:3.19.0     Up (healthy)   8148->3000
dashboard   ghcr.io/novuhq/novu/dashboard:3.19.0  Up (healthy)  8150->4000
mongodb     mongo:8.0.17                        Up (healthy)   27017（仅内网）
redis       redis:alpine                        Up (healthy)   6379（仅内网）
worker      ghcr.io/novuhq/novu/worker:3.19.0   Up (healthy)   3004（仅内网）
ws          ghcr.io/novuhq/novu/ws:3.19.0       Up (healthy)   8149->3002

各服务职责：

• api：对外 REST API（/v1 与 /v2 两套前缀），承载认证、workflow 管理、subscriber 管理、事件触发入口；依赖 MongoDB（数据）与 Redis（队列与缓存）。
• worker：BullMQ 队列消费者，执行通知的实际投递动作——调渠道服务商 SDK、处理 digest 合并、延时、重试；同样依赖 MongoDB+Redis。
• ws：WebSocket 网关，为 Inbox 收件箱组件提供实时消息推送（ws_socket_queue 队列）。
• dashboard：Web 管理台（React/Vite 构建产物），供编辑 workflow、管理集成与订阅者。
• mongodb：唯一持久化主存储（workflow 定义、subscriber、message、notification、preference 等全部集合）。
• redis：BullMQ 任务队列（默认 db2）+ 可选缓存（REDIS_CACHE_SERVICE_HOST 配置后启用 Inbox feed 缓存）。

3.2 一次通知的完整链路

以实测「订单发货 In-App 通知」为例，数据流为：

1. 业务系统 POST /v1/events/trigger（ApiKey 认证），api 侧做工作流解析与 payload 校验，产出 transactionId 并投递队列（实测回显 {"data":{"acknowledged":true,"status":"processed","transactionId":"txn_6ad8c961wo49me5f0qna"}}）；
2. worker 从队列取出 job，按 workflow 步骤逐个执行（in_app 步骤直接落 MongoDB messages 集合并向 ws 队列广播；email/sms 步骤调对应 Provider 的 API）；
3. 终端侧两种获取方式：Inbox 组件经 ws 服务实时收到推送，或轮询 GET /v1/subscribers/{subscriberId}/notifications/feed（实测 totalCount 与消息体、渲染后的内容 订单 SO-2026-1021 已发货，请查收 均正确返回）；
4. 用户已读/归档动作经 POST /v1/subscribers/{subscriberId}/messages/mark-as 等端点回流（实测 unseen 计数 1→0）。

3.3 关键领域模型

• Organization → Environment → ApiKey：注册后自动生成 Development/Production 两个环境，每个环境独立 ApiKey（实测注册后 GET /v1/environments 返回 dev/prod 两环境及各自 apiKeys）；
• Workflow（v2）：workflowId + steps[]，步骤类型小写枚举 in_app / email / sms / push / chat / delay / digest / throttle / custom / http_request，每个步骤的展示内容由 controlValues 承载（模板变量走 {{payload.xxx}}、{{subscriber.xxx}} 命名空间）；
• Subscriber：以业务侧 subscriberId 为主键的用户实体，携带 email/phone/locale/channel 凭证等；
• Preference：subscriber 级通知偏好，含 global（全渠道开关）与按 workflow 的 workflows[] 粒度（实测返回结构见 《Novu 3.19.0 API 使用详解》）；
• Topic：订阅分组广播模型（/v2/topics），向 topic 触发即对全部订阅者 multicast；
• Tenant：多品牌/多项目隔离上下文，触发时可携带，用于同一部署内区分通知归属。

四、功能特性

• 多渠道编排：10 类步骤（含 In-App、Email、SMS、Push、Chat、延时、摘要、节流、自定义、HTTP 请求）自由编排，同一 workflow 内多渠道并发或串行；
• 摘要与频控：digest 步骤支持把窗口期内的多条通知合并为一条（如「每小时汇总一次未读」）；throttle 步骤做频次节流；
• 用户偏好：subscriber 可按全局/工作流/渠道三粒度关闭通知，触发时平台自动过滤；
• In-App 收件箱：官方 React 组件（@novu/react 的 <Inbox>）+ feed/unseen/mark-as/archived 全套 API + WebSocket 实时性；
• 模板变量与多语言：内容模板支持 {{payload.*}} 插值、payloadSchema 入参校验；v3 引入翻译（translations）能力；
• Web 管理台：可视化 workflow 编辑器、集成管理、订阅者浏览、消息日志（Activity Feed）排查；
• 多 Provider 适配：Email（SendGrid、Mailgun、SES、SMTP 等）、SMS（Twilio、Vonage 等）、Push（FCM、APNs）、Chat（Slack、MS Teams、Discord 等）开箱即用，切换只改集成配置；
• 可观测与自托管友好：/v1/health-check 暴露 DB/队列/版本状态（实测返回 apiVersion: 3.19.0）；IS_SELF_HOSTED=true 环境变量体系把全部云依赖参数化。

五、快速开始（最小可用示例）

本节给出 3 条命令验证一套自托管 Novu 的可用性，全部为 3.19.0 实测回显（部署全流程见 《Docker Compose 部署 Novu 指南》）。

# 1. API 健康检查（api 服务端口按部署实际为 8148）
curl -sS http://192.168.146.128:8148/v1/health-check

{"data":{"status":"ok","info":{"db":{"status":"up"},"workflowQueue":{"status":"up"},"apiVersion":{"version":"3.19.0","status":"up"}},"error":{},"details":{"db":{"status":"up"},"workflowQueue":{"status":"up"},"apiVersion":{"version":"3.19.0","status":"up"}}}}

# 2. 用环境 ApiKey 触发一条 In-App 通知（workflow 与 subscriber 需先按 API 文档创建）
curl -sS -X POST http://192.168.146.128:8148/v1/events/trigger \
  -H 'Authorization: ApiKey 16c57f0a2dc1df7fe7ad4efc6fe3a5ee' \
  -H 'Content-Type: application/json' \
  -d '{"name":"order-notify","to":{"subscriberId":"user-001"},"payload":{"orderId":"SO-2026-1021"}}'

{"data":{"acknowledged":true,"status":"processed","transactionId":"txn_6ad8c961wo49me5f0qna"}}

# 3. 查询订阅者收件箱，确认消息已落地并完成变量渲染
curl -sS 'http://192.168.146.128:8148/v1/subscribers/user-001/notifications/feed' \
  -H 'Authorization: ApiKey 16c57f0a2dc1df7fe7ad4efc6fe3a5ee'

{"data":[{"subject":"订单通知","channel":"in_app","content":"订单 SO-2026-1021 已发货，请查收","seen":false,"read":false,"status":"sent","transactionId":"txn_6ad8c961wo49me5f0qna","payload":{"orderId":"SO-2026-1021"},"createdAt":"2026-10-21T14:17:05.490Z"}],"totalCount":1,"hasMore":false,"pageSize":10,"page":0}

三步回显即验证了「触发 → 投递 → 落地 → 渲染」全链路。API 各域的认证方式、参数表与错误码实测见 《Novu 3.19.0 API 使用详解》。

六、适用场景与限制

6.1 适用场景

• SaaS/电商应用的通知中心：需要 In-App 收件箱 + Email 兜底 + 用户偏好管理的组合，Novu 是最贴合的形态；
• 多渠道统一接入：业务侧只想写一次 trigger 调用，由平台决定走邮件还是短信还是站内信；
• 告警分发与摘要：配合 digest/throttle 做「聚合后推送」，避免告警风暴刷屏；
• 多租户/多品牌通知：tenant + environment 模型天然支持一套部署服务多条业务线。

6.2 当前限制（3.19.0 自托管实测）

• In-App 渠道开箱即用，Email/SMS/Push 需自备服务商凭证：自托管环境没有云版的内置发送额度，必须自己创建 SendGrid/Twilio 等集成；
• Topic 广播在 3.19.0 自托管版存在实测异常：to: {"topicKey": ...} 触发返回 processed 但消息不落地（api 日志确认已投递 Workflow 队列、worker 无消费记录、MongoDB 无对应 notification/job 记录；单发与 bulk 正常）。生产使用前应以自己的版本实测验证该路径；
• S3 存储依赖：官方 compose 未内置 S3/localstack 服务，附件/大内容存储需自行提供 S3 兼容端点；
• 资源占用不低：4 个 Node 服务 + MongoDB + Redis 的全家桶，官方建议单机部署至少 4 vCPU/8GB RAM（Novu 服务）+ 2GB RAM（MongoDB）+ 2GB RAM（Redis），远高于 Gotify/ntfy 级别；
• v0 → v2/v3 迁移成本：旧版 API 契约不兼容，存量 v0 用户需走官方迁移路径（官方提供 v0→v2 Dashboard 迁移文档）。

七、同类选型对比

7.1 站内已实测同类组件对比

关键差异：Gotify 与 ntfy 回答的问题是「如何把一条消息推到我的手机」，部署一个无依赖二进制即可；Novu 回答的问题是「我的应用如何把通知发给成千上万的终端用户，并且让他们能管理自己想收什么」。二者不是替代关系——常见组合是业务侧用 Novu 编排，其中某个自定义渠道（http_request 步骤）把告警再转发到 Gotify/ntfy。

7.2 云端商业竞品对比

选型建议：对数据主权有要求、有 MongoDB/Redis 运维能力、需要深度定制渠道逻辑的团队选 Novu 自托管；无运维投入、接受数据出域、追求开箱即用的团队选商业 SaaS（Courier/Knock）；个人与小团队的「系统推手机」场景直接选 Gotify 或 ntfy（见上表站内实测篇），不必引入 Novu 的重量级全家桶。

八、参考链接

• 官方仓库：https://github.com/novuhq/novu
• 官方自托管文档（Deploy with Docker）：https://docs.novu.co/community/self-hosting-novu/deploy-with-docker
• 官方 API Reference（OpenAPI 3.0 规范）：https://docs.novu.co/openapi.json
• Releases 列表：https://github.com/novuhq/novu/releases
• 站内同批文档：《Docker Compose 部署 Novu 指南》、《Novu 3.19.0 配置参数详解》、《Novu 3.19.0 API 使用详解》
• 站内同类组件实测：《Gotify 3.1.1 介绍与选型指南》、《ntfy 2.32.0 介绍与选型指南》