這張卡做什麼（白話）

做換版升級：客戶拿到新版 bundle 後跑 install.sh --upgrade，四步自動完成——先備份整顆資料庫 → 載入新 image 並驗完整性 → 套資料庫增量變更（migration）→ 換版重起服務。出事時的回滾＝還原備份＋換回舊版 image，明文定位為災難逃生、不是常規操作（會丟升級後產生的資料）。

• 母案 CM-1189：https://app.notion.com/p/FR-065-Installer-3bc346da4cd081c4abf3ce74a28ba384
• 所屬子需求卡 CM-1245：https://app.notion.com/p/FR-065-3-Web-3be346da4cd081f3b401c610fa8e419d
• 設計文件：docs/features/FR-065-2608-onprem-installer/design.md §4.7（D5）

具體實作內容

install.sh --upgrade 四步：

1. pg_dump 全量備份（落地到指定備份目錄）
2. docker load 新 image＋manifest digest 驗證（同安裝時的拒裝邏輯）
3. one-shot init 容器套增量 migration（與 T-2.4 建庫容器同形態）：移植 BE repo align_migrations.sh 的 diff＋--apply 演算法到客戶端形態——現版寫死內部 IP、密碼讀 repo .env，客戶端重做連線層（連線參數外部注入）；SQL＋manifest.tsv 隨 bundle 出貨；依 schema_migrations 判斷起點（T-2.1 的 baseline marker＋補登讓這裡無縫接軌）
4. 改 GUIDANT_VERSION → docker compose up -d（自動 recreate 服務）

• 相容性檢查 v1 最簡版：bundle manifest 標「適用起始版號區間」，目前版本不在區間內即拒跑
• 回滾語意：restore 備份＋GUIDANT_VERSION 回舊 tag 重跑 up -d；手冊明文「回滾會丟升級後產生的資料，屬災難逃生非常規操作」

易踩雷提醒

• migration 套之前備份必須已成功落地——備份失敗就中止，不可裸升
• align_migrations 移植時環境限定 migration（manifest.tsv envs 非 * 的 11 筆）不屬客戶端基線，過濾邏輯要帶
• up 指令同樣永遠帶 service 名（recreate DB 防護）
• 升級用 init 容器與建庫容器同 image——別分家成兩套維護

驗收條件

• 舊版→新版升級通（資料保留、healthcheck 全綠）