Откат EDMS#

Общая информация об откате#

Откат всех компонентов EDMS выполняется полной переустановкой предыдущей версии EDMS.

Перед переустановкой предыдущей версии EDMS необходимо выполнить откат БД до версии, соответствующей устанавливаемой версии UI EDMS.

Если требуется выполнить откат до начальной версии EDMS, то выполняется последовательный откат всех версий от текущей до необходимой.

Для возврата текущей версии к настройкам по умолчанию необходимо восстановить первоначальную версию конфигурационных файлов (со значениями по умолчанию) и запустить установку EDMS.

Удаление текущей версии компонента перед откатом на предыдущую версию не требуется.

Обратная совместимость возможна при откате БД до предыдущей версии. Без отката БД предыдущая версия не поддерживается.

Откат БД#

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

Откат БД необходимо выполнить ДО запуска переустановки UI EDMS. Откат БД осуществляется запуском скрипта db-rollback, который поставляется внутри дистрибутива EDMS-dbinit-<версия>-distrib.zip в папке /db.

Для корректной работы скриптов необходимо произвести настройку Liquibase, она осуществляется с помощью файла liquibase.properties, в котором необходимо указать следующие параметры:

  • url — ссылка на базу данных;

  • schemas — название схемы, в которой будут находиться таблицы БД;

  • username — имя пользователя, имеющего права на запись в БД;

  • password — пароль пользователя;

  • logLevel — уровень логов, выводимый во время работы Liquibase (возможные значения: off, debug, info, warning, severe).

Запуск скрипта производится командой в терминале:

./db-rollback.sh <название тега>

Здесь <название тега> — имя тега БД, соответствующее версии БД, например release_1.2.

Список доступных тегов можно узнать в таблице БД EDMS edms_databasechangelog в поле tag. Скрипт для поиска по БД EDMS.

select id,filename,dateexecuted,tag from edms.edms_databasechangelog where tag like 'release_%';

Так же можно узнать список тегов по наличию файла-миграции. Для этого необходимо выполнить команду ls -R в директории /db, после чего произвести поиск CMD + F по ключевому слову release

Если выполнить команду с тегом, которого нет, то Liquibase выведет ошибку в логи. При этом миграции применяться не будут.

Команда tag используется для пометки состояния базы данных путем добавления тега к последней строке таблицы edms_databasechangelog. После установки тега становится возможным использовать команду отката (rollback) для отката всех изменений до этого тега.

Тег устанавливается в отдельном наборе изменений БД (в отдельном changeset), например:

<changeSet id="Add release 1.2 tag"
           author="Author"
           logicalFilePath="file.xml">
    <tagDatabase tag="release_1.2"/>
</changeSet>

Во время выполнения команды rollback производится последовательный откат всех изменений, указанных в наборе изменений changeset до строки tag в таблице edms_databasechangelog. Например, можно использовать команду rollback, когда необходимо отменить серию изменений, внесенных в БД, относящихся к определенному тегу, например, пронумерованному релизу.

Если указано несколько тегов, т.е. имеется несколько версий БД, то при попытке отката не на последнюю версию будет производиться последовательный откат до требуемой версии начиная с последней. Например, если существуют теги БД для версии 1, версии 2 и версии 3, и необходимо выполнить откат до версии 2, то сначала будет произведен откат до версии 3, затем до версии 2.

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

Функция бекап текущего состояния базы данных осуществляется администраторами БД.

Откат БД до предыдущей версии (ручной способ отката)#

Скрипты отката базы данных поставляются в составе дистрибутива ./EDMS-dbinit-{version}-distrib.zip .

Скрипты отката хранятся в папке emergency.

Для отката к версии компонента EDMS {version} необходимо использовать файл rollback_db_{version}.sql.

Установка или откат миграций БД с помощью Jenkins#

Получение cкриптов Jenkins пайплайн#

  1. Получить скрипты Jenkins пайплайн из каталога дистрибутива EDM-*-owned-distrib.zip/EDMS-scripts-*-distrib.zip/Pipeline.

  2. Выбрать в Jenkins New Item для создания нового Jenkins Job

NewItem

2.1. Добавить название создаваемого Jenkins Job.

2.2. Выбрать Pipeline и нажать кнопку «ОК».

NewItem_create

2.3. На появившейся странице необходимо заполнить поля в блоке Pipeline поля:

  • Поменять значение параметра „Definition“ на Pipeline script from SCM;

  • Поменять значение параметра SCM на Git;

  • Заполнить параметр „Repository URL“, в котором указать путь до вашего репозитория;

  • Заполнить параметр „Credentials“, в котором указать ваши Credentials с правами на чтение;

  • В параметре „Branches to build“ выбрать ветку, в которой находятся скрипты;

  • В параметре „Script Path“ указать путь до groovy-скрипта Pipeline/db_action.groovy;

  • Убедиться, что снята галочка Lightweight checkout.

