ServerHost
Центральный серверный модуль Pilot: единственный .servext, который ставится штатно. Остальные серверные модули он
загружает сам и обновляет без перезапуска сервера. Открывать в Visual Studio - ServerHost.sln.
dotnet build ServerHost.sln
dotnet test ServerHost.sln
ServerHost/
├─ ServerHost/ сам модуль (net8.0), в Release - dist/ServerHost.zip
│ ├─ Contract/ API хоста для веб-админки (IServerModulesApi; копия - в proadmin)
│ ├─ Exports/ то, что видит Pilot через MEF: 64 слота активностей + фабрика API
│ └─ Hosting/ хранение, проверка архива, загрузка в выгружаемые контексты, статистика
└─ ServerHost.Tests/ xUnit-тесты хоста
Установка: собрать в Release и один раз загрузить dist/ServerHost.zip в Pilot («Модули расширения» / серверное расширение).
Обновление самого хоста: Pilot-Server читает хост только при старте, поэтому новая версия вступает в силу после перезапуска сервера Pilot (всех узлов в кластере). Загрузить dist/ServerHost.zip новой версии можно из веб-админки (страница «Серверные модули», блок «Сам ServerHost», только администратору прода) вместо клиента Pilot: она проверяет архив (в корне ServerHost.servext.dll, версия не ниже записанной в базе) и записывает его в объект хоста. Остальные модули при этом обновляются на лету, как и раньше.
Как это работает
GitLab (репозиторий модуля, ci-template)
│ build_module / zip
Веб-админка (proadmin) POST /api/ci/server-modules/deploy, страница «Серверные модули»
│ IServerModulesApi (через подключение к базе, только администратор)
Pilot-Server ── ServerHost.servext ── modules/<Имя>/current ── <Имя>.servext.dll (свой AssemblyLoadContext)
Почему нужен хост. Pilot-Server загружает *.servext один раз при старте, и замена модуля штатно требует
перезапуска сервера. ServerHost - единственный модуль, установленный штатно; остальные он грузит сам
в выгружаемые AssemblyLoadContext и обновляет на лету.
Слоты активностей. Pilot собирает IServerActivity через MEF один раз, поэтому хост заранее экспортирует
64 слота (ServerHost/Exports/ActivitySlots.g.cs). Слот получает имя активности модуля и пересылает вызов в текущую
загруженную версию:
- обновление модуля с теми же именами активностей действует сразу;
- новое имя занимает свободный слот и начинает работать после ближайшего изменения метаданных базы (админка делает это сама);
- слот не переименовывается до перезапуска сервера, чтобы привязанный сценарий не вызвал чужую активность.
Хранение (ServerHost/Hosting/ModuleStorage.cs): modules/<Имя>/current - рабочая версия, previous - для отката,
staging/<id> - загрузки (на диске, см. «Кластер»), trash - последние 5 удалённых. Папка: SERVER_MODULES_DIR,
иначе том с базами в Docker (/usr/share/ascon/databases), иначе ProgramData.
Проверка архива (ServerHost/Hosting/ArchiveInspector.cs): в корне архива ровно один *.servext.dll (один архив - один модуль), пути без ...
Имя модуля (имя главной сборки без .servext.dll) - это имя его папки: буквы, цифры, _, - и . внутри имени, не длиннее 100 символов;
пустое имя, . и .. отвергаются. Начиная с 1.1.1 пробелы и прочие символы вне этого набора не допускаются: ранее установленный модуль с такой папкой
перестаёт отображаться и недоступен для remove и rollback, пока папку не переименуют вручную (на сервере, в modules) в допустимое имя. То же правило действует для параметра name операций remove, setEnabled, reload и rollback.
Распакованный размер архива (суммарно по фактически прочитанным байтам) не больше 512 МБ, файлов не больше 5000 (сжатый размер - не больше 200 МБ).
Сборки, которые уже есть у сервера (Ascon.Pilot.*, MEF, Newtonsoft.Json…), модуль всё равно получит серверные:
та же версия - ошибка, если админка не выбросила файл сама (галочка при загрузке), другая версия - предупреждение.
Если в корне архива есть signature.json, хост сверяет с ним все остальные файлы (в том же проходе по архиву, где читает сборки), а при заданных
доверенных ключах требует подпись - см. «Подпись модулей».
Версия модуля - три числа X.Y.Z (из FileVersion, иначе AssemblyVersion главной сборки; ServerHost/Hosting/ModuleVersions.cs).
Четвёртое число .NET, если это .0, не показывается: 1.2.3.0 / 1.2.3. В csproj пишите <Version>1.2.3</Version>.
Статистика (ServerHost/Hosting/ServerStats.cs): события load/action / report-metrics-collector / Grafana
«Pilot - серверные модули». Настройка - STATS_* или stats.json в папке модулей.
Кластер. Хост рассчитан на кластерный Pilot-Server (несколько узлов за балансировщиком); проверено тестами на двух экземплярах хоста
над одним каталогом на стенде из двух узлов Pilot-Server на одной машине (общий локальный каталог) и на двух машинах с общим каталогом по NFS 4.2 (версия 1.2.0 загружена обоими узлами; см. stack/Install/docs/Pilot-Server_cluster.md, раздел 9). Условие:
SERVER_MODULES_DIR указывает на один общий каталог. Он служит источником истины:
- Загрузка архива целиком лежит на диске в
staging/<id>(метаданные, архив, распакованные файлы), поэтому beginUpload, uploadChunk, validate и install могут попасть на разные узлы. Идентификатор загрузки - 32 шестнадцатеричных символа, иное отвергается до обращения к диску. Загрузки старше 30 минут удаляются; стартующий узел чужие свежие загрузки не трогает. - Изменяющие операции (validate на время распаковки и пробной загрузки, install, setEnabled, reload, rollback, remove)
и сверка узла выполняются под межузловым замком - файл
.lockв каталоге модулей, создаваемый атомарно. Замок старше 2 минуты считается брошенным и перехватывается; пока операция идёт, держатель обновляет время файла (раз в ~20 с), поэтому долгая проверка архива замок не теряет. Ожидание замка ограничено (30 с), затем операция завершается понятной ошибкой. Возраст замка сравнивается по времени файла с часами узла, поэтому часы узлов должны быть синхронизированы (расхождение в минуты делает замок «брошенным»). - После каждой изменяющей операции узел записывает новую метку поколения (файл
generation), а вmodule.jsonмодуля меняется полеrevision(в том числе при reload). Остальные узлы замечают смену метки при обращении (GetState, чтение имени слота, вызов активности - не чаще раза в 250 мс и без ожидания) и фоновым таймером раз в 5 с, затем под замком сверяют свои загруженные модули с манифестами: меняют изменившиеся и новые, выгружают удалённые. Итог: изменение доходит до всех узлов с задержкой до 5 с. Манифесты безrevision(от прежней версии хоста) читаются как обычно. - Имена слотов назначаются в каждом процессе отдельно, индексы на узлах могут различаться: сценарии привязаны к имени активности.
- Ограничение: файловая система каталога должна поддерживать атомарное создание файла (
CreateNew) и переименование (rename). - Обновлять хост нужно на всех узлах сразу: узлы со старой версией (1.1.x) не знают ни замка, ни метки поколения и держат загрузки в памяти.
Кому доверяет хост
Хост выполняет код модулей в процессе Pilot-Server. По умолчанию границей доверия служит право администратора базы Pilot
(RequireAdmin): любой такой администратор может загрузить любой архив, через веб-админку или напрямую в API хоста. В штатной схеме
модули выкладывает веб-админка (из CI - по ключу контура и job-токену GitLab). Учётная запись администратора Pilot и порт сервера
защищайте как доступ к исполнению кода на сервере. Чтобы принимались только сборки из CI, включите проверку подписи (следующий раздел).
Режим «общий модуль» (библиотеки одного модуля доступны остальным) намеренно не изолирует зависимости модулей друг от друга.
Кто установил модуль (Actor из запроса и учётная запись администратора), записывается в module.json и в журнал хоста.
Подпись модулей (необязательно, с версии 1.3.0)
Зачем. Сейчас хост ставит любой архив, который загрузил администратор Pilot. Подпись - это «печать» CI: CI ставит её на zip при сборке, а сервер, которому выдали «образец печати» (открытый ключ), принимает только архивы с настоящей печатью. Загрузить в обход CI свой zip, подменить в нём файл или дописать лишний уже не получится: печать перестанет сходиться, а подделать её без закрытого ключа нельзя. Пока ключа на сервере нет, всё работает как раньше, подписанные и неподписанные архивы принимаются.
Как включить (один раз, 5 минут; порядок важен):
Выпустить пару ключей на любой машине с
openssl(он есть в Git for Windows и в Linux):openssl ecparam -name prime256v1 -genkey -noout -out signing.key openssl ec -in signing.key -pubout -out signing.pubБез
opensslто же делает контейнер:docker run --rm -v "${PWD}:/k" -w /k mcr.microsoft.com/dotnet/sdk:10.0 sh -c "openssl ecparam -name prime256v1 -genkey -noout -out signing.key && openssl ec -in signing.key -pubout -out signing.pub".signing.key- закрытый ключ, секрет: он нужен только CI, храните его в менеджере паролей, а файл удалите.signing.pub- открытый ключ, его можно показывать.CI. GitLab / группа серверных модулей / Settings / CI/CD / Variables / Add variable: имя
MODULE_SIGNING_KEY, значение - всё содержимоеsigning.key(вместе со строками-----BEGIN…). Тип Variable или File. Маской (Masked) PEM закрыть нельзя, он многострочный: если маска нужна, вставьте вместо PEM его base64 (base64 -w0 signing.key), шаг сборки распознаёт и такое значение. Флаг Protected ставьте, когда проверку подписи включаете только на стейдже и проде: веткиmainиrelease/*защищены, а сборка изdev(тест) такой переменной не увидит и выложит zip без подписи, что тестовому серверу допустимо. Если проверка включена и на тесте, Protected не ставьте или защитите веткуdev. Дальше шагbuild_moduleизci-templateсам подпишет каждый zip; в журнале задания будет строка «Подписан …: ключ …». Нет переменной - в журнале жёлтое предупреждение, сборка идёт как раньше.Сервер. Только после того, как в журнале CI появилась строка «Подписан», положить открытый ключ на сервер одним из способов:
- файл
trusted-keys.pem(содержимоеsigning.pub) в каталог модулей: в стенде это<DATA_ROOT>\<контур>\databases\.server-modules\trusted-keys.pem(/usr/share/ascon/databases/.server-modules/в контейнере). Каталог общий для узлов кластера, поэтому файл - основной способ; перезапуск не нужен, хост читает его при каждой проверке архива; - или переменная окружения
SERVER_MODULES_TRUSTED_KEYSпроцесса Pilot-Server (PEM; перевод строки можно писать как\n), у каждого узла своя. Чтобы передать её в контейнер, добавьте строку вenvironmentсервисаpilot-server-<контур>вdocker-compose.yml.
Ключей можно положить несколько (по блоку
-----BEGIN PUBLIC KEY-----на ключ): так меняют ключ без остановки выкладки - сначала добавляют новый вtrusted-keys.pem, потом меняют переменную группы, потом убирают старый.- файл
Как проверить. Загрузите на страницу «Серверные модули» любой неподписанный zip: проверка ответит «Архив не подписан, а на сервере включена проверка подписи».
Собранный в CI модуль проходит без замечаний, а в журнале хоста появляется «подпись архива проверена, ключ …». Если подпись есть, но ключей на сервере нет, админка
показывает предупреждение «Доверенные ключи на сервере не заданы - подлинность подписи не проверяется»: целостность архива хост подтвердил, но доверять ему пока нечем.
Как выключить: удалить trusted-keys.pem и переменную SERVER_MODULES_TRUSTED_KEYS.
Что проверяется. Ключи заданы: подписан должен быть каждый архив, ключом из списка, и каждый его файл должен совпадать с подписанным (подмена, лишний или пропавший файл - ошибка в validate; install после отвергнутого validate невозможен). Ключей нет: подпись, если она есть, всё равно сверяется с файлами, неверная - ошибка. Если список задан, но ни один ключ в нём не читается (опечатка, закрытый ключ вместо открытого), принимаются никакие архивы: защита не отключается молча, а причина показана в ошибке. Проверяется архив целиком, как он загружен (в том числе сборки, которые админка потом выбросит как серверные).
Чего подпись не даёт. Она подтверждает «собрано в CI тем, у кого есть ключ», а не безопасность кода: подписать может любой, кто читает переменные группы или правит .gitlab-ci.yml
в проекте модуля. Уже установленные модули при загрузке заново не проверяются, и rollback на previous (версию, поставленную раньше, в том числе неподписанную) подпись не проверяет: проверка работает только при загрузке нового архива. Обновление самого ServerHost (его кладут в Pilot как штатное расширение, мимо этой проверки) подпись не охватывает.
CI подписывает один zip в bin (по тому же правилу, что выбирает админка: имя с .servext/.ext2, затем самый большой); остальные zip в bin остаются как есть.
Вручную загруженный zip при включённой проверке не примется: подпишите его так же, как CI, или соберите модуль в CI.
Формат (если подписывать надо не из CI). В корне zip файл signature.json: {"version":1,"algorithm":"ECDSA-P256-SHA256","keyId":"<sha256 открытого ключа SubjectPublicKeyInfo, hex>","publicKey":"<SubjectPublicKeyInfo, base64>","files":{"<путь>":"<sha256 файла, hex>"},"signature":"<base64>"}.
Подписывается текст манифеста: по строке <sha256>␣␣<путь>\n на каждый файл архива, кроме самого signature.json, в порядке побайтового (Ordinal) сравнения путей, UTF-8 без BOM; подпись ECDSA P-256 с SHA-256 в формате DER (его выдаёт и openssl dgst -sha256 -sign).
Проверить вручную: openssl dgst -sha256 -verify signing.pub -signature sig.der manifest.txt.
Что связано снаружи
proadmin/.../Pilot/ServerModules/ServerModulesContract.cs - копия ServerHost/Contract/IServerModulesApi.cs.
Pilot сопоставляет интерфейс по имени, поэтому при изменении контракта править оба файла
(совпадение проверяет тест RepoCopiesTests админки).
Тесты
ServerHost.Tests проверяют хост на настоящем модуле: SampleModule.cs компилирует его из исходника прямо
в тестах (Roslyn), тесты упаковывают его в zip и прогоняют проверку архива, установку, горячую замену, отключение,
перезапуск и удаление. Newtonsoft.Json тесты добавляют в архив намеренно - на нём проверяется обработка сборок,
которые уже есть у сервера. Другие проекты и репозитории тестам не нужны.
ArchiveSignatureTests покрывают подпись: без ключей, валидная подпись, нет подписи, подмена, лишний и пропавший файл, чужой ключ, битый файл подписи, список доверенных ключей.
SigningCiStepTests берут шаг подписи прямо из ci-template/.gitlab-ci.yml, запускают его в контейнере образа SDK (как в CI), подписывают собранный zip и проверяют его кодом хоста.
Им нужны Docker и локальный образ mcr.microsoft.com/dotnet/sdk:10.0 (другой образ - переменная TEST_SDK_IMAGE); образ тест не скачивает.
Нет Docker или образа - эти тесты пропускаются с пояснением, SKIP_DOCKER_TESTS=1 пропускает их явно.