五、升級與回滾¶
這章在講什麼：收到新版出貨包之後，怎麼把系統換到新版；萬一新版有問題，怎麼退回舊版。
換版有點像換車上的引擎——車體（您的資料）不動，只換裡面那顆。升級會保留全部資料，正常情況下只需要短暫停機幾分鐘。而「退回舊版」則像把引擎裝回去、同時把里程表也倒回換裝那一刻——換裝之後跑的那段路會不見，所以是最後手段。
什麼時候看：收到原廠的新版出貨包時。升級後系統無法使用、已與原廠確認要退版時，看本章 5.5。
5.1 升級前的準備¶
一共四件事，花不了幾分鐘。
| 要準備的 | 為什麼 / 怎麼做 |
|---|---|
| 磁碟空間 | 升級會先做一份完整的資料庫備份，落在 <資料目錄>/backup/。請確認該分割區的可用空間大於資料庫大小（保險起見預留兩倍） |
| 通知使用者 | 升級過程中服務會短暫中斷（約 1～5 分鐘，視資料量而定） |
| 確認現行版本 | 跑 sudo guidant status，第一行就會顯示 |
| 確認版號區間 | 新出貨包的 images/bundle-info.txt 內有「適用起始版號」。現行版本低於它時升級會被拒絕，需依原廠指示逐版升級 |
不需要事先手動備份——升級的第一步就是備份，而且備份失敗就會中止、不會裸升。但若貴單位有既有的備份流程，照跑無妨。
5.2 執行升級¶
這兩行在做什麼：切到新版出貨包所在的目錄，然後執行升級。
🔴 要在新版出貨包的目錄下執行（不是舊版那份）。升級要用的映像檔、資料庫變更、以及新版的服務定義都在新包裡。
升級不會再問任何參數——資料目錄、埠、主機名全部沿用既有安裝，您不需要重新填一次。
同版號重套（--force）¶
預設情況下，新舊版號一樣時升級會直接被擋下（顯示「現行版本已是 x.y.z，無需升級」）。這是防呆，避免無謂重跑。
但有一種情形版號一樣卻真的需要重套：同一個版號重新編了映像檔（例如原廠在同版號內修正了映像內容、或重出了一次貨包）。此時加上 --force。
這一行在做什麼：跳過「版號沒變」這一項檢查，其餘照常升級。
--force 只放行「版號相同」這一項，其餘保護一個都沒少——備份、映像檔 sha256 比對（sha256 是檔案指紋，用來確認檔案沒有被改過或傳壞）、資料庫變更比對照跑，只是不再因為版號沒變而中止。它也不會跳過備份失敗或檔案驗證失敗的中止。
⚠️ 風險與代價：同版重套一樣會完整跑一次備份（耗時視資料量而定）與服務重啟（期間服務短暫中斷）。若沒有真的換過映像檔，重跑不會帶來任何改變，只是白花一次停機時間。
🔴 不要改用手動 docker 指令代替。遇到被擋下時自行下
docker compose up -d --force-recreate，會跳過備份與檔案驗證；更危險的是漏帶服務名時 compose 會連資料庫容器一起重建。--force就是為了避免這種繞道而存在。
--force 只能與 --upgrade 併用，單獨使用會被擋下。
5.3 升級的每一步在做什麼¶
升級是一連串步驟自動跑完的。以下逐步說明畫面上會出現什麼，好讓您在盯著畫面時知道現在到哪、以及哪些訊息代表要停下來。
① 升級前檢查¶
這一步在做什麼：確認既有安裝的設定檔存在、讀出現行版號、比對版號區間、確認 Docker 可用。
成功長什麼樣：現行版本：1.15.0 → 新版本：1.16.0、✓ 版號區間符合。
失敗長什麼樣：兩種情形會被擋下——
- 現行版本已是新版 → 不需要升級。若確實要重套同版（同版號重編了映像檔），依訊息提示加上
--force（見 5.2）。 - 版號區間不符 → 跨太多版直接套可能遇到不可跳過的資料庫變更。請聯繫原廠取得中間版本，逐版升級。
② 備份資料庫¶
這一步在做什麼：把升級前的資料庫完整倒出來存檔，落在 <資料目錄>/backup/guidant_ai-pre-<舊版號>-<日期時間>.sql.gz。
成功長什麼樣：✓ 備份完成（xxx MB），接著印出還原指令——請把這行留著，回滾時要用。
🔴 備份失敗就會中止，系統完全沒有變更。資料庫變更是不可逆的寫入，沒有備份就沒有回頭路。這一步不會被跳過。
③ 載入新版映像¶
這一步在做什麼：把新版的映像檔（映像檔＝服務程式的完整打包檔）讀進本機，並用與安裝時同一套完整性驗證確認檔案沒有被改過，不符即拒絕。
成功長什麼樣：每個映像檔一行 ✓ 完整性符合。
這一步不影響執行中的舊版服務（新舊版是不同的映像標籤），系統此時仍然正常運作。
③-2 準備物件儲存設定（僅從舊版升上來的機器）¶
這一步在做什麼：若您的機器是從沒有內建檔案儲存的版本升上來的，這一步會補齊新服務需要的設定。
成功長什麼樣：✓ 物件儲存設定已存在，沿用 或 已從既有憑證檔回填…。
🔴 升級不會改變您現有的檔案儲存位置。新版雖然內建了檔案儲存服務，但要不要改用它是貴單位的決定——擅自改掉等於把檔案位置換掉。要切換請看 第七章（動手前務必先讀完）。
③-3 補齊檢測 Agent 對接金鑰（缺了才補）¶
這一步在做什麼：從沒有這組金鑰的舊版升上來時，這一步會補齊；已經有的一律不動（含您自行調整過的對外位址）。
成功長什麼樣：✓ Agent 對接金鑰已備妥 或 偵測到既有的 Agent 對接金鑰，保留不覆蓋。
🔴 既有金鑰不會被覆蓋是刻意的：重新產生等於重新簽發，會讓所有已註冊的檢測 Agent 全部離線並需逐台重新註冊。
④ 套用資料庫變更¶
這一步在做什麼：新版若調整了資料庫結構，這一步會套用。先列出將要套用的變更清單（dry-run＝只演練給您看、不實際動手），再實際套用。
成功長什麼樣：清單 → ✓ 資料庫變更套用完成。
失敗長什麼樣：畫面會告訴您資料庫可能處於「部分升級」狀態，並給出還原指令。此時服務仍在舊版（尚未換版），還原備份後即可繼續使用。請把錯誤訊息中的檔名回報原廠。
④-2 補建出廠儲存快照（僅從舊版升上來的機器）¶
自 1.15.0 起，儲存設備設定頁多了一顆「恢復系統內建儲存」按鈕（把儲存改接自有設備後，可以一鍵切回系統內建的那組，不必上主機抄帳號密碼）。這顆按鈕靠的是安裝當下留下的一份「出廠設定快照」。
這一步在做什麼：舊版安裝的機器沒有這份快照，升級時會據現有設定補建一份。
成功長什麼樣：✓ 已補建出廠儲存快照（設定頁「恢復系統內建儲存」自本版起可用），或 ✓ 出廠儲存快照已存在，沿用。
另外兩種訊息也不需要緊張：
- 看到
主機設定內無內建物件儲存憑證，略過出廠儲存快照補建——代表這台沒有在用系統內建的檔案儲存，不需要這份快照，屬正常情形。 - 看到補建失敗的警告——升級本身沒有問題、系統照常運作，只是那顆按鈕不會出現。可重跑一次升級補上（這一步重複執行不會出問題），或聯繫原廠。
快照留的是安裝當下那組內建儲存設定，升級不會刷新它；已經有快照的機器一律不動。
⑤ 換版並重啟服務¶
這一步在做什麼：改版號 → 重新建立容器 → 等健康檢查（服務自我回報「我還活著而且運作正常」）。
成功長什麼樣：六行 ✓ <服務名> 健康。
⑥ 更新維運工具¶
這一步在做什麼：把 guidant 指令與服務定義檔換成新版的，讓維運工具永遠跟著目前的系統版本走。您不需要做任何事，也不需要記得去更新它。
成功長什麼樣：✓ 維運指令與部署定義檔已更新為本版（sudo guidant status 可用）。
⑦ 升級完成¶
成功長什麼樣：
════════════════════════════════════════════════════════════
已從 1.15.0 升級至 1.16.0
════════════════════════════════════════════════════════════
站台網址：https://192.168.1.50
升級前備份：/srv/guidant-ai/backup/guidant_ai-pre-1.15.0-20260826-143022.sql.gz
畫面下方會印出回滾步驟——請把這段留下來（也可在安裝紀錄檔內找到）。
升級後請自己驗這三項：
- 用瀏覽器開站台、登入。
sudo guidant status六個服務都健康。- 隨機開幾個既有專案，確認資料都在。
5.4 升級紀錄¶
升級的全程輸出會寫進一個檔，出問題時這是最有用的線索：
純文字、不含密碼，可以直接傳給原廠。
5.5 回滾（🔴 災難逃生，不是常規操作）¶
回滾＝把系統退回升級前的樣子。
⚠️ 回滾會丟掉升級後產生的所有資料¶
備份是升級前那一刻的狀態。從升級完成到執行回滾之間，使用者所做的一切（新建的專案、上傳的證據、填寫的紀錄）都會消失，且無法復原。
只在「升級後系統無法使用、且已與原廠確認需要回滾」時才做。 系統只是某個功能不正常時，請先聯繫原廠——多數情形有不需要回滾的解法。
回滾步驟¶
假設從 1.15.0 升到 1.16.0 後需要回到 1.15.0。三步：把資料庫灌回舊備份、把版號改回舊版、用舊版重新起服務。
這三段在做什麼：如註解所示，依序執行。
# ① 還原資料庫（用升級時那份備份）
gunzip -c /srv/guidant-ai/backup/guidant_ai-pre-1.15.0-20260826-143022.sql.gz \
| sudo docker exec -i guidant-db psql -U cmmgr -d guidant_ai
# ② 把版號改回舊版
sudo sed -i 's/^GUIDANT_VERSION=.*/GUIDANT_VERSION=1.15.0/' /srv/guidant-ai/.env
# ③ 換回舊版容器
sudo guidant start
🔴 第 ③ 步必須用
start，不能用restart。restart只是把現有容器停了再起，不會重讀版號——跑起來的還是新版，回滾等於沒做，而畫面上一切正常。這是回滾最容易出錯的一步。
舊版的映像檔仍在本機（升級不會刪除舊映像），不需要重新載入。
回滾後請自己驗這兩項：
sudo guidant status版本應顯示舊版號、六個服務健康。- 登入系統，確認可以正常操作。
回滾後要做什麼¶
回滾只是讓系統恢復可用，問題本身還在。 請把下列資料傳給原廠：
- 升級紀錄檔
/srv/guidant-ai/log/upgrade-*.log - 失敗時的畫面訊息
sudo guidant logs <出問題的服務名>的內容
在原廠給出解法之前，不要重複嘗試同一份升級包。