Como se recuperar de um snapshot corrompido do Keeper

Snapshots corrompidos ou inválidos do ClickHouse Keeper podem causar instabilidade significativa no sistema, como inconsistências de metadados, tabelas em modo somente leitura, esgotamento de recursos ou backups com falha. Este artigo aborda:

O que são snapshots e onde encontrá-los
Como o problema se manifesta
Possíveis estratégias de recuperação e o que cada uma significa

Visão geral dos snapshots do Keeper

O que é um snapshot?

Um snapshot é um estado serializado dos dados internos do Keeper (como metadados sobre clusters, caminhos de coordenação de tabelas e configurações) em um ponto específico no tempo. Snapshots são essenciais para ressincronizar nós do Keeper em um cluster, recuperar metadados durante falhas e dar suporte a processos de inicialização ou reinicialização que dependem de um estado conhecido e íntegro do Keeper.

Onde posso encontrar snapshots?

Os snapshots são armazenados como arquivos no sistema de arquivos local dos nós do Keeper. Por padrão, eles ficam em /var/lib/clickhouse/coordination/snapshots/ ou no caminho personalizado definido por snapshot_storage_path no arquivo keeper_server.xml. Os snapshots são nomeados sequencialmente (por exemplo, snapshot.23), e os mais recentes têm números maiores. Em clusters com vários nós, cada nó do Keeper tem seu próprio diretório de snapshots.

A consistência dos snapshots entre os nós é fundamental para a recuperação.

Principais sintomas e manifestações de snapshots corrompidos do Keeper

A tabela abaixo detalha alguns sintomas e manifestações comuns de snapshots corrompidos do Keeper:

Categoria	Tipo de problema	O que observar
Problemas operacionais	Modo somente leitura	As tabelas passam inesperadamente para o modo somente leitura
	Falhas de consulta	Falhas persistentes de consulta com erros `Coordination::Exception`
Corrupção de metadados	Metadados desatualizados	Tabelas removidas não são refletidas; falhas de operação devido a metadados obsoletos
Sobrecarga de recursos	Esgotamento de recursos do sistema	Nós do Keeper consomem CPU, memória ou espaço em disco em excesso; possível indisponibilidade
	Disco cheio	Disco cheio durante a criação do snapshot
Backup e restauração	Falhas de backup	Backups falham devido a metadados do Keeper ausentes ou inconsistentes
Criação/transferência de snapshots	Falha do Keeper	Falha do Keeper no meio da criação do snapshot (procure erros “SEGFAULT”)
	Corrupção na transferência de snapshot	Corrupção durante a transferência de snapshot entre réplicas
	Condição de corrida	Condição de corrida durante a compactação de log - thread de commit em segundo plano acessando logs excluídos
	Sincronização de rede	Problemas de rede impedindo a sincronização de snapshots do líder para os seguidores

Indicadores nos logs: Antes de diagnosticar corrupção de snapshot, verifique os logs do Keeper em busca de padrões de erro específicos:

