Микросервис приложений Citeck

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

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

Микросервис, который управляет деплоем приложений и артефактов, называется ECOS Applications, или сокращённо ecos-apps.

Цели микросервиса:

  1. Версионирование артефактов. Изменения, принятые политикой загрузки, сохраняются как отдельные неизменяемые ревизии.

  2. Доставка артефактов от всех микросервисов к целевому (например, доставка форм из ecos-integrations, ecos-model, alfresco в ecos-uiserv).

  3. Отслеживание зависимостей. Если артефакт зависит от другого артефакта, то микросервис соблюдает порядок деплоя.

  4. Управление патчами для артефактов.

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

Простое описание

После обнаружения нового микросервиса ECOS Apps выполняет три основных этапа:

  1. Получает сведения о типах артефактов и поддерживающих их микросервисах.

  2. Загружает артефакты из зарегистрированных источников и сохраняет принятые изменения.

  3. Применяет патчи и развёртывает артефакты с учётом зависимостей и состояния целевых микросервисов.

Подробное описание

После готовности приложения запускается фоновый процесс ApplicationsWatcherJob. При нескольких экземплярах ECOS Apps обновлением управляет владелец блокировки watcher-job.

  1. Процесс получает статусы микросервисов через RemoteAppService и обновляет сведения об их экземплярах. После цикла предусмотрено ожидание до 5 секунд; полная длительность цикла зависит также от времени выполнения запросов.

  2. По отметкам изменения выбираются актуальные сведения о типах и источниках артефактов. ECOS Apps обновляет каталог типов, регистрирует источники и обработчики деплоя для поддерживаемых целевыми микросервисами типов.

  3. Из источников запрашиваются артефакты с учётом каталога типов и сохранённого времени предыдущей загрузки (since). Это позволяет загружать изменения, а не повторять полную загрузку на каждом цикле.

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

  5. ECOS Apps применяет патчи и проверяет зависимости. Артефакты, готовые к деплою, отправляются в целевой микросервис. Патчи могут потребовать повторного деплоя.

Изменение артефакта не гарантирует немедленного успешного деплоя. В частности, используются следующие статусы:

Статус

Значение

DRAFT

Артефакт ожидает деплоя.

DEPS_WAITING

Артефакт ожидает готовности зависимостей.

DEPLOY_FAILED

При деплое возникла ошибка.

DEPLOYED

Артефакт развёрнут.

Удалённые операции с типами, источниками и деплоем выполняются через RemoteAppService; для команд используется библиотека ecos-commands. ECOS Apps также предоставляет Records API и REST API.

Сообщения в логах

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

Фрагмент сообщения

Событие

Register deployer for

Регистрация обработчика деплоя с перечнем поддерживаемых типов.

Add application artifacts source. App:

Регистрация источника артефактов микросервиса.

Start artifacts uploading from source

Начало загрузки из источника с указанием новой и предыдущей отметок времени.

Create new artifact revision entity

Создание ревизии артефакта.

Artifact deploy failed:

Ошибка деплоя с описанием причин.

Полезные скрипты (EApps)

Получение артефактов по типу

Для получения страницы артефактов типа ui/form выполните следующий скрипт:

Records.query({
    sourceId: 'eapps/artifact',
    language: 'predicate',
    query: { t: 'eq', att: 'type', val: 'ui/form' },
    page: { maxItems: 100, skipCount: 0 }
}).then(console.log);

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

Для дальнейших операций используйте полную ссылку из результата поиска. Глобальная запись формы может иметь вид eapps/artifact@ui/form$ECOS_FORM, а запись рабочего пространства — eapps/artifact@ui/form$wsSysId:ECOS_FORM. Здесь wsSysId — системный идентификатор рабочего пространства; двоеточия в самом идентификаторе артефакта экранируются при формировании ссылки.

Получение содержимого артефактов

В журнале артефактов доступно действие выгрузки ревизий. REST API микросервиса предоставляет GET /api/artifact/download-revisions с параметрами ref (полная ссылка на артефакт) и fromTime (начальный момент времени в формате ISO 8601 со смещением). Ответ — ZIP-архив ревизий. Внешний URL зависит от маршрутизации к микросервису.

Извлечение содержимого ревизии напрямую из БД

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

select artifact.ext_id, artifact.workspace,
       rev.created_date, rev.created_by, rev.source_type, rev.content_id
from ecos_artifact artifact
join ecos_artifact_rev rev on artifact.id = rev.artifact_id
where artifact.ext_id = 'ECOS_FORM'
  and artifact.type = 'ui/form'
  and artifact.workspace = ''
  and artifact.deleted = false
order by rev.created_date desc;

Выбираем ревизию и подставляем её content_id в запрос содержимого. Ниже 14809 — пример значения, которое нужно заменить результатом предыдущего запроса:

select id, encode(data, 'base64')
from ecos_apps_content
where id = 14809;

Для сохранения base64 без заголовков и оформления таблицы в клиенте psql можно использовать команду \copy. Она создаст файл на компьютере, где запущен клиент:

\copy (select replace(encode(data, 'base64'), chr(10), '') from ecos_apps_content where id = 14809) to 'artifact.base64'

Декодируем файл локально, например в PowerShell из каталога, где он сохранён:

$artifactBase64 = [IO.File]::ReadAllText((Join-Path $PWD 'artifact.base64'))
[IO.File]::WriteAllBytes((Join-Path $PWD 'artifact.bin'), [Convert]::FromBase64String($artifactBase64))

Символ + входит в алфавит base64, поэтому удалять его из данных нельзя. При копировании из табличного вывода SQL-клиента удаляйте только оформление, однозначно отделённое от значения.

Полученный файл содержит байты выбранной ревизии. Формат определяется сериализацией типа артефакта; расширение следует выбирать по фактическому формату. Для получения ZIP-архива ревизий используйте действие выгрузки или REST API, описанные выше.

Полезные скрипты в базе ECOS Apps

Получение пользовательских ревизий артефакта
select artifact.ext_id, artifact.workspace,
       rev.created_date, rev.created_by, rev.source_type, rev.content_id
from ecos_artifact artifact
join ecos_artifact_rev rev on artifact.id = rev.artifact_id
where artifact.ext_id = 'ECOS_FORM'
  and artifact.type = 'ui/form'
  and artifact.workspace = ''
  and artifact.deleted = false
  and rev.source_type = 0
order by rev.created_date desc;

Источник конкретной ревизии определяется полем source_type:

Значение

Тип источника

Описание

0

USER

Пользователь.

1

ECOS_APP

ECOS-приложение.

2

APPLICATION

Микросервис.

3

PATCH

Патч.