Comment récupérer après un snapshot Keeper corrompu

Des snapshots ClickHouse Keeper corrompus ou défectueux peuvent provoquer une forte instabilité du système, notamment des incohérences de métadonnées, des tables en lecture seule, un épuisement des ressources ou des échecs de sauvegarde. Cet article couvre :

Ce que sont les snapshots et où les trouver
Comment le problème se manifeste
Les stratégies de récupération possibles et ce que chacune d’elles implique

Vue d’ensemble des snapshots de Keeper

Qu’est-ce qu’un snapshot ?

Un snapshot est un état sérialisé des données internes de Keeper (comme les métadonnées sur les clusters, les chemins de coordination des tables et les configurations) à un instant donné. Les snapshots sont essentiels pour resynchroniser les nœuds Keeper au sein d’un cluster, restaurer les métadonnées en cas de défaillance, ainsi que pour les processus de démarrage ou de redémarrage qui s’appuient sur un état valide connu de Keeper.

Où puis-je trouver des snapshots ?

Les snapshots sont stockés sous forme de fichiers sur le système de fichiers local des nœuds Keeper. Par défaut, ils sont enregistrés dans /var/lib/clickhouse/coordination/snapshots/, ou dans le chemin personnalisé défini par snapshot_storage_path dans votre fichier keeper_server.xml. Les snapshots sont numérotés de manière incrémentielle (par exemple, snapshot.23), les plus récents portant des numéros plus élevés. Dans les clusters multinœuds, chaque nœud Keeper possède son propre répertoire de snapshots.

La cohérence des snapshots entre les nœuds est essentielle à la récupération.

Principaux symptômes et manifestations de snapshots Keeper corrompus

Le tableau ci-dessous présente quelques symptômes et manifestations courants de snapshots Keeper corrompus :

Catégorie	Type de problème	À surveiller
Problèmes opérationnels	Mode lecture seule	Les tables passent inopinément en mode lecture seule
	Échecs de requête	Échecs persistants de requêtes avec des erreurs `Coordination::Exception`
Corruption des métadonnées	Métadonnées obsolètes	Tables supprimées non prises en compte ; échecs d’opération dus à des métadonnées obsolètes
Surcharge des ressources	Épuisement des ressources système	Les nœuds Keeper consomment excessivement le CPU, la mémoire ou l’espace disque ; risque d’indisponibilité
	Disque plein	Disque saturé pendant la création du snapshot
Sauvegarde et restauration	Échecs de sauvegarde	Les sauvegardes échouent en raison de métadonnées Keeper manquantes ou incohérentes
Création/transfert de snapshot	Crash de Keeper	Crash de Keeper en cours de snapshot (recherchez les erreurs « SEGFAULT »)
	Corruption du transfert de snapshot	Corruption lors du transfert du snapshot entre les répliques
	Race condition	Race condition pendant la compaction des logs - thread de commit en arrière-plan accédant à des logs supprimés
	Synchronisation réseau	Problèmes réseau empêchant la synchronisation du snapshot depuis le leader vers les followers

Indicateurs dans les logs : Avant de diagnostiquer une corruption de snapshot, vérifiez les logs Keeper afin d’identifier des motifs d’erreur spécifiques :

Type de log	À surveiller
Erreurs de corruption de snapshot	• `Aborting because of failure to load from latest snapshot with index` • `Failure to load from latest snapshot with index {}: {}. Manual intervention is necessary for recovery` • `Failed to preprocess stored log at index {}, aborting to avoid inconsistent state` • Échecs de sérialisation/chargement du snapshot au démarrage
Autres problèmes Keeper	• `Coordination::Exception` • `Zookeeper::Session Timeout` • Problèmes de synchronisation ou d’élection • Race conditions lors de la compaction des logs

Récupération après des snapshots Keeper corrompus

Avant de toucher aux fichiers, veillez toujours à :

Arrêter tous les nœuds Keeper pour éviter toute corruption supplémentaire
Sauvegarder l’ensemble en copiant l’intégralité du répertoire de coordination dans un emplacement sûr
Vérifier le quorum du cluster afin de vous assurer qu’au moins un nœud dispose de données intactes

1. Restaurer à partir d’une sauvegarde existante

Suivez cette procédure si :

La corruption des métadonnées de Keeper ou d’un snapshot rend les données actuelles irrécupérables.
Une sauvegarde existe avec un état Keeper connu comme sain.

Suivez les étapes ci-dessous pour restaurer une sauvegarde existante :

Repérez et validez la sauvegarde la plus récente afin de vérifier la cohérence des métadonnées.
Arrêtez les services ClickHouse et Keeper.
Remplacez les snapshots et les logs défectueux par ceux du répertoire de sauvegarde.
Redémarrez le cluster Keeper et vérifiez la synchronisation des métadonnées.

Sauvegardez régulièrementSi les sauvegardes ne sont pas à jour, vous risquez de perdre des modifications récentes des métadonnées. C’est pourquoi nous vous recommandons d’effectuer des sauvegardes régulièrement.

2. Revenir à un snapshot plus ancien

Suivez cette procédure dans les cas suivants :

Des snapshots récents sont corrompus, mais d’anciens snapshots restent exploitables.
Les logs incrémentiels sont intacts, ce qui permet une restauration cohérente.

Suivez les étapes ci-dessous pour revenir à un snapshot plus ancien :

Identifiez et sélectionnez un ancien snapshot valide (par exemple, snapshot.19) dans le répertoire Keeper.
Supprimez les snapshots et les logs plus récents.
Redémarrez Keeper afin qu’il rejoue les logs pour reconstruire l’état des métadonnées.

