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

Примечание

На текущий момент поддерживается резервное копирование только кластерных системных таблеток. Резервное копирование системных таблеток баз данных не поддерживается.

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

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

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

Важно

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

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

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

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

Важно

Из-за асинхронной записи возможна потеря последних изменений, не успевших попасть в резервную копию до момента сбоя.

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

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

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

Важно

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

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

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

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

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

Важно

Директория для резервных копий должна быть доступна для записи процессом YDB на каждом хосте, где работают системные таблетки. Убедитесь, что на диске каждого хоста достаточно свободного места для хранения нескольких резервных копий всех системных таблеток. Для крупных рабочих сред, состоящих из десятков узлов хранения, рекомендуется как минимум 5 ГБ.

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

Важно

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

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

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

Важно

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

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

Таблетку, которую требуется восстановить, необходимо перевести в Recovery-режим.

Важно

Если восстановление выполняется после полной потери статической группы, все системные таблетки должны быть переведены в Recovery-режим одновременно с пересозданием статической группы на новых хостах. Если пересоздать статическую группу, не переведя таблетки в Recovery-режим, они автоматически запустятся поверх пустой статической группы, что приведёт к неправильной работе кластера.

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

  2. Сохраните текущую конфигурацию кластера в файл config.yaml.

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

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

    Создайте изолированное окружение с PyYAML:

    python3 -m venv ./recovery && ./recovery/bin/pip install pyyaml

    Создайте файл скрипта:

    cat > find-tablet-hosts.py <<'EOF'
#!/usr/bin/env python3
import argparse
import yaml


def find_nodes(cfg, tid):
    bootstrap = (cfg.get("bootstrap_config") or {}).get("tablet") or []
    for tablet in bootstrap:
        if str(tablet.get("info", {}).get("tablet_id")) == tid:
            return tablet.get("node") or []

    for tablets_by_type in (cfg.get("system_tablets") or {}).values():
        for tablet in tablets_by_type or []:
            if str(tablet.get("info", {}).get("tablet_id")) == tid:
                return tablet.get("node") or []

    return []


parser = argparse.ArgumentParser()
parser.add_argument("--config-path", required=True, help="Path to cluster configuration file")
parser.add_argument("--tablet-id", required=True, help="System tablet id")
args = parser.parse_args()

with open(args.config_path) as f:
    cfg = yaml.safe_load(f) or {}

cfg = cfg.get("config", cfg)

hosts_by_id = {h["node_id"]: h["host"] for h in cfg.get("hosts") or []}

node_ids = find_nodes(cfg, args.tablet_id)
if not node_ids:
    node_ids = list(hosts_by_id)

for node_id in sorted(set(node_ids)):
    host = hosts_by_id.get(node_id)
    if host is not None:
        print(host)
EOF

    Запустите скрипт, подставив путь к своей конфигурации и идентификатор таблетки:

    Пример:

    ./recovery/bin/python find-tablet-hosts.py --config-path config.yaml --tablet-id <tablet-id> > hosts.txt

  4. Измените сохраненную конфигурацию, добавив boot_type: RECOVERY в секцию конфигурации запуска восстанавливаемой таблетки и сократите список узлов, где может запускаться восстанавливаемая таблетка (массив node), до одного узла.
    Пример для таблетки Hive с идентификатором 72057594037968897:

    • При использовании bootstrap_config:

          bootstrap_config:
        tablet:
        - type: FLAT_HIVE
            node:
            - 1
            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_type: RECOVERY

    • При использовании system_tablets:

      flat_hive:
- info:
    tablet_id: 72057594037968897
  node:
  - 9
  boot_type: RECOVERY

  5. Обновите конфигурацию в кластере.

    • При использовании конфигурации V1 необходимо обновить статическую конфигурацию на всех хостах, полученных на шаге 3, с помощью команды:

      Скопируйте обновлённую конфигурацию во временный файл на каждом хосте:

      pscp -h hosts.txt config.yaml /tmp/config.yaml.new

      Сделайте резервную копию текущей конфигурации, замените её новой версией и защитите от случайных изменений:

      pssh -h hosts.txt 'sudo cp /opt/ydb/cfg/config.yaml /opt/ydb/cfg/config.yaml.bak && sudo mv /tmp/config.yaml.new /opt/ydb/cfg/config.yaml && sudo chattr +i /opt/ydb/cfg/config.yaml'

    • При использовании конфигурации V2, воспользуйтесь инструкцией.

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

    Пример:

    pssh -h hosts.txt 'sudo systemctl restart ydbd-storage; sleep 10'

    Важно

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

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

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

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

  1. На каждом хосте, полученном на шаге 3, проверьте наличие резервных копий. Путь к резервным копиям определяется параметром path в секции конфигурации system_tablet_backup_config.

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

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

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

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

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

    ls /path/to/backup/directory/hive/72057594037968897/backup_20251007T193502_g214_s1222/snapshot/

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

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

    ls -lh /path/to/backup/directory/hive/72057594037968897/backup_20251007T193502_g214_s1222/snapshot

    total 128K