Tipo de log	O que observar
Erros de corrupção 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` • Falhas de serialização/carregamento de snapshot durante a inicialização
Outros problemas do Keeper	• `Coordination::Exception` • `Zookeeper::Session Timeout` • Problemas de sincronização ou eleição • Condições de corrida na compactação de log

Recuperando snapshots corrompidos do Keeper

Antes de alterar qualquer arquivo, sempre:

Pare todos os nós do Keeper para evitar mais corrupção
Faça backup de tudo copiando todo o diretório de coordenação para um local seguro
Verifique o quorum do cluster para garantir que pelo menos um nó tenha dados íntegros

1. Restaurar a partir de um backup existente

Você deve seguir este processo se:

A corrupção dos metadados do Keeper ou dos snapshots tornar os dados atuais irrecuperáveis.
Houver um backup com um estado íntegro e conhecido do Keeper.

Siga as etapas abaixo para restaurar um backup existente:

Localize e valide o backup mais recente quanto à consistência dos metadados.
Desligue os serviços do ClickHouse e do Keeper.
Substitua os snapshots e logs com falha pelos do diretório de backup.
Reinicie o cluster do Keeper e valide a sincronização dos metadados.

Faça backups regularmenteSe os backups estiverem desatualizados, você poderá perder alterações recentes nos metadados. Por esse motivo, recomendamos fazer backups regularmente.

2. Reverter para um snapshot mais antigo

Você deve seguir este processo quando:

Snapshots recentes estiverem corrompidos, mas os mais antigos ainda puderem ser usados.
Os logs incrementais estiverem íntegros para uma recuperação consistente.

Siga as etapas abaixo para reverter para um snapshot mais antigo:

Identifique e selecione um snapshot válido mais antigo (por exemplo, snapshot.19) no diretório do Keeper.
Remova os snapshots e logs mais recentes.
Reinicie o Keeper para que ele reaplique os logs e reconstrua o estado dos metadados.

Risco de desincronização de metadadosHá risco de desincronização de metadados se snapshots e logs estiverem ausentes ou incompletos.

3. Restaure os metadados usando `SYSTEM RESTORE REPLICA`

Você deve seguir este processo quando:

Os metadados do Keeper forem perdidos ou corrompidos, mas os dados da tabela ainda existirem em disco
As tabelas tiverem passado para o modo somente leitura devido à ausência de metadados do ZooKeeper/Keeper
Você precisar recriar os metadados no Keeper com base nas partes de dados disponíveis localmente

Siga as etapas abaixo para restaurar os metadados:

Verifique se os dados da tabela existem localmente no caminho de dados do clickhouse-server, definido por <path> na config. (/var/lib/clickhouse/data/ por padrão)
Para cada tabela afetada, execute:

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

Para recuperação no nível do banco de dados (se estiver usando o Replicated database engine):

SYSTEM RESTORE DATABASE REPLICA db_name;

Aguarde a sincronização ser concluída:

SYSTEM SYNC REPLICA [db.]table_name;

Verifique a recuperação conferindo system.replicas para is_readonly = 0 e monitorando system.detached_parts

Como funcionaSYSTEM RESTORE REPLICA desanexa todas as partes existentes, recria os metadados no Keeper (como se fosse uma nova tabela vazia) e, em seguida, anexa novamente todas as partes. Isso evita baixar os dados novamente pela rede.

Pré-requisitosIsso só funciona se as partes de dados locais estiverem intactas. Se os dados também estiverem corrompidos, use a estratégia nº 5 (reconstruir o cluster).

4. Remover e recriar os metadados da réplica no Keeper

Você deve seguir este processo quando:

O erro ocorre em uma única réplica do cluster e há metadados corrompidos ou inconsistentes no Keeper
Você encontrar erros como “Part XXXXX intersects previous part YYYYY”
Você precisa redefinir completamente os metadados da réplica no Keeper, preservando os dados locais

Siga as etapas abaixo para remover e recriar os metadados:

Na réplica afetada, desanexe a tabela:

DETACH TABLE [db.]table_name;

Remova os metadados da réplica do Keeper (execute em qualquer réplica):

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

Para encontrar o caminho correto no ZooKeeper:

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

Anexe novamente a tabela (ela ficará em modo somente leitura):

ATTACH TABLE [db.]table_name;

Restaure os metadados da réplica:

SYSTEM RESTORE REPLICA [db.]table_name;

Sincronize-se com as outras réplicas:

SYSTEM SYNC REPLICA [db.]table_name;

Verifique system.detached_parts em todas as réplicas após a recuperação

Execute em todas as réplicas afetadasSe a corrupção afetar várias réplicas, repita estas etapas em cada uma, sequencialmente.

Para o banco de dados inteiroSe estiver usando um banco de dados Replicated, você pode usar SYSTEM DROP REPLICA ... FROM DATABASE db_name.

Alternativa: usar a flag force_restore_data Para a recuperação automática de todas as tabelas replicadas na inicialização do servidor:

Pare o servidor ClickHouse
Crie a flag de recuperação:

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

Inicie o servidor ClickHouse
O servidor removerá automaticamente a flag e restaurará todas as tabelas replicadas
Monitore os logs para acompanhar o progresso da recuperação

Essa abordagem é útil quando várias tabelas precisam ser recuperadas simultaneamente.

5. Reconstruir o cluster do Keeper

Você deve seguir este processo quando:

Não houver snapshots, logs ou backups válidos disponíveis para recuperação.
For necessário recriar todo o cluster do Keeper e seus metadados.

Siga as etapas abaixo para reconstruir o cluster do Keeper:

Pare completamente os clusters do ClickHouse e do Keeper.
Redefina cada nó do Keeper limpando os diretórios de snapshot e log.
Inicialize um nó do Keeper como líder e adicione os outros nós de forma incremental.
Reimporte os metadados, se estiverem disponíveis em registros externos.

Processo demoradoEste processo é demorado e traz o risco de indisponibilidade prolongada. Será necessária a reconstrução total dos dados.

​Visão geral dos snapshots do Keeper

​O que é um snapshot?

​Onde posso encontrar snapshots?

​Principais sintomas e manifestações de snapshots corrompidos do Keeper

​Recuperando snapshots corrompidos do Keeper

​1. Restaurar a partir de um backup existente

​2. Reverter para um snapshot mais antigo

​3. Restaure os metadados usando SYSTEM RESTORE REPLICA

​4. Remover e recriar os metadados da réplica no Keeper

​5. Reconstruir o cluster do Keeper

Visão geral dos snapshots do Keeper

O que é um snapshot?

Onde posso encontrar snapshots?

Principais sintomas e manifestações de snapshots corrompidos do Keeper

Recuperando snapshots corrompidos do Keeper

1. Restaurar a partir de um backup existente

2. Reverter para um snapshot mais antigo

3. Restaure os metadados usando `SYSTEM RESTORE REPLICA`

4. Remover e recriar os metadados da réplica no Keeper

5. Reconstruir o cluster do Keeper