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

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

Проблемы окружения¶

ModuleNotFoundError: No module named 'orbita_*'¶

Симптомы:

ModuleNotFoundError: No module named 'orbita_cli'
ModuleNotFoundError: No module named 'pydantic_settings'

Причина: Виртуальное окружение не активировано или зависимости не установлены.

Решение:

# Проверьте активное окружение
which python
# Должен показать путь в venv

# Активируйте окружение
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Переустановите зависимости
pip install -r requirements.txt

# Проверьте установку
pip list | grep orbita

ImportError: cannot import name 'X' from 'Y'¶

Причина: Несовместимые версии пакетов.

Решение:

# Обновите pip
pip install --upgrade pip

# Переустановите все зависимости
pip install -r requirements.txt --force-reinstall

# Или пересоздайте окружение
deactivate
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Проблемы с базой данных¶

Alembic: FAILED: Can't locate revision identified by 'xyz'¶

Причина: Несинхронизированное состояние миграций.

Решение:

# Проверьте текущую версию
alembic current

# Посмотрите историю
alembic history

# Откатитесь к предыдущей версии
alembic downgrade -1

# Или принудительно установите версию
alembic stamp head

ClickHouse: Connection refused (port 8123)¶

Симптомы:

Connection refused: http://localhost:8123

Диагностика:

# Проверьте что ClickHouse запущен
docker ps | grep clickhouse

# Или для нативной установки
sudo systemctl status clickhouse-server  # Linux
brew services list | grep clickhouse     # macOS

# Проверьте доступность порта
curl http://localhost:8123
# Должен вернуть: Ok.

# Проверьте логи
docker logs clickhouse  # Docker
sudo tail -f /var/log/clickhouse-server/clickhouse-server.log  # Linux

Решение:

# Запустите ClickHouse
docker start clickhouse  # Docker
sudo systemctl start clickhouse-server  # Linux
brew services start clickhouse  # macOS

PostgreSQL: Connection refused (port 5432)¶

Диагностика:

# Проверьте статус
docker ps | grep postgres
sudo systemctl status postgresql

# Проверьте подключение
psql -h localhost -p 5432 -U orbita_user -d orbita

Решение:

# Запустите PostgreSQL
docker start postgres-metadata
sudo systemctl start postgresql

# Проверьте что БД создана
psql -h localhost -U postgres -c "\l" | grep orbita

# Создайте БД если нужно
createdb -h localhost -U postgres orbita

SQLite: database is locked¶

Причина: Одновременный доступ из нескольких процессов.

Решение:

SQLite не подходит для продакшн. Используйте PostgreSQL:

# Миграция с SQLite на PostgreSQL
METADATA_DB_URL=postgresql://user:pass@localhost:5432/orbita
alembic upgrade head

Проблемы с LLM провайдерами¶

OpenAI: AuthenticationError: Incorrect API key¶

Диагностика:

# Проверьте API ключ
cat .env | grep LLM_API_KEY

# Проверьте ключ вручную
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

Решение:

Убедитесь что ключ правильный
Проверьте баланс на https://platform.openai.com/account/usage
Обновите ключ в .env

Ollama: Connection refused (port 11434)¶

Диагностика:

# Проверьте что Ollama запущен
curl http://localhost:11434/api/tags

# Проверьте список моделей
ollama list

Решение:

# Запустите Ollama
ollama serve

# Скачайте модель если нужна
ollama pull llama2

GigaChat: SSL Certificate Verify Failed¶

Решение:

# config.yaml
llm:
  type: gigachat
  verify_ssl_certs: false

Проблемы с запросами¶

Р13.Орбита не понимает вопрос¶

Симптомы:

"Не могу определить таблицы для запроса"
"Домен не найден"

Диагностика:

# Проверьте доступные домены
python -m orbita_cli chat
> /domains

# Проверьте конфигурацию доменов
ls domains/
cat domains/ecommerce.yaml

Решение:

Уточните вопрос, упоминая таблицы явно
Убедитесь что домен настроен в domains/*.yaml
Проверьте что таблицы существуют в ClickHouse

SQL Execution Error: Table doesn't exist¶

Причина: Таблица не существует в ClickHouse.

Диагностика:

clickhouse-client --query "SHOW TABLES"
clickhouse-client --query "SHOW TABLES FROM ecommerce"

Решение:

Создайте таблицу в ClickHouse
Обновите конфигурацию домена в domains/*.yaml
Проверьте CLICKHOUSE_DATABASE в .env

Проблемы с API¶

API: 502 Bad Gateway¶

Причина: API сервер не запущен или недоступен.

Диагностика:

# Проверьте что API запущен
ps aux | grep uvicorn

# Проверьте логи
tail -f logs/orbita-api.log

# Проверьте порт
netstat -an | grep 8000

Решение:

# Запустите API
uvicorn orbita_api.main:app --host 0.0.0.0 --port 8000

API: 401 Unauthorized¶

Причина: Проблема с аутентификацией.

Диагностика:

# Проверьте настройки auth
cat config.yaml | grep -A 10 "auth:"

# Для Keycloak проверьте доступность
curl http://localhost:8080

Решение:

Если auth не нужен: AUTH_ENABLED=false в .env
Проверьте Keycloak настройки
Проверьте JWT токен

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

Запросы выполняются медленно¶

Диагностика:

# Включите метрики
python -m orbita_cli chat
> /metrics on
> /sql on

# Проверьте SQL запрос

Оптимизация:

Используйте индексы в ClickHouse
Ограничивайте временной диапазон
Используйте агрегацию вместо детализации
Увеличьте pool_size в конфигурации

Высокое использование памяти¶

Причина: Большие результаты запросов.

Решение:

# config.yaml
processing:
  auto_limit_rows: 1000  # Уменьшите лимит

Проблемы с Docker¶

Docker Compose: Container failed to start¶

Диагностика:

# Проверьте логи
docker-compose logs clickhouse
docker-compose logs postgres-metadata

# Проверьте статус
docker-compose ps

Решение:

# Пересоздайте контейнеры
docker-compose down
docker-compose up -d

# Очистка (осторожно - удалит данные)
docker-compose down -v
docker-compose up -d

Port already allocated¶

Причина: Порт занят другим процессом.

Диагностика:

# Найдите процесс на порту 8000
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

Решение:

# Остановите процесс
kill -9 <PID>

# Или измените порт в docker-compose.yml

Логи и диагностика¶

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

CLI:

~/.orbita/logs/cli.log

API:

logs/orbita-api.log

Docker services:

docker-compose logs -f orbita-api
docker-compose logs -f clickhouse

Системные логи:

# Linux
sudo journalctl -u orbita-api

# macOS
tail -f /usr/local/var/log/orbita.log

Увеличение детализации логов¶

# config.yaml
logging:
  level: DEBUG  # Было: INFO

Или через переменную окружения:

LOG_LEVEL=DEBUG python -m orbita_cli chat

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

Если проблема не решена:

Проверьте логи - часто ошибка описана там
FAQ - частые вопросы
GitHub Issues - создайте issue с:
Описанием проблемы
Шагами воспроизведения
Логами (без секретов!)
Версией Р13.Орбита (cat config.yaml | grep version)
ОС и версией Python

Чеклист диагностики¶

При возникновении проблем пройдите этот чеклист: