備份與還原

這一頁解決什麼

備份範圍收斂成一個資料夾根加上一份環境設定檔。這一頁列出要備份什麼、怎麼備、怎麼還原，以及還原之後要驗哪十件事才算數。備份走 pg_dump、pg_restore 與 tar，用的是資料庫與作業系統本身的工具。

需要什麼

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

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

再加上 .env，它帶著金鑰組態。備份檔一律加密保管，而且不要和主金鑰材料放在同一處。 DATA_PATH 的目錄權限建議 0750 或更嚴。

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

怎麼設定

內建資料庫的安裝包部署可從 custodexa.sh 互動選單選「備份」，或執行 sudo /opt/custodexa/custodexa.sh backup。下列手動程序以內建資料庫及本機 postgres 目錄為前提。外接資料庫部署須自行完成一致的外接資料庫、資料檔案、.env 與 tls/ 備份。${DATA_PATH}/exports 是匯出產物的持久化落點，不在預設備份範圍；需長期保存的產物請在期限內下載。

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
docker compose start backend guacd frontend
以 pg_restore --list 和 tar -tzf 確認兩份產物可讀

2. 不停機備份

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

怎麼還原

順序和備份不同的一點是 .env 要先還原，變數後取值：

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

還原後驗證十項

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

物件儲存桶的建議設定

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

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

稽核看得到什麼

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