Архитектура механизма PITR

Восстановление на момент времени в Tarantool DB выполняется с помощью двух основных компонентов:

• консольная утилита tt CLI — выполняет резервное копирование и восстановление на узлах Tarantool и отдельном хосте-менеджере точек восстановления: строит план создания резервной копии и восстановления, запускает копирование на нужных экземплярах, собирает артефакты и выгружает их в хранилище. Для создания резервной копии tt использует встроенный API box.backup;
• внешняя система-оркестратор (Ansible Tarantool Enterprise, скрипты или CI/CD) — автоматизирует резервное копирование и восстановление всего кластера: запускает нужные команды tt CLI на всех экземплярах по инвентарю, переносит файлы между узлами и менеджером.

Существующие гарантии и ограничения в PITR приведены в разделе Гарантии и ограничения.

Восстановление выполняется на одну из периодически создаваемых точек восстановления — именованную метку времени в журналах упреждающей записи (WAL) со следующей структурой:

• label — строковый идентификатор точки. Один и тот же идентификатор создается на всех наборах реплик;
• replica_id, lsn — позиция точки в потоке транзакций мастер-узла набора реплик. Вместе эти значения указывают ровно на одну запись, по которой при восстановлении обрезается журнал;
• timestamp — Unix-время создания точки. Используется только для навигации пользователя по времени.

Точки восстановления хранятся в системном спейсе _recovery_point: они попадают в снимок данных, сохраняются после восстановления и реплицируются. Количество хранимых точек ограничено, при переполнении спейса удаляется самая старая точка.

В шардированном кластере точку восстановления периодически создает технологическая роль roles.recovery-point-manager через метод vshard.router.map_callrw(). Роль создает точку восстановления на мастер-узле каждого набора реплик. Для точки предусмотрена защита от ребалансировки.

Кластерная точка — это совокупность точек восстановления с одним и тем же идентификатором, которые созданы на мастер-узле всех наборов реплик шардированного кластера. По одинаковому идентификатору tt CLI собирает точки восстановления в одну кластерную точку. Такая точка считается валидной, только если успешно создана на всех наборах реплик.

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

• полная резервная копия содержит снимок данных (файл .snap) и журналы упреждающей записи (WAL, файлы .xlog), записанные после снимка до момента завершения резервного копирования. Такая копия полностью определяет состояние базы на момент ее создания;
• инкрементальная резервная копия содержит записи в WAL (файлы .xlog), которые добавлены после создания предыдущей резервной копии. Такая копия создается быстрее и занимает меньше места, но для восстановления нужно иметь полную цепочку копий, начиная с полной.

Каждая запись в WAL получает позицию, которую описывают векторные часы Tarantool (vclock). Это таблица, где каждому идентификатору экземпляра (replica_id) соответствует номер его последней записи (LSN, log sequence number). Векторные часы определяют позицию в потоке транзакций всего набора реплик. Компонента с LSN N для экземпляра означает, что этот экземпляр применил N транзакций.

При создании инкрементальной копии параметр from_vclock в методе box.backup.start() задает позицию vclock: в инкрементальную копию попадают только те файлы .xlog, которые добавлены начиная с этого значения vclock. Если переданное значение векторных часов не совпадает с началом какого-либо .xlog, вернется ошибка.

Минимальное и максимальное значение векторных часов, на которые можно восстановиться в этой копии, можно определить по полям vclock_begin и vclock_end, которые хранятся в манифесте резервной копии. Инкрементальная копия считается целостной только в том случае, если значение ее параметра vclock_begin совпадает со значением vclock_end предыдущей копии. Если их значения отличаются, цепочка копий считается разорванной.

Позиция точки восстановления задается парой (replica_id, lsn) — значением векторных часов, которое указывает ровно на одну запись. Нужный файл .xlog определяется по значению prev_vclock в его заголовке.

Результат резервного копирования состоит из двух элементов:

• архивы с данными (файлы .snap и .xlog);
• манифест — JSON-документ с составом резервной копии кластера: наборы реплик, экземпляры, границы восстановления (vclock_begin/vclock_end), точки восстановления и ссылки на архивы. Манифест ссылается на предыдущую резервную копию (previous_backup_id), образуя цепочку, по которой при восстановлении восстанавливается история изменений. Манифест загружается в хранилище последним, после всех архивов с данными. Отсутствие манифеста означает, что резервная копия не была создана.

Для восстановления кластера на момент времени последовательно выполняются шаги ниже:

