#Резервное копирование и восстановление ClickHouse на локальном хранилище или NAS

#Обзор

В этом документе описывается, как создавать резервные копии и выполнять восстановление таблиц ClickHouse в базе данных observability с использованием локального хранилища или каталога, смонтированного по NAS. Эта процедура применяется к кластерам, использующим движок таблиц ReplicatedMergeTree.

Для ClickHouse NAS-монтирование рассматривается как путь локальной файловой системы. Поэтому для локального хранилища и NAS можно использовать один и тот же метод резервного копирования и восстановления.

В этом документе приведены следующие рекомендации:

• Создание полной резервной копии.
• Создание инкрементной резервной копии на основе полной.
• Хранение данных резервного копирования в локальном каталоге или в пути монтирования NAS.
• Восстановление данных из локальной резервной копии или резервной копии на NAS.
• Проверка результатов резервного копирования и восстановления.

В качестве примера в этом документе используется таблица observability.audit. Тот же порядок действий можно применить и к другим таблицам.

Наиболее распространенные примеры таблиц:

• audit: хранит данные аудита.
• event: хранит данные событий.
• log_kubernetes: хранит журналы Kubernetes.
• log_platform: хранит журналы сервисов платформы.
• log_system: хранит системные журналы уровня узла.
• log_workload: хранит журналы приложений и нагрузок.

Типы хранилищ различаются следующим образом:

• LocalVolume: данные ClickHouse хранятся в каталоге, локальном для узла, например /cpaas/data/clickhouse/. Команда BACKUP ... TO File(...) записывает файлы резервной копии в каталог резервного копирования ClickHouse в этом локальном каталоге данных, например /cpaas/data/clickhouse/backups.
• StorageClass, например TopoLVM, NFS или Ceph: данные ClickHouse хранятся на томе соответствующего StorageClass. Команда BACKUP ... TO File(...) записывает файлы резервной копии в каталог резервного копирования ClickHouse на этом томе.
• Путь архива NAS: файлы резервной копии можно скопировать из каталога резервного копирования ClickHouse в смонтированный путь NAS или в другой пользовательский каталог резервного копирования для долговременного хранения.

Для развертываний как LocalVolume, так и StorageClass используйте фактический каталог резервного копирования ClickHouse в качестве исходного пути при архивировании файлов резервной копии и в качестве пути назначения при обратном копировании файлов резервной копии для восстановления.

#Предварительные требования

Перед началом убедитесь, что выполнены следующие условия.

#Требования к среде

#Требования к доступу

Все SQL-операторы в этом документе используют встроенную учетную запись администратора ClickHouse default.

Вы можете выполнять SQL-операторы на любом исправном экземпляре ClickHouse. Для единообразия в этом документе в качестве примера используется один Pod ClickHouse.

Перед выполнением SQL-операторов подключитесь к целевому Pod:

kubectl exec -ti -n cpaas-system chi-cpaas-clickhouse-replicated-0-0-0 -- bash

Затем подключитесь к ClickHouse в контейнере:

clickhouse-client

Пользователь default уже имеет необходимые привилегии для этой процедуры, включая BACKUP, RESTORE, SELECT и ALTER.

#Требования к каталогу

Убедитесь, что выполнены следующие условия:

• Процесс ClickHouse имеет права на чтение и запись в целевой каталог.
• В целевом каталоге достаточно свободного места.
• Если используется NAS, точка монтирования автоматически восстанавливается после перезапуска Pod или хоста.
• В Kubernetes каталог монтируется через PVC, hostPath или CSI.

#Стратегия резервного копирования

Используйте следующую стратегию резервного копирования:

• Выполняйте операцию резервного копирования только один раз на любом исправном реплике.
• Используйте BACKUP TABLE, чтобы создать согласованный снимок без остановки сервиса.
• Используйте base_backup для дедупликации на уровне файлов в инкрементных резервных копиях.
• При восстановлении инкрементной резервной копии сохраняйте доступность базовой полной резервной копии.
• Используйте одну полную резервную копию в неделю и одну инкрементную резервную копию в день, чтобы сбалансировать сложность восстановления и стоимость хранения.

