本文へスキップ
Ankole

ディザスタリカバリ

AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/disaster-recovery/index.md にあります。ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。

ディザスタリカバリとは、導入インスタンスが失われたときに行うことです。ホストが壊れ、クラスタを失い、ボリュームが破壊され、それをどこか別の場所で復元する必要がある場合です。これはインシデントではありません（システムが誤動作しているのではなく、存在しないのです）。アップグレードでもありません（先へ進めるものは何もありません）。このページは、他のガイドが扱うバックアップの規律と移行の仕組みの上に築かれた、エンドツーエンドの復旧の全体像です。

決定的な性質を先に述べます。復旧とは新しいデプロイへの復元であり、古いものの修理ではありません。Ankole をゼロからデプロイし、バックアップから PostgreSQL と Agent Home を復元し、ブートストラップの secret を再入力します。復旧できるのは、バックアップしたものと正確に同じです。それ以上でもそれ以下でもありません。そして、リハーサルしていない復旧は、能力ではなく計画にすぎません。

何が復旧できて、何ができないか

状態 復旧可能? 何から
Principals、agent、session、job、audit、AuthZ の付与 はい PostgreSQL の pg_dump アーカイブ
Agent ごとの workspace、永続ドキュメント、インストール済み Skill、会話と Job のファイル はい Agent Home ボリュームのスナップショット
Provider の credential、chat channel の credential、暗号化された環境変数 はい これらは PostgreSQL と Agent Home に保存されるため、バックアップがそれらを復元します
ブートストラップ secret（ANKOLE_SECRET_BASE、worker 認証キー） 手動で再入力 バックアップには含まれません。新しいものを生成するか、記録しておいたものを再使用します
進行中の turn、実行中の background job、ライブの worker 状態 いいえ 一時的なものです。プロセスとともに失われます
外部の取り込み先へ出荷されなかったログ いいえ 失われたホスト上にありました

驚かされるのはブートストラップ secret の行です。他のキーを導出する secret はデプロイ時の入力であり、PostgreSQL の状態ではありません。そのため pg_dump には含まれません。これらは secret マネージャに保管してください（インスタンスのバックアップの中ではなく、その横に）。または再生成し、導出キーが変わることを受け入れてください。

復旧手順

手順 1: Ankole をゼロから新規デプロイする

クイックスタート に従い、新しいホストまたはクラスタに新しい導入インスタンスを立ち上げます。新しいインスタンスを古いホストのボリュームやデータベースに接続しようとしないでください。古いものは復旧の対象であり、中途半端に接続したインスタンスは、きれいな状態のものより悪いです。新しいデータベース、新しい Agent Home ボリューム、新しいブートストラップ secret（または記録しておいた古いもの。手順 4 を参照）を使ってください。

手順 2: PostgreSQL を復元する

control plane を本番で起動する前に、アーカイブからデータベースを復元します。

# on the fresh deployment, with the control plane stopped or in setup mode
docker compose exec -T postgresql \
  pg_restore -U ankole -d ankole --clean --if-exists \
  < "ankole-YYYYMMDD.dump"

次にマイグレーションを実行し（ローカルでは bun run control-plane:setup、または Helm の init コンテナに任せます）、復元した schema をイメージのレベルに合わせます。復元されたデータベースには、バックアップ取得時点の Principals、agent、session、job、AuthZ の付与が含まれています。

手順 3: Agent Home を復元する

ankole_agents_data ボリューム（または Helm の RWX claim）をスナップショットから、同じ /agents マウントパスに復元します。Agent キーごとのディレクトリ構造によって /agents/<agent-key>/... が正確に再現されます。これを PostgreSQL の復元とペアにしてください。データベースの行は Agent Home 配下のファイルを参照しており、ペアが不一致だと、生きているように見えて欠落ファイルを指すデプロイになります。

手順 4: ブートストラップ secret を処理する

ブートストラップ secret（ANKOLE_SECRET_BASE、ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY、POSTGRES_PASSWORD）はバックアップに含まれません。2 つの道があります。

  • 記録しておいたものを再使用する。secret マネージャに、インスタンスのバックアップと並べて（中ではなく）保管している場合、それらを再入力します。導出キーが同じため、復元した PostgreSQL 内の既存の暗号化行は正しく復号されます。
  • 再生成する。.env（Compose）または Secret（Helm）で新しいものを生成します。復元した PostgreSQL は無傷ですが、古い ANKOLE_SECRET_BASE で暗号化された Provider credential、chat channel credential、環境変数は復号できません。復旧後にこれらの値を Console で再入力してください。