Risque de désynchronisation des métadonnéesIl existe un risque de désynchronisation des métadonnées si des snapshots et des logs sont manquants ou incomplets.

3. Restaurer les métadonnées à l’aide de `SYSTEM RESTORE REPLICA`

Vous devez suivre ce processus dans les cas suivants :

les métadonnées de Keeper sont perdues ou corrompues, mais les données de la table existent toujours sur le disque
les tables sont passées en mode lecture seule en raison de métadonnées ZooKeeper/Keeper manquantes
vous devez recréer les métadonnées dans Keeper à partir des parties de données disponibles localement

Suivez les étapes ci-dessous pour restaurer les métadonnées :

Vérifiez que les données de la table existent localement dans le chemin de données de votre clickhouse-server, défini par <path> dans votre configuration. (/var/lib/clickhouse/data/ par défaut)
Pour chaque table concernée, exécutez :

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

Pour une récupération au niveau de la base de données (si vous utilisez le moteur de base de données Replicated) :

SYSTEM RESTORE DATABASE REPLICA db_name;

Attendez la fin de la synchronisation :

SYSTEM SYNC REPLICA [db.]table_name;

Vérifiez la récupération en vérifiant que system.replicas a is_readonly = 0 et en surveillant system.detached_parts

Comment cela fonctionneSYSTEM RESTORE REPLICA détache toutes les parts existantes, recrée les métadonnées dans Keeper (comme s’il s’agissait d’une nouvelle table vide), puis réattache toutes les parts. Cela évite de retélécharger les données via le réseau.

PrérequisCela fonctionne uniquement si les parties de données locales sont intactes. Si les données sont également corrompues, utilisez plutôt la stratégie #5 (reconstruire le cluster).

4. Supprimer et recréer les métadonnées de la réplique dans Keeper

Vous devez suivre cette procédure dans les cas suivants :

L’erreur se produit sur une seule réplique du cluster et les métadonnées correspondantes dans Keeper sont corrompues ou incohérentes
Vous rencontrez des erreurs du type “Part XXXXX intersects previous part YYYYY”
Vous devez réinitialiser complètement les métadonnées d’une réplique dans Keeper tout en conservant les données locales

Suivez les étapes ci-dessous pour supprimer et recréer les métadonnées :

Sur la réplique affectée, détachez la table :

DETACH TABLE [db.]table_name;

Supprimez de Keeper les métadonnées de la réplique (à exécuter sur n’importe quelle réplique) :

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

Pour trouver le bon chemin ZooKeeper :

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

Réattachez la table (elle sera en mode lecture seule) :

ATTACH TABLE [db.]table_name;

Restaurez les métadonnées de la réplique :

SYSTEM RESTORE REPLICA [db.]table_name;

Synchronisez-vous avec les autres répliques :

SYSTEM SYNC REPLICA [db.]table_name;

Vérifiez system.detached_parts sur toutes les répliques après la récupération

Exécutez cette opération sur toutes les répliques affectéesSi la corruption affecte plusieurs répliques, répétez ces étapes sur chacune d’elles, l’une après l’autre.

Pour toute la base de donnéesSi vous utilisez une base de données Replicated, vous pouvez utiliser SYSTEM DROP REPLICA ... FROM DATABASE db_name à la place.

Alternative : utiliser le flag force_restore_data Pour récupérer automatiquement toutes les tables répliquées au démarrage du serveur :

Arrêtez le serveur ClickHouse
Créez le flag de récupération :

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

Démarrez le serveur ClickHouse
Le serveur supprimera automatiquement le flag et restaurera toutes les tables répliquées
Surveillez les logs pour suivre la progression de la restauration

Cette approche est utile lorsque plusieurs tables doivent être restaurées simultanément.

5. Reconstruire le cluster Keeper

Vous devez suivre ce processus lorsque :

Ni snapshots, ni logs, ni sauvegardes valides ne sont disponibles pour la restauration.
Vous devez recréer l’intégralité du cluster Keeper et de ses métadonnées.

Suivez les étapes ci-dessous pour reconstruire le cluster Keeper :

Arrêtez complètement les clusters ClickHouse et Keeper.
Réinitialisez chaque nœud Keeper en nettoyant les répertoires de snapshots et de logs.
Initialisez un nœud Keeper comme leader, puis ajoutez progressivement les autres nœuds.
Réimportez les métadonnées si elles sont disponibles depuis des enregistrements externes.

Processus longCe processus est long et comporte un risque d’indisponibilité prolongée. Une reconstruction complète des données est requise.

​Vue d’ensemble des snapshots de Keeper

​Qu’est-ce qu’un snapshot ?

​Où puis-je trouver des snapshots ?

​Principaux symptômes et manifestations de snapshots Keeper corrompus

​Récupération après des snapshots Keeper corrompus

​1. Restaurer à partir d’une sauvegarde existante

​2. Revenir à un snapshot plus ancien

​3. Restaurer les métadonnées à l’aide de SYSTEM RESTORE REPLICA

​4. Supprimer et recréer les métadonnées de la réplique dans Keeper

​5. Reconstruire le cluster Keeper

Vue d’ensemble des snapshots de Keeper

Qu’est-ce qu’un snapshot ?

Où puis-je trouver des snapshots ?

Principaux symptômes et manifestations de snapshots Keeper corrompus

Récupération après des snapshots Keeper corrompus

1. Restaurer à partir d’une sauvegarde existante

2. Revenir à un snapshot plus ancien

3. Restaurer les métadonnées à l’aide de `SYSTEM RESTORE REPLICA`

4. Supprimer et recréer les métadonnées de la réplique dans Keeper

5. Reconstruire le cluster Keeper