#Процедура

В следующих примерах используется начальная полная резервная копия и ежедневная инкрементная резервная копия.

#Создание полной резервной копии

Полная резервная копия создает базовую точку для последующих инкрементных резервных копий.

Выполните следующую команду на любом исправном экземпляре ClickHouse:

BACKUP TABLE observability.audit
TO File('audit_full_20260423')
SETTINGS compression_method = 'zstd';

Примечания:

• File(...) записывает резервную копию в каталог резервного копирования ClickHouse на томе данных ClickHouse.
• Для развертываний LocalVolume каталог резервного копирования обычно находится по пути /cpaas/data/clickhouse/backups на узле хоста.
• Для развертываний StorageClass, таких как TopoLVM, NFS или Ceph, каталог резервного копирования находится на соответствующем томе StorageClass.
• compression_method = 'zstd' сжимает содержимое резервной копии с помощью zstd, чтобы уменьшить объем занимаемого места.
• Если требуется архивировать резервную копию в NAS или в другой пользовательский каталог резервного копирования, скопируйте резервную копию после завершения задачи резервного копирования.

#Проверка успешного завершения резервного копирования

После завершения резервного копирования проверьте результат.

#Проверка состояния задачи резервного копирования

Выполните следующий запрос на экземпляре ClickHouse, на котором была запущена команда резервного копирования:

SELECT
    id,
    name,
    status,
    error,
    start_time,
    end_time,
    num_files,
    total_size
FROM system.backups
ORDER BY start_time DESC
LIMIT 10
FORMAT Vertical;

Ожидаемый результат:

Найдите запись резервного копирования для observability.audit по полю name. Резервное копирование считается успешным, если выполнены следующие условия:

• status = 'BACKUP_CREATED'
• error пуст
• end_time имеет значение
• num_files > 0
• total_size > 0

#Проверка каталога резервного копирования

Выполните следующую команду на узле или в контейнере, где доступен каталог резервного копирования ClickHouse.

Для развертываний LocalVolume каталог резервного копирования обычно находится по пути /cpaas/data/clickhouse/backups:

ls -lah /cpaas/data/clickhouse/backups

Для развертываний StorageClass проверьте каталог резервного копирования на соответствующем томе StorageClass.

Ожидаемый результат:

• Каталог резервного копирования существует.
• Каталог содержит файлы или папки, созданные этой резервной копией.
• Количество файлов и общий размер больше 0.

#Создание инкрементной резервной копии

Инкрементная резервная копия использует base_backup и записывает только новые или измененные файлы данных.

Выполните следующую команду на любом исправном экземпляре ClickHouse:

BACKUP TABLE observability.audit
TO File('audit_incr_20260424')
SETTINGS
  base_backup = File('audit_full_20260423'),
  compression_method = 'zstd';

Примечания:

• Инкрементная резервная копия зависит от резервной копии, указанной в base_backup.
• В этом документе рекомендуется, чтобы каждая ежедневная инкрементная резервная копия использовала последнюю полную резервную копию в качестве base_backup, а не предыдущую инкрементную резервную копию. Это упрощает зависимости при восстановлении: для восстановления ежедневной инкрементной резервной копии требуются только сама инкрементная копия и соответствующая ей полная резервная копия.
• При восстановлении инкрементной резервной копии сохраняйте соответствующую полную резервную копию.
• Периодически создавайте новую полную резервную копию, чтобы не полагаться слишком долго на одну и ту же базовую копию.

#Архивирование файлов резервной копии

BACKUP ... TO File(...) записывает файлы резервной копии в каталог резервного копирования ClickHouse на томе данных ClickHouse, где выполняется команда резервного копирования.

Каталог резервного копирования зависит от типа хранилища:

• Для развертываний LocalVolume каталог данных ClickHouse находится на узле хоста, обычно /cpaas/data/clickhouse/, а файлы резервной копии создаются в /cpaas/data/clickhouse/backups.
• Для развертываний StorageClass, таких как TopoLVM, NFS или Ceph, каталог данных ClickHouse находится на соответствующем томе StorageClass, а файлы резервной копии создаются в каталоге резервного копирования ClickHouse на этом томе.

