升級與回滾

這一頁解決什麼

安裝包部署以 custodexa.sh upgrade 升級。腳本先預覽停機，在切換版本前自動做一份停機備份，升級後核對服務與證據鏈。要回到升級前的版本時，用 custodexa.sh rollback。備份與還原步驟見備份與還原。

需要什麼

目前 .env、資料目錄與四個金鑰指紋的紀錄。
足夠的停機視窗，用來等候既有會話結束、稽核佇列排空及資料庫遷移。
Docker 資料夾容得下新版映像，備份目錄容得下升級前備份；腳本在開始前會檢查可用空間。

怎麼設定

升級前

預覽會顯示目前的連線數與預估停機時間，請先公告維護時段並讓會話結束。腳本在停止服務前等候稽核佇列排空，排不空就停在原處，服務照常運作。建議在主機上以 tmux 或 screen 執行，避免 SSH 斷線中斷升級。記錄版本、映像 ID、金鑰指紋及資料列數。DATA_PATH 使用絕對路徑。

需要提前停下服務時，custodexa.sh stop 會先確認，並等未寫入的稽核紀錄落庫後才停止；custodexa.sh start 啟動整組服務並等到後端就緒。

${DATA_PATH}/exports 保存新版匯出產物，不在預設備份範圍。從舊版手動升級時，先將仍需保存的容器內匯出產物搬到持久化位置或下載保存。

安裝包部署

使用已安裝的 custodexa.sh 查詢新版、在選單選目標，或執行：

sudo /opt/custodexa/custodexa.sh upgrade             # 只查詢
sudo /opt/custodexa/custodexa.sh upgrade <version>   # 指定目標版本
sudo /opt/custodexa/custodexa.sh status

也可指定下載好的安裝包路徑。不帶目標的查詢不接受 --images-from。已安裝 1.14.0 或更新腳本時，選單會詢問映像來源；指令可選 --images-from auto|source，省略為 auto。自動來源依序嘗試本機、離線包、GHCR、Docker Hub、最後本機建置。source 核對安裝包內原始碼後建置 backend 與 frontend；上游映像和建置依賴仍須取得，並非完全離線。下載、驗證與建置的長步驟先顯示進度行，完成後顯示結果。

從 1.13.x 第一次升到 1.14.0 時，由已安裝的舊腳本啟動，該腳本不接受 --images-from，選單也沒有來源選擇。不帶此旗標，1.14.0 目標版使用 auto。安裝 1.14.0 後的後續升級才可選原始碼建置。後端啟動時執行資料庫遷移，請核對日誌。

升級前備份

切換版本前，腳本停下 backend、guacd 與 frontend，寫出一份單檔停機備份，內含錄影、不加密，格式與 custodexa.sh backup 相同。外接資料庫的部署同樣由腳本備份：發行版附 PostgreSQL 16、17、18 用戶端，依資料庫伺服器的主版本選用，並在停止任何服務前先檢查資料庫。

也可以改用自己的快照，例如虛擬機或儲存快照。在終端機上，腳本會先詢問是否由它備份；選擇自備快照時，在服務停止後開始快照，涵蓋資料目錄、.env 與 tls/（外接資料庫另含停機後開始的資料庫備份），再輸入快照名稱、開始時間與還原程序的位置。沒有終端機時，先執行 custodexa.sh stop 停止服務，在停止後開始快照，再以 --backup-ref、--backup-time 與 --backup-restore 一併提供。腳本取不到資料庫用戶端或連不上外接資料庫時，預覽會說明原因，改由自備快照完成這一步。

舊版映像

升級成功後，腳本只保留新版與前一版的 backend、frontend 映像，其餘舊版刪除，rollback 需要的映像因此一直都在。上游映像、容器使用中的映像，以及同時帶有其他 repository 標籤的映像不會刪除。結束畫面列出刪除的數量與釋出的空間；無法刪除的映像會附上手動執行的 docker rmi 指令，升級仍算成功。

要保留全部映像，在 upgrade 加上 --keep-images。這個選項由啟動升級的已安裝腳本讀取，因此已安裝的腳本須為 1.17.6 或更新版本。要還原已刪除映像的版本所做的備份時，須能連到映像登錄服務，或備妥該版的離線映像包。

舊 git clone 部署的人工遷移

舊 git clone 樹內直接執行 scripts/custodexa/custodexa.sh，或將 CUSTODEXA_HOME 指向該樹，會說明這是舊版原始碼部署、部署檔案與服務未變更，並拒絕操作。請先核對備份與部署設定，依產品升級 SOP 的「舊原始碼部署的手動遷移」處理；或在另一個乾淨目錄安裝安裝包，再依備份與還原手動還原。不要在既有資料目錄直接執行 install。

升級後與回滾

確認健康檢查、金鑰指紋、檢查點鏈、舊錄影回放及一條新連線的稽核紀錄，再讓使用者連線。

要回到升級前的版本，執行：

sudo /opt/custodexa/custodexa.sh rollback

新版尚未變更資料庫時，rollback 把部署指回前一版，保留資料、.env 與憑證。新版已變更資料庫時，rollback 不切換版本，畫面列出還原該次升級備份的 restore 指令。回退中斷時，rollback --resume 接續完成，rollback --revert 回到升級後的版本。rollback 一次退一版，退回的版本須為 1.16.0 或更新；從 1.16.0 回到 1.15.x，依備份與還原手動還原升級前的備份。資料庫遷移不作反向執行。

升級在備份之後失敗時，完成一次 restore 即可再執行 upgrade，status 會顯示這次還原已處理該失敗。

稽核看得到什麼

檢查點驗證、舊錄影與新會話紀錄可核對升級後的證據鏈。文字會話以錄影為事實來源，無回顯輸入不留指令文字紀錄；查詢主控台的結構化語句紀錄是該查詢的事實來源。