ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

影子模組與灰度轉正

Tip


何時需要閱讀本文:需要進行灰度發布——新版本並行試運行、行為對比與轉正回滾時。若不需要則可跳過,不會影響其他功能的使用。

閱讀本文後你會知道:影子模組的五道隔離閘、行為 diff 的對齊方式、
promote 轉正與失敗回滾流程,以及框架無法阻止的誠實邊界。

本文不涉及:普通模組的熱重載與歸屬清理通用機制
(請參閱歸屬權(owner)系統)。

影子 = 同一模組的新版本,以獨立 owner(如 roll_shadow)與線上舊版
並存試運行:它收到真實事件的副本、其出站被拦截記帳而非真正發出——
在 shadow_diff 裡對比兩個版本的行為,確認無害後 promote 一鍵轉正,
dismiss 隨時放棄。模組程式碼零修改,全程運行時 API 驅動:與
load / unload / reload 同類的運維動作,Dashboard / 自訂管理模組直接
呼叫,沒有任何設定項目要寫。

{!--< tips >!--}

  1. 啟動:await sdk.module.shadow_start("roll", source="路徑/到/v2")
    ——新版本程式碼以獨立 owner(預設取路徑名)與舊版並存
  2. 影子不參與真實分發與依賴圖:同名命令進入影子目錄、路由只登記不掛載、
    生命週期廣播靜默、module.call 與依賴解析仍指向 v1
  3. 轉正永遠由人確認:await sdk.module.promote_shadow("roll"),失敗
    自動回滾舊實例繼續服務;dismiss_shadow 隨時放棄 {!--< /tips >!--}

快速上手

# v2 代碼:普通模組寫法,零影子感知(任意目錄,如 downloads/roll_v2/)
# 線上機器人裡(Dashboard / 管理模組呼叫),一行啟動灰度:
await sdk.module.shadow_start("roll", source="downloads/roll_v2")
# → 影子以獨立 owner "roll_v2" 與 v1 並存,出站被攔截記帳

# 試運行期間對比行為:
report = sdk.module.shadow_diff("roll")
# {"shadow_owner": "roll_v2", "count": 3, "aligned": [...]}
  • v1 實際發送:來自收件箱(transcript)的 bot 時間線
  • v2 意向發送:影子帳本(出站閘記錄的"想發什麼")
  • 兩者按 trace_id 對齊——同一條訊息,兩個版本各自為什麼觸發/沒觸發、 想發什麼/實際發了什麼,一目了然

確認無誤後轉正:

await sdk.module.promote_shadow("roll")   # 轉正,失敗自動回滾 v1
await sdk.module.dismiss_shadow("roll")   # 或:放棄影子

五道隔離閘

閘 機制
事件副本 影子處理器收到事件的獨立副本(帶 shadow 標記)——影子的改寫 / 認領 / 停止傳播只作用於副本,不影響原事件鏈
出站閘門 影子的 Send DSL 與 Api 調用全部攔截記賬(成功形狀假回應),不真正發出——影子不會重複回覆
存儲覆蓋層 影子的 KV 寫入進入記憶體覆蓋層並丟棄落庫;讀取先查覆蓋層、未命中透傳真庫(灰度對著真實數據跑);刪除記墓碑
路由屏蔽 影子的 HTTP/WS/SSE 路由只登記不掛載;同名命令進入影子命令目錄、平台事件方法注入禁止
生命週期靜默 影子不廣播自身的生命週期事件、不參與生態依賴圖(module.call 與依賴解析仍指向 v1,避免半成品被依賴)

配置繼承:影子預設繼承原模組的配置節(否則灰度失真),轉正後配置原地生效。

誠實邊界(無法攔阻的)

  • 走框架的發送 / API / KV 存儲 / 統一 HTTP 客戶端全部可以攔阻; 模塊繞過框架裸起 aiohttp、開線程寫外部系統——框架攔不住
  • ORM 讀寫不在覆蓋層語義內(按行 overlay 無法在 SQL 層乾淨實現)—— 影子期間建議避免依賴 ORM 寫隔離
  • 影子源為本地路徑:新版代碼以路徑導入、獨立 owner 裝載;同一 PyPI 包 在同解釋器內受 sys.modules 單鍵限制,無法新舊兩版本並存
  • 泄漏審計器(sdk.module.audit)可見影子資源歸屬;繞過框架的副作用 至少不會無聲

轉正與回滾

promote 流程:快照當前版本(含級聯依賴者)→ 完全卸載 → 以真名註冊影子加載 → 任一步失敗自動回滾、舊實例繼續服務(盡力而為語義:on_unload 已執行的副作用不可撤銷,回滾後舊實例處於已收尾態)。轉正成功的影子資源被回收、綁定解除;原模組配置節原地生效。

持久化提醒:promote 是運行時切換——重啟後仍以 v2 運行,需要將新版本持久化安裝(pip install -U 新版本 / 替換插件檔案)。運行時切換不會替你完成套件管理。Dashboard 的「轉正並持久化」會在轉正成功後後台 pip 安裝上傳時落盤的 whl 原件,把這一步自動化;普通 promote 不落盤。

三條硬邊界

邊界 說明
pip 排他 影子期只解包不安裝:whl 原件落盤到 shadows/<module>/,僅供轉正後持久化;影子運行期間不會 pip 安裝,避免覆蓋已安裝包導致線上行為漂移
promote 不落盤 promote_shadow 只做運行時切換,不寫包管理器;重啟後回退 v1(配置中仍指向舊版本)。需要重啟保持 v2 時用「轉正並持久化」或手動 pip install
第三方依賴 = 進程已安裝版本 影子 import 的第三方庫用的是當前進程已安裝的版本;whl 聲明的新依賴不會自動安裝,缺依賴時影子載入失敗(錯誤原樣拋出)

whl 摄取、list_shadows 與「轉正並持久化」(shadow_ingest_whl / shadow_promote_persist / shadow_persist_status)需要 ErisPulse **2.12+**; 舊版 SDK 自動降級為基礎影子(僅解包啟動,無持久化),Dashboard 能力探測自動切換。

運維查詢面:sdk.module.list_shadows() 返回當前全部綁定 {原模組名: 影子 owner 名},供 Dashboard / 腳本聚合展示。

whl 摄取與「轉正並持久化」的實現歸屬 SDK:解包 / 落盤 / pip 編排跟隨 SDK 版本演進,Dashboard 只是呼叫入口。

相關文件