事件紀錄
事件紀錄是一條只追加的紀錄,跟贊助帳本分開。帳本回答「這筆訂單有沒有入帳」。事件紀錄回答「疊層與外掛有沒有看到這件事」。
s4n.donation.test 會寫進事件紀錄,讓 OBS 能顯示測試贊助。它不會建立 Donation 列,也不會變成已付款。
表名是 EventLog。遷移檔是 20261118140000_event_log。
| 欄位 | 作用 |
|---|---|
sequence |
BIGSERIAL。單調遞增,刪除之後也不會重用。客戶端把它當成「我看到哪裡」 |
eventId |
事件自己的 id。同一則可能送達超過一次,客戶端用它排除重複 |
type |
例如 s4n.donation.succeeded、s4n.chat.message |
payload |
JSON。不得含金鑰、權杖、密文或主金鑰 |
createdAt |
寫入時間。保留期限用這個欄位 |
donationId |
只有 s4n.donation.* 會填。同一筆贊助、同一種事件只留一列。它不是帳本的外鍵 |
聊天與其他事件的 donationId 是空的。PostgreSQL 的唯一索引把空值當成彼此不同,所以聊天可以一直追加。
送達是至少一次。API 重啟、OBS 斷線、或兩個程序同時處理同一則通知時,客戶端可能再看到同一則。疊層與工作台用事件 id 記住最近看過的 id,第二次不顯示。
斷線後的客戶端帶上最後看到的 sequence(查詢參數 since)再連線。伺服器把序號更大的事件依序補上,數量有上限。預設是 200 則符合這個疊層的事件。超過上限時,這次連線只補最舊的那一段,回應裡的 replayTruncated 會是 true;其餘的仍留在紀錄裡,工作台的「事件紀錄」可以查看,直到保留期限。
第一次打開疊層、瀏覽器裡還沒有序號時,不會把歷史全部播一遍,只從當下的最新序號繼續。這樣新加的 OBS 來源不會突然播出一整週的贊助。
贊助提醒會把補上的贊助排成佇列,一則播完再播下一則,避免一次只剩最後一則。聊天疊層則略過已經在畫面上的訊息 id。
多個 API 程序
Section titled “多個 API 程序”寫入成功後,同一個交易會 NOTIFY s4n_event_log。通知裡只有序號,因為 NOTIFY 的負載上限約 8000 位元組,聊天內容可能更大。每個 API 程序用一條專用連線 LISTEN,收到之後再把那一列讀出來。
若通知在重連的空檔漏掉,每個程序每秒會再依序號把缺口讀一次。所以 v1 不需要 Redis 或 NATS。介面在 apps/api/src/realtime/event-store.ts 的 EventStore。之後若要換成 Redis 或 NATS,實作同一組方法即可,呼叫端不用改。
程序內的訂閱者只收到啟動之後的新事件。重啟不會把舊贊助再混進聊天一次。已經連過的 OBS 則靠自己的序號把錯過的事件補上。
清理是這張表唯一的刪除。序號不會回收。
| 變數 | 預設 | 意思 |
|---|---|---|
S4N_EVENT_RETENTION_DAYS |
7 |
聊天以外的事件留幾天 |
S4N_EVENT_CHAT_RETENTION_HOURS |
24 |
s4n.chat.message、delete、clear 留幾小時 |
S4N_EVENT_CLEANUP_INTERVAL_MINUTES |
15 |
多久清一次 |
S4N_EVENT_REPLAY_LIMIT |
200 |
一次重連最多補幾則 |
聊天可以比贊助短。兩組都是正整數。工作台的事件紀錄會顯示目前的天數與小時。
付款成功若在帳本寫入之後、事件寫入之前被中斷,API 會回 503,讓綠界或歐付寶再通知一次。同一筆贊助的入帳事件只會有一列,所以重送不會讓疊層再響一次。
已經在跑的站:
- 備份 PostgreSQL。
- 拉下這個版本。
- 執行
pnpm db:migrate。正式環境或 Compose 是pnpm db:deploy(prisma migrate deploy)。Compose 的 API 容器啟動時會自己跑。 - 重啟每一個 API 程序。升級前只活在記憶體裡的事件不會補回來,這是唯一一次。
- 不需要新的資料庫、Redis 或別的服務。連線字串仍是
DATABASE_URL。 - OBS 來源保持原網址即可。第一次連上只接最新序號;之後斷線再連,才依序號補送。
登入限流仍在單一程序的記憶體裡,多個 API 不會共用那個計數。Twitch 徽章快取也還在程序裡:它含有短暫的應用程式權杖,重啟後徽章先顯示文字,下一次整理(預設一小時)再補圖。事件紀錄不放這個權杖。
登入後的工作台有「事件紀錄」。它列出序號、時間、類型與一行摘要,並用工作階段連到 /ws/dashboard。摘要不含金鑰。測試贊助出現在這裡,帳本頁不會出現。