七、升級¶
這章在講什麼：怎麼把 Agent 換成新版本。
就像手機更新系統——換的是程式本身，您的照片、聯絡人、帳號都還在。Agent 升級也是同一回事：程式換新，資料一個字都不動，也不用重新註冊。
什麼時候看：收到原廠寄來的新版出貨包時。
先說結論：一條指令換版。 不必先解開壓縮檔、不必 cd 進哪個目錄、也不必記得當初裝在哪裡——維運指令自己知道。
7.1 升級指令¶
這兩步在做什麼：第一步先確認新出貨包在傳輸過程中沒有損壞或被動過手腳，第二步才真的換版。
指紋比對／sha256：每個檔案都能算出一串專屬的「檔案指紋」。原廠出貨時附上正確答案，您在這邊重算一次比對，數字一樣就代表檔案完好無缺。
# 先驗證新出貨包沒有在傳輸中損壞
sha256sum -c guidant-agent-compose-<新版號>.tar.gz.sha256
# 換版
sudo guidant-agent-compose upgrade guidant-agent-compose-<新版號>.tar.gz
成功長什麼樣：第一行印出 ... : OK；第二行跑完後畫面顯示服務已重建、健康檢查通過。
健康檢查：服務自我回報「我還活著、而且運作正常」的機制。畫面上看到它轉綠，代表新版真的起來了，不是只有檔案換掉而已。
失敗長什麼樣：第一行印出 FAILED，代表出貨包不完整——這時不要往下跑，先重新取得出貨包。
如果您已經自己把出貨包解開了，直接餵那個目錄也可以：
在解開的目錄裡直接跑
sudo ./install.sh也一樣可以（1.0.0 起）。安裝程式會看出這台機器已經裝過，自動走升級——不會把既有的設定或資料蓋掉。先前必須記得加--upgrade，忘了會裝出「畫面顯示成功、其實還在跑舊版」的結果。
7.2 它會做什麼¶
您下那一條指令之後，背後依序發生這五件事：
| 順序 | 它在做什麼 |
|---|---|
| ① | 解開出貨包到暫存目錄（用完即刪） |
| ② | 逐一比對新映像檔的指紋，確認沒被改過，再載入 Docker |
| ③ | 把新版的服務定義檔覆蓋到安裝目錄（/srv/guidant-ai-agent/；舊版留一份 .bak 備份） |
| ④ | 把設定檔內的映像版號改成新版 |
| ⑤ | 重建服務、等健康檢查轉綠，並確認容器跑的真的是新版映像 |
映像檔：可以想成「安裝母片」——程式本體與它需要的環境整包壓在一起。Docker 拿這片母片開出實際在跑的服務。
升級過程中服務會短暫中斷（大約數十秒到一兩分鐘，視機器速度）。這段時間平台會暫時看不到這台 Agent，屬正常現象，不需要處理。
7.3 什麼東西不會動¶
這是升級最重要的保證：資料完全存活。
| 項目 | 升級後 |
|---|---|
| 證據檔 | ✅ 完全保留 |
| 檔案索引 | ✅ 完全保留 |
| 這台機器的身分憑證 | ✅ 完全保留——不會重新註冊，平台上還是同一台 |
| 安裝時填的四個答案（雲端位址、本機位址、顯示名稱等） | ✅ 完全保留 |
| 儲存位置設定 | ✅ 完全保留 |
您手動投放到 content/ 的檢測內容 |
✅ 完全保留 |
平台憑證信任檔（certs-in/） |
✅ 完全保留 |
這些東西之所以能存活，是因為它們放在資料區／volume（Docker 專門存放資料的獨立空間，容器砍掉重建、資料還在原地）與安裝目錄 /srv/guidant-ai-agent/ 裡，升級只換程式、不碰這兩處。
升級完成後 Agent 直接接回心跳（Agent 定時向平台回報「我還在線上」的訊號），平台端不會看到任何身分變化。
7.4 確認升級成功¶
這步在做什麼：問 Agent 現在是什麼狀態。
成功長什麼樣：畫面上這兩行都對得上——
- 映像那一行顯示的是新版號。
- 雲端註冊顯示「已完成（心跳正常）」。
平台的「檔案 Agent 管理」頁上，該列回報的版本也會換成新版（下一次心跳之後，不是立刻）。
7.5 升級紀錄¶
升級全程的畫面輸出都會寫進 /var/log/guidant-ai-agent/upgrade-<日期時間>.log。純文字檔，可以直接開來看，裡面不含任何密碼。
升級出問題時，請把這個檔一併傳給原廠——它是最快找出原因的線索。
7.6 升級失敗怎麼辦¶
升級過程中任何一步失敗就立刻中止，不會半套。失敗發生在哪一步，影響差很多：
| 失敗發生在哪 | 這時候的狀態 | 您該做什麼 |
|---|---|---|
| 出貨包指紋比對不符 | 完全沒有變更，舊版仍在跑 | 重新取得出貨包；重新下載後仍不符請聯繫原廠 |
| 新版服務起不來 | 服務可能處於停止狀態 | 先看 sudo guidant-agent-compose logs 找原因，並把 upgrade-*.log 一起傳給原廠 |
🔴 沒有「回滾到舊版」這種指令。
要回到舊版，做法是拿舊版的出貨包再跑一次
upgrade——對系統來說那只是「換到另一個版本」，資料一樣完全不動。也因為只有這一條路，請務必保留前一版的出貨包，直到新版確認運作正常為止。舊包丟了就沒有退路了。
7.7 舊出貨包可以刪嗎¶
分兩種東西看，答案不一樣。
可以刪的：升級完成後，整個解開的出貨包目錄都可以刪（1.0.0 起），一次回收約 3.5 GB：
需要長期保留的東西（設定、服務定義檔、您投放的檢測內容）都在
/srv/guidant-ai-agent/，與出貨包已經脫鉤。0.2.32 以前不是這樣，那時候只能刪*.image.tar。
請不要刪的：前一版的出貨包（.tar.gz）建議至少保留一個版本，那是您回到舊版唯一的退路（原因見 7.6）。