Skip to main content
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:

​
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: Indicadores nos logs: Antes de diagnosticar corrupção de snapshot, verifique os logs do Keeper em busca de padrões de erro específicos:

​
Recuperando snapshots corrompidos do Keeper

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

​
  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:
  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.
Faça backups regularmenteSe os backups estiverem desatualizados, você poderá perder alterações recentes nos metadados. Por esse motivo, recomendamos fazer backups regularmente.

​
  1. 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:
  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.
Risco de desincronização de metadadosHá risco de desincronização de metadados se snapshots e logs estiverem ausentes ou incompletos.

​
  1. 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:
  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:
  1. Para recuperação no nível do banco de dados (se estiver usando o mecanismo de banco de dados Replicated):
  1. Aguarde a sincronização ser concluída:
  1. 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).

​
  1. 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:
  1. Na réplica afetada, desanexe a tabela:
  1. Remova os metadados da réplica do Keeper (execute em qualquer réplica):
Para encontrar o caminho correto no ZooKeeper:
  1. Anexe novamente a tabela (ela ficará em modo somente leitura):
  1. Restaure os metadados da réplica:
  1. Sincronize-se com as outras réplicas:
  1. 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:
  1. Pare o servidor ClickHouse
  2. Crie a flag de recuperação:
  1. Inicie o servidor ClickHouse
  2. O servidor removerá automaticamente a flag e restaurará todas as tabelas replicadas
  3. Monitore os logs para acompanhar o progresso da recuperação
Essa abordagem é útil quando várias tabelas precisam ser recuperadas simultaneamente.

​
  1. 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:
  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.
Processo demoradoEste processo é demorado e traz o risco de indisponibilidade prolongada. Será necessária a reconstrução total dos dados.

​
  1. Remover nós órfãos do snapshot na inicialização

Um nó órfão é um nó cujo pai não está presente no snapshot. O Keeper se recusa a carregar esse snapshot e registra no log Failure to load from latest snapshot with index. Siga este procedimento quando:
  • O snapshot estiver estruturalmente danificado exatamente dessa forma e
  • Não houver nenhum backup válido ou snapshot mais antigo disponível (as estratégias 1 e 2 são preferíveis sempre que forem aplicáveis).
Defina as duas configurações a seguir em <keeper_server> e reinicie o nó:
Requer o armazenamento de nós em memóriaA limpeza só é implementada pelo armazenamento de nós em memória. Se use_lsmt_storage estiver habilitado em <coordination_settings>, o Keeper se recusa a iniciar com remove_orphaned_nodes_on_startup definido: desative use_lsmt_storage para a reinicialização de recuperação e habilite-o novamente após uma inicialização bem-sucedida.
Em seguida, o Keeper descarta as subárvores órfãs e inicia. A remoção é registrada no log no nível WARNING em duas linhas: uma com o número total de nós removidos e as raízes das subárvores órfãs removidas, e outra com os caminhos ausentes do snapshot que delimitam a região danificada. Os descendentes abaixo dessas raízes também são removidos, mas não são listados individualmente. Após verificar o final do log local, o Keeper grava a árvore reparada em um novo arquivo de snapshot no mesmo índice de log antes de iniciar o Raft. Reparos concluídos têm precedência sobre cópias mais antigas nesse índice, de modo que uma recuperação interrompida pode ser retomada sem selecionar o snapshot danificado. Novos seguidores recebem o snapshot reparado, e as reinicializações seguintes não precisam mais da remoção de órfãos habilitada. O snapshot original e quaisquer cópias do mesmo índice são preservados com o prefixo orphaned_ no nome do arquivo; esses arquivos são ignorados no carregamento de snapshots e na retenção automática. Mantenha-os para diagnóstico e remova-os manualmente quando não forem mais necessários. A reinicialização de recuperação exige espaço em disco adicional para o snapshot reparado e para o backup do original. Se a gravação do snapshot reparado, a sincronização das alterações no diretório local ou a preservação dos originais falhar, o Keeper se recusa a iniciar. Uma inicialização posterior conclui qualquer arquivamento interrompido.
Repara apenas o estado localIsso remove nós da cópia dos dados deste nó. Os peers que ainda mantêm esses nós passarão a divergir dele e, com digest_enabled definido como false, nada detectará essa divergência depois. Trate isso como uma recuperação de um único nó ou aplique-a a todos os nós do cluster. Restaure ambas as configurações para os valores padrão assim que o nó estiver ativo.
O Keeper se recusa propositalmente a iniciar se uma entrada de log local acima do snapshot fizer referência à região danificada: um nó removido, qualquer coisa abaixo dele ou o pai direto de uma subárvore removida. O pai direto conta como conflito porque seu conjunto de filhos não corresponde mais à árvore sobre a qual o log foi gravado, de modo que mesmo uma entrada que apenas o afete — incluindo a criação ou remoção de um nó irmão sob ele, o que atualiza seus contadores de filhos reparados — poderia ser reaplicada de forma diferente. Entradas que consultam apenas a existência, a versão ou os ids de modificação do pai, como um Check, um CheckNotExists, um CheckStat que não compara numChildren nem cversion, um Set ou SetACL que reescreve apenas os próprios dados ou a ACL do pai, ou os watches de dados, de filhos e de existência que um cliente registra novamente após uma reconexão, não são afetadas e não bloqueiam a recuperação; watches persistentes registrados novamente por um cliente nunca consultam a árvore e nunca a bloqueiam. Os nós mais acima na cadeia não são afetados: eles mantêm exatamente os mesmos dados, versão e filhos que têm em um peer saudável, portanto uma entrada que afete apenas um desses nós é reaplicada de forma idêntica e não bloqueia a recuperação. A exceção é uma entrada que percorre toda a subárvore abaixo do seu caminho, como uma remoção recursiva ou uma listagem recursiva: essas entradas de fato enxergam os nós removidos e entram em conflito em qualquer nível, a menos que o Keeper rejeite a requisição antes de consultar a árvore (por exemplo, uma remoção recursiva de /). O mesmo vale para o encerramento de uma sessão (Close) no final do log quando essa sessão possuía um nó efêmero removido, ou possui um nó efêmero remanescente diretamente sob esse pai: encerrar a sessão remove seus nós efêmeros e atualiza os contadores dos respectivos pais. Reaplicar qualquer uma dessas entradas sobre a árvore reparada produziria silenciosamente um estado diferente. Nesse caso, recupere o nó a partir de um peer saudável: pare-o, limpe seu diretório de coordenação e deixe-o ressincronizar a partir do líder, ou use a estratégia 1 ou 2.