媒體計量部署與運維

本頁供自部署平臺的維護人員使用。租戶儲值和計價規則見音視訊計費。啟用標準時長扣費後，媒體服務必須提供實際接收層計量、簽名上報和持久化補報；僅升級業務後端而繼續使用原始 LiveKit 映象，不能完成新計費鏈路。

部署關係

text

Client SDK → Metered LiveKit → Persistent report spool
                                    ↓ signed report
                              Backend usage API
                                    ↓ transaction
                     Receipt + Monthly total + App wallet

增強映象基於固定 LiveKit v1.13.1。採集由服務端完成，不依賴瀏覽器或 App 自報帳單。普通通話和 RTC 頻道共用一個計量協議。媒體服務的 API Secret 僅儲存在後端和媒體伺服器，不能下發給客戶端。

配置與持久化

設定	要求
媒體映象	使用包含 `im-standard-duration-v1` 適配的增強 LiveKit 映象
`IM_BILLING_URL`	媒體容器可訪問的 `/rtc/v1/usage/<service_id>` 完整後端地址
`IM_BILLING_SECRET`	該媒體服務在平臺登記的 API Secret
`IM_BILLING_SPOOL`	容器內持久目錄，預設 `/var/lib/im-billing`
`IM_BILLING_TIMEZONE`	與後端統計時區一致，預設 `Asia/Shanghai`
LiveKit `keys` 與 Webhook	使用原服務憑據，事件回撥保持可達；用量介面不能代替原 Webhook

將補報目錄掛載到主機持久目錄或持久卷。三臺媒體伺服器應分別有自己的可靠目錄，不能把多個寫程序直接放到同一個無協調的共享目錄。增強 LiveKit 已有需要保留的本地計量資料，重建容器時不能把這些檔案當作快取清理。

後端提供用量接收介面；媒體伺服器 /im/billing-health 用於檢查協議及目標服務 ID。平臺已有媒體服務 ID 不應因更新映象而重新生成，回撥和用量地址都應使用該 ID。

構建與覆蓋檔案示例

在倉庫根目錄構建增強映象：

bash

docker build -f deploy/livekit-billing/Dockerfile -t im/livekit-billing:1.13.1 .

在現有 LiveKit 服務上增加覆蓋檔案，示例僅包含新增部分；原 keys、埠、Redis、WebHook 和媒體公網地址繼續沿用實際執行配置：

yaml

services:
  livekit:
    image: im/livekit-billing:1.13.1
    environment:
      IM_BILLING_URL: ${IM_MEDIA_USAGE_URL:?Set the backend usage URL}
      IM_BILLING_SECRET: ${LIVEKIT_API_SECRET:?Set the existing service secret}
      IM_BILLING_SPOOL: /var/lib/im-billing
      IM_BILLING_TIMEZONE: Asia/Shanghai
    volumes:
      - ./data/livekit-billing:/var/lib/im-billing

部署環境的 IM_MEDIA_USAGE_URL 應是完整的後端用量地址，例如 http://backend:8080/rtc/v1/usage/<service_id>；替換為實際可達地址和服務 ID，不要照抄佔位值。Secret 必須與平臺該服務記錄相同。把覆蓋檔案追加到現有 Compose 檔案列表，先檢查合併配置，再按升級視窗更新媒體服務。多主機部署需把映象分發到每臺節點。

本地聯調也可使用倉庫 make livekit-billing-up，先設定 IM_DEV_LIVEKIT_BILLING_URL；它使用開發 Compose 和獨立持久卷，不應直接用來覆蓋現有生產叢集。

升級順序

