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

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.

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 tabela abaixo detalha alguns sintomas e manifestações comuns de snapshots corrompidos do Keeper:

Indicadores nos logs:

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

Antes de alterar qualquer arquivo, sempre:

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

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:

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

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:

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

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:

1. 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)

2. Para cada tabela afetada, execute:

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

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

SYSTEM RESTORE DATABASE REPLICA db_name;

4. Aguarde a sincronização ser concluída:

SYSTEM SYNC REPLICA [db.]table_name;

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

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:

1. Na réplica afetada, desanexe a tabela:

DETACH TABLE [db.]table_name;

2. 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';

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

ATTACH TABLE [db.]table_name;

4. Restaure os metadados da réplica:

SYSTEM RESTORE REPLICA [db.]table_name;

5. Sincronize-se com as outras réplicas:

SYSTEM SYNC REPLICA [db.]table_name;

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

Alternativa: usar a flag force_restore_data

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

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

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

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

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

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:

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