Раздел 4. Проблемы и их решение¶

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

Не публикуются в тикетах и общих каналах: полные .env-файлы, пароли, токены, JWT, дампы БД, лицензионные файлы, приватные URL, фрагменты логов с чувствительной информацией и персональные данные пользователей.

4.1. Типовые проблемы и способы их устранения¶

Первичная диагностика выполняется с узла поставки:

cd ~/CODE/box3

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

Если ошибка локализована в одном домене, штатное действие восстановления - перезапуск домена через compose.sh restart <domain>. Перезапуск одиночного контейнера используется только после проверки compose-проекта, .env, сети, зависимостей и имени сервиса.

4.2. Порядок локализации сбоя¶

1. Зафиксировать время, окружение, пользователя или сервис, симптом и затронутый бизнес-процесс.
2. Проверить внешний признак: UI, /api/base/ping/, доступность камеры, отчёта, события или интеграции.
3. Проверить состояние домена через compose.sh status <domain> и docker ps.
4. Проверить свободное место, GPU, Kafka и состояние хранилищ, если сбой затрагивает несколько сервисов.
5. Посмотреть последние логи проблемного контейнера. Логи сохраняются до перезапуска, если это не увеличивает ущерб.
6. Определить, является ли сбой прикладным, инфраструктурным, интеграционным или связанным с данными.
7. Выполнить минимальное действие восстановления: исправить конфигурацию, восстановить зависимость, перезапустить домен, выполнить ручную синхронизацию или запустить восстановление по разделу 3.
8. После восстановления выполнить smoke-проверку UI/API/inference и записать результат в журнал эксплуатации.

Минимальный набор логов для анализа:

docker logs <container> --since 30m --tail 300
docker inspect <container> \
  --format '{{index .Config.Labels "com.docker.compose.project.working_dir"}}'
docker inspect <container> \
  --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}'

Если на одном сервере есть несколько каталогов /data/compose-data*, путь к логам и данным определяется фактическими mount-ами контейнера и переменными домена, а не названием похожего каталога на диске.

4.3. Действия, требующие отдельного согласования¶

Следующие действия не выполняются как рядовое устранение проблемы:

• удаление или пересоздание PGDATA, ClickHouse, MinIO, Kafka и каталогов моделей;
• docker system prune или массовое удаление Docker volumes на PROD;
• очистка /dev/shm, IPC и HLS-каталогов без понимания текущих consumers;
• изменение .env, domains.conf, config.json, settings.json, интеграционных URL, JWT и license-параметров без фиксации исходного состояния;
• восстановление БД, ClickHouse или MinIO из разных backup_id;
• перенос результатов TEST в PROD без утверждённого плана;
• отключение доменов или изменение DISABLED_DOMAINS без проверки влияния на UI, роли, nginx-маршруты и зависимости.

4.4. Эскалация¶

Сбой эскалируется ответственному DevOps/VizorLabs или владельцу интеграции, если:

• отказ затрагивает PROD и не локализован за один рабочий цикл диагностики;
• потеряны или повреждены данные PostgreSQL, ClickHouse, MinIO или модели;
• последняя пригодная резервная копия отсутствует или восстановление не возвращает систему в рабочее состояние;
• не подтверждается Guardant-лицензия или недоступна штатная процедура оффлайн-активации;
• ПК-КОТ, CSVN/VMS, АСУ ТП или Keycloak недоступны со стороны внешнего контура;
• после перезапуска домена повторяется один и тот же сбой модели, сценария, Kafka-потребителя или migration;
• проблема требует изменения кода, Docker-образа, схемы БД или ветки поставки.

В обращении указываются:

• окружение и время возникновения;
• затронутый домен и контейнеры;
• выполненные команды и результат;
• вывод compose.sh status all, docker ps, df -h, nvidia-smi;
• короткие отредактированные фрагменты логов;
• версия поставки или Docker-образов;
• наличие актуального backup и границы возможной потери данных.

Чувствительные значения передаются только по утверждённому закрытому каналу и не включаются в открытую документацию, комментарии задач и общие чаты.