Раздел 2. Структура программного обеспечения¶
Раздел описывает структуру программного обеспечения BOX5-DIT-MGSN с точки зрения публичных и внутренних API. Полный состав контейнеров, хранилищ и инфраструктурных компонентов приведён в Приложении Г к ПД, а детальный реестр REST endpoint-ов приведён в Приложении OpenAPI. В данном разделе фиксируются укрупнённые части ПО, их зоны ответственности и связи, необходимые для понимания API.
2.1. Перечень частей ПО¶
Программное обеспечение BOX5-DIT-MGSN построено как набор Docker Compose-доменов и прикладных сервисов. Для типового эксплуатационного состава выделяются 9 основных compose-доменов и 96 уникальных сервисов и компонентов. DEV, TEST и PROD используют один и тот же API-контур применяемых доменов; различия фиксируются в И2/И3 как различия топологии и мощности, а не как отдельные API-контракты.
2.1.1. Уровни программного обеспечения¶
| Уровень | Назначение | Основные компоненты |
|---|---|---|
| Внешний вход и UI | Единая точка входа пользователей и браузерных API. | ui-nginx, ui-react, ui-rest-to-gprc |
| Прикладные backend-сервисы | Реализация бизнес-операций, справочников, событий, отчётов и интеграций. | Домены statistics, severstal, data-storage |
| Видеоаналитика и среда выполнения инференса | Получение видеопотоков, выполнение сценариев видеоаналитики, хранение кадров и публикация событий. | Домены inference, extended-inference |
| Асинхронный обмен | Доставка событий, команд, статусов, audit-записей и служебных уведомлений между доменами. | kafka-domain, доменные Kafka-клиенты |
| Хранилища данных | Транзакционные, аналитические, кэшевые, файловые и объектные данные. | PostgreSQL, ClickHouse, Redis, MinIO, DataTemporaryStorage |
| Наблюдаемость и эксплуатационный контроль | Сбор метрик и логов, контроль доступности сервисов. | elk-log, /metrics, Docker logs |
| Песочница сценариев | Подготовка и проверка Node-RED/NRI-сценариев до переноса в рабочий inference-контур. | node-red-sandbox |
2.1.2. Основные части ПО¶
| Часть ПО | Compose-домен / контур | Назначение | API-поверхность |
|---|---|---|---|
| Пользовательский интерфейс и API gateway | ui-rest |
Публикует web UI, проксирует REST, GraphQL, WebSocket и файловые маршруты. | /, /api/*, /api/graphql, /api/ws/, /api/base/*, /api/config/*, /api/consul/* |
| Авторизация и доступ | statistics |
Управляет входом пользователей, JWT, ролями, группами доступа и правами на объекты/камеры. | /api/statistics/auth/*, /api/statistics/access/* |
| Камеры, объекты и конфигурация видеоаналитики | statistics |
Хранит дерево объектов, камеры, зоны, пресеты категорий, связи камер и клиентскую конфигурацию. | /api/statistics/camera-storage/*, /api/config/*, /api/consul/* |
| События, аудит и комментарии | statistics |
Принимает и хранит события, статусы подтверждения, audit-журнал и комментарии к событиям. | /api/statistics/event-storage/*, /api/statistics/audit/*, /api/statistics/comments/* |
| Отчёты и уведомления | statistics |
Формирует отчёты PDF/XLSX/DOCX/HTML, хранит настройки email-уведомлений и отчётные расписания. | /api/statistics/report-pdf-xlsx-generator/*, /api/statistics/auth-report-pdf-xlsx-generator/*, /api/statistics/report-email/* |
| Событийная статистика и посещение зон | statistics |
Хранит настройки статистического зеркала событий и данные посещения объектов через зоны входа/выхода. | /api/statistics/event-statistics/*, /api/statistics/object-visit-zone-counter/* |
| Видеоаналитика и inference | inference, extended-inference, severstal |
Обрабатывает live/архивные видеопотоки, хранит изображения, отдаёт мониторинг, сведения о моделях, HLS/WebRTC и медиафрагменты. | /api/inference/image-storage/*, /api/inference/models-storage/*, /api/inference/gateway/*, /api/inference/load-balancer/*, /api/inference/monitoring/*, /api/thermal/mediaserver/* |
| Виртуальные камеры и медиа | statistics, data-storage |
Управляет загруженными видео для виртуальных камер, временными файлами и объектными ссылками. | /api/statistics/virt-cam-video-upload/*, /api/data-storage/*, /api/s3/* |
| Интеграционный контур заказчика | severstal, интеграционные входы |
Синхронизирует внешние справочники, камеры, события, АСУ ТП-сигналы и статусы обработки. | /api/integration/*, маршруты gateway для доменов заказчика, Kafka/HTTP-интеграции |
| Файловое и объектное хранение | data-storage |
Предоставляет временное хранение файлов, прокси к MinIO и выдачу бинарных объектов по API. | /api/data-storage/*, /api/s3/*, файловые маршруты ui-nginx |
| Наблюдаемость | elk-log |
Собирает метрики и логи сервисов, используется для эксплуатационного контроля. | /metrics, Loki/Prometheus API внутри эксплуатационного контура |
| Песочница Node-RED/NRI | node-red-sandbox |
Изолирует разработку и проверку сценариев перед переносом в рабочий inference-контур. | /sandbox/*, внутренние API sandbox-сервисов |
2.1.3. Состав REST API по подсистемам¶
REST API документируется по тегам OpenAPI. На уровне структуры ПО теги
объединяются в функциональные группы, чтобы показать владение endpoint-ами.
Теги config, consul и models-storage ниже являются именами API-групп и
не добавляют одноимённые compose-домены к составу сервисов из Приложения Г к
ПД.
| Функциональная группа API | Теги OpenAPI | Назначение |
|---|---|---|
| Авторизация и права | auth, access |
Вход, токены, пользователи, роли, группы доступа, привилегии. |
| Камеры и конфигурация | camera-storage, config, consul |
Камеры, объекты, зоны, пресеты категорий и клиентская конфигурация. |
| События и аудит | event-storage, audit, comments |
События, статусы подтверждения, комментарии и audit. |
| Отчёты и уведомления | report-pdf-xlsx-generator, auth-report-pdf-xlsx-generator, report-email |
Генерация отчётов, скачивание файлов, настройки рассылки и проверка отправки. |
| Аналитические агрегаты | event-statistics, object-visit-zone-counter |
Настройки статистического зеркала событий и учёт посещения объектов через зоны. |
| Видео и медиа | virt-cam-video-upload, image-storage, gateway, s3, data-storage, mediaserver |
HLS/WebRTC, изображения, загруженные видео, файлы и объектное хранилище. |
| Inference и модели | load-balancer, monitoring, models-storage |
Балансировка камер, состояние inference и сведения о моделях; models-storage здесь является OpenAPI-тегом маршрута к реестру svr-models-registry, а не отдельным сервисом поставки. |
| Служебные операции | base |
Проверка доступности API gateway и прохождения запроса через опубликованный вход. |
2.2. Взаимосвязи между частями ПО¶
Взаимосвязи между частями ПО строятся вокруг единого входа ui-nginx и
gateway-сервиса ui-rest-to-gprc. Браузерные клиенты не обращаются напрямую к
внутренним сервисам statistics, inference, severstal и хранилищам:
запросы проходят через опубликованные маршруты gateway и далее адаптируются в
HTTP/gRPC, REST, Kafka, S3 или SQL-вызовы.
2.2.1. Общая схема связей¶
flowchart LR
classDef external fill:#fff7e6,stroke:#b7791f,color:#1f2937;
classDef edge fill:#eef6ff,stroke:#2563eb,color:#1f2937;
classDef app fill:#eefaf3,stroke:#15803d,color:#1f2937;
classDef infra fill:#f5f3ff,stroke:#6d28d9,color:#1f2937;
users["Пользователи
браузер / API-клиент"] cameras["IP-камеры
VMS / видеофайлы"] customer["Системы заказчика
ПК-КОТ / АСУ ТП"] sso["Keycloak / OIDC"] smtp["SMTP / уведомления"] nginx["ui-nginx
внешний вход"] gateway["ui-rest-to-gprc
REST / GraphQL / WS"] ui["ui-react
SPA"] stats["statistics
auth, камеры, события, отчёты"] inference["inference
media, NRI, HLS"] severstal["severstal
интеграции заказчика"] sandbox["node-red-sandbox
подготовка сценариев"] kafka["kafka-domain
событийная шина"] storage["data-storage
MinIO / DTS"] db["PostgreSQL / ClickHouse / Redis
доменные хранилища"] obs["elk-log
Prometheus / Loki"] users -->|"HTTP / HTTPS / WS"| nginx nginx -->|"статический UI"| ui nginx -->|"/api/*"| gateway nginx -->|"/api/s3*, файлы"| storage nginx -->|"/sandbox/*"| sandbox gateway -->|"HTTP/gRPC"| stats gateway -->|"HTTP/REST, gRPC"| inference gateway -->|"API доменов заказчика"| severstal gateway -->|"S3 / files"| storage gateway -->|"audit, websocket события"| kafka cameras -->|"RTSP, VMS API, загрузка"| inference cameras -->|"архивы и топология"| severstal customer -->|"PostgreSQL, HTTP, Kafka/Avro"| severstal sso -->|"OIDC authorization code"| users stats -->|"SMTP"| smtp stats <-->|"events, audit, commands"| kafka inference <-->|"events, heartbeats"| kafka severstal <-->|"sync, statuses"| kafka stats --> db inference --> db severstal --> db stats --> storage inference --> storage severstal --> storage stats -.->|"metrics, logs"| obs inference -.->|"metrics, logs"| obs severstal -.->|"metrics, logs"| obs gateway -.->|"logs"| obs class users,cameras,customer,sso,smtp external; class nginx,gateway,ui edge; class stats,inference,severstal,sandbox app; class kafka,storage,db,obs infra;
браузер / API-клиент"] cameras["IP-камеры
VMS / видеофайлы"] customer["Системы заказчика
ПК-КОТ / АСУ ТП"] sso["Keycloak / OIDC"] smtp["SMTP / уведомления"] nginx["ui-nginx
внешний вход"] gateway["ui-rest-to-gprc
REST / GraphQL / WS"] ui["ui-react
SPA"] stats["statistics
auth, камеры, события, отчёты"] inference["inference
media, NRI, HLS"] severstal["severstal
интеграции заказчика"] sandbox["node-red-sandbox
подготовка сценариев"] kafka["kafka-domain
событийная шина"] storage["data-storage
MinIO / DTS"] db["PostgreSQL / ClickHouse / Redis
доменные хранилища"] obs["elk-log
Prometheus / Loki"] users -->|"HTTP / HTTPS / WS"| nginx nginx -->|"статический UI"| ui nginx -->|"/api/*"| gateway nginx -->|"/api/s3*, файлы"| storage nginx -->|"/sandbox/*"| sandbox gateway -->|"HTTP/gRPC"| stats gateway -->|"HTTP/REST, gRPC"| inference gateway -->|"API доменов заказчика"| severstal gateway -->|"S3 / files"| storage gateway -->|"audit, websocket события"| kafka cameras -->|"RTSP, VMS API, загрузка"| inference cameras -->|"архивы и топология"| severstal customer -->|"PostgreSQL, HTTP, Kafka/Avro"| severstal sso -->|"OIDC authorization code"| users stats -->|"SMTP"| smtp stats <-->|"events, audit, commands"| kafka inference <-->|"events, heartbeats"| kafka severstal <-->|"sync, statuses"| kafka stats --> db inference --> db severstal --> db stats --> storage inference --> storage severstal --> storage stats -.->|"metrics, logs"| obs inference -.->|"metrics, logs"| obs severstal -.->|"metrics, logs"| obs gateway -.->|"logs"| obs class users,cameras,customer,sso,smtp external; class nginx,gateway,ui edge; class stats,inference,severstal,sandbox app; class kafka,storage,db,obs infra;
Исходный Mermaid-код схемы: ПА-MER-002. 2.2.1. Общая схема связей.
2.2.2. Синхронные API-связи¶
| Источник | Получатель | Протокол | Назначение связи | Особенности |
|---|---|---|---|---|
| Браузер пользователя | ui-nginx |
HTTP/HTTPS, WebSocket | Загрузка UI, вызовы REST/GraphQL, обновления в реальном времени. | ui-nginx является внешним входом и проксирует запросы к нижележащим сервисам. |
ui-nginx |
ui-react |
HTTP | Выдача SPA и статических файлов интерфейса. | ui-react не обращается к backend напрямую; после загрузки браузер вызывает /api/*. |
ui-nginx |
ui-rest-to-gprc |
HTTP, WebSocket | Передача браузерного API в gateway. | Основной маршрут: /api/*, GraphQL и /api/ws/. |
ui-rest-to-gprc |
statistics |
HTTP/gRPC, REST | Авторизация, камеры, события, отчёты, аудит, справочники и прикладная аналитика. | Для защищённых операций используется Bearer-токен; схема отражена в OpenAPI. |
ui-rest-to-gprc |
inference и extended-inference |
HTTP/gRPC, REST | Мониторинг inference, HLS/WebRTC, модели и изображения. | Медиаответы могут быть бинарными или потоковыми, без JSON-схемы ответа. |
ui-rest-to-gprc |
severstal |
HTTP/gRPC, REST | Операции доменов заказчика, интеграционные справочники и сценарии. | Набор маршрутов зависит от включённых доменов и эксплуатационной конфигурации. |
ui-rest-to-gprc |
data-storage, ds-minio |
HTTP, S3 API | Загрузка, выдача и проксирование файлов, изображений и отчётных артефактов. | Доступ к объектам выполняется через gateway/nginx, прямые параметры хранилища не раскрываются. |
statistics |
Keycloak / OIDC | HTTP/OIDC | Внешняя авторизация и обмен authorization code на локальные токены. | Параметры внешнего провайдера задаются в конфигурации контура. |
statistics |
SMTP | SMTP | Сброс пароля, отчёты и уведомления. | Учетные данные и адреса серверов не публикуются в документации. |
inference |
IP-камеры и VMS | RTSP, HTTP/VMS API | Получение live-потоков, preview и архивных фрагментов. | Физические камеры и VMS находятся за границей ПО BOX5-DIT-MGSN. |
2.2.3. Асинхронные связи¶
Асинхронный обмен используется для событий, команд, heartbeats, audit-записей, статусов и синхронизации справочников. Основной брокер решения - Kafka-домен; отдельные технологические Kafka-контуры могут использоваться внутри интеграционных или sandbox-доменов.
| Отправитель | Получатель | Тип сообщений | Назначение |
|---|---|---|---|
inf-nri-inference, inf-load-balancer, медиа- и inference-сервисы |
statistics, ui-rest-to-gprc, мониторинг |
События инференса, heartbeat, статусы камер | Передача результатов видеоаналитики, состояния камер и состояния inference. |
st-camera-storage |
inference, statistics, нижележащие сервисы |
Изменения камер, объектов, зон и пресетов | Распространение актуальной топологии камер и правил обработки. |
st-event-storage, st-event-statistic, st-object-visit-zone-counter |
UI и отчётные сервисы | События, статусы, аналитические агрегаты и события посещения зон | Обновление ленты событий, статистических представлений и отчётов. |
st-audit, ui-rest-to-gprc, прикладные сервисы |
st-audit, хранилище audit |
Audit-записи действий пользователей и сервисов | Централизованное хранение истории действий. |
severstal |
Основной контур BOX5-DIT-MGSN и внешние получатели | Синхронизация, статусы, интеграционные события | Обмен с ПК-КОТ, АСУ ТП и другими системами заказчика. |
node-red-sandbox |
Основной контур после публикации сценариев | Версии flows и сценарные артефакты | Перенос проверенных сценариев в рабочий inference-контур. |
2.2.4. Связи с хранилищами¶
| Тип хранилища | Использующие части ПО | Назначение |
|---|---|---|
| PostgreSQL | statistics, inference, severstal, node-red-sandbox |
Основное транзакционное состояние: пользователи, права, камеры, события, сценарии, справочники и служебные таблицы. |
| ClickHouse | statistics, gateway-аналитические маршруты |
Агрегаты событий, аналитические запросы и ускорение выборок для дашбордов. |
| Redis | statistics, inference, data-storage, node-red-sandbox |
Кэш, блокировки, очереди задач, временное состояние и служебные координаторы. |
| MinIO / S3 | statistics, inference, severstal, ui-rest-to-gprc |
Изображения событий, preview, отчётные файлы, импорт/экспорт конфигураций и медиаартефакты. |
| DataTemporaryStorage | data-storage, ui-rest-to-gprc, прикладные сервисы |
Временное хранение загруженных изображений и файлов по uuid. |
| Файловые каталоги compose-контура | ui-nginx, mediaserver, отчётные и видео-сервисы |
Статические файлы UI, HLS-данные, загруженные видео и локальные отчётные артефакты. |
2.2.5. Границы ответственности API¶
| Граница | Описание |
|---|---|
| Внешняя API-граница | Для пользователей и внешних API-клиентов опубликован gateway-слой. Внутренние сервисы не рассматриваются как самостоятельные публичные точки входа. |
| Браузерный API | Основная поверхность - REST endpoint-ы /api/*, GraphQL /api/graphql, WebSocket /api/ws/, файловые маршруты и HLS/WebRTC-маршруты через ui-nginx. |
| Внутренний service-to-service API | Внутренние связи между gateway и доменными сервисами выполняются через HTTP/gRPC, REST, Kafka, S3 и SQL-клиенты. |
| Файловые и потоковые ответы | Для отчётов, изображений, видео и HLS endpoint может возвращать бинарное или потоковое содержимое без отдельной JSON-схемы. |
| Авторизация | Защищённые операции используют Bearer-токен или специальные контурные ключи для синхронизационных входов; точная схема по endpoint-ам приведена в OpenAPI-приложении. |
| Конфигурация | Состав доступных доменов, внешние endpoints, SMTP/OIDC/S3-параметры, версии сервисов и функциональные флаги задаются эксплуатационной конфигурацией и не раскрываются в ПА как чувствительная информация. |
Таким образом, структура ПО в ПА связывает опубликованные API с внутренними
частями решения: ui-rest формирует внешний контракт, домены statistics,
inference, severstal и data-storage реализуют прикладную
логику, kafka-domain обеспечивает асинхронную связность, а доменные хранилища
и elk-log поддерживают состояние, файлы, метрики и журналы.