Раздел 2. Администрирование системы¶

Настоящий раздел описывает административные функции, периодические проверки и порядок планового обслуживания BOX5-DIT-MGSN. Раздел предназначен для администратора, который сопровождает действующий контур: управляет пользователями и ролями, контролирует доступы, проверяет состояние сервисов, готовит обновления и технологические окна.

Технологическая установка и восстановление поставки описаны в И2, разделе 2 и И2, разделе 3. Резервное копирование и восстановление данных как отдельный регламент приведены в И3, разделе 3. Состав сервисов и назначение доменов приведены в приложении Г.

Администрирование выполняется через три поверхности:

• web-интерфейс BOX5-DIT-MGSN, разделы Администрирование, Настройки, Мониторинг, Журналы;
• REST API за ui-nginx и ui-rest-to-gprc, если нужна проверка без ручной работы в UI;
• сервер поставки ~/CODE/box3, compose.sh, Docker, каталоги данных и контейнерные логи.

Исходный Mermaid-код схемы: И3-MER-004. Раздел 2. Администрирование системы.

На схеме Keycloak показан только как внешний контур аутентификации. Его администрирование выполняется вне BOX5-DIT-MGSN; в BOX5-DIT-MGSN администратор работает с прикладными ролями, профилями, объектными правами, аудитом и состоянием сервисов.

2.1. Функции администрирования¶

2.1.1. Управление ролями и профилями пользователей¶

В промышленном контуре вход пользователей в BOX5-DIT-MGSN выполняется через Keycloak. Keycloak является внешней системой и в настоящем разделе не описывается. Администрирование внутри BOX5-DIT-MGSN начинается после успешной аутентификации пользователя во внешнем контуре: BOX5-DIT-MGSN хранит прикладной профиль пользователя, ролевую модель, объектные права доступа, историю входов и журнал действий.

Web-интерфейс публикует эти операции в разделе Администрирование:

• Пользователи - просмотр пользователей, известных BOX5-DIT-MGSN, и их прикладных параметров;
• Ролевая модель - создание и изменение ролей BOX5-DIT-MGSN, назначение доступных действий и страниц;
• Логирование действий - просмотр действий пользователей и выгрузка отчёта;
• профиль пользователя - просмотр персональных параметров в пределах назначенных прав.

Основные операции:

Создание учётных записей, отключение входа пользователя и требования к аутентификации относятся к внешнему контуру и не выполняются средствами BOX5-DIT-MGSN. В BOX5-DIT-MGSN администратор проверяет только прикладные настройки: роль, доступ к камерам и объектам, отображение пользователя в отчётах и журналах.

Токены, значения JWT_*, параметры интеграции с внешним контуром и другая чувствительная информация не публикуется в документации, тикетах и общих чатах. Для REST-проверок используется bearer token действующей авторизованной сессии или утверждённой служебной процедуры проверки; порядок получения токена в настоящей инструкции не приводится.

Пример безопасного smoke-проверочного набора через REST API:

curl -fsS http://<sova-host>/config.json \
  | jq '.ADDITIONAL_SETTINGS.IS_REDIRECT_TO_KEYCLOAK'

curl -fsS -H "Authorization: Bearer ${token}" \
  http://<sova-host>/api/statistics/auth/me/
curl -fsS -H "Authorization: Bearer ${token}" \
  http://<sova-host>/api/statistics/auth/users/
curl -fsS -H "Authorization: Bearer ${token}" \
  'http://<sova-host>/api/statistics/auth/roles-v2/?page=1&page_size=20'

2.1.2. Настройка прав доступа¶

Права доступа к камерам и наблюдаемым объектам хранятся в сервисе st-access и БД st-access-postgres. Сервис поддерживает простые выдачи доступа, именованные группы доступа, массовое назначение одинаковых прав пользователям и пересборку плоского кэша привилегий.