Пример заполнения параметров
Pipeline_create

  1. Сохраняем получившийся Jenkins Pipeline.

  2. На появившейся странице, в боковом меню выбрать «Собрать сейчас». Запускается первоначальная сборка.

Now

  1. Результатом первого запуска Jenkins Job должно быть Finished: ABORTED.

  2. Проверить, что после запуска появились дополнительные параметры. Указать в поле jenkins_slave лейбл Jenkins Job для запуска задачи, в поле ansible_version указать версию tool Ansible (например ansible29).

  3. Запустить Jenkins Job повторно. После второго запуска должны появиться параметры nexus_user_cred, vault_cred, server_ssh_cred, заполнить их, используя jenkins credentials (или значения из Hashicorp Vault по примеру) и перезапустить Jenkins Job с включенным параметром job_config_renew для сохранения указанных значений.

  4. Настройка Jenkins Job выполнена.

  5. Опционально: если необходимо работать с несколькими ветками скриптов развертывания при помощи одного Jenkins Job, то это можно сделать при помощи параметра ansible_branch. Для этого необходимо зайти в настройки Jenkins Job и поменять параметр Branch Specifier (blank for „any“) на ${ansible_branch}.

Параметры Jenkins Job#

  • job_config_renew - обновление параметров job. Завершает сборку со статусом ABORTED.

  • inventory — имя inventory для установки.

  • nexusUrl — ссылка на дистрибутив со скриптами миграции (dbinit).

  • db_action

    • update — установка миграций

    • rollback — откат миграций к тегу $rollback_tag

  • rollback_tag — тег для отката миграций

  • custom_vault_password — требуется ли ручной ввод пароля для Ansible Vault?

  • jenkins_slave — выбор jenkins slave

  • ansible_branch — используется для работы с несколькими ветками скриптов развертывания. Работает только при значении Branch Specifier (blank for „any“) равным ${ansible_branch}.

  • ansible_version — версия ansible. Например, значение ansible29.

  • nexus_user_cred — Jenkins credential ID типа username with password для выкачивания дистрибутива. При задании secman_url - полный путь в Hashicorp Vault до пользователя и пароля, например, {ID credential типа vault app role для получение секретов из SecMan}|path/to/nexus:{имя пользователя},{пароль}.

  • vault_cred — Jenkins credential ID ID типа secret file со строкой для расшифровки паролей (ansible vault) (несколько через запятую). При задании secman_url - полный путь в Hashicorp Vault до пароля, например {Jenkins credential ID}|/path/to/vault:{password_1},{Jenkins credential ID_2}|/path/to/vault:{password_2} (в качестве пароля можно использовать не строку, а файл в base64 формате с ключом секрета, заканчивающимся на Base64, например, myVaultBase64).

  • server_ssh_cred — Jenkins credential ID credential типа ssh key для подключения к серверам. При задании secman_url - полный путь в Hashicorp Vault, например {Jenkins credential ID типа vault app role для получение секретов из SecMan}|/path/to/ssh:{юзер},{ключ},{passphrase} (в качестве ключа можно использовать не строку, а файл в base64 формате с ключом секрета, заканчивающимся на Base64, например myPrivateKeyBase64).

  • secman_url — URL для подключения к Hashicorp Vault.

  • second_hand_approve — подтверждение запуска другим администратором (контроль «второй рукой»). Двухэтапное подтверждение запуска, требующее действия другого администратора для запуска задания Jenkins Job. При активации этой опции одному администратору будет недоступна возможность запуска задания Jenkins Job без подтверждения со стороны другого администратора;

  • ssl_verify — проверка, являются ли сертификаты Hashicorp Vault/Nexus доверенными.

  • inventories_repo, inventories_branch, inventories_path - необязательные параметры. Выкачивание inventory из стороннего репозитория.

Использование Jenkins Job#

  1. Запустить Jenkins Job с помощью пункта меню Собрать с параметрами.

  2. Выбрать необходимое значение из списка inventory.

  3. Заполнить параметр nexusUrl ссылкой на дистрибутив со скриптами миграции.

  4. Выбрать необходимый db_action (update или rollback) и rollback_tag (при необходимости).

  5. Нажать кнопку Собрать.

  6. Дождаться окончания выполнения Jenkins Job.

В рамках работы Jenkins Job устанавливаются или откатываются миграции базы данных для компонента EDMS. В случае ошибки можно проанализировать ее через лог выполнения Jenkins Job.