Перейти к содержанию

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

Типичные проблемы при развёртывании и эксплуатации AegisAI.

API не отвечает

Симптомы

  • curl http://localhost:8000/api/v1/health — connection refused
  • Панель показывает «API unavailable»

Диагностика

# Статус контейнеров
docker compose ps

# Логи API
docker compose logs --tail=100 app

# Проверка порта
ss -tlnp | grep 8000

Решения

Причина Решение
Контейнер не запущен docker compose up -d app
Ошибка миграции docker compose exec app poetry run alembic upgrade head
Порт занят Измените порт в docker-compose.yml
Нехватка памяти Увеличьте RAM или уменьшите --workers

PostgreSQL недоступен

Симптомы

  • /health/ready возвращает "database": "error"
  • sqlalchemy.exc.OperationalError

Диагностика

docker compose logs postgres
docker compose exec postgres pg_isready -U aegisai

Решения

# Перезапуск PostgreSQL
docker compose restart postgres

# Проверка подключения из app
docker compose exec app poetry run python -c "
from app.config import settings; print(settings.database_url)
"

# Пересоздание volume (ПОТЕРЯ ДАННЫХ!)
docker compose down
docker volume rm aegisai_postgres_data
docker compose up -d

Удаление volume

docker volume rm удаляет все данные. Используйте только при наличии бэкапа.

Redis недоступен

Симптомы

  • /health/ready → "redis": "error"
  • WebSocket-события не доставляются

Решения

docker compose restart redis
docker compose exec redis redis-cli ping
# Ожидается: PONG

OPA не загружает политики

Симптомы

  • Лог: OPA policy loading skipped after retries
  • Политики возвращают fallback-решения

Диагностика

docker compose logs opa
curl http://localhost:8181/health

Решения

# Перезапуск OPA
docker compose restart opa

# Проверка загрузки политик
docker compose restart app
docker compose logs app | grep "Loaded.*Rego"

Fallback

При недоступности OPA платформа использует встроенный fallback-движок. Политики работают, но без полной функциональности Rego.

Ошибки аутентификации

Зависание формы входа

Причина Решение
SIEM с недоступным URL SIEM_ENABLED=false или настройте реальный Splunk/ELK
Неверный пароль init_super_admin.py --force-sync
Путают ADMIN_API_KEY с паролем В форме нужны email + password

SSO не работает

См. SSO — проверьте SSO_CALLBACK_URL, *_ENABLED, cookies.

401 Unauthorized

Причина Решение
Неверный API-ключ Проверьте ключ в Settings
Истёкший JWT Перелогиньтесь
Неверная подпись webhook Проверьте WEBHOOK_SECRET

403 Forbidden

Причина Решение
Недостаточная роль Обратитесь к администратору
Чужой tenant Используйте ключ своего арендатора
Попытка назначить super_admin Только super_admin может это делать

Панель не загружается

Симптомы

  • Белый экран на :5173
  • Ошибки в консоли браузера

Диагностика

docker compose logs frontend
# Или локально:
cd frontend && npm run dev

Решения

Причина Решение
node_modules отсутствуют cd frontend && npm install
Неверный proxy Проверьте VITE_PROXY_TARGET
CORS Проверьте, что API доступен
Нет API-ключа Настройте в /settings

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

Симптомы

  • Индикатор «Disconnected» в панели
  • Нет real-time обновлений

Решения

  1. Проверьте JWT-токен (перелогиньтесь)
  2. Для Nginx — убедитесь в настройке Upgrade / Connection headers
  3. Проверьте Redis: docker compose exec redis redis-cli ping
# Тест WebSocket
websocat "ws://localhost:8000/api/v1/ws?token=<jwt>"

Anomaly Detector не обучен

Симптомы

  • /anomalies/detector/status → model_trained: false
  • Страница аномалий пуста

Решения

# Загрузить демо-данные
docker compose exec app poetry run python scripts/seed_data.py --reset

# Или обучить вручную
curl -X POST http://localhost:8000/api/v1/anomalies/detector/train \
  -H "Authorization: Bearer <admin-jwt>" \
  -d '{"min_samples": 100}'

Миграции Alembic

Ошибка при миграции

# Текущая версия
docker compose exec app poetry run alembic current

# История
docker compose exec app poetry run alembic history

# Откат на одну версию
docker compose exec app poetry run alembic downgrade -1

# Применить все
docker compose exec app poetry run alembic upgrade head

Экспорт аудита зависает

Симптомы

  • Async export в статусе processing долгое время

Решения

# Проверить статус
curl http://localhost:8000/api/v1/audit/export/status/<job_id> \
  -H "X-API-Key: <key>"

# Проверить директорию экспорта
docker compose exec app ls -la /app/storage/exports/

Для больших объёмов увеличьте MAX_EXPORT_LIMIT или используйте фильтры.

Полезные команды

# Полный перезапуск
docker compose down && docker compose up --build -d

# Зайти в контейнер API
docker compose exec app bash

# Python shell с контекстом приложения
docker compose exec app poetry run python

# Проверить все health checks
curl -s http://localhost:8000/api/v1/health/ready | python3 -m json.tool

# Размер volumes
docker system df -v

Получение помощи

  1. Проверьте логи: docker compose logs -f
  2. Проверьте health: /api/v1/health/ready
  3. Проверьте статус: /api/v1/status
  4. Создайте issue на GitHub с логами и версией

Версия

Версия платформы доступна в GET /api/v1/health → поле version.