Skip to main content
Las instantáneas corruptas o defectuosas de ClickHouse Keeper pueden provocar una inestabilidad importante en el sistema, como inconsistencias de metadatos, tablas en estado de solo lectura, agotamiento de recursos o fallos en las copias de seguridad. En este artículo se explica:

​
Descripción general de las instantáneas de Keeper

​
¿Qué es una instantánea?

Una instantánea es un estado serializado de los datos internos de Keeper (como metadatos sobre clústeres, rutas de coordinación de tablas y configuraciones) en un momento determinado. Las instantáneas son fundamentales para volver a sincronizar los nodos de Keeper dentro de un clúster, recuperar metadatos durante fallos y realizar procesos de arranque o reinicio que dependen de un estado válido y conocido de Keeper.

​
¿Dónde puedo encontrar las instantáneas?

Las instantáneas se almacenan como archivos en el sistema de archivos local de los nodos de Keeper. De forma predeterminada, se guardan en /var/lib/clickhouse/coordination/snapshots/ o en la ruta personalizada especificada por snapshot_storage_path en su archivo keeper_server.xml. Las instantáneas se nombran de forma incremental (por ejemplo, snapshot.23), y las más recientes tienen números más altos. En clústeres multinodo, cada nodo de Keeper tiene su propio directorio de instantáneas.
La consistencia de las instantáneas entre los nodos es fundamental para la recuperación.

​
Síntomas y manifestaciones clave de instantáneas corruptas de Keeper

La siguiente tabla detalla algunos síntomas y manifestaciones habituales de instantáneas corruptas de Keeper: Indicadores en los logs: Antes de diagnosticar corrupción en instantáneas, revise los logs de Keeper para detectar patrones de error específicos:

​
Recuperación ante instantáneas corruptas de Keeper

Antes de tocar cualquier archivo, haz siempre lo siguiente:
  1. Detén todos los nodos de Keeper para evitar que la corrupción se agrave
  2. Haz una copia de seguridad de todo copiando el directorio completo de coordinación a una ubicación segura
  3. Verifica el cuórum del clúster para asegurarte de que al menos un nodo tenga datos en buen estado

​
1. Restaurar desde una copia de seguridad existente

Debe seguir este proceso si:
  • La corrupción de los metadatos o de una instantánea de Keeper hace que los datos actuales sean irrecuperables.
  • Existe una copia de seguridad con un estado de Keeper cuya validez se conoce.
Siga los pasos que se indican a continuación para restaurar una copia de seguridad existente:
  1. Localice y valide la copia de seguridad más reciente para comprobar la consistencia de los metadatos.
  2. Detenga los servicios de ClickHouse y Keeper.
  3. Sustituya las instantáneas y los logs dañados por los del directorio de la copia de seguridad.
  4. Reinicie el clúster de Keeper y valide la sincronización de los metadatos.
Haga copias de seguridad con regularidadSi las copias de seguridad están desactualizadas, podría perder cambios recientes en los metadatos. Por este motivo, recomendamos hacer copias de seguridad con regularidad.

​
2. Revertir a una instantánea anterior

Conviene seguir este proceso cuando:
  • Las instantáneas recientes estén dañadas, pero las anteriores sigan siendo utilizables.
  • Los logs incrementales estén intactos para garantizar una recuperación coherente.
Siga estos pasos para revertir a una instantánea anterior:
  1. Identifique y seleccione una instantánea anterior válida (por ejemplo, snapshot.19) en el directorio de Keeper.
  2. Elimine las instantáneas y los logs más recientes.
  3. Reinicie Keeper para que reprocese los logs y reconstruya el estado de los metadatos.
Riesgo de desincronización de metadatosExiste riesgo de desincronización de metadatos si faltan instantáneas y logs, o si están incompletos.

​
3. Restaurar metadatos con SYSTEM RESTORE REPLICA

