Резервное копирование системных таблеток

Механизм резервного копирования системных таблеток обеспечивает инкрементальное копирование метаданных кластера — таких как Hive, BSController и SchemeShard — на локальную файловую систему хостов кластера.

Этот механизм предназначен для восстановления метаданных кластера, когда другие способы восстановления недоступны — например, резервная копия базы данных отсутствует или объём базы данных слишком велик для восстановления ее из резервной копии за приемлемое время. Механизм позволяет восстановить метаданные в существующем кластере без необходимости пересоздавать кластер и восстанавливать базы данных из резервных копий.

Если есть возможность восстановить кластер с помощью команд export/import или dump/restore, рекомендуется использовать эти способы.

Принцип работы

Резервное копирование состоит из двух компонентов:

• Снимок состояния (snapshot) — при каждом запуске таблетка сканирует все свои таблицы и записывает свое полное состояние в резервную копию, включая схему данных. Сканирование выполняется на основе снимка состояния и не блокирует работу таблетки.
• Журнал изменений (changelog) — при каждом изменении данных или схемы таблетка асинхронно записывает изменение в журнал параллельно с записью в распределённое хранилище. Когда размер журнала превышает размер снимка состояния, таблетка автоматически делает новый снимок.

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

Количество хранимых резервных копий на хосте ограничено в конфигурации. После успешного снятия снапшота самая старая копия автоматически удаляется при превышении лимита. Незавершённые копии (без полностью записанного снапшота) удаляются при создании новой резервной копии.

Включение и настройка резервного копирования

По умолчанию резервное копирование системных таблеток выключено, так как требует настройки хранилища. Узлы YDB обычно не используют локальную файловую систему, поэтому включение требует осознанного решения администратора.

Для включения добавьте секцию system_tablet_backup_config в конфигурацию кластера:

system_tablet_backup_config:
    filesystem:
        path: "/path/to/backup/directory"

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

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

Руководство по восстановлению

Шаг 1. Переведите таблетку в Recovery-режим

Таблетку, которую требуется восстановить, необходимо перевести в Recovery-режим. В этом режиме таблетка запускается и доступна через Embedded UI, но не работает штатно и не вычитывает данные из распределённого хранилища, что позволяет выполнять операции восстановления. Остальные таблетки продолжат работать в штатном режиме, что позволит кластеру продолжать функционировать, но некоторые control-plane операции могут быть недоступны.

1. Определите идентификатор системной таблетки, которую требуется восстановить. Идентификатор таблетки можно найти в разделе Tablets в Embedded UI.

2. Определите список узлов, на которых может работать восстанавливаемая системная таблетка. Этот список находится в секции bootstrap_config соответствующей таблетки в конфигурации кластера. Если секция bootstrap_config отсутствует в конфигурации, используйте список всех статических узлов кластера, указанных в секции hosts конфигурации кластера.

3. Измените конфигурацию, добавив boot_mode: RECOVERY в секцию bootstrap_config восстанавливаемой таблетки.

   • При использовании конфигурации V1, необходимо изменить статическую конфигурацию на всех узлах, на которых может работать восстанавливаемая таблетка.
   • При использовании конфигурации V2, воспользуйтесь инструкцией.
   • Пример для таблетки Hive с идентификатором 72057594037968897:

       bootstrap_config:
           tablet:
           - type: FLAT_HIVE
             node:
             - 1
             - 2
             - 3
             info:
                 tablet_id: '72057594037968897'
                 channels:
                 - channel: 0
                 history:
                 - from_generation: 0
                     group_id: 0
                 channel_erasure_name: mirror-3-dc
                 - channel: 1
                 history:
                 - from_generation: 0
                     group_id: 0
                 channel_erasure_name: mirror-3-dc
                 - channel: 2
                 history:
                 - from_generation: 0
                     group_id: 0
                 channel_erasure_name: mirror-3-dc
             boot_mode: RECOVERY
   

4. Перезапустите все узлы, на которых может работать восстанавливаемая таблетка. Если какой-либо узел недоступен и не может быть перезапущен, изолируйте его от кластера по сети — например, с помощью firewall.

   Важно

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

5. Убедитесь, что:

   • С таблеткой нет проблем в HealthCheck.
   • Таблетка не перезапускается.
   • В App таблетки в Embedded UI доступна форма восстановления.

Шаг 2. Найдите файлы резервной копии

1. Определите, на каких хостах искать. Прежде всего проверьте хосты, на которых таблетка работала до сбоя. Определить эти хосты можно с помощью логов или системы мониторинга.

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

2. Найдите директорию с резервными копиями. На каждом хосте-кандидате проверьте наличие резервных копий. Путь к резервным копиям определяется параметром path в конфигурации system_tablet_backup_config:

   ls /path/to/backup/directory/<tablet_type>/<tablet_id>/
   

   Пример для таблетки Hive с идентификатором 72057594037968897:

   ls /tablet/hive/72057594037968897/
   

   backup_20251007T181003_g213_s1001
   backup_20251007T191002_g214_s1040
   backup_20251007T193502_g214_s1222
   

3. Выберите наиболее актуальную резервную копию. Имя каждой резервной копии содержит ключевую информацию: backup_<timestamp>_g<generation>_s<step>, где:

   • timestamp — время создания резервной копии;
   • generation — поколение таблетки, увеличивается при каждом перезапуске таблетки;
   • step — шаг таблетки в рамках поколения, увеличивается при каждом изменении состояния таблетки.

   Выберите резервную копию с максимальным поколением, а при равном поколении — с максимальным шагом. Если резервные копии найдены на нескольких хостах, сравните их между собой и выберите наиболее актуальную.

