破損した Keeper スナップショットから復旧する方法

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

• スナップショットとは何か、またどこで見つけられるか
• 問題がどのように現れるか
• 考えられる復旧戦略 と、それぞれが何を意味するのか

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

スナップショットは、Keeper ノードのローカルファイルシステム上にファイルとして保存されます。デフォルトでは /var/lib/clickhouse/coordination/snapshots/ に保存され、keeper_server.xml ファイルの snapshot_storage_path でカスタムパスを指定している場合は、そちらに保存されます。スナップショットには連番の名前 (例: snapshot.23) が付けられ、新しいものほど番号が大きくなります。

マルチノードのクラスターでは、各 Keeper ノードごとに独自のスナップショットディレクトリがあります。

以下の表は、破損した Keeper スナップショットでよく見られる主な症状と兆候を示しています。

ログ上の指標:

スナップショットの破損を診断する前に、まず Keeper ログ で特定のエラーパターンを確認してください。

ファイルに手を加える前に、必ず次の対応を行ってください:

1. さらなる破損を防ぐため、すべての Keeper ノードを停止する
2. 協調ディレクトリ全体を安全な場所にコピーし、完全にバックアップを取る
3. 少なくとも 1 つのノードに正常なデータがあることを確認するため、クラスターのクォーラムを確認する

次のいずれかに該当する場合は、この手順に従ってください。

• Keeper のメタデータまたはスナップショットの破損により、現在のデータを復旧できない。
• 正常な Keeper の状態を含むバックアップがある。

既存のバックアップから復元するには、以下の手順に従ってください。

1. 最新のバックアップを特定し、メタデータの整合性を確認します。
2. ClickHouse と Keeper のサービスを停止します。
3. 問題のあるスナップショットとログを、バックアップディレクトリ内のものに置き換えます。
4. Keeper クラスターを再起動し、メタデータが同期されていることを確認します。

次のような場合は、この手順に従ってください。

• 最新のスナップショットは破損しているが、古いスナップショットは引き続き使用できる。
• 整合性のある復旧に必要なインクリメンタルログが無傷で残っている。

古いスナップショットにロールバックするには、以下の手順に従います。

1. Keeper ディレクトリから有効な古いスナップショット (例: snapshot.19) を特定して選択します。
2. より新しいスナップショットとログを削除します。
3. Keeper を再起動し、ログを再生してメタデータの状態を再構築させます。

次のような場合は、この手順に従ってください。

• Keeper のメタデータが失われている、または破損している一方で、テーブルデータは引き続きディスク上に存在している
• ZooKeeper/Keeper のメタデータが欠落しているため、テーブルが読み取り専用モードに切り替わっている
• ローカルで利用可能なデータパーツに基づいて、Keeper 内のメタデータを再作成する必要がある

メタデータを復元するには、以下の手順に従います。

1. テーブルデータが、config の <path> で設定されたローカルの clickHouse-server データパスに存在することを確認します (デフォルトは /var/lib/clickhouse/data/) 。

2. 影響を受ける各テーブルに対して、次を実行します。

SYSTEM RESTART REPLICA [db.]table_name;
SYSTEM RESTORE REPLICA [db.]table_name;

3. データベースレベルで復旧する場合 (Replicated データベースエンジンを使用している場合) :

SYSTEM RESTORE DATABASE REPLICA db_name;

4. 同期が完了するまで待ちます:

SYSTEM SYNC REPLICA [db.]table_name;

5. is_readonly = 0 になっていることを system.replicas で確認し、system.detached_parts を監視して復旧を検証します

次のような場合は、この手順に従ってください。

• エラーがクラスター内の単一のレプリカで発生しており、そのレプリカの Keeper 内のメタデータが破損している、または不整合が生じている
• "Part XXXXX intersects previous part YYYYY" のようなエラーが発生する
• ローカルデータを保持したまま、レプリカの Keeper メタデータを完全にリセットする必要がある

メタデータを削除して再作成するには、以下の手順に従ってください。

1. 影響を受けているレプリカで、テーブルをデタッチします。

DETACH TABLE [db.]table_name;

2. Keeper からレプリカのメタデータを削除します (任意のレプリカで実行) :

SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/{shard}/table_name';

適切な ZooKeeper パスを見つけるには:

SELECT zookeeper_path, replica_name FROM system.replicas WHERE table = 'table_name';

3. テーブルを再アタッチします (読み取り専用モードになります) :

ATTACH TABLE [db.]table_name;

4. レプリカのメタデータを復元します:

SYSTEM RESTORE REPLICA [db.]table_name;

5. 他のレプリカと同期します：

SYSTEM SYNC REPLICA [db.]table_name;

6. 復旧後、すべてのレプリカで system.detached_parts を確認します

代替: force_restore_data フラグを使用する

サーバー起動時にすべてのレプリケートテーブルを自動復旧するには、次の手順を実行します。

1. ClickHouseサーバー を停止します
2. 復旧フラグを作成します:

sudo -u clickhouse touch /var/lib/clickhouse/flags/force_restore_data

3. ClickHouseサーバーを起動します
4. サーバーは自動的にフラグを削除し、すべてのレプリケートテーブルを復元します
5. ログで復旧の進行状況を監視します

この方法は、複数のテーブルを同時に復旧する必要がある場合に有効です。

次の場合は、この手順に従ってください。

• 復旧に使用できる有効なスナップショット、ログ、またはバックアップがない。
• Keeper クラスター全体とそのメタデータを再作成する必要がある。

Keeper クラスターを再構築するには、以下の手順に従ってください。

1. ClickHouse クラスターと Keeper クラスターを完全に停止します。
2. スナップショットとログのディレクトリをクリーンアップして、各 Keeper ノードをリセットします。
3. 1 つの Keeper ノードをリーダーとして初期化し、他のノードを段階的に追加します。
4. 外部の記録が利用できる場合は、メタデータを再インポートします。