Cómo recuperarse de una instantánea corrupta de Keeper

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:

• Qué son las instantáneas y dónde encontrarlas
• Cómo se manifiesta el problema
• Las posibles estrategias de recuperación y qué implica cada una

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.

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 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:

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

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.

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.

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:

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

3. Para la recuperación a nivel de la base de datos (si usa el motor de base de datos Replicated):

SYSTEM RESTORE DATABASE REPLICA db_name;

4. Espere a que se complete la sincronización:

SYSTEM SYNC REPLICA [db.]table_name;

5. Verifica la recuperación comprobando en system.replicas que is_readonly = 0 y supervisando system.detached_parts

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:

DETACH TABLE [db.]table_name;

2. Elimine los metadatos de la réplica en Keeper (ejecute en cualquier réplica):

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

Para encontrar la ruta correcta de ZooKeeper:

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

3. Vuelva a adjuntar la tabla (quedará en modo de solo lectura):

ATTACH TABLE [db.]table_name;

4. Restaura los metadatos de la réplica:

SYSTEM RESTORE REPLICA [db.]table_name;

5. Sincronícese con las demás réplicas:

SYSTEM SYNC REPLICA [db.]table_name;

6. Verifique system.detached_parts en todas las réplicas después de la recuperación

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:

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

3. Inicie el servidor de ClickHouse
4. El servidor eliminará automáticamente el indicador y restaurará todas las tablas replicadas
5. Supervise los logs para seguir el progreso de la recuperación

Este enfoque resulta útil cuando varias tablas necesitan recuperarse simultáneamente.

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.