A / 外部系統通知
業務事件送到外部系統
訂單、票務或帳務狀態要通知別的系統時,用 Webhook 投遞。失敗自動重試,重試用盡後進入死信佇列,可查看、可重放。
邊界:死信佇列只收 Webhook 投遞失敗;publish 與長輪詢消費失敗不會進去。
託管的持久事件總線 · 人與 AI agent 收到同一批訊息
把事件交付,
從業務程式碼裡拆出來。
發布端只管送出業務事件;保留、控權、重試、斷線補回由平台處理。同一批事件,人用 SSE 或 WebSocket 收,AI agent 用 MCP 訂閱。
無需信用卡 · HTTP、SDK 或 MCP 三種接入方式
事件保留
訊息在保留期內留著,對方沒上線也不會消失,期內可依 cursor 回放。
重試與死信
Webhook 投遞失敗自動重試,重試用盡的單獨進死信佇列,可查看、可重放。
斷線補回
SSE 斷線重連時從同一個 cursor 接上,在有界的重播窗內補回漏掉的訊息。
金鑰權限
一把金鑰限定動作與 topic,支援 room 的接口可再限定房間,越權回 403。
使用場景
事件要去哪裡,決定你用哪一條路
五種常見的事件交付形狀。每一種的邊界寫在卡片裡,不必翻文件才知道限制。
B / 前端即時狀態
前端即時顯示後端發生的事
聊天訊息、任務進度、頁面狀態走 SSE 或 WebSocket 下行。斷線重連時從同一個 cursor 接上,不會有缺口也不會重複。
邊界:WebSocket 是單向下行,上行訊息會被丟棄;SSE 補回受保留期與單次 5,000 則上限約束。
C / AI agent 訂閱
agent 直接訂閱業務事件
agent 透過官方 MCP Server 訂閱事件,不必另外寫一層「事件轉 LLM」的橋接服務。新訊息一到就喚醒它,而不是每隔幾分鐘輪詢。
邊界:MCP 的治理類工具需要 admin scope 的金鑰,而金鑰要先有帳號才簽得出來。
D / 多房間隔離
一個 topic 切成多個互不干擾的房間
同一條事件流用 room 分房,發布與 SSE / WebSocket 訂閱都可限定房間,不必每群開一個 topic。
邊界:HTTP 長輪詢沒有房間概念,一律整個 topic;在線人數是整個 topic 的彙總,不分房間。
E / 最小權限
一把金鑰只開一條路
金鑰可限定動作與 topic;支援房間的接口可進一步限定 room。越權的請求回 403,所以外流的影響範圍就是那一把鑰匙開的那一條路。
邊界:面板 UI 簽不出限定房間的金鑰,那要走 API 或 SDK。
為什麼不自己接 Kafka
你要的是事件交付,不一定是再維護一套 Kafka
底層確實是 Kafka。差別在於下面這六件事由誰來扛。
| 自己接 Kafka | 用 MsgMesh | |
|---|---|---|
| 部署維運 | 自建叢集、監控、升級、擴容 | 託管,不用自己顧 Kafka |
| 重試與死信 | 自己設計退避、落地、重放 | Webhook 投遞失敗自動重試,用盡進死信可重放 |
| 斷線續傳 | 自己記位移、處理重連補齊 | SSE 依 cursor 在有界重播窗內自動補回 |
| 歷史補齊 | 自己另建歷史儲存 | 歷史查詢,再用同一個 cursor 接上即時流 |
| 權限 | 自己做 ACL 與多租戶隔離 | 金鑰可限定動作與 topic;支援 room 的接口可進一步限定 room,越權回 403 |
| AI 接入 | 自己寫一層事件橋接到 LLM | 官方 MCP Server,agent 可直接訂閱 |
room 範圍適用於發布、SSE / WebSocket 訂閱,以及帶 room 的歷史查詢;HTTP 長輪詢以整個 topic 為單位。
快速上手
發出第一則事件
建立 topic,然後發布。兩步要分開執行——topic 已存在時建立那步會回 409,寫在同一段腳本會讓第二次執行中斷在第一行。
首次設置(只執行一次)
curl -X POST 'https://msgmesh-api.alderflux.com/v1/topics' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"name": "orders"}'
日常發布(可重複執行)
curl -X POST 'https://msgmesh-api.alderflux.com/v1/topics/orders/messages' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"orderId": "order_12345", "currency": "TWD", "status": "paid"}'
TypeScript、Python 與 MCP 的完整片段,以及三個服務網址怎麼填,見快速上手。
接收方式與限制
四種接收方式,語義不一樣
| 接收方式 | 投遞語義 | 可用環境 | 備註 |
|---|---|---|---|
| Webhook | at-least-once | 需公開可達 URL | 失敗自動重試,用盡進死信可重放 |
| SSE stream() | at-least-once | 瀏覽器;JavaScript SDK 目前在 Node 不支援 SSE | 斷線在有界重播窗內自動補回 |
| WebSocket streamWs() | at-least-once | 瀏覽器,或 Node 22+ | 單向下行,發布走 HTTP |
| HTTP 長輪詢 subscribe() | at-most-once | Node 與瀏覽器都可 | 位移取回即提交,回應遺失就取不回 |
正式環境請明確指定 consumer group。同一 group 內的消費者會分攤訊息;不同的邏輯訂閱者應各自使用不同 group,避免意外共用 default。
Python 的 WebSocket 需要額外安裝選用依賴,詳細執行環境請見文件。
接入方式
一套事件,三種進、四種出
INGEST
- HTTP API任何後端與既有系統
- SDKTypeScript 與 Python
- MCP Serveragent 直接訂閱與治理
DELIVER
- SSE瀏覽器即時,有界補回
- WebSocket單向下行
- HTTP 長輪詢不維持長連線
- Webhook平台主動打你的端點
Public Beta 產品邊界
先把邊界說清楚,再決定適不適合
投遞語義
不提供 exactly-once。SSE、WebSocket 與 Webhook 為至少送達一次;HTTP 長輪詢為至多一次。請依訊息 id 去重。
單一機房 · RF=1
部署在台灣單一機房,Kafka 單副本。磁碟或 broker 故障,保留期內的訊息可能永久遺失。
SSE 是有界重播
補回受保留期與單次 5,000 則上限約束。超出時會收到 msgmesh-resync,應用需自行從業務系統重建狀態——平台沒有快照。
保留期限
目前免費方案保留 3 天;30 天保留方案尚未在 Beta 開放。不是永久事件儲存。
room 的適用範圍
適用於發布、SSE / WebSocket 訂閱與帶 room 的歷史查詢。HTTP 長輪詢以整個 topic 為單位,在線人數也是整個 topic 的彙總。
死信只收 Webhook
死信佇列只處理 Webhook 投遞失敗。publish 失敗與長輪詢消費失敗都不會進去。
如果事件會直接影響付款、庫存或其他核心交易,請先評估 RF=1 與單一機房是否符合你的風險要求。