備份與還原

這一頁解決什麼

備份範圍是一個資料夾根、一份環境設定檔與 TLS 憑證目錄。這一頁列出要備份什麼、怎麼備、怎麼還原，以及還原之後要驗哪十件事才算數。安裝包部署用 custodexa.sh backup 與 custodexa.sh restore 完成整套流程；手動程序走 pg_dump、pg_restore 與 tar，用的是資料庫與作業系統本身的工具。

需要什麼

三個持久化落點，全部是 bind mount：

主機落點	內容
`${DATA_PATH}/postgres`	全部業務資料、稽核紀錄、加密後的憑證與金鑰包裹
`${DATA_PATH}/recordings`	會話錄影檔
`${DATA_PATH}/audit`	稽核降級檔案與封印期日誌

再加上 .env 與 TLS 憑證目錄 tls/。.env 帶著金鑰組態；tls/ 含外部憑證的私鑰，自簽模式下另含本地憑證機構的私鑰。有設定 TLS_NGINX_TEMPLATE 時，它指向的自訂代理範本也要一併備份。備份檔一律加密保管，而且不要和主金鑰材料放在同一處。 DATA_PATH 的目錄權限建議 0750 或更嚴。

匯出產物的落點與離機暫存區不在備份範圍內：證據包有自己的保留期，到期即清；離機暫存區的內容在上傳完成後就沒有保存意義。

怎麼設定

單檔備份（安裝包部署）

從 custodexa.sh 互動選單選「備份」，或執行：

sudo /opt/custodexa/custodexa.sh backup

腳本暫停 backend、guacd 與 frontend，寫出可複製到其他主機的單一備份檔 backups/custodexa-backup-<version>-<time>.tar，旁邊附 .sha256 校驗檔，完成後重新啟動服務。備份檔包含資料庫、稽核檔案、.env、tls/，以及 TLS_NGINX_TEMPLATE 指向的自訂代理範本；status 會顯示最近一次備份。

錄影可在提示時選擇放入，或加上 --with-recordings。
備份檔可用 12 至 256 個字元的密語加密，於提示時輸入或以 --passphrase-file <檔案> 讀取。加密檔的副檔名是 .tar.enc，以 OpenSSL 1.1.1 以上與 tar 即可開啟；還原時須提供同一組密語。
外接資料庫的部署以同樣方式備份。發行版附 PostgreSQL 16、17、18 用戶端，依資料庫伺服器的主版本選用。資料庫 CA 檔會放入備份，用戶端私鑰不放入，請與部署的其他機密一起保管。

升級時腳本也會在切換版本前寫出同格式的備份，見升級與回滾。${DATA_PATH}/exports 是匯出產物的持久化落點，不在預設備份範圍；需長期保存的產物請在期限內下載。

手動程序

下列手動程序以內建資料庫及本機 postgres 目錄為前提，適用於非安裝包部署，或需要自訂備份流程時。

0. 先取變數

每段程序的第一步都一樣。字面讀取 .env，不要 source 它：

ENV_FILE="${ENV_FILE:-./.env}"
env_get() { sed -n "s/^[[:space:]]*$1=//p" "$ENV_FILE" | tail -n 1; }
DATA_PATH="${DATA_PATH:-$(env_get DATA_PATH)}"
DB_USER="${DB_USER:-$(env_get DB_USER)}"
DB_NAME="${DB_NAME:-$(env_get DB_NAME)}"
printf 'DATA_PATH=%s\nDB_USER=%s\nDB_NAME=%s\n' "$DATA_PATH" "$DB_USER" "$DB_NAME"

後續指令一律用 "${VAR:?}" 的形式引用，讓變數缺值時當場失敗。

1. 停機備份

升級前的備份必須是停機備份。順序是停應用、備資料庫、備檔案、備設定、再啟動：

docker compose stop backend guacd frontend
pg_dump -Fc 匯出資料庫
tar -czf 打包 recordings 與 audit 兩個目錄
複製一份 .env，並打包 tls/ 目錄
docker compose start backend guacd frontend
以 pg_restore --list 和 tar -tzf 確認兩份產物可讀

2. 不停機備份

日常備份可以不停機：跳過停止與啟動兩步，先備資料庫再複製錄影目錄。一致性的方向是刻意的，寧可錄影目錄比資料庫新。

怎麼還原

以 `restore` 還原單檔備份

安裝包部署以 restore 還原 1.16.0 以後版本所做的單檔備份，可還原到原主機，也可還原到尚未安裝的新主機：

sudo /opt/custodexa/custodexa.sh restore <備份檔>

已安裝的主機：覆蓋前先做一份目前資料的安全備份，被取代的資料夾以 *.before-restore-<time> 名稱保留。還原後部署執行備份當時的版本。
尚未安裝的新主機：先以 get-custodexa.sh 放置與備份同版或更新版本的安裝包，再用它放置的腳本執行 restore。腳本會安裝備份當時的版本並還原，過程中詢問這台主機的資料路徑、TLS 名稱與位址，以及對外網址。
主金鑰：後端解封所用的主金鑰與備份記錄的相符時，還原才算完成。KEK_PROVIDER=env 在啟動時即完成；ui 或 kms 模式在匯入後先結束，於解封頁解封，再執行 restore --resume 完成。
中途停下：還原失敗或中斷時停在原處。restore --resume 接續，restore --revert 在已安裝的主機以安全備份回到還原前，restore --abandon 讓新主機回到未安裝狀態。
外接資料庫：同一個指令即可，原主機或其他主機皆可。還原使用備份記錄的資料庫伺服器與資料庫，在單一交易內清空並匯入；匯入失敗時資料庫維持原狀。備份連線用過用戶端憑證時，以 --db-client-cert 與 --db-client-key 提供。

手動還原

不是單檔格式的備份，以及 1.16.0 以前版本所做的備份檔，依下列順序手動還原。順序和備份不同的一點是 .env 要先還原，變數後取值：

docker compose down
還原 .env 與 tls/ 目錄
用還原後的 .env 取變數
解開錄影與稽核目錄的封存檔（目標的 postgres 目錄必須是空的）
只起資料庫服務，等它接受連線
pg_restore --clean --if-exists 還原資料庫
在 Linux 主機把 recordings 目錄設為 1000:0 所有與群組、權限 2770，再以 docker compose up -d 起全部服務

還原後驗證十項

服務全部起來。
後端健康檢查通過。
啟動日誌沒有致命錯誤。
前端回 200。
登入鏈路可用。
金鑰清冊上四個指紋與備份時相同。
加密欄位可以解開（開一台資產的編輯頁確認憑證仍可用）。
抽一支錄影確認可以播放。
稽核鏈驗證通過。
啟用離機保存的部署，另外做一次帳冊與儲存桶的對帳。

物件儲存桶的建議設定

離機保存的儲存桶由部署方管理，建議：

S3 或相容服務：啟用版本化；需要防刪改就在建桶時啟用物件鎖定（建好之後不能補開）；生命週期規則的到期天數對齊錄影保留政策，並加上非目前版本的到期規則；存取權限收斂到寫入指定前綴、讀取物件與其中繼資料、讀取儲存桶組態。
GCS：以儲存桶保留政策為基準，權限給到物件建立與物件檢視的量級。

稽核看得到什麼

還原後的鏈驗證結果，逐區間出具狀態，可以證明還原回來的稽核資料仍然自洽。
金鑰指紋比對是「加密材料沒有被換掉」的直接證據。
離機帳冊逐件記錄雜湊與保管鏈事件，對帳結果見證據離機保存。