После изменения прав st-access публикует обновлённый список привилегий в Kafka topic statistic_access. Нижестоящие сервисы используют эти данные для фильтрации уведомлений, отчётов, ответственных пользователей и доступных камер. Если пользователь не видит ожидаемые события, администратор проверяет не только роль, но и объектные права в st-access.

2.1.3. Управление конфигурацией камер, объектов, сценариев и моделей¶

Конфигурация технологического контура включает камеры, наблюдаемые объекты, сценарии Node-RED/NRI, версии моделей и параметры балансировки. Эти операции относятся к администрированию, потому что влияют на то, какие видеопотоки обрабатываются и какие события попадают операторам.

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

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

2.1.4. Мониторинг состояния системы¶

Администратор контролирует работоспособность на уровне UI, API, контейнеров, данных, GPU и inference-пайплайна. В web-интерфейсе для этого используются разделы Мониторинг, Журналы и Администрирование -> Мониторинг кластера.

Основные контрольные точки:

Команды первичного контроля на сервере:

cd ~/CODE/box3

compose.sh status all
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
curl -fsS http://localhost/api/base/ping/

df -h / /data
nvidia-smi

Проверка inference через REST API:

curl -fsS -X POST http://<sova-host>/api/inference/monitoring/light \
  -H "Authorization: Bearer ${token}" \
  -H 'Content-Type: application/json' \
  -d '{"camera_ids":[]}'

curl -fsS http://<sova-host>/api/inference/load-balancer/info2/ \
  -H "Authorization: Bearer ${token}"

curl -fsS http://<sova-host>/api/inference/models-storage/ \
  -H "Authorization: Bearer ${token}"

Состав Prometheus-метрик, источники технического мониторинга и ограничения применения /metrics приведены в приложении «Метрики мониторинга».

2.1.5. Управление обновлениями¶

Обновление BOX5-DIT-MGSN выполняется как управляемое изменение версии поставки:

1. Зафиксировать текущие версии ~/CODE/box3, domains.conf, .env-файлов и Docker-образов.
2. Проверить свободное место и состояние резервных копий.
3. Сделать резервную копию конфигурации и данных по разделу 3.
4. Применить изменение на TEST и выполнить smoke-проверку UI/API/inference.
5. В технологическое окно применить изменение на PROD.
6. Перезапустить затронутый домен, а не одиночный контейнер, если изменение относится к сервису внутри домена.
7. Выполнить контрольный чек-лист после запуска.
8. Зафиксировать результат обновления: дата, версия, затронутые домены, выполненные проверки, обнаруженные отклонения и решение по откату.

Для одноузлового compose-профиля используются команды:

cd ~/CODE/box3

compose.sh check
compose.sh pull <domain>
compose.sh restart <domain>
compose.sh status <domain>

Для полного запуска или остановки:

cd ~/CODE/box3

compose.sh stop all
compose.sh start all
compose.sh status all

Если контур развёрнут в Docker Swarm, применяются штатные swarm-скрипты из поставки, описанные в И2. Нельзя смешивать compose-команды и swarm-операции без отдельного решения ответственного администратора.

2.1.6. Журналирование административных действий¶

Действия пользователей и администратора фиксируются в st-audit; часть событий создаёт ui-rest-to-gprc при выполнении UI/REST-операций. В домене severstal отдельный сервис svr-security-notice может зеркалировать тот же audit-поток во внешний контур безопасности.

Администратор использует журнал действий для:

• расследования изменения конфигурации камер, ролей, прав доступа и событий;
• проверки неуспешных или подозрительных действий пользователя;
• выгрузки CSV-отчёта за период;
• подтверждения, что операция обновления или массового изменения была выполнена назначенным ответственным.

API-поверхность audit:

curl -fsS http://<sova-host>/api/statistics/audit/services/ \
  -H "Authorization: Bearer ${token}"

