Ручная миграция на Grav 2.0¶

Для большинства сайтов подходящий инструмент — плагин Migrate to Grav 2.0. Он автоматизирует каждый шаг процесса и выполняется в чистом окружении PHP вне Grav 1.x.

Есть конфигурации, для которых допущения мастера не подходят:

• Мультисайтовые установки с общими папками пользователей или окружениями для каждого сайта
• Сложные схемы символических ссылок (например, user/pages, user/data или отдельные папки плагинов, связанные символическими ссылками в процессе развёртывания)
• Внешне смонтированные папки user/ (NFS, sshfs, тома Docker)
• Собственные или приватные плагины, которых нет в GPM и которые пока не заявляют совместимость с 2.0
• Конвейеры сборки, где сайт генерируется CI, а не редактируется на месте

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

Предварительные требования¶

• Доступ к оболочке сервера
• PHP 8.3 или новее, доступный где-нибудь в PATH (он не обязан пока быть PHP по умолчанию для действующего сайта)
• Права на запись в папку рядом с действующим webroot для подготовленной установки

Шаг 1. Создайте резервную копию действующего сайта¶

Перед любыми изменениями сделайте полную резервную копию действующей установки 1.x:

cd /path/to/grav-site
bin/grav backup

Или вручную упакуйте user/, backup/ и logs/.

Храните эту резервную копию вне webroot.

Шаг 2. Подготовьте свежую установку Grav 2.0¶

Скачайте последнюю стабильную сборку Grav 2.0:

cd /path/to/grav-site
curl -L -o /tmp/grav-2.0.zip https://getgrav.org/download/core/grav-update/latest

Распакуйте её рядом с действующей установкой. Архив содержит папку верхнего уровня grav-admin/, которую мы переименуем в grav-2/:

unzip /tmp/grav-2.0.zip -d /tmp/grav-2.0-extract
mv /tmp/grav-2.0-extract/grav-admin ./grav-2

Теперь у вас есть чистая установка Grav 2.0 в ./grav-2/ рядом с неизменённым Grav 1.x в ./.

Шаг 3. Решите вопросы совместимости плагинов и тем¶

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

Для каждого пакета в user/plugins/ и user/themes/:

Проверьте флаг совместимости¶

Откройте blueprints.yaml пакета и найдите блок compatibility::

compatibility:
  grav:
    - '1.7'
    - '2.0'

• Указан 2.0: пакет готов для 2.0. Установите его через GPM в подготовленную копию.
• Указан только 1.7: пакет не готов для 2.0. Пропустите его, установите отключённым или портируйте самостоятельно (см. ниже).
• Блока compatibility: нет: используйте вывод по зависимостям: если dependencies: объявляет grav >= 2.0, считайте пакет совместимым с 2.0; иначе — только с 1.7.

Полные правила см. в разделе Совместимость плагинов.

Заново установите совместимые пакеты¶

Не копируйте папки плагинов из установки 1.x. Загрузите каждый совместимый пакет заново из GPM в подготовленную копию:

cd grav-2
bin/gpm install <plugin-slug>

Для тем:

bin/gpm install -t <theme-slug>

Так вы гарантированно получите релиз, готовый для 2.0, а не копию 1.x. Многие плагины в версиях 2.0 претерпели значительные изменения (зависимости Composer, папки vendor, интеграция с API), которые потерялись бы при копировании.

Работа с собственными и приватными плагинами¶

Для плагинов, которых нет в GPM:

1. Скопируйте папку плагина из user/plugins/<name>/ в grav-2/user/plugins/<name>/.
2. Откройте его blueprints.yaml и добавьте блок compatibility:, объявляющий 2.0, после того как убедитесь, что он работает.
3. Если плагин использует зависимости Composer, выполните composer install --no-dev в его папке с PHP 8.3+.
4. Если плагин ещё не портирован, см. страницу Разработка с помощью ИИ — там описан быстрый путь портирования.

Отключите, а не удаляйте¶

Если есть плагины, которые вы хотите оставить в файловой системе, но не загружать в 2.0 (например, пока ждёте версию 2.0 от автора), скопируйте папку и добавьте запись конфигурации, отключающую плагин:

grav-2/user/config/plugins/<plugin-name>.yaml:

enabled: false

Это соответствует поведению политики «disable» в мастере.

Шаг 4. Скопируйте учётные записи пользователей¶

Скопируйте файлы учётных записей:

cp -a user/accounts/. grav-2/user/accounts/

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

В Grav 1.7 с классической админкой разрешения админки находятся в пространстве имён admin.*:

access:
  admin:
    login: true
    super: true
  site:
    login: true

Админка Grav 2.0 (admin2) — клиент плагина API, и она проверяет пространство имён api.*. Учётная запись, которая даёт только admin.login, будет отклонена на экране входа в admin2. В каждом файле учётной записи продублируйте каждый ключ admin.* соответствующим ключом api.* с тем же значением:

