多租戶 IM 整合服務 · 設計與契約

Babao IM 服務契約

呼叫端 POST 一則領域無關的訊息,服務 fan-out 到該 topic 的訂閱者。 呼叫端永遠拿不到 channel 憑證,只有一把 API token —— 這是這個服務存在的主要理由。

BASE https://babao-im-service.selfcloud.workers.dev RUNTIME Cloudflare Workers · D1 · Queues CHANNELS LINE · Telegram

這一頁是這個服務的單一參考:設計模型在前,API 契約在後。 閱讀慣例貫穿全篇 —— 襯線體是「為什麼」(設計理由與取捨), 無襯線體是「是什麼」(規格),等寬體是字面值(路徑、代碼、JSON)。 這裡寫的行為不會在沒有預告的情況下改變;沒寫的一律不保證。

為什麼存在

每個專案各自持有 LINE access token 與 Telegram bot token 時,憑證外洩的爆炸半徑是「所有專案」。 把憑證收攏到一個服務之後,新增一個專案就是發一把 token, 而那把 token 送不出任何東西給它範圍以外的人,也永遠看不到憑證本身。

第二個理由是領域無關。訊息契約是 {title, lines, link}, 服務不理解訊息在講什麼,也不得依內容改變投遞行為。一旦長出「股票」「策略」這類欄位, 它就不再是通用的 IM 服務,而是某一個產品的一部分。

邊界

這條線是硬的。它決定了每一次「這個功能該做在哪一邊」的爭論。

服務管

  • 租戶與其隔離
  • channel 憑證(永不外流)
  • recipients 名冊與 profile
  • topic 訂閱狀態
  • fan-out、冪等、投遞紀錄
  • 頻率限制與大量發送的佇列
  • webhook 驗證與名冊維護

呼叫端管

  • 訊息內容與何時發送
  • topic 的命名與意義
  • 自助訂閱介面(LIFF 等)
  • 終端使用者的身分驗證
  • 重試策略
  • 失敗後要不要讓工作流程失敗

「終端使用者的身分驗證」這一條容易被誤放。服務只看得到呼叫端的 service token, 結構上無法確認請求背後是哪一個真人—— 所以自助訂閱介面必須由呼叫端自己驗(例如驗 LINE 的 ID token),不能把 caller token 下放到前端。

資料模型

tenant 隔離的最外層。所有查詢都以它為條件
1 — n擁有
channel line / telegram,持有憑證與 default_topics
1 — n擁有
recipient (tenant, channel, external_id) 唯一
n — nsubscription
topic 自由字串。登記簿是描述性的,不是外鍵

delivery 紀錄橫跨全部:(tenant, topic, dedupe_key, recipient) 是冪等的權威

關係基數強度
recipient → channel 多對一 硬約束。複合外鍵 (tenant_id, channel_id) 加唯一索引,跨租戶的組合在 schema 層級不存在
recipient ↔ topic 多對多 由 subscriptions 建模。取消是標記 cancelled_at 而非刪除,所以「某人在某個時間點該不該收到」可以事後查證
topic ↔ channel 多對多 沒有被建模。經由 recipient 湧現 —— 一個 topic 的收件人可以散在多個 channel

recipient 屬於且只屬於一個 channel。 同一個人在 LINE 與 Telegram 上是兩筆獨立的 recipient,各自訂閱、各自的封鎖狀態。 這不是簡化,是事實:LINE 的 userId 每個 OA 一組,跨 channel 認同一個人在技術上做不到。

認證與範圍

Authorization: Bearer <caller token>

租戶身分只從 token 解析。 服務不接受以 body、query string 或 header 指定 tenant_id,傳了也不會有任何作用。

每把 token 帶一組 allowed_topics,三種比對模式:

模式意義
*該租戶底下所有 topic
tw-stock.*前綴比對,涵蓋 tw-stock.analysis
daily完全相同

