Миграция с 7.14.x на 8.7.0+

В разделе описывается обновление до версий 8.7.0+

1. Предварительная подготовка

Указание версии 7.14.x+ означает, что приводимая информация относится к версии 7.14.x или более поздним версиям системы.

  • Прежде всего убедитесь, что установленная система соответствует требованиям, указанным в Таблице совместимости.

  • Вначале рекомендуется запустить процесс миграции на тестовом экземпляре системы и уже после удачного переноса запустить процесс на рабочем экземпляре системы.

Не забудьте сделать резервные копии файлов системы и БД.

  • Обновите установленную версию SuiteCRM 7.x до версии 7.14.x.
    Обязательно выполните все дополнительные действия по обновлению, если они отдельно описаны в примечаниях к релизу для соответствующей версии.

  • По умолчанию команды обновления устанавливают для директивы error_reporting менее строгий режим для подавления предупреждений, присваивая ей значение E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE & ~E_WARNING.
    Если вы хотите установить более строгий режим, укажите -vvv для каждой из команд. Этот ключ присвоит директиве error_reporting значение E_ALL.

Обратите внимание: в процессе миграции из папки public/legacy могут быть удалены любые файлы и папки, не относящиеся к основным файлам SuiteCRM.

2. Шаги обновления

Запускайте процесс миграции только после обновления до последней актуальной версии SuiteCRM ветки 7.x.

Перед выполнение команд, указанных ниже, убедитесь, что переменная APP_ENV в файлах .env или .env.local установлена в значение prod.

2.1. Загрузка пакета

  1. Загрузите необходимый пакет с этой страницы (например - 8.7.0 Migrate from 7.14.x.)

  2. Распакуйте скачанный архив в папку, в которой должна быть установлена SuiteCRM 8.x, например, в папку /var/www/<SuiteCRM8-folder>

  3. При необходимости установите соответствующие права доступа.

2.2. Копирование файлов SuiteCRM 7.14.x+

  1. Скопируйте папку с уже установленной SuiteCRM 7.14.x+ в папку public устанавливаемой SuiteCRM 8.x, например, из указанного выше примера в папку /var/www/<SuiteCRM8-folder>/public/<SuiteCRM 7 Instance>

  2. Переименуйте скопированную папку с SuiteCRM 7.14.x+ в legacy.

  3. При необходимости установите соответствующие права доступа.

Если вы используете git, настоятельно рекомендуется удалить папку .git из папки public/legacy/.

2.3. Ручное обновление некоторых файлов и папок

Начиная с SuiteCRM 8.7.x / Symfony 6.4, процесс миграции требует ручного обновления некоторых папок и файлов перед запуском скриптов миграции.

Это обеспечит более плавную миграцию с SuiteCRM 7 на SuiteCRM 8.

Для этого необходимо заменить две папки и один файл новыми, входящими в состав пакета миграции.

  1. Скопируйте папку vendor из /var/www/<SuiteCRM8-folder>/tmp/package/upgrade/legacy-migration/vendor и полностью замените существующую папку /var/www/<SuiteCRM8-folder>/public/legacy/vendor

  2. Скопируйте папку include из /var/www/<SuiteCRM8-folder>/tmp/package/upgrade/legacy-migration/include и полностью замените существующую папку /var/www/<SuiteCRM8-folder>/public/legacy/include

  3. Скопируйте файл deprectated.php из /var/www/<SuiteCRM8-folder>/tmp/package/upgrade/deprecated.php и замените существующий файл /var/www/<SuiteCRM8-folder>/public/legacy/deprectated.php

2.4. Права доступа

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

2.5. Выполнение команды предварительной подготовки

  1. Из корневой папки SuiteCRM 8 запустите:

    ./bin/console suitecrm:app:setup-legacy-migration
  2. Вам будет предложено вручную выполнить ряд действий по изменению некоторых директив в файле конфигурации, расположенном в папке legacy:

    • Установите директиву session_dir в пустое значение (''). По окончании миграции вы можете установить необходимое значение session_dir.
      Обратите внимание, что настройка session_dir в SuiteCRM 8 отличается от SuiteCRM 7, детали описаны в разделе Настройка сессий.

    • Измените значение директивы site_url на адрес, по которому будет доступна SuiteCRM 8.x.

      Если виртуальный сервер не указывает на каталог public в корневой папке SuiteCRM 8, то необходимо добавить /public к значению параметра site_url, например 'site_url' ⇒ 'https://your-host/crm/public',.

  3. Вам будет предложено вручную выполнить ряд действий по изменению директивы RewriteBase в файле .htaccess, расположенном в папке legacy:

Если виртуальный сервер указывает на каталог public, то директива RewriteBase должна выглядеть как RewriteBase /legacy.
В противном случае необходимо указать путь до папки public. Например, если адрес сайта - https://your-host/crm/public, то директива RewriteBase должна выглядеть как RewriteBase /crm/public/legacy.

2.6. Выполнение команды обновления

Из корневой папки SuiteCRM 8 запустите: ./bin/console suitecrm:app:upgrade -t "<версия>",

где <версия> - название пакета с устанавливаемой SuiteCRM 8, например: SuiteCRM-8.7.0

Пример:

./bin/console suitecrm:app:upgrade -t SuiteCRM-8.7.0

2.7. Выполнение команды финализации

