Устранение неполадок

Контейнер не запускается

Диагностика

# Проверка статуса всех контейнеров
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Логи проблемного контейнера
docker logs <имя-контейнера>

# Последние 50 строк логов
docker logs --tail 50 <имя-контейнера>

# Проверка конфигурации docker-compose
docker compose config

Типичные причины

Симптом	Возможная причина	Решение
Exited (1)	Ошибка в конфигурации или зависимости	Проверьте логи: docker logs <контейнер>
Exited (137)	OOMKilled — нехватка памяти	Увеличьте лимиты памяти или RAM сервера
Exited (126)	Ошибка прав доступа	Проверьте права на файлы конфигурации
Restarting	Цикл перезапусков	Проверьте healthcheck и зависимости
Created	Не запускается	Проверьте зависимости (depends_on)

---

Миграции завершились с ошибкой

Диагностика

# Проверка статуса контейнеров миграций
docker ps -a --filter "name=migrations" --format "table {{.Names}}\t{{.Status}}"

# Логи конкретной миграции
docker logs model-management-migrations
docker logs scan-profile-migrations
docker logs jailbreak-migrations

Типичные ошибки

Connection refused (PostgreSQL не готов)

sqlalchemy.exc.OperationalError: ... Connection refused

Решение:

# Проверьте, что PostgreSQL запущен и здоров
docker ps --filter "name=postgres"
docker exec postgres pg_isready -U postgres

# Перезапустите миграции
docker compose restart model-management-migrations

Schema already exists

psycopg2.errors.DuplicateSchema: schema "model_management" already exists

Решение: это информационное сообщение, не ошибка. Схемы создаются с IF NOT EXISTS.

Alembic revision conflict

alembic.util.exc.CommandError: Can't locate revision identified by 'xxx'

Решение:

# Проверьте текущую ревизию
docker exec model-management alembic current

# Пометить текущую ревизию как head
docker exec model-management alembic stamp head

# Перезапустить миграции
docker compose restart model-management-migrations

---

NATS: потоки не созданы

Диагностика

# Логи контейнера инициализации
docker logs nats-init

# Проверка состояния кластера
curl -s http://localhost:8222/jsz | jq .

# Проверка наличия потоков
curl -s http://localhost:8222/jsz?streams=true | jq '.streams[].name'

Ручное создание потоков

Если контейнер nats-init завершился с ошибкой, потоки можно создать вручную:

# Запуск NATS Box
docker run --rm -it --network appsec-genai natsio/nats-box

# Создание потоков
nats stream add ATTACKS --subjects='attacks.*.*' --storage=file \
    --retention=limits --max-age=7d --max-msg-size=10MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

nats stream add SCANS --subjects='scans.*' --storage=file \
    --retention=limits --max-age=30d --max-msg-size=1MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

nats stream add RESULTS --subjects='results.*.*' --storage=file \
    --retention=limits --max-age=90d --max-msg-size=10MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

nats stream add ARTIFACTS --subjects='artifacts.*.*' --storage=file \
    --retention=limits --max-age=30d --max-msg-size=10MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

nats stream add VULNERABILITIES --subjects='vulnerabilities.*.*' --storage=file \
    --retention=limits --max-age=90d --max-msg-size=5MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

nats stream add NOTIFICATIONS --subjects='notifications.*' --storage=file \
    --retention=workq --max-age=7d --max-msg-size=1MB \
    --replicas=3 --server=nats://nats-1:4222 --defaults

# Проверка
nats stream list --server=nats://nats-1:4222

NATS кластер не формируется

# Проверка здоровья каждого узла
curl -s http://localhost:8222/healthz
curl -s http://localhost:8223/healthz
curl -s http://localhost:8224/healthz

# Информация о кластере
curl -s http://localhost:8222/routez | jq .

# Перезапуск кластера
docker compose restart nats-1 nats-2 nats-3
sleep 15

---

