文件版本化從 2.0.1 開始，本站刻意不提供更早版本的升級矩陣。本頁定義的是「離開 2.0.1 基準」時應做的維運檢查；目標版本特有的不相容變更，應以該版本自己的文件為準。
切換執行版本前
- 記錄目前部署
保存精確的 hs-sql-agent、容器或套件版本、拓樸、管理資料庫 provider 與共用狀態 provider。
- 備份控制平面狀態
在新版程式有機會修改持久狀態之前，先建立可還原的管理資料庫備份。
- 保存受保護的金鑰資料
確認 HMAC_KEY、JWT_KEY、webhook 密鑰與 DATA_PROTECTION_KEY_PATH 內容都能讓新部署繼續使用。
- 比對設定差異
把目標版本的範例與 options 跟目前 2.0.1 正式環境設定逐項比對，不要直接用新範例覆蓋正式設定值。
- 盤點整合項目
列出 MCP 用戶端、Custom Tools、OIDC、SMTP、webhooks / SIEM、Prometheus / OTLP、Redis / 共用狀態、反向代理，以及外部 Admin API 使用者。
不應在升級時隨意重新產生的狀態
HMAC / JWT 密鑰
HMAC_KEY 參與 MCP 金鑰驗證，JWT_KEY 用於管理端身分驗證 token。密鑰輪替應該是明確的安全性遷移，不應只是部署新映像檔時順便發生的副作用。
Data-protection key ring
受保護的身分與 MFA 狀態使用 ASP.NET Core data protection 時，DATA_PROTECTION_KEY_PATH 必須放在持久儲存空間。如果 key ring 被替換，先前受保護的資料可能無法再次讀取。
管理資料庫
管理資料庫就是控制平面，會保存身分與角色、資料庫註冊、MCP 金鑰紀錄、政策、語意中繼資料、Custom Tool 定義與修訂版本、稽核資料，以及其他維運狀態。任何可能變更持久化內容的升級，都應依 SQLite / PostgreSQL 拓樸先做好正式備份。
設定差異檢查表
不要從全新的 .env 重建正式環境設定；應逐組比對：
- 應用程式 host / 公開 MCP endpoint；
- 管理資料庫 provider / connection；
- HMAC / JWT / 身分設定；
- bootstrap；
- OIDC / MFA / data protection；
- 稽核保留 / 外送；
- 速率限制 / 安全政策同步；
- cache / SQL concurrency / Redis 協調；
- Prometheus / OTLP。
2.0.1 基準請見 設定參考。
升級後驗證
- 管理端身分驗證
登入並確認預期角色與權限；若有啟用，也要驗證 OIDC / MFA。
- 資料庫連線
對實際使用的 provider 驗證受管理連線與 schema 中繼資料瀏覽。
- MCP 金鑰範圍
確認代表性金鑰仍對應正確資料庫、工具、資料表白名單與實際生效限制。
- 唯讀 SQL
執行代表性的已支援查詢形式，確認編譯器與輸出行為。
- Safe DML
使用非正式環境目標，同時測試拒絕（Decline）與接受（Accept）Elicitation，確認提交前後行為。
- 維運
檢查稽核、健康狀態、金鑰使用、遙測匯出與外送狀態。
Custom Tools / 語意中繼資料
對每個已發布的 Custom Tool，確認目標版本的編譯器與政策仍能通過驗證，而且資料庫與金鑰的對外範圍沒有漂移。語意中繼資料則確認資料表 / 欄位說明、關聯與指標，仍能如預期出現在 schema discovery。
API 使用者
2.0.1 Admin controllers 沒有放在版本化的 /v1 契約下。如果外部自動化直接呼叫 Admin HTTP routes，路由、請求與回應相容性都必須列入升級測試。
回復規劃
實際上線時，應保留舊版部署成品與設定、升級前的管理資料庫備份，以及受保護的金鑰資料，直到新版本完成必要的功能與維運基本驗證（smoke test）。