После успешного завершения резервного копирования скопируйте файлы резервной копии из фактического каталога резервного копирования ClickHouse в пользовательский каталог резервного копирования или в путь монтирования NAS для долговременного хранения.

Для развертываний LocalVolume исходный путь обычно /cpaas/data/clickhouse/backups:

cp -r /cpaas/data/clickhouse/backups/audit_full_20260423 /my_dir/audit_full_20260423
cp -r /cpaas/data/clickhouse/backups/audit_incr_20260424 /my_dir/audit_incr_20260424

Для развертываний StorageClass замените /cpaas/data/clickhouse/backups на фактический каталог резервного копирования ClickHouse на томе StorageClass.

Примечания:

• /my_dir может быть выделенным локальным каталогом архива или путем монтирования NAS.
• Используйте путь архива вне каталога данных ClickHouse. В противном случае файлы резервной копии могут быть удалены при очистке каталога данных ClickHouse во время аварийного восстановления.
• После каждой полной или инкрементной резервной копии копируйте соответствующий каталог резервной копии в место архивации.
• После успешного копирования инкрементной резервной копии вы можете удалить локальную инкрементную резервную копию из каталога резервного копирования ClickHouse, если она больше не нужна.
• Удаляйте локальную полную резервную копию из каталога резервного копирования ClickHouse только после успешного завершения следующей полной резервной копии и если политика хранения позволяет выполнить очистку.
• Если позже вы будете выполнять восстановление с помощью RESTORE ... ON CLUSTER ... FROM File(...), убедитесь, что необходимые каталоги полной и инкрементной резервных копий скопированы обратно в каталог резервного копирования ClickHouse на каждом узле хоста ClickHouse до запуска команды восстановления.

#Восстановление

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

#Предварительные условия для восстановления

Перед началом процедуры восстановления убедитесь, что выполнены следующие условия:

• У вас есть действующая полная резервная копия или инкрементная резервная копия.
• Если вы восстанавливаете из инкрементной резервной копии, соответствующая полная резервная копия доступна в пути восстановления.
• Вы знаете каталог архива, в котором хранится последняя инкрементная резервная копия и соответствующая ей полная резервная копия.
• У вас есть доступ к кластеру Kubernetes и к узлам хоста, на которых запланированы экземпляры ClickHouse.

#Процедура восстановления

Эта процедура восстанавливает данные ClickHouse по таблицам. Выберите подготовительные шаги в зависимости от масштаба сбоя, а затем выполните ту же процедуру восстановления для каждой требуемой таблицы.

#Остановка записи

Сначала остановите razor, чтобы предотвратить запись новых данных во время восстановления.

Войдите на узел master кластера и создайте ResourcePatch, чтобы остановить razor:

cat <<EOF > /tmp/rp-stop-razor.yaml
apiVersion: operator.alauda.io/v1alpha1
kind: ResourcePatch
metadata:
  generateName: rp-
  name: rp-stop-razor
spec:
  jsonPatch:
  - op: replace
    path: /spec/replicas
    value: 0
  release: cpaas-system/logclickhouse
  target:
    apiVersion: apps/v1
    kind: StatefulSet
    name: razor
    namespace: cpaas-system
EOF

kubectl apply -f /tmp/rp-stop-razor.yaml

#Подготовка ClickHouse в зависимости от масштаба сбоя

Выберите один из следующих вариантов подготовки в зависимости от масштаба сбоя. После завершения подготовки продолжайте ту же процедуру восстановления по таблицам.

#Сценарий A: Данные таблицы повреждены, но каталог данных исправен

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

В этом случае не останавливайте ClickHouse и не очищайте каталог данных ClickHouse. Сразу переходите к процедуре восстановления таблицы.

#Сценарий B: Каталог данных или метаданные Keeper повреждены

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

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

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