Сервис не может подключиться к другим сервисам

Диагностика

# Проверка Docker-сети
docker network inspect appsec-genai_appsec-genai

# Проверка DNS-разрешения внутри контейнера
docker exec scan-orchestrator nslookup model-management

# Проверка сетевого подключения
docker exec scan-orchestrator curl -s http://model-management:8000/healthz

# Проверка IP-адресов
docker inspect --format '{{.NetworkSettings.Networks}}' model-management

Типичные причины

Причина	Решение
Контейнер не в сети appsec-genai	Проверьте networks в docker-compose.yml
DNS не разрешается	Перезапустите Docker daemon: sudo systemctl restart docker
Сервис ещё не запущен	Проверьте порядок depends_on
Healthcheck не прошёл	Увеличьте start_period в healthcheck

---

TooManyConnectionsError (PostgreSQL)

Симптомы

asyncpg.exceptions.TooManyConnectionsError: sorry, too many clients already

Причина

Суммарное количество подключений всех сервисов превышает max_connections в PostgreSQL.

Подсчёт подключений

Каждый сервис использует пул: DATABASE_POOL_SIZE (по умолчанию 20) + DATABASE_MAX_OVERFLOW (по умолчанию 10) = 30 подключений.

При 9 сервисах: 9 * 30 = 270 подключений (максимум при полной нагрузке).

Решение

Увеличьте max_connections в compose/postgres/postgres.conf:

# Было
max_connections = 200

# Стало (с запасом)
max_connections = 400

Перезапустите PostgreSQL:

docker compose restart postgres

Или уменьшите размер пулов в отдельных сервисах (в docker-compose.yml):

DATABASE_POOL_SIZE: 10
DATABASE_MAX_OVERFLOW: 5

---

OOMKilled у воркеров

Симптомы

docker inspect <контейнер> --format '{{.State.OOMKilled}}'
# Вывод: true

Или в логах Docker:

Container killed due to OOM (Out of Memory)

Типичные сценарии

Воркер	Причина	Потребление RAM
cv-adversarial-attacker	Загрузка моделей VGG19/ResNet50 в память	2--8 ГБ на модель
asr-adversarial-attacker	Загрузка модели Whisper	1--4 ГБ
jailbreak-attacker	Большое количество параллельных промптов	500 МБ--2 ГБ

Решение

1. Увеличьте RAM сервера (рекомендуется 64 ГБ для полной функциональности).

2. Установите лимиты памяти в docker-compose.yml:

   cv-adversarial-attacker:
     deploy:
       resources:
         limits:
           memory: 8G
         reservations:
           memory: 4G
   

3. Запускайте ресурсоёмкие атаки последовательно — не запускайте CV whitebox и ASR whitebox одновременно.

4. Уменьшите кеш моделей:

   MODEL_CACHE_MAX_SIZE_GB: "5.0"  # Было 10.0
   

---

Конфликт портов

Диагностика

# Проверка занятых портов
sudo lsof -i :8080
sudo lsof -i :3000
sudo lsof -i :5432

# Или через ss
sudo ss -tlnp | grep -E ':(8080|3000|5432|6379|4222|9000)'

Решение

Измените маппинг портов в docker-compose.yml:

# Пример: изменение порта UI с 8080 на 8888
ui:
  ports:
    - "8888:8080"  # Было: "8080:8080"

---

UI не загружается

Диагностика

# Проверка контейнера UI
docker ps --filter "name=ui"
docker logs ui

# Проверка UI Gateway
docker ps --filter "name=ui-gateway"
docker logs ui-gateway

# Проверка доступности
curl -s http://localhost:8080
curl -s http://localhost:3000/api/health

Типичные причины