4. Убедитесь, что резервная копия полностью записана. Выбранная резервная копия должна содержать директорию snapshot, а не snapshot.tmp. Наличие snapshot.tmp означает, что запись снапшота не была завершена и копия непригодна для восстановления. В этом случае выберите предыдущую по актуальности копию.

   ls /tablet/hive/72057594037968897/backup_20251007T193502_g214_s1222/snapshot/
   

   manifest.json
   schema.json
   Tablet.json
   TabletFollowerGroup.json
   ...
   

Шаг 3. Перенесите файлы резервной копии

1. Определите, на каком хосте запущена таблетка в Recovery-режиме. Для этого откройте Embedded UI и найдите узел, на котором работает таблетка.

2. Если файлы резервной копии находятся на другом хосте, скопируйте их на хост с таблеткой в Recovery-режиме с помощью scp, rsync или любого другого доступного инструмента:

   scp -r /tablet/hive/72057594037968897/backup_20251007T193502_g214_s1222 \
       user@target-host:~/backup_20251007T193502_g214_s1222
   

3. Убедитесь, что файлы доступны для чтения процессу YDB на целевом хосте.

Шаг 4. Выполните восстановление

1. Откройте App восстанавливаемой таблетки в Embedded UI.

2. В форме восстановления укажите полный путь до директории с файлами резервной копии, например:

   /tablet/hive/72057594037968897/backup_20251007T193502_g214_s1222
   

3. При необходимости установите флаги:

   • Dry Run — выполняет пробное восстановление без внесения изменений в хранилище. Позволяет убедиться в корректности резервной копии.
   • Skip Checksum Validation — пропускает проверку контрольных сумм файлов резервной копии.

   Важно

   Всегда выполняйте Dry Run перед первым восстановлением, чтобы убедиться в корректности резервной копии.

   Важно

   Пропускайте проверку контрольных сумм только в случае ручного редактирования файлов резервной копии. В остальных случаях рекомендуется оставлять проверку включённой для обеспечения целостности восстанавливаемых данных.

4. Нажмите кнопку Start Restore. Перед началом восстановления система запросит подтверждение, так как операция перезаписывает существующие данные таблетки. Подтвердите действие для запуска. После начала восстановления форма становится недоступной — повторный запуск невозможен до перезапуска таблетки.

   Примечание

   Восстановление также можно запустить с помощью curl, отправив POST-запрос на страницу App таблетки с параметром restoreBackup:

   curl -X POST "http://<host>:<mon_port>/tablets/app?TabletID=72057594037968897&restoreBackup=/tablet/hive/72057594037968897/backup_20251007T193502_g214_s1222"
   

   Где <host> — адрес узла кластера, <mon_port> — порт мониторинга этого узла.

5. Отслеживайте прогресс восстановления. Страница не обновляется автоматически — для получения актуального статуса обновляйте страницу вручную. Продолжительность восстановления зависит от объёма резервной копии.

   Примечание

   Восстановление выполняется на стороне сервера и не зависит от браузера. Вы можете закрыть страницу или браузер — это не прервёт процесс восстановления. При повторном открытии страницы отобразится актуальный статус.

   Под формой отображается текущий статус операции. Возможные статусы:

   • Restoring from '<путь>' — восстановление выполняется, данные из резервной копии считываются и записываются в хранилище. Дополнительно отображается прогресс-бар с процентом выполнения операции.
   • Restore from '<путь>' completed successfully — восстановление завершено успешно. Можно переходить к следующему шагу.
   • Restore from '<путь>' completed, but changelog is not fully restored — основные данные таблетки восстановлены, но хвост журнала изменений в резервной копии повреждён, и часть последних изменений потеряна. Изучите, какие данные были потеряны, и при необходимости восстановите их вручную, либо переходите к следующему шагу.
   • Restore from '<путь>' failed: <описание ошибки> — восстановление завершилось с ошибкой. Изучите описание ошибки и при необходимости повторите попытку.

   Для принудительного прерывания восстановления перезапустите таблетку.

6. Дождитесь успешного завершения восстановления. Если форма восстановления снова стала доступна (кнопка Start Restore активна, статус сброшен), это означает, что таблетка была перезапущена и восстановление прервано. В этом случае начните восстановление заново с пункта 2.

Шаг 5. Верните таблетку к нормальному режиму работы

После успешного восстановления:

1. Определите список узлов, на которых может работать восстанавливаемая системная таблетка. Этот список находится в секции bootstrap_config соответствующей таблетки в конфигурации кластера. Если секция bootstrap_config отсутствует в конфигурации, используйте список всех статических узлов кластера, указанных в секции hosts конфигурации кластера.
2. Измените конфигурацию, удалив boot_mode: RECOVERY из секции bootstrap_config восстанавливаемой таблетки.
   • При использовании конфигурации V1, необходимо изменить статическую конфигурацию на всех узлах, на которых может работать восстанавливаемая таблетка.
   • При использовании конфигурации V2, воспользуйтесь инструкцией.
3. Перезапустите все узлы, на которых может работать восстанавливаемая таблетка. Если какие-либо узлы были изолированы от кластера по сети на предыдущих шагах, снимите сетевую изоляцию.
4. Убедитесь, что:
   • С таблеткой нет проблем в HealthCheck.
   • Таблетка не перезапускается.
   • В App таблетки в Embedded UI отсутствует форма восстановления.