Очистите фактический каталог данных ClickHouse для каждого экземпляра ClickHouse в соответствии с типом хранилища. Для развертываний LocalVolume каталог обычно находится по пути /cpaas/data/clickhouse/ на узле хоста. Для развертываний StorageClass очистите каталог данных ClickHouse на соответствующем томе StorageClass или PV. Не используйте /cpaas/data/clickhouse/ для развертываний StorageClass, если не подтверждено, что это фактический путь смонтированных данных.

Войдите на узел master кластера и создайте ResourcePatch, чтобы остановить ClickHouse:

cat <<EOF > /tmp/rp-stop-ck.yaml
apiVersion: operator.alauda.io/v1alpha1
kind: ResourcePatch
metadata:
  generateName: rp-
  name: rp-stop-ck
spec:
  jsonPatch:
  - op: add
    path: /spec/stop
    value: "true"
  release: cpaas-system/logclickhouse
  target:
    apiVersion: clickhouse.altinity.com/v1
    kind: ClickHouseInstallation
    name: cpaas-clickhouse
    namespace: cpaas-system
EOF

kubectl apply -f /tmp/rp-stop-ck.yaml

Убедитесь, что все Pod ClickHouse остановлены:

kubectl get pod -n cpaas-system | grep -i "chi-cpaas-clickhouse-replicated"

Очистите каталог данных ClickHouse для каждого экземпляра ClickHouse в соответствии с типом хранилища.

Для развертываний LocalVolume выполните следующую команду на каждом узле хоста, где развернут экземпляр ClickHouse:

