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

mxBackup умеет разворачивать архив обратно: файлы, базу данных или и то и другое. Операция необратима, поэтому она разделена на два шага — проверка и собственно восстановление — и защищена кодом подтверждения, отдельным правом доступа и обязательной страховочной копией.

Перед запуском

Восстановление изменяет файлы сайта и выполняет DROP TABLE для таблиц из дампа. Откатить это одной транзакцией MySQL не позволяет.

1. Закройте сайт для посетителей: Система → Системные настройки → «Сайт опубликован» → «Нет». Посетители увидят сообщение о недоступности, а менеджер продолжит работать. mxBackup эту настройку не трогает — переключаете вы. Если сайт закрывается иначе (правило веб-сервера, балансировщик), сделайте это своим способом.
2. Остановите cron, очереди, импорты и всё остальное, что пишет в базу: закрытый для посетителей сайт их не останавливает.
3. Убедитесь, что на диске хватает места: архив распаковывается целиком во временный каталог, и только потом файлы применяются.

Зачем закрывать сайт

Восстановление идёт не мгновенно: пока файлы и таблицы заменяются, сайт живёт с наполовину старым кодом и наполовину новой базой. Запросы в этот момент могут как отдать ошибку, так и записать в базу данные, которые тут же будут затёрты импортом дампа.

Шаг 1. Проверка архива

php core/components/mxbackup/cli/mxbackup.php restore-check --archive=/srv/backups/mxbackup-prod-20260805-031500.tar.gz

Что проверяется:

• архив существует, читается и распознаётся как ZIP или tar.gz;
• внутри есть mxbackup-manifest.json и database.sql;
• манифест корректен: схема, версии, профиль, режим, статус payload_ready и контрольная сумма database.sql;
• все пути внутри архива безопасны — абсолютные пути, выходы за пределы архива (..), повторяющиеся имена и символические ссылки отклоняются;
• основная версия MODX совпадает — архив с MODX 2 не восстановится в MODX 3 и наоборот, независимо от линии пакета и наоборот;
• при указании --checksum — контрольная сумма архива совпадает с ожидаемой (её удобно взять из истории запусков).

В ответе — состав архива, манифест, предупреждения и код подтверждения:

{
  "archive_name": "mxbackup-prod-20260805-031500.tar.gz",
  "archive_checksum": "3f7a…",
  "confirmation": "3f7a1c9d0e2b",
  "format": "tar.gz",
  "encrypted": false,
  "site_files": 12483,
  "warnings": []
}

Код подтверждения — первые 12 символов SHA-256 архива. Он привязан к конкретному файлу: подменённый или повреждённый архив даст другой код, и восстановление не начнётся.

Типичные предупреждения: версия MODX в архиве отличается от текущей в пределах одной основной версии; архив снят профилем dev и содержит обезличенную базу.

Шаг 2. Восстановление

php core/components/mxbackup/cli/mxbackup.php restore \
  --archive=/srv/backups/mxbackup-prod-20260805-031500.tar.gz \
  --scope=all \
  --confirm=3f7a1c9d0e2b

Если запустить restore без --confirm, команда выполнит проверку, напечатает нужный код и завершится с кодом возврата 2 — ничего не изменив.

--scope	Что восстанавливается
all	файлы и база данных
files	только файлы
database	только база данных

Что происходит внутри

1. Проверка конфигурации и разрешение каталога хранения.
2. Распаковка во временный каталог рядом с архивами. Перед распаковкой проверяется свободное место, после — контрольная сумма database.sql из манифеста и то, что сам архив не изменился по ходу проверки.
3. Сверка кода подтверждения и совместимости версии MODX.
4. Страховочная копия текущего сайта — незамаскированная production-копия по профилю pre-restore: почта выключена, ротация не применяется, чтобы копию не удалило собственными правилами хранения. Если копия не создалась, восстановление отменяется.
5. Блокировка каталога — параллельный запуск копии в этот момент невозможен.
6. Применение файлов и/или базы.
7. Запись в историю и сообщение в журнал уровня warning — восстановление всегда остаётся заметным событием.

Как применяются файлы

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

Режим — merge: файлы из архива перезаписывают одноимённые, недостающие каталоги создаются, а файлы, которых в архиве нет, остаются на месте.

Merge не убирает лишнее

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

Отдельные ограничения безопасности: элемент, которого нет в каталоге site/ архива, не восстанавливается; заменять каталог или символическую ссылку обычным файлом пакет не станет — вместо этого остановится с ошибкой.

Как применяется база данных

Импортёр принимает только тот синтаксис, который порождает сам mxBackup:

• DROP TABLE IF EXISTS для таблицы из дампа;
• CREATE TABLE;
• INSERT INTO.

Любое другое выражение прерывает импорт с ошибкой. Это защита от подсунутого файла: чужой дамп с триггерами, процедурами или GRANT через восстановление mxBackup не проедет.

Восстанавливаются только таблицы, которые есть в дампе. Таблицы, появившиеся после снятия копии, останутся нетронутыми — это важно помнить при частичном восстановлении.

Зашифрованный архив

Для архива с AES-256 нужен пароль:

MXBACKUP_ARCHIVE_PASSWORD='…' php core/components/mxbackup/cli/mxbackup.php restore-check --archive=/srv/backups/backup.zip

или файлом:

php core/components/mxbackup/cli/mxbackup.php restore-check --archive=/srv/backups/backup.zip --password-file=/root/.mxbackup-password

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

Восстановление из менеджера

Во вкладке «История» у успешной копии есть действие восстановления: пункт контекстного меню в MODX 2, кнопка в строке — в MODX 3. Порядок тот же: сначала проверка архива, затем ввод кода подтверждения и выбор области восстановления. В MODX 3 диалог проходит эти шаги явно, и кнопка запуска остаётся недоступной, пока введённый код не совпадёт с выданным. Действие доступно только при праве mxbackup_restore — см. Права и безопасность.

Через веб — только небольшие сайты

Восстановление выполняется синхронно, в одном запросе, и включает создание страховочной копии. На сколько-нибудь крупном сайте запрос оборвётся по таймауту — используйте CLI.

После восстановления

1. Очистите кэш MODX штатными средствами — через менеджер или консоль от пользователя сайта; вручную создавать каталоги в core/cache нельзя.
2. Проверьте вход в менеджер и работу сайта.
3. Верните настройку «Сайт опубликован» в «Да» и запустите обратно cron и очереди.
4. Сохраните путь к страховочной копии — он записан в отчёте о восстановлении и в журнале. Пока вы не убедились, что всё работает, удалять её не стоит.

Восстанавливайте только доверенные архивы

Контрольная сумма защищает от случайной порчи файла, но не является цифровой подписью: тот, кто подменил архив, мог пересчитать и её. Архив из непроверенного источника разворачивать нельзя.