-rw-r--r-- 1 ydb disk  591 May 27 11:34 manifest.json
-rw-r--r-- 1 ydb disk  12K May 27 11:34 schema.json
-rw-r--r-- 1 ydb disk  47K May 27 11:34 Tablet.json
-rw-r--r-- 1 ydb disk  41K May 27 11:34 TabletFollowerGroup.json
...

    Посчитайте чексумму от файла changelog.json и сверьте ее с чексуммой, записанной в changelog.json.sha256:

    sha256sum /path/to/backup/directory/hive/72057594037968897/backup_20251007T193502_g214_s1222/changelog.json

    ea4bdc2f7afaf7b6d35adbf13b5360e4e4a19046f742effdf1b4f0bb9c449185

    cat /path/to/backup/directory/hive/72057594037968897/backup_20251007T193502_g214_s1222/changelog.json.sha256

    ea4bdc2f7afaf7b6d35adbf13b5360e4e4a19046f742effdf1b4f0bb9c449185

    В случае, если чексуммы отличаются, то возможны две ситуации:

    • Последняя запись в changelog.json не была полностью записана. В этом случае, чексумма, хранящаяся в changelog.json.sha256 находится в одной из записей в changelog.json в поле prev_sha256. Для восстановления необходимо отредактировать файлы: удалить/дополнить не полностью записанные записи в changelog.json и обновить чексумму в changelog.json.sha256.
    • Произошло повреждение данных, восстановление невозможно.

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

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

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

    Скопируйте бекап из директории с бекапами в свою домашнюю директорию:

    cp -R /path/to/backup/directory/hive/72057594037968897/backup_20251007T193502_g214_s1222 ~/backup_20251007T193502_g214_s1222

    Скопируйте бекап на целевой хост:

    scp -r ~/backup_20251007T193502_g214_s1222 target-host:~/backup_20251007T193502_g214_s1222

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

    
scp -r backup-host:~/backup_20251007T193502_g214_s1222 backup_20251007T193502_g214_s1222

scp -r backup_20251007T193502_g214_s1222 target-host:~/backup_20251007T193502_g214_s1222

    После копирования бекапа на целевой хост, предоставьте доступ к нему процессу ydb:

    chown -R ydb ~/backup_20260527104029Z_g1911_s

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

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

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

    /path/to/backup/directory/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. Верните конфигурацию в исходное состояние, удалив boot_type: RECOVERY из секции конфигурации запуска восстанавливаемой таблетки и восстановив изначальный список узлов, где может запускаться восстанавливаемая таблетка.

    • При использовании конфигурации V1 необходимо обновить статическую конфигурацию на всех хостах, полученных на шаге 3, с помощью команды:

      Снимите защиту от случайных изменений и замените новую конфигурацию исходной версией:

      pssh -h hosts.txt 'sudo chattr -i /opt/ydb/cfg/config.yaml && sudo mv /opt/ydb/cfg/config.yaml.bak /opt/ydb/cfg/config.yaml'

    • При использовании конфигурации V2, воспользуйтесь инструкцией.

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

    Пример:

    pssh -h hosts.txt 'sudo systemctl restart ydbd-storage; sleep 10'

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

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

  4. Поочерёдно перезапустите все узлы кластера для синхронизации состояния внутренних кешей в памяти с состоянием таблетки. После перезапуска каждого узла дождитесь его возвращения в рабочее состояние и убедитесь в отсутствии проблем в HealthCheck; только после этого переходите к следующему узлу.

Предыдущая
Резервное копирование и восстановление
Следующая
Для разработчиков