rm -rf /cpaas/data/clickhouse/*

Для развертываний StorageClass очистите каталог данных ClickHouse на соответствующем томе StorageClass или PV. Точный путь зависит от реализации StorageClass и CSI. Используйте фактический путь смонтированных данных ClickHouse вместо пути-примера для LocalVolume.

Запустите только компоненты ClickHouse, удалив ResourcePatch ClickHouse. razor пока не запускайте.

kubectl delete -f /tmp/rp-stop-ck.yaml

Убедитесь, что все Pod ClickHouse запущены:

kubectl get pod -n cpaas-system | grep -i "chi-cpaas-clickhouse-replicated"

#Подготовка файлов резервной копии на каждом узле ClickHouse

Убедитесь, что файлы резервной копии доступны в каталоге резервного копирования ClickHouse на каждом узле хоста ClickHouse.

Если файлы резервной копии были архивированы в пользовательский каталог резервного копирования или в путь монтирования NAS, а локальные файлы в каталоге резервного копирования ClickHouse были удалены, скопируйте последнюю инкрементную резервную копию и соответствующую полную резервную копию обратно в каталог резервного копирования ClickHouse на каждом узле хоста ClickHouse перед восстановлением таблицы.

Для развертываний LocalVolume путь назначения обычно /cpaas/data/clickhouse/backups:

mkdir -p /cpaas/data/clickhouse/backups
cp -r /my_dir/audit_full_20260423 /cpaas/data/clickhouse/backups/audit_full_20260423
cp -r /my_dir/audit_incr_20260424 /cpaas/data/clickhouse/backups/audit_incr_20260424

Для развертываний StorageClass скопируйте файлы резервной копии обратно в фактический каталог резервного копирования ClickHouse на томе StorageClass.

Примечания:

• Если вы восстанавливаете из инкрементной резервной копии, одновременно подготовьте зависимую полную резервную копию.
• Файлы резервной копии должны быть размещены в каталоге резервного копирования ClickHouse на каждом узле хоста ClickHouse, чтобы RESTORE ... ON CLUSTER ... FROM File(...) мог получить к ним доступ на каждом экземпляре ClickHouse.
• Замените /my_dir, /cpaas/data/clickhouse/backups, audit_full_20260423 и audit_incr_20260424 фактическим путем архива, каталогом резервного копирования ClickHouse и именами каталогов резервных копий.

#Проверка готовности кластера

Перед запуском команды восстановления убедитесь, что конфигурация кластера ClickHouse и macros доступны.

Проверьте конфигурацию кластера replicated:

SELECT *
FROM system.clusters
WHERE cluster = 'replicated';

Проверьте локальные macros ClickHouse:

SELECT *
FROM system.macros;

Убедитесь, что в кластере есть ожидаемые реплики ClickHouse и что доступны macros, такие как shard и replica.

#Восстановление таблиц по одной

Выполните следующую процедуру восстановления для каждой таблицы, которую необходимо восстановить.

Удалите целевую таблицу в кластере ClickHouse:

DROP TABLE observability.audit ON CLUSTER 'replicated' SYNC;

Восстановите таблицу из локальной резервной копии или резервной копии NAS:

RESTORE TABLE observability.audit
ON CLUSTER 'replicated'
FROM File('audit_incr_20260424');

Примечания:

• Для таблицы ReplicatedMergeTree в этом развертывании с 3 репликами используйте ON CLUSTER 'replicated', чтобы операция восстановления была распределена по всем репликам ClickHouse в кластере.
• Если вы восстанавливаете из инкрементной резервной копии, ClickHouse автоматически читает зависимую базовую резервную копию.
• Сохраняйте доступность соответствующего каталога полной резервной копии во время восстановления.
• Замените observability.audit и имя каталога резервной копии на фактические таблицу и резервную копию, которые вы хотите восстановить.
• Повторите ту же процедуру для каждой таблицы, которую необходимо восстановить. Список таблиц определяется заказчиком.

#Проверка состояния задачи восстановления

После выполнения каждой команды восстановления проверьте состояние задачи восстановления, прежде чем запускать связанные компоненты:

SELECT
    id,
    name,
    status,
    error,
    start_time,
    end_time,
    num_files,
    total_size
FROM system.backups
ORDER BY start_time DESC
LIMIT 10
FORMAT Vertical;

Ожидаемый результат:

Восстановление считается успешным, если выполнены следующие условия:

• status указывает, что операция восстановления успешно завершена.
• error пуст.
• end_time имеет значение.

#Проверка успешного восстановления

После завершения восстановления проверьте результат с точки зрения данных, разделов и реплик.

#Проверка общего количества строк

Выполните следующий запрос на каждом экземпляре ClickHouse:

SELECT count(*) AS total_rows
FROM observability.audit;

Ожидаемый результат:

Значение total_rows одинаково на всех экземплярах ClickHouse.

#Проверка данных на уровне разделов

Выполните следующий запрос на каждом экземпляре ClickHouse:

SELECT
    partition,
    sum(rows) AS rows,
    count() AS active_parts
FROM system.parts
WHERE active
  AND database = 'observability'
  AND table = 'audit'
GROUP BY partition
ORDER BY partition;

Ожидаемый результат:

• Список partition одинаков на всех экземплярах ClickHouse.
• Значение rows для каждого раздела одинаково на всех экземплярах ClickHouse.

active_parts используется только для наблюдения за физическим размещением частей. Разное количество частей не обязательно означает сбой восстановления.

#Проверка состояния реплик

Выполните следующий запрос на любом экземпляре ClickHouse:

SELECT
    database,
    table,
    total_replicas,
    active_replicas,
    queue_size,
    absolute_delay
FROM system.replicas
WHERE database = 'observability'
  AND table = 'audit';

Ожидаемый результат:

Для кластера с 3 репликами восстановление считается успешным, если выполнены следующие условия:

• total_replicas = 3
• active_replicas = 3
• queue_size = 0
• absolute_delay близко к 0

#Запуск связанных компонентов

После успешной проверки восстановления снова запустите razor, удалив ResourcePatch:

kubectl delete -f /tmp/rp-stop-razor.yaml

#Рекомендации

В производственной среде используйте следующие рекомендации:

• Поддерживайте цепочку резервного копирования: одна полная резервная копия в неделю и одна инкрементная резервная копия в день.
• Используйте единообразную схему именования каталогов резервных копий, например full_YYYYMMDD и incr_YYYYMMDD.
• Регулярно выполняйте пробные восстановления в тестовой среде.
• Определите политику хранения для устаревших инкрементных резервных копий и исторических полных резервных копий.