記錄各節點映象、媒體服務 ID、時區和有效配置，備份資料庫、配置及舊映象；已有計量部署還需儲存補報目錄。備份實際執行配置，不只備份倉庫模板。
規劃切換日和無活動媒體房間的更新視窗。執行新增遷移 billing/0008_app_wallets 及實際待執行遷移，多節點共享資料庫只遷移一次。
核對 media_billing_from。遷移初始日期按 UTC 寫入，而業務統計按配置時區劃日；維護人員應在正式啟用前按既定切換日核對，避免時區邊界錯位。已有資金和回執產生後，不應隨意前移／後移切換日。
升級全部後端和媒體節點，配置簽名端點、原事件回撥和持久目錄。使用現有 Compose 覆蓋檔案的部署應繼續載入全部叢集覆蓋，不要只啟動基礎 Compose。
驗證每臺 /readyz、計量協議、服務 ID、簽名鑑權及補報目錄讀寫；確認所有節點相容後啟用新規則。業務後端會檢查計量協議，舊映象或服務 ID 不匹配會阻止新媒體資源建立。
為隔離驗收應用儲值，實測已知時長的語音、單路影片、多路接收和跨日場景，對照標準時長及流水；重複上報不應重複扣費。

部署成功、埠返回 200、真實通話扣費驗收是不同結論。記錄實際完成的驗證範圍，不用匿名頁面檢查替代真實儲值和媒體測試。

回傳與補報

媒體連線建立後開始計量，停止後結束；採集實際轉發的接收流空間層，每秒歸一個檔位。
每 5 秒將累計快照原子寫入持久目錄，斷開時立即儲存；每 5 秒嘗試傳送。HTTP 失敗保留快照，最終快照成功確認後刪除。
程序重啟補報已經儲存的秒數，不把停機時間補算成通話。持久快照不能保證恢復尚未落盤的所有采樣，異常退出需結合最後成功快照核對。
簽名是 HMAC-SHA256(API Secret, timestamp + "." + raw JSON)，通過 X-IM-Usage-Time、X-IM-Usage-Signature 傳遞，允許 5 分鐘時鐘偏差。保持伺服器時鐘同步。
後端根據媒體服務及房間繫結確定應用，客戶端提供的應用標識不能代替繫結。回執、月累計、餘額和流水一起提交；同版衝突拒絕，舊版忽略，新版只結算差額。

健康檢查與告警

檢查項	如何判斷與處理
後端就緒	各例項 `/readyz` 正常，同時檢查依賴和遷移狀態
媒體計量協議	`/im/billing-health` 返回 `im-standard-duration-v1`，用量路徑中的 ID 與該服務一致
補報積壓	關注檔案數量、最舊快照時間和傳送錯誤；通話結束後積壓持續增長需排查
磁碟與許可權	補報目錄可寫、容量足夠、掛載在重建後仍然存在
時鐘與鑑權	401 時檢查 Secret、原始 JSON、時間戳與時鐘偏差
房間繫結	404 時檢查服務 ID 和持久房間定位，不通過偽造應用欄位繞過
帳目一致	核對餘額 = 累計儲值 − 累計消耗、月標準時長與已扣分鐘、重複與更正流水

排障時保留服務 ID、房間／回執標識、版本、請求 ID、時間與 HTTP 狀態。日誌和工單不應包含 Secret、使用者令牌或完整通知憑據。用未知房間做鑑權探測可以檢查簽名邊界，但不能代替真實媒體計量測試。

備份、恢復與回退

資料庫儲存錢包、流水、媒體回執和月累計，持久補報目錄儲存尚待確認的媒體快照，執行配置儲存簽名和路由關係。恢復方案必須同時考慮三者。

重建單臺媒體容器時，保留原持久卷、服務身份與 Secret；連通後觀察補報是否收斂。恢復舊目錄但保留較新的資料庫時，舊回執由冪等規則處理；不能因此刪除仍未確認的新版快照。備份應保留原許可權，並按部署的憑據管理要求保護。

回退業務或媒體映象前，檢查新規則啟用後是否已產生應用儲值和用量帳本，舊版本是否識別它們。不要通過覆蓋舊資料庫或刪除流水來回退。發生持續計量故障時先限制新的媒體准入、保留資料並修復回傳，再根據已確認回執核對差額，避免繼續提供無法核算的新媒體服務。

媒體計量部署與運維 ​

部署關係 ​

配置與持久化 ​

構建與覆蓋檔案示例 ​

升級順序 ​

回傳與補報 ​

健康檢查與告警 ​

備份、恢復與回退 ​