バックアップと復元

このページで解決すること

バックアップの範囲はフォルダの根ひとつ、環境設定ファイル一つ、TLS 証明書のフォルダです。このページでは何をバックアップし、どう取り、どう戻し、戻したあと何を十件確かめれば済んだと言えるかを並べます。パッケージ導入では custodexa.sh backup と custodexa.sh restore で一連の流れを行えます。手動の手順は pg_dump、pg_restore、tar を使います。データベースと OS 自身の道具です。

必要なもの

永続化の置き場所は三つで、いずれも 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` で単一ファイルのバックアップを戻す

パッケージ導入では、1.16.0 以降の版で取った単一ファイルのバックアップを restore で戻します。同じホストにも、まだ導入していないホストにも戻せます。

sudo /opt/custodexa/custodexa.sh restore <バックアップファイル>

導入済みのホスト：置き換える前に現在のデータの安全バックアップを取り、置き換えたフォルダは *.before-restore-<time> の名前で残します。復元後はバックアップを取ったときの版で動きます。
まだ導入していないホスト：get-custodexa.sh でバックアップと同じ版かそれより新しい版のパッケージを置き、置かれたスクリプトで restore を実行します。スクリプトはバックアップの版を導入して復元し、このホストのデータパス、TLS の名前とアドレス、公開 URL を尋ねます。
マスター鍵：バックエンドが封印解除に使ったマスター鍵がバックアップの記録と一致した時点で復元は完了します。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：バケットの保持ポリシーを基準にし、権限はオブジェクトの作成とオブジェクトの閲覧の水準にします。

監査で見えること

復元後のチェーンの検証の結果は区間ごとに状態を出すので、戻した監査データがまだ自分と整合していることを示せます。
鍵のフィンガープリントの突き合わせは、暗号材料が入れ替わっていないことの直接の証拠です。
オフサイトの台帳は一件ごとにハッシュと保管の連鎖のイベントを記録します。突き合わせの結果は証拠のオフサイト保管を参照してください。