access:
  admin:
    login: true
    super: true
  api:
    login: true
    super: true
  site:
    login: true

Несколько деталей, которые стоит знать:

• Дублируйте, а не переименовывайте. Оставьте записи admin.* на месте и добавьте рядом api.*. Если оставить оба варианта, учётная запись будет работать независимо от того, проверяет ли конкретный плагин старое пространство имён или новое.
• Встречаются обе формы YAML. Старые учётные записи иногда используют плоскую форму с точками (admin.login: true как один ключ внутри access:), а не вложенный блок выше. Правило то же: каждый admin.X получает соседний api.X.
• Разрешения site.* не затрагиваются. Перемещается только пространство имён admin.*; доступ site.* на фронтенде переносится как есть.

Шаг 5. Скопируйте контент и конфигурацию¶

Эти папки совместимы по формату контента между 1.7 и 2.0 и могут быть скопированы как есть:

cp -a user/pages/.     grav-2/user/pages/
cp -a user/config/.    grav-2/user/config/
cp -a user/data/.      grav-2/user/data/
cp -a user/env/.       grav-2/user/env/
cp -a user/languages/. grav-2/user/languages/

Проверьте устаревшие ключи конфигурации¶

Небольшое число ключей system.yaml в 2.0 переименовано или удалено. Мастер migrate-grav показывает их с предложенными заменами; при ручной миграции нужно после копирования просмотреть system.yaml и сверить все помеченные ключи с примечаниями к выпуску Grav 2.0.

Шаг 6. Проверьте подготовленный сайт¶

Откройте подготовленную копию в браузере. В зависимости от конфигурации веб-сервера это один из вариантов:

• http://your-site.test/grav-2/ (относительная подпапка)
• http://stage.your-site.test/ (отдельный виртуальный хост, указывающий на grav-2/)
• Отдельная машина разработки, где вы полностью настроили подготовленную копию

Проверьте:

• Главная страница и репрезентативная выборка страниц отображаются корректно
• Вход в админку работает с существующими учётными данными
• Каждый включённый плагин загружается без ошибок (проверьте logs/grav.log)
• Активная тема отображается корректно (Grav 2.0 поставляется с Quark 2 в качестве темы по умолчанию; если для вашей старой темы ещё нет версии 2.0, возможно, стоит переключиться)
• Отправка форм, вход пользователей и любая функциональность плагинов работают как ожидается
• Страницы, которые использовали Twig в контенте ({{ ... }} или {% ... %} в теле страницы), по-прежнему отображаются как задумано. Grav 2.0 по умолчанию отключает эту фичу, поэтому такие страницы показывают необработанный Twig, пока вы её не включите; отчёт Инструменты → Отчёты → Twig в контенте перечисляет все затронутые страницы. Как включить фичу и какие есть более безопасные альтернативы, см. в разделе Twig в контенте
• Страницы, которые вставляли необработанный HTML в тело (например, YouTube <iframe>, виджет <script> и подобное), по-прежнему отображаются. По умолчанию Grav 2.0 экранирует небольшой фиксированный список запрещённых тегов необработанного HTML в выводе Markdown (GitHub Flavored Markdown tagfilter), поэтому затронутая вставка теперь показывается как обычный текст. Почему это происходит и как снова разрешить тег или вставить элемент через шорткод, см. в разделе Разрешение iframe и другого необработанного HTML

Шаг 7. Переключитесь на подготовленную копию¶

Это единственный шаг, который изменяет действующий webroot. Если можете, делайте это в часы низкой нагрузки.

Создайте окончательную резервную копию¶

cd /path/to/grav-site
zip -r migration-backup-$(date +%Y%m%d-%H%M%S).zip . -x 'grav-2/*' 'tmp/*' 'cache/*' 'backup/*'
mv migration-backup-*.zip /somewhere/safe/

Замените подготовленной копией действующий сайт¶

Отодвиньте все элементы верхнего уровня, кроме grav-2/, а затем переместите содержимое grav-2/ на их место:

cd /path/to/grav-site
mkdir _old
shopt -s extglob dotglob
mv !(grav-2|_old|tmp|cache|backup) _old/ 2>/dev/null
mv grav-2/* grav-2/.* . 2>/dev/null
rmdir grav-2

Очистите кэш¶

bin/grav clear-cache --all

Проверьте¶

Перезагрузите действующий сайт. Если всё работает, готово. Папка _old/ — ваш немедленный путь к откату: верните её на место, если что-то сломалось.

Шаг 8. Уберите за собой¶

После дня-двух стабильной работы на 2.0 удалите папку для отката:

rm -rf _old

Zip-архив резервной копии миграции, созданный на шаге 7, храните бессрочно.

Когда лучше вернуться к плагину¶

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

1. rm -rf grav-2/, чтобы отбросить частичную ручную подготовку
2. Установите плагин Migrate to Grav 2.0 на действующий сайт 1.x
3. Позвольте мастеру сделать остальное

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