Раздел 4. Методы и средства разработки¶
4.1. CI/CD и порядок поставки¶
Поставка BOX5-DIT-MGSN выполняется как поставка набора Docker-образов, compose-файлов, моделей, runtime-конфигурации и эксплуатационной документации. CI/CD не публикуется как пользовательский API: он относится к внутреннему контуру разработки и эксплуатации поставщика. Для заказчика фиксируются состав поставки, версии артефактов, порядок обновления и проверки, которые применяются при выпуске в эксплуатационный контур.
4.1.1. Артефакты поставки¶
| Объект | Где ведётся | Что фиксируется |
|---|---|---|
| Исходный код сервисов | Репозитории сервисов в GitLab поставщика | Коммит, ветка или релизный tag, изменения API/схем, Dockerfile и .gitlab-ci.yml конкретного сервиса. |
| Solution-репозиторий | Репозиторий состава решения box3/BOX5-DIT-MGSN |
Compose-домены, domains.conf, docker-compose.yml, .env.demo, скрипты установки и утилиты поставки. |
| Реестр состава поставки | Манифест поставки и deployment/spec-файлы | Набор сервисов и pinned versions: image-tag, git-commit, дата подтверждения версии и отклонения конкретного контура. |
| Docker-образы | Внутренний Docker Registry поставщика | Версионированные образы сервисов, infrastructure sidecar-ов и UI/gateway-компонентов. |
| Python-пакеты и схемы RPC | Package registry GitLab, в первую очередь vzrpc |
Версии protobuf/gRPC-схем и клиентских библиотек, используемых downstream-сервисами. |
| Модели и runtime-артефакты инференса | Локальное файловое хранилище контура и/или модельный registry поставщика | Версия модели, конвертированные ONNX/TensorRT-артефакты, структура MODELS_STORAGE и параметры выбора registry. |
| Документация | Репозиторий документации BOX5-DIT-MGSN | HTML-сайт и, при отдельном запросе, PDF/DOCX выгрузки документов. |
Чувствительная информация поставки не входит в артефакты CI/CD. Пароли, JWT-ключи подписи, ключи S3, SMTP, Kafka, OIDC, GitLab Registry и параметры внешних систем передаются через защищённую эксплуатационную конфигурацию и не фиксируются в ПА.
4.1.2. Общая схема CI/CD¶
flowchart LR
code["Коммит в сервисный репозиторий"] --> ci["GitLab CI
lint / test / build"] ci --> image["Docker image
Registry tag"] ci --> pkg["Python package / RPC schema
при необходимости"] image --> pin["Фиксация версии
.env.demo / deployment spec"] pkg --> pin pin --> deploy["Развёртывание
compose.sh pull + restart/start"] deploy --> verify["Проверки
status, logs, API, UI, data flow"] verify --> release["Версия поставки
эксплуатационный контур"] verify -. "ошибка" .-> rollback["Rollback
предыдущие tags + restart"] rollback --> verify
lint / test / build"] ci --> image["Docker image
Registry tag"] ci --> pkg["Python package / RPC schema
при необходимости"] image --> pin["Фиксация версии
.env.demo / deployment spec"] pkg --> pin pin --> deploy["Развёртывание
compose.sh pull + restart/start"] deploy --> verify["Проверки
status, logs, API, UI, data flow"] verify --> release["Версия поставки
эксплуатационный контур"] verify -. "ошибка" .-> rollback["Rollback
предыдущие tags + restart"] rollback --> verify
Исходный Mermaid-код схемы: ПА-MER-004. 4.1.2. Общая схема CI/CD.
4.1.3. Этапы сборки¶
| Этап | Описание | Результат |
|---|---|---|
| Подготовка изменения | Изменение выполняется в сервисном репозитории или solution-репозитории. Если меняются protobuf/gRPC-схемы, сначала обновляется и публикуется vzrpc. |
Коммит/ветка с изменением и связанная задача релиза. |
| Автоматическая сборка | Pipeline GitLab CI запускается из .gitlab-ci.yml соответствующего репозитория. Типовые шаги: установка зависимостей, статические проверки, тесты, сборка Docker-образа или Python-пакета. |
CI job с журналом сборки, Docker image tag или package version. |
| Публикация артефактов | Docker-образ публикуется в registry; Python-пакет публикуется в package registry. Tag образа должен быть воспроизводимым и связанным с Git commit. | Артефакт доступен для pull/install в контуре поставки. |
| Фиксация состава | В solution-конфигурации и deployment-спецификации фиксируются image tag, commit и дата подтверждения. Runtime .env на контуре обновляется только значениями, требуемыми для поставки. |
Воспроизводимый состав поставки без чувствительной информации. |
| Сборка документации | Документация собирается через mkdocs build --strict; PDF/DOCX экспорт выполняется только при отдельном запросе. |
Актуальный HTML-раздел документации и контроль отсутствия ошибок ссылок/схем. |
Матрица поставки по группам сервисов:
| Группа сервисов | Где pipeline | Как сборка | Как деплой | Ручные шаги | Rollback | Проверки перед релизом | Права на деплой | Где артефакты |
|---|---|---|---|---|---|---|---|---|
UI и gateway: ui-nginx, ui-react, ui-rest-to-gprc |
Репозитории UI/gateway и solution-репозиторий. | Docker images, UI assets, gRPC/client dependencies. | compose.sh pull ui-rest и compose.sh restart ui-rest. |
Обновить UI-config, published URL, логотипы, OIDC/Keycloak параметры при изменении. | Вернуть предыдущие tags UI/gateway и runtime UI-config. | /login, /config.json, /api/base/ping/, авторизация, WebSocket/GraphQL при применимости. |
DevOps/инженер поставки, maintainer релиза. | Docker Registry, pinned tags в deployment/spec и .env. |
statistics-домены |
Репозитории сервисов statistics, vzrpc, solution-репозиторий. |
Docker images, Python packages, миграции сервисов-владельцев БД. | compose.sh pull/restart затронутого statistics-домена. |
Миграции PostgreSQL, проверка Redis/Kafka/ClickHouse, настройка SMTP/OIDC при изменении. | Вернуть tags; при необратимой миграции восстановить резервную копию БД. | Auth/read-only API, камеры, события, audit, отчёты, /metrics где доступно. |
DevOps и администратор контура в согласованное окно. | Docker Registry, package registry, backup-журнал. |
inference и extended-inference |
Репозитории inference/NRI/медиасервисов, модельные репозитории. | Docker images, ONNX/TensorRT/model artifacts, runtime NRI nodes. | compose.sh pull/restart inference-доменов; на многонодовом контуре с учётом placement/GPU. |
Подготовить MODELS_STORAGE, проверить GPU runtime, камеры и bind directories на compute-нодах. |
Вернуть tags сервисов и предыдущую версию моделей. | Состояние моделей, доступность камер, preview/HLS/WebRTC, пробное событие или read-only диагностика. | DevOps, ML/inference maintainer, администратор контура. | Docker Registry, model storage/registry, deployment spec. |
Customer-domain severstal и интеграции |
Репозитории severstal, интеграционных connector-ов и solution-репозиторий. |
Docker images, настройки connector-ов, при необходимости схемы обмена. | compose.sh pull/restart severstal и связанных доменов. |
Обновить endpoints внешних систем, credentials, feature flags и расписания синхронизации. | Вернуть tags/feature flags; повторную отправку выполнять только с контролем идемпотентности. | Read-only проверки CSVN/VMS, ПК-КОТ, АСУ ТП, статусов launch и integration logs. | DevOps и ответственный за интеграцию с согласованием заказчика. | Docker Registry, эксплуатационная конфигурация, журнал интеграционных проверок. |
| Хранилища и инфраструктура данных: PostgreSQL, Redis, ClickHouse, MinIO, Kafka | Solution-репозиторий и образы инфраструктурных компонентов. | Как правило, pinned image tags и compose-конфигурация; прикладные схемы поставляются сервисами-владельцами. | compose.sh pull/restart соответствующего домена только после оценки влияния на данные. |
Backup, проверка volumes, retention, свободного места, Kafka topics и consumer lag. | Вернуть image/config; при повреждении данных восстановить backup по И3/В7. | Подключения сервисов, миграции, Kafka lag, MinIO/ClickHouse/PostgreSQL health. | DevOps и администратор контура. | Docker Registry, volumes/backups, deployment spec. |
node-red-sandbox |
Репозитории sandbox, Node-RED/NRI и solution-репозиторий. | Docker images, Node-RED flows, backend/frontend sandbox, Celery worker images. | compose.sh pull/restart node-red-sandbox. |
Проверить sandbox Kafka/Redis, рабочие каталоги, публикацию flows и доступ через /sandbox/. |
Вернуть tags sandbox и предыдущие flow/runtime artifacts. | UI sandbox, запуск тестовой обработки, статусы Celery/Flower, публикация сценария в рабочий контур. | DevOps, инженер сценариев, администратор контура. | Docker Registry, MinIO/DTS, sandbox volumes. |
| Документация ПА и комплект РД | Репозиторий документации BOX5-DIT-MGSN. | mkdocs build --strict; PDF/DOCX только по отдельному запросу. |
Публикация HTML-сайта или передача сборочного артефакта документации. | Сверить ссылки, Mermaid/PlantUML, OpenAPI-приложение и статус документов. | Вернуть предыдущую опубликованную версию сайта/артефакта. | mkdocs build --strict, ./scripts/build.sh, выборочная проверка ссылок и схем. |
Ответственный за документацию, maintainer репозитория. | Git repository, HTML build, при запросе PDF/DOCX. |
Для итерационной отладки допускается локальная сборка Docker-образа на целевом
контуре с tag, совпадающим по форме с CI tag. Такой образ должен быть заменён
registry-сборкой или явно зафиксирован как поставочный артефакт до передачи в
эксплуатацию. Пакет vzrpc публикуется через GitLab CI и затем используется
downstream-сервисами как поставочный артефакт.
4.1.4. Порядок развёртывания¶
| Шаг | Действие | Контроль |
|---|---|---|
| 1 | Зафиксировать состав обновления: список сервисов, image tags, commits, изменения API/БД/моделей и затронутые compose-домены. | Состав совпадает с deployment-спецификацией и release notes. |
| 2 | Проверить prerequisites контура: Docker/Compose, доступ к registry, GPU/NVIDIA runtime для inference, модельные артефакты, свободное место, наличие требуемых volumes. | Предусловия выполнены до остановки сервисов. |
| 3 | Выполнить compose.sh check из корня solution-репозитория. |
Конфигурация compose-доменов валидна, обязательные файлы и пути доступны. |
| 4 | Выполнить compose.sh pull <domain> для доменов, где используются registry-built образы. |
Образы успешно получены из registry, tag соответствует поставке. |
| 5 | Выполнить compose.sh restart <domain> для затронутого домена или compose.sh start all при первичной установке. |
Контейнеры пересозданы с новой конфигурацией и находятся в ожидаемом состоянии. |
| 6 | Выполнить smoke/read-only проверки API, UI, Kafka/Redis/PostgreSQL/MinIO/ClickHouse-связей и профильных пользовательских сценариев. | Нет критических ошибок в логах, API отвечает, данные проходят по ожидаемому контуру. |
| 7 | Обновить эксплуатационную фиксацию версии: deployment spec, журнал поставки, список изменённых сервисов и результаты проверки. | По поставке можно восстановить точный набор images/commits. |
Развёртывание выполняется доменно. Для изменения одного сервиса используется
рестарт соответствующего compose-домена, а не одиночный docker restart
контейнера. Это сохраняет единый порядок применения env-файлов, network-настроек,
hooks и зависимостей домена.
4.1.5. Ручные шаги¶
| Ручной шаг | Когда требуется | Требование |
|---|---|---|
Настройка runtime .env |
Первичная установка, смена адресов внешних систем, SMTP/OIDC/S3/Kafka credentials, TLS/доменного имени, feature flags. | Чувствительная информация не коммитится и не переносится в документацию. Изменение должно быть отражено в эксплуатационном журнале без раскрытия значений. |
| Подготовка моделей | До запуска inference или при обновлении модели. | Конвертированные модели должны быть доступны в согласованном MODELS_STORAGE/registry и совместимы с текущим inference runtime. |
| Миграции БД | Если сервисная версия требует изменения схемы. | Миграции выполняет сервис-владелец схемы; перед обновлением должны быть сделаны резервные копии критичных PostgreSQL/MinIO данных. |
| Обновление UI-конфигурации | При изменении published URL, логотипов, ссылок на внешние разделы и feature flags. | Проверяется /config.json, загрузка UI и отсутствие рассинхронизации browser-facing API. |
| Swarm/кластерные операции | Для многонодового развёртывания с compute-нодами. | Синхронизируются локальные COMPOSE_DATA, модели и bind directories на каждой ноде; проверяются placement, GPU и overlay-сети. |
4.1.6. Rollback¶
Rollback выполняется возвратом к ранее зафиксированным image tags,
compose-файлам и runtime-настройкам. Перед обновлением должны быть известны
предыдущие значения tags и сохранены резервные копии изменяемых .env и
config-файлов.
| Сценарий | Действие rollback | Ограничения |
|---|---|---|
| Ошибка нового Docker-образа | Вернуть предыдущий image tag в runtime .env, выполнить compose.sh pull <domain> при registry-образе и compose.sh restart <domain>. |
Если был изменён формат данных или выполнены необратимые миграции, требуется отдельный план восстановления БД. |
| Ошибка gateway/UI | Вернуть tags ui-rest/ui-react/ui-nginx или runtime UI-config, перезапустить домен ui-rest. |
Уже выданные JWT могут действовать до истечения срока; проверять совместимость JWT_SECRET и auth-сервисов. |
| Ошибка inference/моделей | Вернуть предыдущую версию образа, модели и MODELS_STORAGE; перезапустить inference-домен. |
События, уже сохранённые в st-event-storage, не удаляются автоматически. |
| Ошибка интеграции | Отключить проблемный feature flag или вернуть версию severstal-сервиса; восстановить предыдущие credentials/endpoint-настройки, если они менялись. |
Повторная отправка внешних статусов должна учитывать идемпотентность внешнего API. |
| Ошибка БД-миграции | Восстановить резервную копию БД/MinIO и вернуть сервисы к совместимой версии. | Требует окна обслуживания и согласования, так как может затронуть события, отчёты и справочники. |
4.1.7. Проверки перед релизом¶
| Группа проверок | Минимальный состав |
|---|---|
| CI | Pipeline завершён успешно; Docker image/package опубликованы; tag связан с commit; чувствительная информация не попала в job logs и артефакты. |
| Сборка документации | mkdocs build --strict проходит; OpenAPI-приложение и реестр интерфейсов соответствуют опубликованным API применяемых сервисов. |
| Compose-конфигурация | compose.sh check, корректность domains.conf, .env.demo, runtime .env, volumes, networks и disabled domains. |
| API smoke | /api/base/ping/, авторизация, ключевые read-only REST/gRPC операции, GraphQL/WebSocket при применимости. |
| Асинхронный обмен | Доступность inf-kafka, отсутствие критического consumer lag, delivery событий инференса/audit/status в сервисы-потребители. |
| Хранилища | PostgreSQL/Redis/ClickHouse/MinIO доступны; миграции выполнены; критичные данные резервируются до обновления. |
| Инференс и медиа | Камеры/потоки доступны, inference-сервисы видят модели, HLS/WebRTC/preview работают для контрольных камер. |
| Интеграции заказчика | ПК-КОТ, АСУ ТП, CSVN/VMS, SMTP/OIDC и внешние HTTP API проверяются только в части согласованных read-only или безопасных контрольных операций. |
4.1.8. Права и ответственность¶
| Роль | Полномочия |
|---|---|
| Разработчик сервиса | Вносит кодовые изменения, запускает/исправляет CI, обновляет тесты и описание API своего сервиса. |
| Maintainer репозитория | Принимает merge request, управляет protected branches/tags, утверждает релизный commit и публикацию artifacts. |
| DevOps/инженер поставки | Обновляет image tags, runtime-конфигурацию, deployment spec, выполняет compose.sh pull/restart, проверяет контейнеры и откат. |
| Администратор эксплуатационного контура | Предоставляет доступы, окно обслуживания, сетевые правила, credentials внешних систем и подтверждает готовность контура. |
| Заказчик / владелец эксплуатации | Согласует поставку в промышленный контур, принимает результаты проверок и фиксирует эксплуатационные ограничения. |
Доступ на промышленный контур предоставляется только уполномоченным лицам. CI/CD-права, registry credentials, SSH-доступы и конфиденциальные параметры внешних интеграций не передаются через исходный код или документацию и должны храниться в утверждённом защищённом хранилище.