萬用字元只在結尾有意義;空字串不是有效模式,不會被當成放行全部。 撤銷即時生效 —— 每次請求直接查資料庫,不快取。

觀察不設限,改變才檢查範圍。 這條原則決定了哪些端點檢查 allowed_topics:讀取類(名冊、訂閱、topic 清單)一律不檢查, 因為看得到誰沒訂閱才能回答「他為什麼沒收到」;寫入類一律檢查, 因為能改變某 topic 的收件範圍,等於一把送不了該 topic 的 token 可以決定那些訊息送給誰。

端點總覽呼叫端可用 5 條

端點用途範圍檢查限流
POST /v1/messages 發送給某個 topic 的訂閱者 檢查 60 / 60s
GET /v1/topics 有哪些 topic、誰在聽、我能送哪些 不檢查 無
PUT /v1/topics 宣告或撤銷一個 topic 檢查 無
GET /v1/recipients 名冊,含不可投遞者與原因(分頁) 不檢查 無
GET /v1/subscriptions 單一使用者目前訂了什麼 不檢查 無
PUT /v1/subscriptions 設定某人對某 topic 的訂閱狀態 檢查 無

另有 POST /v1/webhook/{line|telegram}/{channel_id},那是給 LINE 與 Telegram 呼叫的,不對呼叫端開放;以及 /admin/api/*(22 條),由 Cloudflare Access 保護。

發送

POST /v1/messages 送給某個 topic 目前所有有效訂閱者
{
  "topic": "tw-stock.analysis",
  "dedupe_key": "analysis-daily-2026-09-07",
  "message": {
    "title": "9/7 盤後籌碼",
    "lines": ["外資買超 120 億", "投信連三買"],
    "link": { "text": "看完整報表", "url": "https://analysis.tw-stock.selfcloud.tw/" }
  },
  "overrides": { "telegram": { "text": "*9/7 盤後*", "parse_mode": "MarkdownV2" } },
  "recipients": ["U123abc", "987654321"]
}
欄位必填限制與說明
topic是≤ 200 字元。不在 allowed_topics 內回 403
message.title是≤ 200 字元
message.lines是非空陣列,≤ 100 行,每行 ≤ 2000 字元
message.link否{text, url},url 必須是絕對的 http/https
dedupe_key否≤ 200 字元。省略即不做重複判定
overrides否channel 原生格式,優先於預設渲染
recipients否≤ 500 筆,每筆 ≤ 200 字元。只會縮小範圍

預設渲染

標題、每一行、連結,以換行串接成純文字:

9/7 盤後籌碼
外資買超 120 億
投信連三買
看完整報表: https://analysis.tw-stock.selfcloud.tw/

超過 channel 上限時截斷而非丟棄(LINE 5000 字元、Telegram 4096), 並在回應中 truncated: true。

指名收件者只會縮小範圍

服務是從訂閱者出發做篩選,而不是從指名出發去查人。 前者不可能送給未訂閱者,後者只要漏一個檢查就會 —— 授權邊界因此是結構性的, 不靠記得檢查。被指名卻不在訂閱者中的識別字會出現在 unmatched,並讓整體不算成功。

空陣列是 400 而不是「送給零個人」:算出零個對象幾乎一定是呼叫端的 bug, 靜默回報成功會讓那個 bug 一直看起來像正常運作。省略這個欄位才是「不指名」。

原生格式覆寫

存在時優先於預設渲染,服務不會退回預設——那會讓呼叫端誤以為覆寫已生效。格式不合法時整則請求回 400,不會先送出一部分。

overrides.line     { "messages": [ { "type": "text", "text": "..." } ] }   1–5 則,每則需要 type
overrides.telegram { "text": "...", "parse_mode": "Markdown" }            text ≤ 4096
                                                  parse_mode: Markdown | MarkdownV2 | HTML

chat_id 與 disable_web_page_preview 由服務填入,傳了也會被覆蓋。

冪等

dedupe_key 的權威是投遞紀錄本身,而且是 per-recipient 的:

  • 全部失敗過的請求 → 不佔用 key → 重試會全部重送
  • 部分成功過的請求 → 只扣除已成功者 → 重試只補送未成功的人
  • 省略 dedupe_key → 不做任何重複判定,重送就是再送一次

紀錄保留 90 天,之後相同的 key 不再被視為重複。保留期必須明顯長於你的重試間隔。

狀態碼與原因代碼

狀態碼反映的是投遞結果,不是 HTTP 層的成敗。 判準只有一個:每一位該收到的人,是不是都收到了。

碼意義
200是。每位訂閱者不是這次送達、就是先前已送達。沒有訂閱者也算 200
202收件者超過同步門檻,已排入佇列,本次一則都還沒送出
207否,但至少有人收到,或未送達的原因不是上游故障(被封鎖而略過、指名的人不在訂閱者裡)
502一位都沒收到,且原因全是投遞失敗
{
  "topic": "tw-stock.analysis",
  "dedupe_key": "analysis-daily-2026-09-07",
  "delivered": 12, "failed": 1, "skipped": 2, "already_delivered": 0,
  "unmatched": [], "truncated": false,
  "results": [
    { "recipient_id": "...", "status": "delivered" },
    { "recipient_id": "...", "status": "failed",  "reason_code": "recipient_unreachable" },
    { "recipient_id": "...", "status": "skipped", "reason_code": "recipient_skipped" }
  ]
}
兩個容易誤讀的欄位

202 的 delivered: 0 不是失敗。 那批還沒開始送,另有 queued 表示排入人數。用 dedupe_key 到後台的投遞紀錄追進度。

送達零人時會多一個 topic_registered。 true 代表 topic 是真的、只是沒人訂;false 代表沒有人宣告過這個名字,多半是打錯字。只在零人時查詢,順利的路徑不多付成本。

原因代碼

代碼性質意義
channel_quota_exceeded暫時channel 回報已達發送額度上限
channel_timeout暫時對 channel 的請求逾時
channel_unavailable暫時channel 回 5xx,或連線失敗
channel_unauthorized永久channel 憑證無效或未授權
channel_misconfigured永久本服務設定有問題:憑證解不出來,或該 kind 沒有註冊 adapter
channel_rejected永久channel 拒絕了這則投遞,原因未分類
recipient_unreachable永久使用者已封鎖或帳號失效。該 recipient 會被標記為不可投遞
recipient_skipped—該 recipient 目前被標記為不可投遞,本次略過

channel_rejected 存在的理由是誠實。在它之前,未分類的失敗會被歸成 channel_misconfigured——一個宣稱特定成因的代碼被用在成因未知的地方。 2026-08-12 有一次故障因此把排查引向憑證,花了三輪才發現真正的原因是收件者不存在於該 channel。 現在未分類就是未分類,而真正的線索(channel 回應的狀態碼與原文)留在投遞紀錄裡。

Topic

topic 沒有外鍵、不需要事先註冊。token 範圍允許的前提下, 直接用一個新名字就等於建立了它 —— tw-stock.* 這種 scope 的存在, 就是為了讓 app 自己開新 topic 而不必找人。登記簿因此是描述性的,不是開通手續。

GET /v1/topics 我被授權送哪些、有沒有人在聽
{
  "allowed_topics": ["tw-stock.analysis*"],
  "topics": [
    { "name": "tw-stock.analysis-digest", "registered": true,  "subscribers": 2, "sendable": true },
    { "name": "tw-stock.reports",         "registered": false, "subscribers": 4, "sendable": false }
  ]
}

清單是已宣告 ∪ 實際被訂閱。兩個集合的落差就是訊號:

樣態代表
已宣告、零訂閱者topic 是真的,只是還沒有人訂
未宣告、有訂閱者有人在用一個沒宣告過的名字
在 allowed_topics 卻不在清單裡從來沒有人訂過它。如果你的 app 正在對它發送,那就是在空轉
PUT /v1/topics 宣告或撤銷,回應同 GET
{ "name": "tw-stock.analysis-foo", "registered": true }

兩個欄位都必填,name ≤ 200 字元,registered 必須是布林且沒有預設值。 名字放在 body 不放路徑 —— topic 是自由字串,塞進路徑會多一層編碼問題。

撤銷宣告不會取消任何訂閱。 刪掉一個名字不該讓已經在收的人靜默停收,那是兩個不同的決定。

建議用法

把你在用的 topic 用 PUT /v1/topics 宣告一次,之後看到回應裡的 topic_registered: false 就當成錯誤處理。這比在 CI 對照清單更即時,也不需要額外的部署步驟。

名冊與訂閱

GET /v1/recipients 整份名冊,keyset 分頁
GET /v1/recipients?topic=tw-stock.analysis&channel_id=channel-...&limit=100&cursor=...

{
  "recipients": [{
    "external_id": "U123abc", "display_name": "Raymond",
    "picture_url": "https://...", "deliverable": true,
    "undeliverable_reason": null, "undeliverable_at": null,
    "topics": ["tw-stock.analysis", "tw-stock.reports"]
  }],
  "next_cursor": "MjAyNi0wOS0wM..."
}

limit 預設 100、上限 200,超過回 400 而不是默默降低—— 默默降低會讓你把「回應比 limit 少」誤讀成「沒有更多了」而忽略 next_cursor。 cursor 解不開同樣回 400,不靜默從頭開始。

回應包含不可投遞者並標示原因。濾掉他們會讓你無法解釋「他為什麼沒收到」。

GET /v1/subscriptions?channel_id=&external_id= 單一使用者訂了什麼

回應與 PUT 完全同一個形狀——寫進去什麼,讀回來就是什麼。三種情況要分開處理:

回應情況介面該做什麼
200 topics 有內容在名冊上、有訂閱顯示已勾選的開關
200 topics: []在名冊上、沒訂閱顯示未勾選的開關
404不在名冊上請他先加好友
PUT /v1/subscriptions 設定訂閱狀態
{ "channel_id": "channel-...", "external_id": "U123abc",
  "topic": "tw-stock.analysis", "subscribed": true }

四個欄位都必填;三個字串各 ≤ 200 字元。subscribed 必須是布林且沒有預設值——省略時預設為 true 的話,一個組錯的請求會變成「訂閱」,而訂閱的錯誤方向是把訊息送給不該收的人。

宣告式,不是動詞式。 送的是要的結果,重送同一個請求不產生第二筆。 動詞式介面會逼呼叫端先讀狀態再決定送什麼,而讀與寫之間的空隙在兩個管理員同時操作時會出錯。

不建立 recipient。 指定的組合不存在時回 404。 順手建立的話,一個打錯的識別字會產生一筆在名冊上與真人無異、卻永遠送不到的 recipient。 找不到通常代表對方還沒加好友 —— 而那正是要顯示給操作者的事實。

LIFF 自助訂閱的三層與一個前提

LIFF 前端 → 你的後端 → im-service。 caller token 帶著整個租戶的發送權限,絕不能出現在瀏覽器裡。後端還必須驗 liff.getIDToken(),否則任何人都能拿別人的 userId 改別人的訂閱。

LIFF 的 LINE Login channel 與 OA 的 Messaging API channel 必須在同一個 provider。 不同 provider 的 userId 是不同的值,名冊裡對不上,PUT 會回 404。好消息是這個失敗很大聲,不會默默長出假人。

收訊行為webhook,不對呼叫端開放

POST /v1/webhook/{line|telegram}/{channel_id} —— 這條路徑必須維持公開, 因為 LINE 與 Telegram 的伺服器在公網上。安全性來自驗證,不是來自隱藏。

Channel驗證方式建立名冊標記不可投遞
LINE x-line-signature
HMAC-SHA256,固定時間比較
follow unfollow → unfollowed
Telegram x-telegram-bot-api-secret-token
由服務產生,固定時間比較
/start
my_chat_member → member / administrator / creator
my_chat_member → kicked = blocked
→ left = removed

加入時套用該 channel 的 default_topics。 不可投遞不會刪除訂閱——使用者解除封鎖後重新加入即自動恢復,不需要人工重設。

一般訊息不解讀、不建立 recipient。加入名冊是一個明確的動作, 而兩個平台對每一位私訊使用者都必然先送出加入事件,所以不會因此漏掉任何人。 訂閱指令這類需求屬於呼叫端 —— 指令語彙是產品決定,服務一旦開始解讀訊息內容, 就不再是領域無關的。設定 forward_url 之後原始 payload 會原封轉發給下游自行處理。

運作限制

項目值為什麼是這個值
發送頻率60 次 / 60 秒key 是 token id 而非租戶,同租戶的不同呼叫端互不影響。超限不建立投遞紀錄、不佔用 dedupe_key
同步 fan-out 上限40 人Workers Free plan 每次呼叫 50 個 subrequest,D1 查詢也算。同步路徑約在 43 人斷掉,40 留餘裕。升級 Paid(10,000)後可設到 900
佇列批次10 則 / 次同一 dedupe_key 併成一次 dispatch,一批約 13 個 subrequest。調大會直接吃掉這個保護
佇列訊息保留24 小時Free plan 不可調。consumer 壞掉超過一天那批就沒了 —— 已知代價
投遞紀錄保留90 天屆期清除,之後相同 dedupe_key 不再視為重複
Profile 更新TTL 7 天 · 50 筆/日channel 沒有批次取 profile 的端點,也沒有變更通知,輪詢是唯一手段
訊息長度LINE 5000 · TG 4096超過截斷而非丟棄,並回報 truncated

刻意不做的事

寫出來是為了讓邊界明確,不是待辦清單。這些不是還沒做,是決定不做。

  • 不含領域知識 訊息契約永遠是 {title, lines, link}。需要 channel 的原生表達能力時走 overrides,而不是往契約裡加欄位。
  • 不建立 recipient 只有 channel 的真實事件(加好友、/start、bot 被加進群組)或明確的 provisioning 會建立。bot 本來就無法主動聯繫從未互動過的對象,手動建立只會長出永遠收不到訊息的假人。
  • 不讓呼叫端拿到 channel 憑證 這是這個服務存在的主要理由。憑證只在服務內部從 D1 取出,不進 log、不進投遞紀錄、不進佇列訊息。
  • 不讓呼叫端繞過訂閱 訂閱是授權邊界。後台有一條不看訂閱的直接推播路徑,那條刻意只給 Cloudflare Access 保護的 /admin/,不對持有 caller token 的呼叫端開放。
  • 不重試 暫時性失敗由呼叫端決定要不要重試,而 per-recipient 的冪等機制保證那是安全的。服務自己重試會讓「送了幾次」這件事失去單一答案。
  • 不強制 topic 先宣告 目前如此。等登記簿累積出實際使用狀況,再決定要不要把「未宣告即拒送」變成硬規則 —— 屆時只剩 backfill 與一個開關。

後台與存取模型

/admin/ 有六個分頁:推播、收件者、通道、Topic、API token、投遞紀錄。 後台的推播與呼叫端的 POST /v1/messages 走同一條投遞路徑, 所以冪等、投遞紀錄與不可投遞標記完全一致 —— 後台送的訊息與呼叫端送的在資料上是同一種形狀。

路徑保護方式狀態
/admin/*Cloudflare Access(人)已啟用
/v1/*(webhook 除外)caller API token已啟用
同上Access Service Token(機器)計畫中
/v1/webhook/*簽章 / secret token維持公開

caller token 不是要被取代的東西。tenant_id 只能從它解析出來, 它是路由機制而不只是權限機制 —— Access 是額外的一層,不是替代品。