登入、外掛與疊層
登入需要 PostgreSQL。沒有資料庫時,畫面與多數測試仍可執行,但建立營運者會失敗。
docker compose up -d postgrespnpm db:migratepnpm dev打開 http://127.0.0.1:5180 。若還沒有營運者,會進到初次設定。
初次設定與登入
Section titled “初次設定與登入”初次設定只會成功一次。它建立第一位營運者,並寫入工作階段 Cookie s4n_session。
- 密碼以 Argon2id 儲存(記憶體 19 MiB、時間成本 2、平行度 1),資料庫裡沒有明文
- Cookie 是
httpOnly、SameSite=Lax。S4N_ENV=production才加上Secure,本機 HTTP 不加 - Cookie 的值只是伺服器上的工作階段編號。約 12 小時後到期,使用一段時間後會換成新編號,舊的立即失效
- 登出會刪掉伺服器上的那一筆
- 登入失敗太多次會先被擋下。這個計數在單一程序的記憶體裡,多個 API 實例不會共用
會改動狀態的儀表板請求仍要通過來源允許清單。本機會同時接受 localhost 與 127.0.0.1。開發時儀表板把 /api 轉到 API,瀏覽器看起來是同一個來源。
贊助頁的「建立贊助」不需要登入。付款回呼也不看這個 Cookie。
外掛頁列出已安裝外掛。每個外掛可以啟用或停用。預設是停用。這一頁只做這兩件事:啟用或停用,以及填寫密文。
密文是 manifest 裡標了 x-s4n-secret: true 的欄位,例如商店代號、HashKey、HashIV、Twitch Client ID 與 Client Secret。畫面只顯示「已設定」或「未設定」,不會顯示內容。儲存之後,API 不會回明文,也不會回密文。留空表示不改掉已經存好的密文。加密方式沒有改,仍是 S4N_MASTER_KEY 的 AES-256-GCM。
其餘設定不是密文。贊助提醒的範本、顏色、動畫與顯示時間、聊天疊層的過濾與停留、Twitch 的頻道名稱、金流的測試站或正式站,都在側欄「外掛」折疊選單。選單只列出目前啟用、而且有一般設定或屬於疊層的外掛。停用後該項會從選單消失。點進去是 /plugins/:id/settings。直接打開已停用外掛的這條路徑,只會看到短訊息和回到外掛頁的連結,不會出現表單。
publicFieldKeys 與 secretFieldKeys 用同一個 x-s4n-secret 分開一般設定與密文,沒有另外的旗標。
payments.provider、secrets、network 只給明確列在官方允許清單上的外掛。名字以 official. 開頭並不夠。
安裝、更新與移除在 外掛市集。移除時可以選擇留下或刪除設定與密文。
帳本與測試贊助
Section titled “帳本與測試贊助”帳本頁讀取核心訂單:待付款、待繳費、已付款、已過期、待人工處理、失敗,可以用狀態篩選。時間以台北時間顯示。付款方式寫出信用卡、ATM、超商代碼或超商條碼,不顯示金鑰。待繳費會附上銀行代碼、帳號或超商代碼。待人工處理表示過期後才收到付款通知:沒有入帳,也沒有送到提醒,畫面上會留下不含金鑰的通知內容。
工作台上的「送出測試贊助」會發出 s4n.donation.test。它會標成測試,寫進事件紀錄,不會寫進帳本,也不會變成已付款的贊助。工作台下方的「事件紀錄」看得到這一筆。
待付款和待繳費可以「向金流查詢」。這會用伺服器上的金鑰向廠商查單,金額仍以帳本為準。期限過了且查單仍未付款,會標成已過期。
把贊助提醒加進 OBS
Section titled “把贊助提醒加進 OBS”- 在外掛頁啟用「贊助提醒」。側欄「外掛」會出現這一項。標題與內文範本、標題顏色、內文顏色、通知主色與副色、進場與退場動畫、顯示時間、音量都在那裡改。設定頁右側有即時預覽。
- 同一頁可以上傳提示音(mp3、ogg 或 wav,最大 2 MB)。伺服器核對 MIME 與檔頭,不看副檔名,存檔名是隨機的。可以試聽,也可以移除。沒有音效時提醒維持靜音。音量是 0 到 100,疊層播放時會套用。音效檔用疊層權杖讀取,不需要登入 Cookie。OBS 瀏覽器來源若沒有聲音,請在來源屬性勾選「透過 OBS 控制音訊」。正式環境把檔案放在 API 容器的 volume,見 正式環境。
- 範本可用
{name}、{amount}、{message}、{currency}。沒有寫過的{變數}會原樣留下。畫面上的結果是純文字,不會變成 HTML。舊的設定如果只有顯示時間,其餘用預設值,不會壞掉。 - 系統若設定減少動態,進場與退場都不會播放。
- 打開「疊層」,產生一條網址。網址裡的 token 就是通行權杖。OBS 只加一個瀏覽器來源。正式環境的主機是
S4N_OVERLAY_ORIGIN,不是儀表板那個網域,見 正式環境。 - 寬度與高度要和 OBS 的畫布,或這個瀏覽器來源的尺寸一致。預設是 1920×1080,也可以選 1280×720、直式 1080×1920。勾選透明背景。不要加上
preview=1。正式網址只有權杖和transparent=1,背景是透明的,不會寫「已連線」或「等待贊助」。那些字只出現在工作台的棋盤預覽(preview=1)。畫布編輯器的外框會標外掛名稱,框裡的畫面跟 OBS 相同。 - 在畫布上拖曳贊助提醒(以及啟用後的聊天疊層、目標、跑馬燈),按「儲存位置」。位置是畫布寬高的比例。之後改尺寸,區塊會跟著縮放,不會黏在舊的像素上。
- 在疊層頁的預覽,或回到工作台,送出測試贊助。疊層會依範本顯示。名稱和留言只當文字畫出來。測試贊助不計入目標,也不進跑馬燈。
以前分開的贊助提醒網址與聊天疊層網址(帶 plugin)會打開同一張畫布,不再各畫各的。OBS 裡若還留著舊網址,可以改貼這一條,或留著也會看到全部已啟用的疊層。
疊層頁可以預覽 OBS 畫面。預覽載入與 OBS 相同的疊層,並按畫布比例縮小。背景可換成深色棋盤、淺色棋盤、純綠,或一張遊戲畫面。範例畫面與上傳的圖片只留在這個瀏覽器,不會送到伺服器。
預覽裡的測試贊助與工作台同一條路徑,不會寫進帳本。重新產生網址後,預覽會改用新權杖。預覽用受限的 iframe 載入疊層,並設定不送出 Referer。權杖仍只放在疊層網址裡。
把 Twitch 聊天加進 OBS
Section titled “把 Twitch 聊天加進 OBS”聊天分成兩個官方外掛。official.twitch-chat 是來源,只負責連到 Twitch。official.chat-overlay 是顯示,只吃已經正規化的聊天事件。之後若加上 YouTube,換的是另一個來源外掛,這塊疊層不用改。
- 在外掛頁啟用「Twitch 聊天」與「聊天疊層」。兩項會出現在側欄「外掛」。
- 打開側欄的 Twitch 聊天,填頻道名稱(登入名稱,不含
#)。不填 Client ID 也能連線:伺服器使用匿名的justinfan與公開的SCHMOOPIIE,那不是你的 Twitch 權杖。 - 若要頻道與全域徽章圖,回到外掛頁填 Twitch Client ID 與 Client Secret。這兩欄是密文,畫面只顯示「已設定」或「未設定」。它們用
S4N_MASTER_KEY做 AES-256-GCM,不會出現在 OBS 網址。 - 側欄的聊天疊層可以調訊息停留秒數(0 表示一直留著)、最多行數、隱藏機器人、隱藏以
!開頭的指令、關鍵字遮罩(換成同樣長度的 *),以及是否同步刪除與封鎖。預設會隱藏 Nightbot、StreamElements、Moobot、Streamlabs、Fossabot。 - 「把贊助混進聊天」預設關閉。打開之後,已入帳的贊助與測試贊助會多一行在聊天裡。測試贊助(
s4n.donation.test)仍然不寫入帳本。 - 打開「疊層」。聊天和贊助提醒共用這一條網址。把網址貼進 OBS 的瀏覽器來源,勾選透明背景,寬高跟畫布相同。不要加
preview=1,也不要把 Twitch 的任何權杖貼進網址。在畫布上把聊天區塊拖到想要的位置,按儲存位置。 - 預覽面板的「送出測試聊天訊息」會送一則帶徽章與 Kappa 表情的訊息,不需要開著實況。若要同時看到贊助樣式,打開混入贊助後再送測試贊助。
刪除訊息(CLEARMSG)與封鎖、超時、清空(CLEARCHAT)會從疊層拿掉對應的行。伺服器會重連、回應 Twitch 的 PING 與 RECONNECT,並限制單則文字長度與每秒則數。畫面上的名稱、內文與徽章標題都是文字,不會被當成 HTML。
徽章圖放在 API 程序的記憶體裡,連同一起的還有向 Twitch 換到的短暫應用程式權杖。重啟之後,圖還沒回來時疊層改畫文字標題。這個快取不進資料庫,也不進事件紀錄。詳見 事件紀錄。
重新產生網址會使舊權杖失效。請不要把網址貼到公開的地方;它不使用登入 Cookie。疊層頁面會拿掉網址列裡的 token,並要求瀏覽器不要送出 Referer。
目標與跑馬燈都宣告了 overlaySlot,啟用後會出現在同一張畫布上,可以拖曳、調整大小,再按儲存位置。
目標的名稱、金額、起算時間,以及文字與進度條顏色,在側欄的目標設定。進度只加總已入帳的贊助(狀態為已付款)。待人工處理、待付款、待繳費、失敗、已過期與測試贊助都不算。以前若存過「只計已入帳」,API 啟動時會拿掉那個欄位;沒拿掉也不會再影響數字。起算時間看訂單更新時間,入帳時會更新那一欄。重設為現在之後,只計算這個時間之後的金額。數字經由現有的疊層 WebSocket 推送,新的入帳會再發一則 s4n.goal.updated。達標時進度條有一個短動畫;系統若設定減少動態,就只留下「達成」。
跑馬燈的自訂文字一行一則。可以接上最近幾筆已付款,顯示名稱與金額,也可以帶留言。速度、方向、文字顏色、背景主色與副色都在設定頁。送到疊層的句子是純文字:隱藏字元會拿掉,長度有上限。
語音外掛已移除。舊資料庫若還有 official.tts 的安裝列,遷移會刪掉它(密文跟著刪)。API 啟動時也會再試一次,失敗只留下警告,不會因此起不來。事件紀錄裡若還有以前的 s4n.tts.request,仍會顯示成一行文字,但不會送到疊層。
之後的外掛只要在清單裡加上版位,就可以排進同一條網址。疊層只會收到已啟用外掛對應的事件。贊助提醒停用時,測試贊助不會出現在畫面上。
畫布尺寸與各外掛的位置存在 OverlayLayout,一筆營運者一列。沒有存過的人用 1920×1080,以及外掛清單上的預設比例,不必改寫舊的設定。
事件寫在 PostgreSQL,重啟 API 或 OBS 斷線後可以依序號補上。規則、保留期限與升級步驟見 事件紀錄。登入失敗的計數仍在單一程序的記憶體裡。帳號、工作階段、外掛設定與疊層權杖留在資料庫。