> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Как восстановиться после поврежденного снимка Keeper

> Статья о том, как восстановиться после поврежденного снимка Keeper: как проявляется проблема, что такое снимок, где его найти и какие стратегии восстановления возможны.

Поврежденные или некорректные снимки ClickHouse Keeper могут приводить к серьезной нестабильности системы, например к несогласованности метаданных, переходу таблиц в состояние только для чтения, исчерпанию ресурсов или сбоям резервного копирования. В этой статье рассматриваются:

* [Что такое снимки и где их найти](#overview)
* [Как проявляется проблема](#symptoms)
* [Возможные стратегии восстановления](#recovery-strategies) и что означает каждая из них

<div id="overview">
  ## Обзор снимков Keeper
</div>

<div id="what-is-snapshot">
  ### Что такое снимок?
</div>

Снимок — это сериализованное состояние внутренних данных Keeper (таких как метаданные о кластерах, путях координации таблиц и конфигурациях) на определённый момент времени. Снимки крайне важны для повторной синхронизации узлов Keeper в кластере, восстановления метаданных при сбоях, а также для процессов запуска и перезапуска, которым требуется заведомо корректное состояние Keeper.

<div id="where-to-find-snapshots">
  ### Где найти снимки?
</div>

Снимки хранятся в виде файлов в локальной файловой системе узлов Keeper. По умолчанию они находятся в `/var/lib/clickhouse/coordination/snapshots/` либо по пользовательскому пути, заданному параметром `snapshot_storage_path` в файле `keeper_server.xml`. Снимки именуются последовательно (например, snapshot.23): чем новее снимок, тем больше его номер.

В многоузловых кластерах у каждого узла Keeper есть свой каталог снимков.

<Note>
  Для восстановления критически важно, чтобы снимки на разных узлах были согласованными.
</Note>

<div id="symptoms">
  ## Основные симптомы и проявления поврежденных снимков Keeper
</div>

В таблице ниже перечислены некоторые распространенные симптомы и проявления поврежденных снимков Keeper:

| **Категория**                              | **Тип проблемы**                | **На что обратить внимание**                                                                         |
| ------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Эксплуатационные проблемы**              | Режим только для чтения         | Таблицы неожиданно переходят в режим только для чтения                                               |
|                                            | Сбои запросов                   | Постоянные сбои запросов с ошибками `Coordination::Exception`                                        |
| **Повреждение метаданных**                 | Устаревшие метаданные           | Удаленные таблицы не отображаются; сбои операций из-за устаревших метаданных                         |
| **Перегрузка ресурсов**                    | Исчерпание системных ресурсов   | Узлы Keeper потребляют чрезмерно много CPU, памяти или дискового пространства; возможен простой      |
|                                            | Диск переполнен                 | Переполнение диска во время создания снимка                                                          |
| **Резервное копирование и восстановление** | Сбои резервного копирования     | Сбой резервного копирования из-за отсутствующих или несогласованных метаданных Keeper                |
| **Создание/передача снимков**              | Сбой Keeper                     | Сбой Keeper во время создания снимка (ищите ошибки "SEGFAULT")                                       |
|                                            | Повреждение при передаче снимка | Повреждение во время передачи снимка между репликами                                                 |
|                                            | Состояние гонки                 | Состояние гонки во время компактации журнала — фоновый поток коммита обращается к удаленным журналам |
|                                            | Сетевая синхронизация           | Сетевые проблемы, мешающие синхронизации снимка от лидера к ведомым узлам                            |

**Признаки в журналах:**

Прежде чем диагностировать повреждение снимка, проверьте **журналы Keeper** на наличие характерных шаблонов ошибок:

| **Тип журнала**               | **На что обратить внимание**                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ошибки повреждения снимка** | • `Aborting because of failure to load from latest snapshot with index`<br />• `Failure to load from latest snapshot with index {}: {}. Manual intervention is necessary for recovery`<br />• `Failed to preprocess stored log at index {}, aborting to avoid inconsistent state`<br />• Сбои сериализации/загрузки снимка при запуске |
| **Другие проблемы Keeper**    | • `Coordination::Exception`<br />• `Zookeeper::Session Timeout`<br />• Проблемы с синхронизацией или выбором лидера<br />• Состояния гонки при компактации журнала                                                                                                                                                                     |

<div id="recovery-strategies">
  ## Восстановление после повреждения снимков Keeper
</div>

Прежде чем работать с какими-либо файлами, обязательно:

1. Остановите все узлы Keeper, чтобы предотвратить дальнейшее повреждение данных
2. Сделайте резервную копию всего содержимого, скопировав весь каталог coordination в безопасное место
3. Проверьте кворум кластера, чтобы убедиться, что хотя бы на одном узле сохранились корректные данные

***

<div id="restore-from-existing-backup">
  ### 1. Восстановление из существующей резервной копии
</div>

Используйте этот способ, если:

* Повреждение метаданных Keeper или снимков делает текущие данные невосстановимыми.
* Существует резервная копия с заведомо корректным состоянием Keeper.

Чтобы восстановить данные из существующей резервной копии, выполните следующие шаги:

1. Найдите и проверьте самую новую резервную копию на согласованность метаданных.
2. Остановите сервисы ClickHouse и Keeper.
3. Замените повреждённые снимки и журналы версиями из каталога резервной копии.
4. Перезапустите кластер Keeper и проверьте синхронизацию метаданных.

<Tip>
  **Регулярно создавайте резервные копии**

  Если резервные копии устарели, вы можете потерять недавние изменения метаданных. Поэтому мы рекомендуем создавать резервные копии регулярно.
</Tip>

***

<div id="rollback-to-older-snapshot">
  ### 2. Откат к более старому снимку
</div>

Используйте этот процесс в следующих случаях:

* Недавние снимки повреждены, но более старые всё ещё пригодны к использованию.
* Инкрементальные журналы не повреждены, что позволяет выполнить согласованное восстановление.

Чтобы откатиться к более старому снимку, выполните следующие шаги:

1. Найдите и выберите корректный старый снимок (например, snapshot.19) в каталоге Keeper.
2. Удалите более новые снимки и журналы.
3. Перезапустите Keeper, чтобы он заново воспроизвёл журналы и восстановил состояние метаданных.

<Warning>
  **Риск рассинхронизации метаданных**

  Существует риск рассинхронизации метаданных, если снимки и журналы отсутствуют или неполны.
</Warning>

***

<div id="restore-metadata-with-system-restore-replica">
  ### 3. Восстановление метаданных с помощью `SYSTEM RESTORE REPLICA`
</div>

Следуйте этому процессу, если:

* метаданные Keeper утрачены или повреждены, но данные таблицы по-прежнему есть на диске
* таблицы перешли в режим только для чтения из-за отсутствия метаданных ZooKeeper/Keeper
* вам нужно заново создать метаданные в Keeper на основе локально доступных частей данных

Чтобы восстановить метаданные, выполните следующие действия:

1. Убедитесь, что данные таблицы локально присутствуют в пути к данным вашего clickhouse-server, заданном параметром `<path>` в конфигурации. (по умолчанию `/var/lib/clickhouse/data/`)

2. Для каждой затронутой таблицы выполните:

```sql theme={null}
SYSTEM RESTART REPLICA [db.]table_name;
SYSTEM RESTORE REPLICA [db.]table_name;
```

3. Для восстановления на уровне базы данных (если используется движок базы данных Replicated):

```sql theme={null}
SYSTEM RESTORE DATABASE REPLICA db_name;
```

4. Дождитесь завершения синхронизации:

```sql theme={null}
SYSTEM SYNC REPLICA [db.]table_name;
```

5. Проверьте восстановление: убедитесь, что в `system.replicas` значение `is_readonly = 0`, и следите за `system.detached_parts`

<Info>
  **Как это работает**

  `SYSTEM RESTORE REPLICA` отсоединяет все существующие части, заново создает метаданные в Keeper (как будто это новая пустая таблица), а затем снова присоединяет все части. Это позволяет избежать повторной загрузки данных по сети.
</Info>

<Warning>
  **Предварительные требования**

  Это работает только в том случае, если локальные части данных не повреждены. Если данные тоже повреждены, используйте стратегию № 5 (пересобрать кластер).
</Warning>

***

<div id="drop-and-recreate-replica-metadata">
  ### 4. Удаление и повторное создание метаданных реплики в Keeper
</div>

Используйте этот порядок действий, если:

* Ошибка возникает только на одной реплике кластера, и её метаданные в Keeper повреждены или несогласованы
* Вы сталкиваетесь с ошибками вида "Part XXXXX intersects previous part YYYYY"
* Вам нужно полностью сбросить метаданные реплики в Keeper, сохранив локальные данные

Чтобы удалить и заново создать метаданные, выполните следующие действия:

1. На затронутой реплике отсоедините таблицу:

```sql theme={null}
DETACH TABLE [db.]table_name;
```

2. Удалите метаданные реплики из Keeper (выполните на любой реплике):

```sql theme={null}
SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/{shard}/table_name';
```

Чтобы найти правильный путь ZooKeeper:

```sql theme={null}
SELECT zookeeper_path, replica_name FROM system.replicas WHERE table = 'table_name';
```

3. Повторно выполните ATTACH таблицы (она будет в режиме только для чтения):

```sql theme={null}
ATTACH TABLE [db.]table_name;
```

4. Восстановите метаданные реплики:

```sql theme={null}
SYSTEM RESTORE REPLICA [db.]table_name;
```

5. Синхронизируйтесь с другими репликами:

```sql theme={null}
SYSTEM SYNC REPLICA [db.]table_name;
```

6. Проверьте `system.detached_parts` на всех репликах после восстановления

<Warning>
  **Выполните на всех затронутых репликах**

  Если повреждение затронуло несколько реплик, повторите эти шаги на каждой из них по очереди.
</Warning>

<Tip>
  **Для всей базы данных**

  Если используется база данных Replicated, вместо этого можно выполнить `SYSTEM DROP REPLICA ... FROM DATABASE db_name`.
</Tip>

**Альтернатива: использование флага force\_restore\_data**

Для автоматического восстановления всех реплицируемых таблиц при запуске сервера:

1. Остановите сервер ClickHouse
2. Создайте флаг восстановления:

```bash theme={null}
sudo -u clickhouse touch /var/lib/clickhouse/flags/force_restore_data
```

3. Запустите сервер ClickHouse
4. Сервер автоматически удалит флаг и восстановит все реплицированные таблицы
5. Следите за ходом восстановления в журналах

Этот подход полезен, когда нужно одновременно восстановить несколько таблиц.

***

<div id="rebuild-keeper-cluster">
  ### 5. Пересборка кластера Keeper
</div>

Используйте этот процесс в следующих случаях:

* Для восстановления недоступны пригодные снимки, журналы или резервные копии.
* Необходимо заново создать весь кластер Keeper и его метаданные.

Чтобы пересобрать кластер Keeper, выполните следующие шаги:

1. Полностью остановите кластеры ClickHouse и Keeper.
2. Сбросьте каждый узел Keeper, очистив каталоги снимков и журналов.
3. Инициализируйте один узел Keeper в качестве лидера и постепенно добавляйте остальные узлы.
4. Повторно импортируйте метаданные, если они доступны из внешних записей.

<Warning>
  **Трудоёмкий процесс**

  Этот процесс требует много времени и сопряжён с риском длительного простоя. Потребуется полное восстановление данных.
</Warning>