Debes seguir este proceso cuando:
  • Los metadatos de Keeper se han perdido o están corruptos, pero los datos de la tabla siguen existiendo en disco
  • Las tablas han pasado a modo de solo lectura debido a la ausencia de metadatos de ZooKeeper/Keeper
  • Necesitas volver a crear los metadatos en Keeper a partir de las partes de datos disponibles localmente
Sigue los pasos que se indican a continuación para restaurar los metadatos:
  1. Verifica que los datos de la tabla existan localmente en la ruta de datos de tu clickHouse-server, definida por <path> en tu configuración. (/var/lib/clickhouse/data/ de forma predeterminada)
  2. Para cada tabla afectada, ejecuta:
  1. Para la recuperación a nivel de la base de datos (si usa el motor de base de datos Replicated):
  1. Espere a que se complete la sincronización:
  1. Verifica la recuperación comprobando en system.replicas que is_readonly = 0 y supervisando system.detached_parts
Cómo funcionaSYSTEM RESTORE REPLICA desadjunta todas las partes existentes, recrea los metadatos en Keeper (como si fuera una tabla nueva vacía) y luego vuelve a adjuntar todas las partes. Esto evita tener que volver a descargar los datos por la red.
Requisitos previosEsto solo funciona si las partes de datos locales están intactas. Si los datos también están corruptos, usa en su lugar la estrategia n.º 5 (reconstruir el cluster).

​
4. Eliminar y volver a crear los metadatos de la réplica en Keeper

Debes seguir este proceso cuando:
  • El error se produce en una sola réplica del clúster y esta tiene metadatos dañados o incoherentes en Keeper
  • Encuentras errores como “Part XXXXX intersects previous part YYYYY”
  • Necesitas restablecer por completo los metadatos de una réplica en Keeper mientras conservas los datos locales
Sigue los pasos a continuación para eliminar y volver a crear los metadatos:
  1. En la réplica afectada, desvincula la tabla:
  1. Elimine los metadatos de la réplica en Keeper (ejecute en cualquier réplica):
Para encontrar la ruta correcta de ZooKeeper:
  1. Vuelva a adjuntar la tabla (quedará en modo de solo lectura):
  1. Restaura los metadatos de la réplica:
  1. Sincronícese con las demás réplicas:
  1. Verifique system.detached_parts en todas las réplicas después de la recuperación
Ejecute esto en todas las réplicas afectadasSi la corrupción afecta a varias réplicas, repita estos pasos en cada una de ellas de forma secuencial.
Para toda la base de datosSi usa una base de datos Replicated, puede usar SYSTEM DROP REPLICA ... FROM DATABASE db_name como alternativa.
Alternativa: uso del indicador force_restore_data Para la recuperación automática de todas las tablas replicadas al iniciar el servidor:
  1. Detenga el servidor ClickHouse
  2. Cree el indicador de recuperación:
  1. Inicie el servidor de ClickHouse
  2. El servidor eliminará automáticamente el indicador y restaurará todas las tablas replicadas
  3. Supervise los logs para seguir el progreso de la recuperación
Este enfoque resulta útil cuando varias tablas necesitan recuperarse simultáneamente.

​
5. Reconstruir el Keeper clúster

Debe seguir este proceso cuando:
  • No hay instantáneas, logs ni copias de seguridad válidos disponibles para la recuperación.
  • Necesita volver a crear todo el Keeper clúster y sus metadatos.
Siga los pasos a continuación para reconstruir el Keeper clúster:
  1. Detenga por completo los clústeres de ClickHouse y Keeper.
  2. Restablezca cada nodo de Keeper limpiando los directorios de instantáneas y logs.
  3. Inicialice un nodo de Keeper como líder y agregue los demás nodos de forma incremental.
  4. Vuelva a importar los metadatos si están disponibles en registros externos.
Proceso que requiere mucho tiempoEste proceso requiere mucho tiempo y conlleva el riesgo de una interrupción prolongada. Es necesario reconstruir por completo los datos.
Última modificación el 23 de julio de 2026