Если обновляемый экземпляр системы был значительно кастомизирован, на этом этапе могут возникнуть проблемы. Убедитесь, что изменённый код совместим с минимальной версией php, указанной в Таблице совместимости.

Из корневой папки SuiteCRM 8 запустите:

./bin/console suitecrm:app:upgrade-finalize

Режимы слияния метаданных

В этой команде вы можете указать режим слияния, который вы хотите использовать при объединении метаданных, указав необходимый режим после ключа -m.

По умолчанию используется режим keep.

  1. Режим KEEP

    • Этот режим сохранит все существующие ранее метаданные, слияние выполняться не будет.

    • Этот режим используется по умолчанию.

      В консоли выполните:

      ./bin/console suitecrm:app:upgrade-finalize -m keep
  2. Режим MERGE

    • Этот режим попытается объединить все существующие ранее метаданные с новыми метаданными. Объединение будет выполнено для каждого модуля.

    • Объединенные метаданные помещаются в папку custom соответствующего модуля: public/legacy/custom/<Module>/metadata

    • В эту же папку добавляется файл резервной копии предыдущей версии метаданных

      В консоли выполните:

      ./bin/console suitecrm:app:upgrade-finalize -m merge
  3. Режим OVERRIDE

    • Этот режим заменит все текущие настройки новой версией метаданных.

В результате будут удалены все текущие файлы настроек из папки public/legacy/custom/<Module>/metadata!

В консоли выполните:

./bin/console suitecrm:app:upgrade-finalize -m override

2.8. Переустановка прав

Если во время процесса миграции вы использовали пользователя/группу, которые не совпадают с теми, которые используются веб-сервером, вам следует переустановить соответствующие права.

2.9. Очистка кеша php (опционально)

Если вы используете OPCache, ACP или другие оптимизаторы, может потребоваться перезапуск веб-сервера, чтобы применённые изменения вступили в силу.

2.10. Вход в систему

Если все вышеперечисленные шаги были выполнены правильно, вы сможете войти в обновленный экземпляр SuiteCRM 8.

3. Файлы журнала и отладка системы

3.1. Файлы журнала

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

Есть несколько файлов журнала, которые могут предоставить дополнительную информацию:

  1. logs/upgrade.log

    Файл журнала, создаваемый при обновлении SuiteCRM 8.

  2. public/legacy/upgradeWizard.log

    Специальный журнал обновления, создаётся устаревшей частью приложения. файл создается на этапе legacy-post-upgrade.

  3. logs/<app-env-mode>/<app-env-mode>.log

    Основной журнал системы. Путь к файлу и его имя меняются в соответствии со значением, установленным в переменной APP_ENV. Например, если значение установлено в prod, путь к файлу журнала будет logs/prod/prod.log

    В этом журнале скорее всего не будет содержаться много информации об обновлении.

  4. public/legacy/suitecrm.log

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

3.2. Переменная APP_ENV

При запуске приложения в рабочем режиме переменная APP_ENV в файлах .env или .env.local должна быть установлена в значение prod. Однако в этом режиме не вся отладочная информация будет регистрироваться.

Один из способов получить более детальную информацию — изменить значение переменной APP_ENV на qa (этот режим следует использовать только временно).

После этого очистите кеш symfony.

4. Возможные проблемы

4.1. Проблемы с токеном CSRF

При выполнении наших внутренних тестов мы сделали несколько установок и обновлений. Эти тесты обычно проводились на одном и том же URL / экземпляре приложения.

Может случиться так, что в процессе обновления файлы cookie не обновляются, что может помешать пользователю использовать приложение.

Если вы получаете сообщение об ошибке Invalid CSRF token, попробуйте очистить файлы cookie и обновить страницу. Это позволит серверу сгенерировать новые cookie для новой сессии.

4.2. Администратор забыл переустановить права после миграции на новую версию SiuteCRM

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

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

Имейте в виду, что когда вы запускаете команды под другим пользователем (например, под пользователем root), php будет использовать именно его, что повлияет на создание файлов: права будут установлены именно для этого пользователя и группы.

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

4.3. Отсутствует команда suitecrm:app:setup-legacy-migration или возникают ошибки при её выполнении

Мы заметили, что обычно эти ошибки возникают при использовании неправильного пакета.

Убедитесь, что вы используете именно пакет миграции на новую версию, а не пакет установки SuiteCRM 8. Пакет миграции — это специальный пакет, созданный специально для перехода с версии 7.x на 8.x.

Название пакета миграции соответствует шаблону SuiteCRM-8.x-7.x-migration, где 8.x и 7.x — номера соответствующих версий.

4.4. Не знаю, куда поместить папку/экземпляры SuiteCRM 7 или SuiteCRM 8

При обновлении до SuiteCRM 8 вам понадобится специальный пакет миграции. Пакет миграции не применяет обновление поверх существующего экземпляра SuiteCRM 7, другими словами, вы не должны загружать этот пакет в мастер обновления SuiteCRM 7.

Процесс работает наоборот, экземпляр SuiteCRM 7 будет перемещен/скопирован в экземпляр SuiteCRM 8.

Пакет миграции аналогичен установочному пакету SuiteCRM 8, но без папки public/legacy. Папка SuiteCRM 7 должна быть скопирована в папку public разархивированного пакета миграции, а затем переименована в legacy.

Позже, при запуске команд обновления, код SuiteCRM 7, находящийся в папке public/legacy, будет обновлён соответствующим кодом из пакета миграции SuiteCRM 8.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.