再使用の方が単純で secret を保持します。旧 secret が災害中に漏洩した可能性があるなら、再生成の方が安全です。復旧する理由に合う道を選んでください。

手順 5: バックアップにないものを再入力する

復元後、設定の各画面を確認し、それぞれが無傷であることを確認します。

  • Provider と model profile。PostgreSQL にあり、復元されています。
  • signal ルーティングルール。PostgreSQL に保存され、復元されます。手順 4 で ANKOLE_SECRET_BASE を再生成した場合は、Channel Provider の credential を再入力する必要があるかもしれません。
  • Identity Provider。同じです。行は復元されますが、credential の再入力が必要かもしれません。
  • Control Plane Plugin の有効化リスト。復元されますが、効果が出るのは次回のプロセス起動時です。

binding を通じて実際の turn を 1 つ送信し、新しいデプロイでエンドツーエンド経路が機能することを確認してください。

クロスホスト移行（計画版）

新しいホストへの計画的な移行は、意図的に行う同じ手順です。

  1. 古いデプロイを停止します（worker を静止させ、書き込みを止めます）。
  2. 最終の PostgreSQL バックアップと Agent Home スナップショットを取ります。これらが移行の事実のソースです。
  3. 新しいホストで新規デプロイし、ペアを復元し、ブートストラップ secret を処理します。
  4. 新しいホストで実際の turn を 1 つ使って検証します。
  5. DNS（またはロードバランサ）を新しいホストに切り替えます。自信が持てれば、古いものを退役できます。

ディザスタリカバリとの違いは「古いデプロイを停止する」手順です。災害では古いデプロイが自ら停止し、持っているバックアップはその前のものです。ギャップを最小にするため、最終バックアップは切り替えにできるだけ近い時点で取ってください。

リハーサル

リハーサルしていない復旧は計画であり、能力ではありません。リハーサルは、このガイドの中で突出してハイレバレッジなものです。

  • 毎月、使い捨てのホストで、昨夜の PostgreSQL と Agent Home を復元し、イメージをデプロイし、実際の turn を 1 つ実行します。復元が機能すれば、復旧は本物です。機能しなければ、災害の最中ではなく、使い捨てホストの上で見つけることになります。
  • ブートストラップ secret の手順を含めます。 それを省略したリハーサルは、人々を驚かせる部分をテストしていません。記録した secret を再使用するか、再生成して credential を再入力するか、実際にやる方を行ってください。
  • ホストを変えます。 毎回同じホストに復元するのはバックアップのテストであり、復旧のテストではありません。定期的に別のホスト（別の OS、別のクラウド）に復元してください。災害があなたに渡すものはそれだからです。

このガイドと他のガイドの関係

  • バックアップと復元 は復旧を可能にする規律です。バックアップがソースです。
  • システムがまだ存在するが誤動作している場合は、まず障害を診断してください。このページの対象は、インスタンスが利用できないかデータが失われたときです。
  • 計画的なアップグレードは既存のインスタンスを前進させます。ディザスタリカバリは、新しい環境でバックアップからインスタンスを再構築します。
  • セキュリティ強化 は、復元元となるバックアップがテスト済みであることを前提とします。このページがそのテストです。

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

それは、データが一切失われないことの保証ではありません。バックアップにないものはすべて失われ、進行中の作業は常に一時的です。それはリハーサルの代わりでもありません。リハーサルこそが本質です。それは単一のコマンドでもありません。復旧は新規デプロイ＋ペア復元＋secret であり、各手順に独自の検証があります。時間節約のために手順を飛ばすと、復旧が壊れたデプロイを生み出します。

次のステップ

  • 復旧が依存するバックアップの規律については バックアップと復元 を読んでください。
  • 新規デプロイの手順については クイックスタート を読んでください。
  • システムがまだ稼働しているが誤動作しているときは、ログ読み取り で最初の障害を見つけてください。