curl -fsS 'http://<sova-host>/api/statistics/audit/logs/?page=1&page_size=50' \
  -H "Authorization: Bearer ${token}"

2.1.7. Контроль конфигурационных переменных¶

Конфигурация BOX5-DIT-MGSN распределена между runtime-конфигурацией web-интерфейса, .env-файлами доменов поставки, compose-файлами и конфигурацией Nginx. Перед изменением параметров администратор фиксирует текущие файлы, проверяет изменение на TEST, затем применяет его на PROD в согласованное окно. Полные .env-файлы, значения паролей, токенов, приватных URL и ключей доступа в документацию и общие каналы не переносятся.

Основные файлы:

Frontend-параметры в runtime-конфигурации:

Backend-параметры целесообразно вести группами, потому что каждый сервис имеет собственный набор .env-ключей и часть значений является чувствительной:

DS/inference-параметры:

Data-storage-параметры:

После изменения переменных выполняется проверка:

cd ~/CODE/box3

compose.sh check
compose.sh restart <domain>
compose.sh status <domain>
curl -fsS http://localhost/api/base/ping/

Для ui-rest/ui-config/config.json или settings.json дополнительно проверить, что внешний GET /config.json или GET /settings.json возвращает новое значение, а нужный экран UI работает после жёсткого обновления страницы в браузере.

2.2. Регламентные операции¶

Регламентные операции выполняются в порядке от наименее вмешивающихся проверок к операциям, которые могут повлиять на обработку видеопотоков. Сначала администратор собирает статус и логи, затем проверяет данные и резервные копии, и только после этого выполняет перезапуски, очистки или обновления.

Минимальный ежедневный чек-лист:

cd ~/CODE/box3

date -Is
compose.sh status all
curl -fsS http://localhost/api/base/ping/
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
df -h / /data
nvidia-smi

Проверка резервных копий st-auth и st-access:

for container in \
  statistics-st-auth-postgres-backup-1 \
  statistics-st-access-postgres-backup-1
do
  docker exec "$container" ls -l /backup/latest.psql.gz
  docker exec "$container" gzip -t /backup/latest.psql.gz
done

Проверка мониторинга камер:

curl -fsS -X POST http://localhost/api/inference/monitoring/light \
  -H "Authorization: Bearer ${token}" \
  -H 'Content-Type: application/json' \
  -d '{"camera_ids":[]}' \
  | jq 'length'

Проверка балансировки:

curl -fsS http://localhost/api/inference/load-balancer/info2/ \
  -H "Authorization: Bearer ${token}" \
  | jq '{nodes: (.nodes | length), cameras_without_nodes}'

Операции, которые запрещено выполнять как рядовой регламент без согласования:

• удаление или пересоздание PostgreSQL, ClickHouse, MinIO и Kafka-каталогов;
• docker system prune на PROD без оценки используемых образов и свободного места;
• изменение .env, domains.conf, ui-config/config.json, сценариев, моделей или прав доступа без фиксации исходного состояния;
• перезапуск одиночного контейнера внутри домена, если штатный доменный compose.sh restart <domain> применим;
• публикация .env, токенов, JWT, дампов БД, чувствительной информации и персональных данных в документацию, Git или общие каналы.

2.3. Регламент обслуживания¶

2.3.1. Плановое техническое обслуживание¶

Плановое обслуживание выполняется в согласованное технологическое окно. Для PROD оно проводится после проверки на TEST и после подтверждения, что резервная копия пригодна для восстановления.

Порядок обслуживания:

1. Назначить окно и ответственных: исполнитель, проверяющий, контакт для отката и владелец бизнес-процесса.
2. Зафиксировать исходное состояние:

cd ~/CODE/box3
date -Is
git rev-parse --short HEAD
compose.sh status all
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
df -h / /data