1. Пользователь запрашивает восстановление на момент времени T. Команда tt restore plan обходит цепочку манифестов в хранилище, проверяет целостность соседних резервных копий, собирает точки восстановления по идентификаторам в кластерные и приводит T к ближайшей доступной кластерной точке. В результате формируется план, состоящий из следующих компонентов:

   • полная резервная копия;
   • цепочка инкрементальных копий, сделанных после полного резервного копирования;
   • выбранная точка с ее позициями (replica_id, lsn) по каждому набору реплик;
   • список архивов для скачивания.

   При восстановлении данных укажите в команде tt restore plan через параметр --replicasets наборы реплик, которые нужно восстановить. Параметр --replicasets требует передать конфигурацию кластера через параметр -c, например:

    
   tt restore plan --target-time 2026-03-25T10:30:00Z -c cluster.yaml \    --replicasets storage-1,storage-2 \    --backup-storage file:///var/backups -d /tmp/restore/

   Кластерная точка собирается только по указанным наборам реплик. Это позволяет исключить роутер из восстановления данных: он не хранит данные и не записывает точки восстановления, поэтому без --replicasets кластерная точка в кластере с роутером не формируется. Наборы реплик, не указанные в параметре, не восстанавливаются.

2. Оркестратор проверяет, что остановлены все узлы кластера, включая реплики;

3. По цепочке резервных копий команда tt restore apply очищает, а затем готовит рабочие директории экземпляров: распаковывает архивы, меняет instance_uuid в заголовках файлов .snap и .xlog и обрезает финальный .xlog по значению (replica_id, lsn) выбранной точки — записи мастер-узла с LSN больше точки отсекаются.

4. Администратор запускает Tarantool DB на всех узлах. Экземпляры обнаруживают файлы в рабочих директориях и воспроизводят все .xlog, включая обрезанный финальный. Кластер запускается в состоянии, соответствующем выбранной точке восстановления.

Консольная утилита tt CLI управляет резервным копированием и восстановлением с помощью групп команд tt backup и tt restore.

На узле Tarantool утилита:

• tt backup start — создает локальный архив данных резервной копии на экземпляре;
• tt backup finalize — завершает создание локальных артефактов резервной копии;
• tt restore apply — при восстановлении подготавливает каталог данных на основе цепочки резервных копий;

На хосте-менеджере (отдельной машине с tt) утилита:

• tt backup plan — строит план резервного копирования (вычисляет последний действительный манифест);
• tt backup upload — собирает манифест кластера из фрагментов по отдельным наборам реплик и выгружает архивы и манифест в хранилище;
• tt restore plan — скачивает цепочку архивов и строит план восстановления.

Артефакты резервного копирования хранятся в хранилище (локальной файловой системе или объектном хранилище S3). Одно хранилище может содержать несколько кластеров, для их разделения используются параметры --cluster-name и --environment.

Автоматизировать резервное копирование (полное и инкрементальное) и восстановление кластера на момент времени можно через инсталлятор Ansible Tarantool Enterprise (ATE), используя сценарии backup_pitr.yml и restore_pitr.yml.

Сценарий резервного копирования backup_pitr.yml:

1. Строит план резервного копирования (tt backup plan).
2. Запускает копирование на мастер-узлах наборов реплик (tt backup start).
3. Собирает артефакты на хосте сбора. Хост сбора задается переменной tarantool_pitr_backup_host (по умолчанию это localhost, управляющий узел Ansible). Конфигурация кластера передается через URI централизованного хранилища конфигураций, который сценарий формирует из переменных tt_config_storage_*.
4. Выгружает архивы и манифест в хранилище (tt backup upload).
5. Завершает копирование на мастер-узлах (tt backup finalize).
6. Проверяет результат резервного копирования (tt backup last и verify).

Подробная информация о сценарии backup_pitr.yml приведена в документации по инсталлятору ATE в разделе Tarantool 3.x: PITR-резервирование.

Сценарий восстановления на момент времени restore_pitr.yml:

1. Строит план восстановления (tt restore plan).
2. Останавливает кластер.
3. Переносит каталоги данных в сторону (с возможностью отката).
4. Применяет архивы (tt restore apply) и удаляет отложенные копии данных.
5. Кластер после восстановления не запускается автоматически — запуск выполняет администратор отдельным шагом.

Подробная информация о сценарии restore_pitr.yml приведена в документации по инсталлятору ATE в разделе Tarantool 3.x: PITR-восстановление.