Миграция в Drupal: рабочие приёмы без потери данных

Миграция в Drupal 10 или 11 редко сводится к переносу таблиц из одной базы в другую. Основные потери происходят позже: ссылки на пользователей превращаются в пустые значения, изображения остаются на старом сервере, а повторный запуск создаёт дубликаты. Ниже — рабочий подход для переноса контента из Drupal 7 в Drupal 10/11 через Migrate API: как выбрать способ, описать поля, сохранить связи и проверить результат до переключения сайта.

Сначала определите границы переноса

Не начинайте с YAML-файлов. Сначала составьте карту данных: какие сущности переезжают, какие поля обязательны, что делать с удалёнными материалами, пользователями, файлами, таксономией, переводами и URL.

• Зафиксируйте исходную версию Drupal, целевую версию и версии PHP, базы данных и Drush.
• Составьте список типов материалов, таксономий, ролей, пользователей и медиафайлов.
• Отдельно отметьте поля, для которых нет прямого соответствия в новой схеме.
• Сохраните резервную копию исходной базы и файловой директории.
• Определите критерии готовности: число материалов, доступность файлов, работа ссылок, корректность языков и авторов.

Для примеров ниже предполагается перенос с Drupal 7 на Drupal 10 или 11. Команды относятся к актуальным веткам Drush, совместимым с вашей версией Drupal; перед запуском проверьте совместимость в документации конкретного релиза.

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

Сноска. Маппинг — правило соответствия между исходным полем и полем в Drupal. Например, старое поле body должно попасть в value нового текстового поля, а исходный идентификатор автора — в uid после поиска соответствующего пользователя.

Какой способ выбрать

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

Для Drupal 7 обычно разумно начать с миграций ядра и добавить Migrate Plus только там, где стандартного источника недостаточно. Полный экспорт в CSV удобен для небольших справочников, но плохо подходит для материалов с файлами, переводами и ссылками на другие сущности.

Рабочий процесс миграции

1. Подготовьте отдельный стенд

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

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

2. Переносите справочники раньше контента

Сначала запускайте пользователей, роли, термины таксономии и файлы, затем материалы. Иначе поле автора или ссылка на термин не найдут соответствующую сущность.

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

3. Описывайте поля явно

В собственном migration-плагине не полагайтесь на совпадение имён. Для Drupal 7 и Drupal 10/11 схема полей отличается, а текстовое поле состоит как минимум из значения и формата.

id: legacy_articles
label: Legacy articles
migration_group: legacy
source:
  plugin: d7_node
  node_type: article
process:
  type:
    plugin: default_value
    default_value: article
  title: title
  body/value: body/value
  body/format: body/format
  uid:
    plugin: migration_lookup
    migration: upgrade_user
    source: uid
    default_value: 1
destination:
  plugin: entity:node
  default_bundle: article
migration_dependencies:
  required:
    - upgrade_user

Этот фрагмент рассчитан на Drupal 10/11 с миграционными плагинами и соответствующими конфигурациями переноса Drupal 7. Идентификатор миграции пользователей должен совпадать с тем, который реально зарегистрирован в вашем проекте. Если имя отличается, его нужно взять из списка доступных миграций, а не угадывать.

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

4. Сохраняйте связи через таблицу соответствий

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

Ту же логику применяйте к полям ссылок, изображениям и родительским материалам. Если связанная миграция ещё не выполнена, добавьте её в зависимости. Если связь необязательна, заранее определите, что делать с отсутствующим объектом: оставить поле пустым, назначить замену или остановить импорт.

Проверка: выборочная проверка десяти-двадцати материалов показывает правильных авторов, термины и ссылки, а не только заполненные числовые значения.

5. Переносите файлы отдельно от полей

Файл в Drupal — это не только путь на диске. У него есть сущность, URI, владелец и связь с полем материала. Сначала перенесите сами файлы и проверьте доступность URI, затем импортируйте материалы, которые на них ссылаются.

Не заменяйте абсолютные URL строковыми операциями без списка исключений. В тексте могут встречаться внешние ссылки, изображения из CDN и ссылки на документы, которые не должны переезжать.

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

6. Импортируйте небольшими партиями

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

Базовый цикл обычно выглядит так: посмотреть список и статус миграций, выполнить импорт, изучить сообщения, затем проверить данные в интерфейсе и базе. Точные имена команд зависят от версии Drush, но в актуальных версиях используются группы migrate:status, migrate:import, migrate:messages и migrate:rollback.

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

Что обычно ломается

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

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

Материалы есть, но изображения не открываются

Проверьте не только наличие файлов на диске, но и корректность URI, схемы public/private и прав веб-сервера. Ошибка в каталоге файлов часто маскируется под проблему поля изображения.

Текст выглядит как HTML или показывает служебные теги

Обычно перенесено значение, но не перенесён формат текста либо выбран формат, которого нет на целевом сайте. Сопоставьте старые форматы с разрешёнными форматами Drupal 10/11 и отдельно протестируйте фильтры.

Автором становится один и тот же пользователь

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

Откат удаляет не всё

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

Как проверить результат до переключения

Сравнивайте не только общее количество строк. Нужны выборки по редким и проблемным случаям: материал без изображения, материал с несколькими терминами, перевод, удалённый автор, длинное тело, HTML-таблица и документ с пробелами в имени.

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

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

Когда выбирать другой подход

Миграции Drupal подходят, когда важны связи сущностей, повторяемость и журнал операций. Внешний ETL оправдан для большого количества разрозненных источников, но тогда вы сами отвечаете за таблицу соответствий, повторный запуск и обработку ошибок. Ручной CSV-импорт годится для небольших справочников, которые не связаны с файлами, переводами и редакционными правами.

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

Что делать дальше

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