1. Выполнить резервное копирование по разделу 3.
2. Проверить, что нет активных незавершённых операций, которые будут потеряны при остановке: загрузки видео, формирования отчётов, обновления моделей, перенос сценариев, импорт/экспорт архивов.
3. Остановить или перезапустить только затронутые домены.
4. Выполнить обслуживание: обновление образа, изменение конфигурации, очистка согласованных временных данных, замена модели, настройка сценария.
5. Запустить домены и дождаться стабилизации.
6. Выполнить технический smoke: ping, режим входа через Keycloak, auth/me, список пользователей, роли, группы доступа, monitoring/light, load-balancer/info2, API-группу models-storage, список audit-сервисов.
7. Выполнить прикладной smoke: вход в UI, просмотр мониторинга камер, проверка роли администратора, проверка выбранного операторского сценария.
8. Записать результат в журнал эксплуатации.

2.3.2. Плановая остановка системы¶

Плановая остановка требуется для полного файлового backup, миграции узла, обслуживания диска, замены критичных .env-параметров или обновления, которое затрагивает несколько доменов.

Порядок:

1. Уведомить пользователей о времени недоступности UI и обработки видеопотоков.
2. Остановить входящие пользовательские операции: загрузки, настройки камер, сценарии, отчёты.
3. Зафиксировать состояние контейнеров и дисков.
4. Выполнить ручной SQL dump для backup sidecar-контейнеров, если они используются.
5. Остановить основной контур:

cd ~/CODE/box3
compose.sh stop all

1. Остановить песочницу Node-RED, если обслуживание затрагивает сценарии, модели или её данные:

cd ~/CODE/node-red-sandbox
docker compose down

1. Выполнить обслуживание или файловое копирование.
2. Запустить контур:

cd ~/CODE/box3
compose.sh start all

cd ~/CODE/node-red-sandbox
docker compose up -d

1. Проверить UI, API, контейнеры, камеры, модели и audit.

В swarm-профиле вместо compose.sh stop/start all используется штатный swarm-скрипт поставки. Порядок действий сохраняется: фиксация состояния, backup, остановка, обслуживание, запуск, smoke-проверка, запись результата.

2.3.3. Применение обновлений¶

Обновление считается завершённым только после технической и функциональной проверки. Наличие запущенных контейнеров само по себе не подтверждает успешное обновление.

Порядок применения:

1. Подготовить описание изменений: какие домены, сервисы, модели, сценарии, переменные .env и миграции затрагиваются.
2. Проверить дистрибутив на TEST.
3. Зафиксировать исходные версии PROD:

cd ~/CODE/box3
git status --short
git rev-parse --short HEAD
docker images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | sort

1. Сделать backup.
2. Применить изменение:

cd ~/CODE/box3
compose.sh pull <domain>
compose.sh restart <domain>

1. Если образ был собран локально в контуре и не опубликован в registry, не выполнять compose.sh pull <domain> для этого тега, чтобы не заменить его старым registry-образом.
2. Выполнить smoke-проверку и сравнить с ожидаемым состоянием.
3. При ошибке выполнить откат: вернуть предыдущие .env/domains.conf, предыдущий тег образа или восстановить данные из backup, если обновление изменило схему или содержимое БД.

2.3.4. Очистка и обслуживание данных¶

Очистка данных выполняется только для классов данных, которые не являются источником истины или имеют утверждённый срок хранения.

Если свободное место на /data приближается к критическому порогу, сначала выясняется источник роста:

df -h /data
du -xh --max-depth=2 /data | sort -h | tail -n 30
docker system df

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

2.3.5. Верификация раздела¶

Содержание раздела применяется к промышленному контуру BOX5-DIT-MGSN. Проверки выполняются на целевом PROD-окружении через штатный URL BOX5-DIT-MGSN, SSH-доступ к узлам поставки и внутренние API. Адреса промышленного контура, токены, параметры доступа и значения, содержащие промышленную информацию, в настоящей документации не фиксируются; результат проверки заносится в журнал эксплуатации.