1.核心概念
整套系統只有四個名詞，先把它們分清楚，後面都好懂：
| 名詞 | 是什麼 |
|---|---|
| topic | 一條具名的訊息流，例如 orders、chat。發布與訂閱都以 topic 為單位。topic 屬於你的租戶，彼此隔離。 |
| 訊息 | 一段由你決定格式的內容，通常是 JSON。平台不解讀內容，只負責可靠投遞，並保存到保留期結束。 |
| 房間(room) | topic 內部的分流標籤，例如把 chat 一個 topic 切成 room-42、room-43。讓「房間數」不必等於「topic 數」。 |
| 金鑰 / token | 呼叫平台的憑證。長期 API 金鑰放伺服器端；瀏覽器只拿由你後端換發的短期 token。 |
不用先設計佇列、交換機或綁定規則；建立一個 topic 就能開始發布。
2.四種收訊方式
同一條 topic 可以同時被多種方式消費。差別在「誰主動」與「連線活多久」:
| 方式 | 適合 | 要注意 |
|---|---|---|
| 長輪詢（poll） | 後端服務、批次處理、Node 22 以前的環境。用消費群組記錄進度，重啟後可繼續接收。 | at-most-once：位移在取回時就提交；若回應在網路上遺失，該批訊息無法取回。它會接收整條 topic（firehose），不能只收某個房間。 |
| SSE | 瀏覽器即時顯示。瀏覽器原生 EventSource 自帶重連，不裝任何套件也能接。 | 單向，只收不發；發布仍走一般 HTTP。 |
| WebSocket | SSE 被中間裝置擋掉時，或你本來就有 WebSocket 基礎建設。 | 瀏覽器原生 WebSocket 不會自動重連；官方 SDK 已處理退避與 token 更新。 |
| Webhook | 希望由平台主動呼叫你的 HTTPS 端點，不維持長連線。 | 目的位址必須是公開可達的 HTTPS；指向內網會被阻擋（見下方說明）。端點暫時不通會自動重試；404 等重送也無法解決的狀態碼不會重試，而是直接進入死信佇列。 |
3.投遞保證：至少一次、續傳、去重
這一節是整份文件最值得讀完的部分，因為它決定你的程式要不要處理重複。
適用範圍：這一節談的是 SSE、WebSocket 與 Webhook。長輪詢不在此列；它會在取回時提交位移，屬於 at-most-once。若回應在網路上遺失，該批訊息不會補送。需要避免漏訊時，請使用 SSE 或 Webhook。
至少送達一次（at-least-once）。訊息不會因為接收端斷線而遺失，但可能重複送達。重新連線時，伺服器會從上次看到的位置往後補，邊界上可能再次送出少數已看過的訊息。
續傳靠游標。每一則訊息都帶一個 <分割>-<位移> 形式的游標（單調遞增）。你的 client 記住最後看到的那一個，重連時帶回去，伺服器就從那裡接上；斷線期間漏掉的會被補回來，而不是消失。
去重是 client 的事，但 SDK 已經幫你做了。官方 SDK(JavaScript 與 Python)會依游標逐分割去重：位移不大於「該分割已經看過的最大值」就跳過。所以用 SDK 的話，你的 onMessage 收到的就是不重複的訊息。
補不完整時會明確通知。如果斷線太久，超出伺服器的重播窗，伺服器會送出 msgmesh-resync 訊號。此時需從你的業務系統重建狀態；平台不提供快照儲存或快照 API。重建後的即時訊息仍會依 cursor 去重。
順序。同一個 partition 內會維持發布順序。需要讓一組訊息嚴格有序時，請使用同一個 room；room 也是 partition key。
4.憑證：伺服器端金鑰 vs 瀏覽器短期 token
長期 API 金鑰只放伺服器端。它建立時只會以明文顯示一次，之後平台只存雜湊。別提交進版控、別寫進日誌。
不要把 API 金鑰放進瀏覽器。前端程式與網路請求都可能被查看。正確做法是使用 token-broker：由後端保管金鑰，呼叫 POST /v1/tokens 換取短期、降權的 token 給前端。官方 SDK 支援此模式；提供取得 token 的 callback 後，SDK 會處理快取、到期前更新與重連換新。
權限分兩層。角色鍵有 admin / producer / consumer；需要更細就用能力鍵，直接寫明「哪些操作 × 哪些 topic × 哪些房間」。降權時只能變窄，越權會被拒絕(403)。
5.房間：路由與隔離
房間有兩層，分清楚很重要，因為只做第一層沒有安全性:
① 路由（過濾）。發布時帶上 room，訂閱時指定 room，就只會收到該房間的訊息。不指定 room 時，會接收整條 topic，以維持向後相容。
② 隔離(平台強制)。在憑證的能力裡寫明允許的房間，平台就會強制它只能收發那些房間，越界回 403。
6.錯誤與狀態碼
非 2xx 一律回 {"error": "..."};SDK 會依狀態碼丟出可用 instanceof 判別的型別。
| 狀態 | 意思 | 你該怎麼做 |
|---|---|---|
400 / 422 | 參數或內容不合法 | 修請求。重試沒有意義。 |
401 | 憑證無效或已不存在 | 終態。重新取得憑證，不要無限重試。 |
403 | 權限不足，或帳務停權 | 部分情況可恢復，例如加值後自動解除帳務停權；可退避後重試。 |
404 | 資源不存在 | 檢查名稱；若開了嚴格 topic 閘門，未建立的 topic 也會是 404。 |
429 | 超出速率限制或免費含量；含量以 message operations 計 | 退避後重試；若持續發生，請考慮升級方案。 |
500 類回應會附一個 request_id，回報問題時附上它可以直接定位。
7.三分鐘接上
在面板註冊並建立一把金鑰；明文只會顯示一次。接著安裝 SDK：
npm i @msgmesh/sdk # JavaScript / TypeScript
pip install msgmesh # Python（同一組 API，使用 snake_case）import { MsgMesh } from "@msgmesh/sdk";
const mq = new MsgMesh({
apiKey: process.env.MSGMESH_KEY, // 長期金鑰，只放伺服器端
controlPlaneUrl: "...", gatewayUrl: "...", realtimeUrl: "...",
});
await mq.createTopic("orders");
await mq.publish("orders", { hello: 1 });
const msgs = await mq.poll("orders", { group: "g1" });不用 SDK 也可以，一切都是普通 HTTP：帶 Authorization: Bearer <金鑰> 呼叫對應端點即可，格式見 API 參考 ↗。
8.給 AI agent 用(MCP)
MsgMesh 提供官方 MCP server。支援 MCP 的 AI 工具（例如 Claude Code）可直接把事件流當成輸入來源：agent 透過 watch_topic 等待事件，新訊息到達後再進行處理。
npx @msgmesh/mcp-server # 只需要設 MQ_API_KEY這種方式由事件觸發，不必讓 agent 每分鐘輪詢，也不會因輪詢間隔漏掉中間發生的事件。
9.評估與計費 FAQ
MsgMesh 與自己建 Kafka 的差別是什麼？
MsgMesh 底層使用 Kafka，但把叢集維運、HTTP 與即時接入、Webhook 重試與死信、短期 token 和 MCP Server 一起託管。如果你需要控制 broker、跨區拓樸或自訂串流處理，自己建 Kafka 比較合適；如果你的目標是讓應用快速交付事件，MsgMesh 省下的是這一整層產品化工作。
SSE 斷線後會漏事件嗎？
在保留期與單次 5,000 則重播上限內，SSE 會從 cursor 補回。超過界線時會收到 msgmesh-resync，應用必須從自己的業務系統重建狀態；MsgMesh 不提供快照。
Webhook 失敗後怎麼處理？
暫時性失敗會自動重試；明確不應重試的狀態碼會直接進死信佇列。重試用盡的投遞也會進死信，可在面板查看並重放。死信只處理 Webhook 投遞失敗。
message operations 怎麼計費？
每 16 KiB 為一個大小單位，向上取整。operations = 大小單位 ×（1 次發布 + 每一次計費投遞）。歷史查詢與管理操作不計。超額預設關閉，只有先有可用餘額並在面板明確開啟後才會計費。
公開 Beta 可以放正式服務嗎？
目前沒有 SLA，部署在台灣單一機房且 Kafka 為單副本。磁碟或 broker 故障可能永久遺失仍在保留期內的訊息。可以用於能自行容錯的工作負載；若事件直接影響付款、庫存或其他核心交易，請先評估是否符合風險要求。