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

Решение проблем

Диагностика и устранение типичных проблем при работе с Р13.Орбита.

Быстрая диагностика

Проверка состояния системы

# Проверить что контейнер запущен
docker ps | grep orbita

# Проверить health check
curl http://localhost:8000/health

# Проверить логи
docker logs orbita --tail 50

# Проверить использование ресурсов
docker stats orbita --no-stream

Категории проблем

Проблемы установки

Ошибки при первоначальной установке и настройке системы.

Типичные проблемы: - Docker образ не загружается - Контейнер не запускается - Ошибки конфигурации - Отсутствие необходимых зависимостей

➜ Подробнее о проблемах установки

Проблемы подключения

Ошибки при подключении к внешним сервисам.

Типичные проблемы: - Не удается подключиться к ClickHouse - Ошибки подключения к БД метаданных - LLM API недоступен - Таймауты сетевых запросов

➜ Подробнее о проблемах подключения

Проблемы производительности

Медленная работа системы или большое потребление ресурсов.

Типичные проблемы: - Медленные запросы - Высокое использование CPU/памяти - Долгая обработка сложных вопросов - Таймауты при работе с большими датасетами

➜ Подробнее о проблемах производительности

Ошибки выполнения

Ошибки при работе с системой после успешной установки.

Типичные проблемы: - SQL запросы не выполняются - Датасеты не сохраняются - Визуализации не создаются - Ошибки в логах

➜ Подробнее о диагностике

Общие рекомендации по диагностике

1. Проверить логи

Логи - первое место, куда нужно смотреть при любой проблеме:

# Последние 50 строк логов
docker logs orbita --tail 50

# Логи в реальном времени
docker logs orbita --follow

# Логи за последние 10 минут
docker logs orbita --since 10m

# Сохранить логи в файл для анализа
docker logs orbita > orbita-logs-$(date +%Y%m%d-%H%M%S).txt

2. Проверить конфигурацию

# Проверить что .env существует
ls -la ~/orbita/.env

# Проверить основные переменные (без вывода паролей)
cat ~/orbita/.env | grep -v PASSWORD | grep -v API_KEY

# Проверить что домены на месте
ls -la ~/orbita/domains/

3. Проверить подключения

# ClickHouse
curl http://localhost:8123
# Должен вернуть: Ok.

# PostgreSQL (если используется)
docker exec postgres-metadata pg_isready -U orbita_user

# Redis (если используется)
docker exec redis redis-cli ping
# Должен вернуть: PONG

# API Р13.Орбита
curl http://localhost:8000/health
# Должен вернуть JSON с версией

4. Проверить ресурсы

# Использование ресурсов контейнером
docker stats orbita --no-stream

# Использование диска
df -h | grep -E "Filesystem|/$"

# Память на хосте
free -h

# Место в Docker
docker system df

Уровни severity

При классификации проблем используйте следующие уровни:

🔴 Critical - Система не работает

Описание: Р13.Орбита полностью недоступна, критические функции не работают.

Примеры: - Контейнер не запускается - API не отвечает на запросы - Не удается подключиться к ClickHouse (основная БД)

Действия: 1. Проверить логи 2. Проверить подключения к внешним сервисам 3. Рассмотреть откат к предыдущей версии 4. Восстановление из резервной копии (если данные повреждены)

🟠 High - Основные функции нарушены

Описание: Система частично работает, но основные функции недоступны.

Примеры: - Запросы выполняются, но результаты некорректны - Датасеты не сохраняются - LLM провайдер недоступен (fallback работает)

Действия: 1. Диагностировать конкретную проблему 2. Проверить конфигурацию компонента 3. Перезапустить контейнер 4. Применить hotfix если доступен

🟡 Medium - Вспомогательные функции нарушены

Описание: Основная функциональность работает, но некоторые возможности недоступны.

Примеры: - Визуализации не создаются (но данные получить можно) - Медленная работа отдельных запросов - Логи содержат предупреждения (но не ошибки)

Действия: 1. Запланировать исправление 2. Найти workaround для пользователей 3. Исправить в следующем обновлении

🟢 Low - Косметические проблемы

Описание: Незначительные проблемы, не влияющие на работу.

Примеры: - Форматирование ответов немного некорректное - Некоторые сообщения в логах избыточны - CLI интерфейс отображается не идеально

Действия: 1. Добавить в backlog 2. Исправить при возможности 3. Не критично

Структура решения проблем

Для каждой проблемы в этом разделе используется следующая структура:

Симптомы

Что наблюдает пользователь

Причина

Почему возникает проблема

Диагностика

Как подтвердить, что это именно эта проблема

Решение

Шаги для устранения проблемы

Профилактика

Как избежать проблемы в будущем

Частые вопросы

Где найти логи?

# Логи Docker контейнера
docker logs orbita

# Файлы логов (если настроено volume монтирование)
~/orbita/logs/orbita.log
~/orbita/logs/api.log

Как перезапустить Р13.Орбита?

# Мягкий перезапуск (graceful)
docker restart orbita

# Жесткий перезапуск (force)
docker stop orbita
docker start orbita

# Полный пересоздание контейнера
docker stop orbita
docker rm orbita
docker run -d \
  --name orbita \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:latest

Как проверить версию?

# Через API
curl http://localhost:8000/health | jq '.version'

# Внутри контейнера
docker exec orbita cat /app/VERSION

# Версия Docker образа
docker inspect orbita | jq '.[0].Config.Image'

Куда сообщить о проблеме?

Если проблему не удалось решить с помощью этой документации:

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

    # Создать диагностический пакет
./diagnostics.sh  # См. раздел Диагностика

  2. Сохраните логи: 

    docker logs orbita > orbita-issue-$(date +%Y%m%d).log

  3. Обратитесь к администратору или в службу поддержки с этими файлами

Разделы документации

Дополнительные ресурсы