Skip to main content
破損または不正な ClickHouse Keeper スナップショットは、メタデータの不整合、テーブルの読み取り専用状態、リソースの枯渇、バックアップの失敗など、システムに重大な不安定さを引き起こす可能性があります。この記事では、次の内容を扱います。

​
Keeper スナップショットの概要

​
スナップショットとは？

スナップショットは、ある時点における Keeper の内部データ (クラスターに関するメタデータ、テーブルの協調に使用されるパス、設定など) をシリアライズした状態です。スナップショットは、クラスター内の Keeper ノードの再同期、障害発生時のメタデータ復旧、そして既知の正常な Keeper の状態に依存する起動・再起動処理において重要です。

​
スナップショットはどこにありますか？

スナップショットは、Keeper ノードのローカルファイルシステム上にファイルとして保存されます。デフォルトでは /var/lib/clickhouse/coordination/snapshots/ に保存され、keeper_server.xml ファイルの snapshot_storage_path でカスタムパスを指定している場合は、そちらに保存されます。スナップショットには連番の名前 (例: snapshot.23) が付けられ、新しいものほど番号が大きくなります。 マルチノードのクラスターでは、各 Keeper ノードごとに独自のスナップショットディレクトリがあります。
復旧には、ノード間でスナップショットの整合性が保たれていることが極めて重要です。

​
破損した Keeper スナップショットの主な症状と兆候

以下の表は、破損した Keeper スナップショットでよく見られる主な症状と兆候を示しています。 ログ上の指標: スナップショットの破損を診断する前に、まず Keeper ログ で特定のエラーパターンを確認してください。

​
破損した Keeper スナップショットからの復旧

ファイルに手を加える前に、必ず次の対応を行ってください:
  1. さらなる破損を防ぐため、すべての Keeper ノードを停止する
  2. 協調ディレクトリ全体を安全な場所にコピーし、完全にバックアップを取る
  3. 少なくとも 1 つのノードに正常なデータがあることを確認するため、クラスターのクォーラムを確認する

​
1. 既存のバックアップから復元する

次のいずれかに該当する場合は、この手順に従ってください。
  • Keeper のメタデータまたはスナップショットの破損により、現在のデータを復旧できない。
  • 正常な Keeper の状態を含むバックアップがある。
既存のバックアップから復元するには、以下の手順に従ってください。
  1. 最新のバックアップを特定し、メタデータの整合性を確認します。
  2. ClickHouse と Keeper のサービスを停止します。
  3. 問題のあるスナップショットとログを、バックアップディレクトリ内のものに置き換えます。
  4. Keeper クラスターを再起動し、メタデータが同期されていることを確認します。
定期的にバックアップを取得するバックアップが古い場合、直近のメタデータ変更が失われるおそれがあります。そのため、定期的にバックアップを取得することを推奨します。

​
2. 古いスナップショットへのロールバック

次のような場合は、この手順に従ってください。
  • 最新のスナップショットは破損しているが、古いスナップショットは引き続き使用できる。
  • 整合性のある復旧に必要なインクリメンタルログが無傷で残っている。
古いスナップショットにロールバックするには、以下の手順に従います。
  1. Keeper ディレクトリから有効な古いスナップショット (例: snapshot.19) を特定して選択します。
  2. より新しいスナップショットとログを削除します。
  3. Keeper を再起動し、ログを再生してメタデータの状態を再構築させます。
メタデータ不整合のリスクスナップショットやログが欠落している、または不完全な場合、メタデータの不整合が発生するおそれがあります。

​
3. SYSTEM RESTORE REPLICA を使用したメタデータの復元

次のような場合は、この手順に従ってください。
  • Keeper のメタデータが失われている、または破損している一方で、テーブルデータは引き続きディスク上に存在している
  • ZooKeeper/Keeper のメタデータが欠落しているため、テーブルが読み取り専用モードに切り替わっている
  • ローカルで利用可能なデータパーツに基づいて、Keeper 内のメタデータを再作成する必要がある
メタデータを復元するには、以下の手順に従います。
  1. テーブルデータが、config の <path> で設定されたローカルの clickHouse-server データパスに存在することを確認します (デフォルトは /var/lib/clickhouse/data/) 。
  2. 影響を受ける各テーブルに対して、次を実行します。
  1. データベースレベルで復旧する場合 (Replicated データベースエンジンを使用している場合) :
  1. 同期が完了するまで待ちます:
  1. is_readonly = 0 になっていることを system.replicas で確認し、system.detached_parts を監視して復旧を検証します
仕組みSYSTEM RESTORE REPLICA は既存のすべてのパーツをデタッチし、Keeper 内のメタデータを再作成したうえで (新しい空のテーブルであるかのように) 、すべてのパーツを再アタッチします。これにより、ネットワーク経由でデータを再ダウンロードせずに済みます。
前提条件これはローカルのデータパーツが正常な場合にのみ機能します。データも破損している場合は、代わりに戦略 #5 (クラスターの再構築) を使用してください。

​
4. Keeper 内のレプリカのメタデータを削除して再作成する

次のような場合は、この手順に従ってください。
  • エラーがクラスター内の単一のレプリカで発生しており、そのレプリカの Keeper 内のメタデータが破損している、または不整合が生じている
  • “Part XXXXX intersects previous part YYYYY” のようなエラーが発生する
  • ローカルデータを保持したまま、レプリカの Keeper メタデータを完全にリセットする必要がある
メタデータを削除して再作成するには、以下の手順に従ってください。
  1. 影響を受けているレプリカで、テーブルをデタッチします。
  1. Keeper からレプリカのメタデータを削除します (任意のレプリカで実行) :
適切な ZooKeeper パスを見つけるには:
  1. テーブルを再アタッチします (読み取り専用モードになります) :
  1. レプリカのメタデータを復元します:
  1. 他のレプリカと同期します：
  1. 復旧後、すべてのレプリカで system.detached_parts を確認します
影響を受けたすべてのレプリカで実行してください破損が複数のレプリカに及んでいる場合は、各レプリカでこれらの手順を順に繰り返してください。
データベース全体に対する場合Replicated database を使用している場合は、代わりに SYSTEM DROP REPLICA ... FROM DATABASE db_name を使用できます。
代替: force&#95;restore&#95;data フラグを使用する サーバー起動時にすべてのレプリケートテーブルを自動復旧するには、次の手順を実行します。
  1. ClickHouseサーバー を停止します
  2. 復旧フラグを作成します:
  1. ClickHouseサーバーを起動します
  2. サーバーは自動的にフラグを削除し、すべてのレプリケートテーブルを復元します
  3. ログで復旧の進行状況を監視します
この方法は、複数のテーブルを同時に復旧する必要がある場合に有効です。

​
5. Keeper クラスターを再構築する

次の場合は、この手順に従ってください。
  • 復旧に使用できる有効なスナップショット、ログ、またはバックアップがない。
  • Keeper クラスター全体とそのメタデータを再作成する必要がある。
Keeper クラスターを再構築するには、以下の手順に従ってください。
  1. ClickHouse クラスターと Keeper クラスターを完全に停止します。
  2. スナップショットとログのディレクトリをクリーンアップして、各 Keeper ノードをリセットします。
  3. 1 つの Keeper ノードをリーダーとして初期化し、他のノードを段階的に追加します。
  4. 外部の記録が利用できる場合は、メタデータを再インポートします。
時間のかかるプロセスこのプロセスには時間がかかり、長時間の停止につながるおそれがあります。データ全体を再構築する必要があります。
最終更新日 2026年7月23日