ave-cms/help/modules/legacy-migration.md

Миграция из старой AVE.cms

← Назад к разделу «Модули»

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

Когда использовать

Миграция рассчитана на новую установку с двумя стартовыми документами. На сайте, где уже создан рабочий контент, запуск будет заблокирован. Для повторяемой загрузки CSV, Excel или XML используйте «Импорт документов».

Порядок работы

1. Создайте отдельную пустую AVE.cms и установите модуль.
2. Откройте Модули → Миграция AVE.cms, добавьте доступ к старой БД и нажмите Сохранить и проверить.
3. Модуль автоматически выполнит анализ. Он читает схему и счётчики, но не меняет исходную или целевую БД.
4. Проверьте карту переноса. Для каждой сущности показаны исходная таблица, целевая таблица и количество строк. Исправьте критические замечания о таблицах ядра и типах полей.
5. Начните перенос. Запуск сразу создаёт задание, а сжатая JSONL-копия затрагиваемых таблиц, настроек и системных пользователей формируется отдельными AJAX-шагами до очистки стартового контента.
6. Дождитесь сверки количества строк.
7. Упакуйте старый uploads/ в ZIP и загрузите его в завершённый запуск.
8. Установите нужные модули заново, проверьте PHP-код и переиндексируйте поиск.

Прогресс и продолжение

Перенос не выполняется одним длинным HTTP-запросом. Модуль последовательно проходит этапы:

1. резервная копия целевых таблиц;
2. очистка только стартовых данных;
3. перенос таблиц порциями;
4. нормализация полей, запросов, блоков, пользователей и настроек;
5. сверка количества строк.

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

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

Кнопка Откатить перенос появляется только после полного создания резервной копии. Незавершённый файл копии не используется для восстановления.

Что переносится

• шаблоны, рубрики, группы и поля;
• документы, значения полей, ревизии, теги, keywords, редиректы и просмотры;
• запросы и условия, меню и пункты, блоки;
• публичные пользователи и группы;
• привилегированные legacy-пользователи групп 1 и 3 как системные учётные записи.

Главная страница переносится вместе с документом ID 1. Стартовая главная чистой установки удаляется перед записью. Страница 404 также входит в общий перенос документов, а её ID берётся из перенесённых настроек старого сайта. Поэтому ссылки и связи между документами не перенумеровываются.

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

Новые JSON-настройки полей создаются из legacy-значений. Для старых условий запросов создаётся корневая группа. Обычные визуальные блоки переводятся в единый реестр блоков.

Колонки, которых не было в старой AVE.cms, заполняются безопасными начальными значениями. Например, для документов создаются пустые guid и module_catalog, а для рубрик — пустой OG-шаблон. Допустимые в старой MyISAM значения NULL приводятся к формату обязательных колонок новой схемы.

Основные настройки старого сайта переносятся одновременно в системный реестр и в публичную конфигурацию. Старые опечатки в именах параметров хлебных крошек исправляются автоматически. Пароли БД, SMTP и другие секреты не копируются: их нужно заполнить заново после проверки переноса.

Скомпилированный SQL и подтверждение Native не переносятся между базами: условия сохраняются, но запрос запускается в Legacy до новой проверки в панели управления. В конце переноса удаляются старые JSON-снимки документов и схем рубрик. На первом публичном открытии они строятся заново пакетно из уже перенесённых данных. Откат выполняет такой же сброс, поэтому кеш не может остаться от отменённого переноса.

Что не переносится автоматически

• активные сессии, remember-токены, API-ключи и аудит;
• пароли и секреты платёжных систем;
• старые PHP-модули, их файлы и все таблицы с префиксом module_;
• код темы и другие исполняемые файлы;
• данные каталога, корзины, заказов, контактов и других старых модулей.

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

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

Что считается чистой установкой

Установщик создаёт два документа, одну стартовую рубрику, шаблон, поля, меню и служебные строки для главной и 404. Эти данные не блокируют миграцию и будут заменены.

Если в документах, рубриках или шаблонах уже появился другой рабочий контент, анализ остановит запуск. Ключевые слова, ревизии и просмотры тоже допустимы, пока они относятся только к стартовым документам ID 1 и ID 2.

Такое ограничение защищает от случайного запуска миграции поверх уже наполненного нового сайта.

Хуки миграции

Хук	Данные	Назначение
legacy_migration.plan	profile, tables, plan	Дополнить план после анализа.
legacy_migration.row	run, job, row	Изменить одну строку перед записью.
legacy_migration.completed	run, report	Запустить постобработку после сверки.

Обработчик legacy_migration.row должен вернуть весь контекст с изменённым row. Через него модуль-приёмник может перекодировать колонку или перевести значение старого модуля в новый формат.

Безопасность файлов

ZIP распаковывается порциями. Модуль отклоняет:

• абсолютные пути и ../;
• символические ссылки;
• .htaccess, .user.ini, точечные и исполняемые файлы;
• двойные исполняемые расширения;
• архивы свыше 100 000 файлов или 10 ГБ после распаковки.

Файлы записываются только в uploads/. По умолчанию существующие файлы не заменяются.

После переноса

Автоматическая сверка проверяет строки, но не заменяет приёмку. Откройте реальные страницы каждой рубрики, проверьте меню, запросы, блоки, медиа и сохранённый PHP-код. При любом расхождении не удаляйте исходную БД и локальную резервную копию запуска.

Если запись остановилась, отчёт показывает целевую таблицу и ID исходной строки, на которой MySQL вернул ошибку. Это позволяет исправить конкретное значение в копии старой БД и повторить анализ, не перебирая весь дамп.

Кнопка Откатить перенос доступна для завершённого, ошибочного или отменённого запуска. Она восстанавливает снимок целевой БД. Файлы, уже записанные из ZIP в uploads/, автоматически не удаляются: перед файловым переносом сохраните отдельную копию uploads/.