升級與回滾

這一頁解決什麼

升級前留下停機備份與舊版映像，升級後核對服務與證據鏈。安裝包部署使用 custodexa.sh upgrade。備份與還原步驟見備份與還原。

需要什麼

• 升級前的停機備份、舊版安裝包與已驗證映像 ID。
• 目前 .env、資料目錄與四個金鑰指紋的紀錄。
• 足夠的停機視窗，用來等候既有會話結束及資料庫遷移。

怎麼設定

升級前

停止接收新連線，等候會話結束與稽核佇列排空。內建資料庫部署可使用 custodexa.sh backup 或依備份與還原完成停機備份；外接資料庫部署須自行完成一致的資料庫、資料檔案、.env 與 tls/ 備份。記錄版本、映像 ID、金鑰指紋及資料列數。DATA_PATH 使用絕對路徑。

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

安裝包部署

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

sudo /opt/custodexa/custodexa.sh upgrade             # 只查詢
sudo /opt/custodexa/custodexa.sh upgrade 1.14.0      # 指定目標
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 後的後續升級才可選原始碼建置。升級前預覽停機；自管資料庫由腳本備份，外接資料庫需自行準備一致備份。沒有自動回滾。後端啟動時執行資料庫遷移，請核對日誌。

舊 git clone 部署的人工遷移

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

升級後與回滾

確認健康檢查、金鑰指紋、檢查點鏈、舊錄影回放及一條新連線的稽核紀錄。需要回滾時停掉服務，以舊版安裝包及已驗證映像配合升級前停機備份回復資料庫、.env、錄影與稽核目錄，再重做驗證。資料庫遷移不作反向執行。

稽核看得到什麼

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