Серверные расширения Pilot
Всё, что выполняется внутри Pilot-Server или помогает это разрабатывать. Три независимых решения, по одному на папку, и шаблон CI:
| Папка | Решение | Что это |
|---|---|---|
ServerHost/ |
ServerHost.sln |
Загрузчик серверных модулей и его тесты. Единственный .servext, который ставится в Pilot вручную; остальные модули он загружает и обновляет сам, без перезапуска сервера |
Debug/ |
Debug.sln |
Утилита debug.exe: запуск модуля под отладчиком на машине разработчика на реальных данных. Веб-админка для неё не обязательна |
TestServerAction/ |
TestServerAction.sln |
Пример обычного серверного модуля, образец для новых. Отдельный репозиторий в GitLab |
ci-template/ |
- | Шаблон .gitlab-ci.yml для репозитория серверного модуля |
Шаблон CI (ci-template)
ci-template/.gitlab-ci.yml кладётся в корень репозитория модуля (то же самое выдаёт админка): проверка версии и CHANGELOG, сборка zip, проверка библиотек, выкладка через админку в ServerHost контура.
Тег vX.Y.Z и GitLab Release ставит веб-админка при выпуске в прод - в CI их нет.
Это копия proadmin/.../Modules/ModuleCiTemplate.cs, файлы должны совпадать. Совпадение проверяет тест ServerModulesCiTests админки; он ищет папку server-extensions по имени, поэтому не переименовывайте её и ci-template.
Подпись zip необязательна: если в группе серверных модулей задана переменная MODULE_SIGNING_KEY, шаг build_module кладёт в архив signature.json,
и ServerHost, которому выдан открытый ключ, принимает только такие архивы. Нет переменной - zip собирается без подписи, как раньше.
Зачем это нужно и как включить: ServerHost/README.md, раздел «Подпись модулей».
Как написать новый серверный модуль
- Отдельный репозиторий в группе серверных модулей GitLab, в корне - один
.csproj(образец -TestServerAction.csproj):netstandard2.0,AssemblyName=<Имя>.servext,<Version>X.Y.Z</Version>;Ascon.Pilot.ServerExtensions.SDKиSystem.ComponentModel.CompositionсExcludeAssets="runtime"- они уже есть в Pilot-Server.
- Класс
[Export(typeof(IServerActivity))],Name- имя активности, которое указывают в сценарии автоматизации. Имя должно быть уникальным среди всех модулей. CHANGELOG.mdс разделом## [X.Y.Z],.gitlab-ci.yml- изci-template/(или из админки).- Ветки:
feature/KTN-…/dev(тест) /release/X.Y.Z(стейдж) /main(прод; тег и GitLab Release ставит админка).mainиrelease/*в GitLab защищены (см. ниже). - Отладка на реальных данных без выкладки -
Debug.
Ключи выкладки из CI
Job deploy_* отправляет zip в админку с двумя доказательствами: заголовком X-Deploy-Key (ключ контура) и заголовком
X-Job-Token ($CI_JOB_TOKEN задания). Админка проверяет токен в GitLab (GET /api/v4/job) и берёт оттуда ветку, коммит,
проект и pipeline; поля формы ref, sha, project, user, pipeline_url служат только для диагностики и обязаны совпасть
с проверенными значениями. Проект должен лежать в группе серверных модулей из настроек админки. Контур выбирается по проверенной
ветке: dev - тест, release/* - стейдж, main/master - прод; ключ сверяется с ключом этого контура.
Задание check_libraries ничего не выкладывает и шлёт только X-Job-Token.
Ключи раздельные, по одному на контур; админка читает их из proadmin/.env:
| Контур | Переменная proadmin/.env |
Переменная группы GitLab | Флаги в GitLab |
|---|---|---|---|
| тест | MODULES_DEPLOY_KEY_TEST (/ App__CiDeploy__Keys__test) |
DEPLOY_KEY_TEST |
Masked |
| стейдж | MODULES_DEPLOY_KEY_STAGE (/ App__CiDeploy__Keys__stage) |
DEPLOY_KEY_STAGE |
Masked и Protected |
| прод | MODULES_DEPLOY_KEY_PROD (/ App__CiDeploy__Keys__prod) |
DEPLOY_KEY_PROD |
Masked и Protected |
Пустой ключ контура - выкладка в этот контур из CI выключена.
Выпустить ключи (по одному на контур; при смене обновить значение и в proadmin/.env, и в GitLab):
openssl rand -hex 32
- Записать значения в
proadmin/.env(MODULES_DEPLOY_KEY_TEST,_STAGE,_PROD), затемdocker compose up -dвproadmin. - GitLab / группа / Settings / CI/CD / Variables / Add variable: три переменные из таблицы, Visibility Masked;
для
DEPLOY_KEY_STAGEиDEPLOY_KEY_PRODещё и Protect variable. Группы:client-modulesиserver-extensions. - В каждом репозитории модуля защитить ветки
mainиrelease/*(Settings / Repository / Protected branches): Allowed to push - No one, Allowed to merge - Maintainers. Protected-ключи доступны только заданиям на защищённых ветках, поэтому разработчик без права выпуска не прочитает ключ стейджа и прода в задании своей ветки. - Админка не на этом Docker-хосте - там же переменная
ADMIN_URL. Адресhttp://host.docker.internal:5300годится только внутри одного Docker-хоста; для админки на другой машине задайтеhttps://…, иначе ключи и zip идут открытым текстом.
Переход со старого общего ключа
Раньше использовалась одна переменная DEPLOY_KEY (MODULES_DEPLOY_KEY) без флага Protected и без X-Job-Token.
Теперь заданиям нужны токен задания и ключ своего контура, поэтому прежний .gitlab-ci.yml выкладку не пройдёт: обновите его из
ci-template/ (или кнопкой «Обновить CI и версию» в админке) и задайте три новые переменные. Старый общий ключ на стороне админки принимается
только для контура test и только пока не задан MODULES_DEPLOY_KEY_TEST; для stage и прод - никогда. После перехода удалите DEPLOY_KEY из групп GitLab.