バックアップとリストア

Ankole のデプロイメントインスタンスは、再構築できない 2 つのものを保持します。PostgreSQL データベースと Agent Home ボリュームです。PostgreSQL は永続的な control-plane 状態を保存します。Agent Home は workspace、永続的な Agent ドキュメント、インストール済みの Skill、会話と Job のファイルを保存します。

最初に決定的な性質を述べます。データベースの migration は、イメージをロールバックしても元に戻せません。リストアしていないバックアップは、バックアップではなく期待にすぎません。このページの要点はすべてリストアのステップです。それに依存する前に、別のホストでテストしてください。

何をバックアップすべきか、何をすべきでないか

バックアップ	理由	方法
PostgreSQL（Compose では `ankole_postgresql_data`、Helm では外部サーバー）	すべての永続的な意味論的事実	`pg_dump -Fc` アーカイブ
Agent Home（Compose では `ankole_agents_data`、Helm では RWX claim）	Agent ごとの workspace、永続的なドキュメント、インストール済みの Skill、会話と Job のファイル	ボリュームスナップショットまたはファイルシステムレベルのバックアップ。Ankole を停止した状態で実施する

コンテナイメージはバックアップしないでください。レジストリから再構築できます。Caddy のデータや一時的な worker 状態もバックアップしないでください。どちらも再作成できないものを保持していません。また、2 つのうち片方だけをバックアップしないでください。PostgreSQL は Agent Home 内のファイルを参照し、それを指すデータベース行のない Agent Home は孤児です。

PostgreSQL をバックアップする

カスタム形式のアーカイブを作成します（リストアのステップがこれを期待します）。

docker compose exec -T postgresql \
  pg_dump -U ankole -d ankole -Fc \
  > "ankole-$(date +%Y%m%d).dump"

Helm でバンドル版 PostgreSQL を使う場合は、kubectl exec で PostgreSQL pod に入り、同じ pg_dump を実行します。外部 PostgreSQL を使う場合は、そのサーバーでいつも実行している場所で pg_dump を実行します。コマンドの形は同じです。

このバックアップは、すべてのアップグレードの前、破壊的な操作（kit app-db rebuild、docker compose down -v）の前、そしてデータ損失の許容度が求める頻度で取得してください。小規模なデプロイメントインスタンスでは、日次アーカイブが妥当なデフォルトです。

Agent Home をバックアップする

Agent Home はデータベースではなくファイルシステムです。Ankole を停止した状態でバックアップし、バックアップ中に worker が書き込まないようにします。

# Compose: 名前付きボリュームをスナップショットするか、スタック停止中にコピーする
docker compose down
# ankole_agents_data のボリュームスナップショットまたはファイルシステムレベルのバックアップを取る
docker compose up -d

Helm では、Agent Home は RWX claim です。StorageClass が提供する任意のスナップショット機構を使ってください。ファイルシステムレベルのコピー（rsync、restic、クラウドのボリュームスナップショット）はどれでも機能します。ただし、一貫していること、つまり 1 つの時点で取得し、ライターと競走しないことが条件です。

スタックを停止する（または少なくとも worker を静かにする）理由は、バックアップの途中で worker がファイルを書き込むと、引き裂かれたコピーが生じるためです。PostgreSQL の pg_dump はトランザクション的に一貫したアーカイブを提供します。Agent Home にはそのような保証がないので、タイミングでそれを提供します。

PostgreSQL をリストアする

毎回、最初に別のホストへリストアしてください。テストしていないリストアは、インシデントの中で最も高くつくものです。

# 新しい Ankole データベースがあるテストホストで
docker compose exec -T postgresql \
  pg_restore -U ankole -d ankole --clean --if-exists \
  < "ankole-YYYYMMDD.dump"

次に migration を実行して（ローカルでは bun run control-plane:setup、Helm では init コンテナに任せる）、スキーマをイメージの水準に合わせます。migration の前に取得したバックアップは、migration 前のスキーマにリストアされるためです。Principal、agent、既知の session など、データが期待どおりであることを確認してから、リストアが成功したと宣言してください。

Agent Home をリストアする

スナップショットから、ボリュームを同じパス（/agents。Compose では ankole_agents_data から、Helm では RWX claim からマウントされる）にリストアします。ディレクトリ構造は agent-key ごとなので、正しいリストアは /agents/<agent-key>/... を正確に再作成します。これをデータベースのリストアと組み合わせてください。データベースの行は Agent Home の下のファイルを参照し、一致しないペアは、生きているように見えて欠落または古いファイルを指すデプロイメントを生み出します。

ペアを一緒にテストする

README の指示がルールです。「別のホストでデータベースと Agent Home のリストアを一緒にテストする」。この 2 つはペアであり、片方だけをリストアしても何も証明されません。使い捨てホストでの月次サイクル（昨夜の PostgreSQL と Agent Home をリストアし、スタックを起動し、実際の turn を 1 回実行する）が、バックアップと期待の違いです。

テストホストでリストアが機能すれば、本番のバックアップは本物です。機能しなければ、インシデント中ではなくテストホストで発見できたことになります。

バックアップが任意でない場合

いくつかの操作では、バックアップは推奨ではなく必須になります。

すべてのアップグレード — migration は元に戻せません。バックアップがスキーマに対する唯一のロールバック経路です。
kit app-db rebuild --yes — ローカルの ankole_dev データベースを削除します。データが本当に破棄可能な場合にのみ実行し、何か重要なものが含まれているなら先にバックアップしてください。
docker compose down -v — PostgreSQL と Agent Home を含む名前付きボリュームを削除します。これは再起動ではなく削除です。
永続的な状態に影響しうるあらゆる障害 — 修復またはロールバックの前にバックアップを取ってください。

このガイドがそうでないもの

バックアップ製品の推奨ではありません。すでに運用しているボリュームスナップショット、restic、クラウドスナップショットのツールを使ってください。リストアのテストの代替でもありません。リストアのステップこそが要点です。また、気になる部分だけをバックアップする方法でもありません。PostgreSQL と Agent Home はペアであり、部分的なバックアップは壊れたデプロイメントにリストアされます。

次のステップ

クロスホストのリカバリとリハーサルについては、Disaster recoveryを参照してください。
これらのボリュームに名前を付けるデプロイメント構成については、Quick start のデプロイメントのセクションを参照してください。