Симптом	Причина	Решение
Белый экран	UI Gateway недоступен	Проверьте docker logs ui-gateway
502 Bad Gateway	Бэкенд-сервисы не запущены	Проверьте ./scripts/health-check.sh
Ошибка CORS	Неверный CORS_ORIGIN	Проверьте переменную CORS_ORIGIN в ui-gateway
404 при запросах API	Неверная конфигурация проксирования	Проверьте nginx конфигурацию в UI

---

WebSocket не подключается

Диагностика

В консоли браузера (F12 -> Console):

WebSocket connection to 'ws://localhost:3000/ws' failed

Решение

1. Проверьте доступность порта 3000:

   curl -s http://localhost:3000/api/health
   

2. Проверьте, что UI Gateway запущен:

   docker logs ui-gateway | grep -i websocket
   

3. Если используется обратный прокси (nginx), убедитесь в конфигурации WebSocket:

   location /ws {
       proxy_pass http://localhost:3000;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_read_timeout 86400;
   }
   

---

Seed-данные не загружены

Симптомы

• В UI нет предустановленных моделей или определений атак.
• API возвращает пустые списки.

Диагностика

# Проверка статуса seed-контейнеров
docker ps -a --filter "name=seed" --format "table {{.Names}}\t{{.Status}}"

# Логи
docker logs scan-profile-seed
docker logs model-management-cv-seed
docker logs jailbreak-seed

Решение

Перезапустите seed-контейнеры:

# Перезапуск seed для scan-profile
docker compose run --rm scan-profile-seed

# Перезапуск seed для model-management
docker compose run --rm model-management-cv-seed

# Перезапуск seed для jailbreak
docker compose run --rm jailbreak-seed

---

MinIO: файлы по умолчанию не загружены

Диагностика

# Логи инициализации
docker logs minio-init

# Проверка содержимого бакетов
docker exec minio mc ls local/cv-images/defaults/
docker exec minio mc ls local/audio-samples/defaults/
docker exec minio mc ls local/model-weights/defaults/

Решение

# Перезапуск инициализации
docker compose run --rm minio-init

# Или ручная загрузка файлов через консоль MinIO
# http://localhost:9001

---

Полная диагностика

Скрипт для комплексной диагностики:

#!/bin/bash
echo "=== AppSec.GenAI Diagnostics ==="
echo ""

echo "--- Docker version ---"
docker --version
docker compose version
echo ""

echo "--- Container status ---"
docker ps -a --format "table {{.Names}}\t{{.Status}}" | sort
echo ""

echo "--- Failed containers ---"
docker ps -a --filter "status=exited" --format "table {{.Names}}\t{{.Status}}" | \
    grep -v "Exited (0)"
echo ""

echo "--- Resource usage ---"
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" | \
    sort -k3 -h -r | head -15
echo ""

echo "--- Disk usage ---"
docker system df
echo ""

echo "--- Network ---"
docker network inspect appsec-genai_appsec-genai --format \
    '{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{"\n"}}{{end}}' | sort
echo ""

echo "--- Health checks ---"
for svc in postgres redis minio; do
    echo -n "$svc: "
    docker exec $svc echo "OK" 2>/dev/null && echo "reachable" || echo "UNREACHABLE"
done

for port in 8001 8002 8003 8004 8005 8025 8008 8006 8009; do
    echo -n "Port $port: "
    curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port/healthz" 2>/dev/null || echo "FAIL"
    echo ""
done

echo ""
echo "=== Diagnostics complete ==="

---

Получение поддержки

Если проблема не решается приведёнными выше методами:

1. Соберите диагностическую информацию:

   # Версии ПО
   docker --version > diag.txt
   docker compose version >> diag.txt
   
   # Статус контейнеров
   docker ps -a >> diag.txt
   
   # Логи проблемных сервисов
   docker logs <проблемный-контейнер> >> diag.txt 2>&1
   
   # Использование ресурсов
   docker stats --no-stream >> diag.txt
   free -h >> diag.txt
   df -h >> diag.txt
   

2. Обратитесь в техническую поддержку, предоставив файл diag.txt и описание проблемы.