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

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

Docker образ не загружается¶

Симптомы¶

Error response from daemon: unauthorized: authentication required
Error response from daemon: manifest for your-registry.company.com/orbita:latest not found

Причина¶

Не выполнена авторизация в Docker registry
Образ отсутствует в registry или указана неверная версия
Нет прав доступа к образу
Проблемы с сетевым подключением к registry

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

# Проверьте авторизацию
docker login your-registry.company.com

# Проверьте доступность registry
ping your-registry.company.com

# Проверьте доступные теги
curl -X GET https://your-registry.company.com/v2/orbita/tags/list \
  -u username:password

# Проверьте права пользователя
id
# Пользователь должен быть в группе docker

Решение¶

# 1. Войдите в Docker registry
docker login your-registry.company.com
# Введите username и password

# 2. Проверьте доступность образа
docker pull your-registry.company.com/orbita:latest

# 3. Если пользователь не в группе docker
sudo usermod -aG docker $USER
# Выйдите и войдите заново для применения изменений

# 4. Если используется приватный registry с self-signed сертификатом
# Добавьте insecure registry в /etc/docker/daemon.json
sudo nano /etc/docker/daemon.json

{
  "insecure-registries": ["your-registry.company.com"]
}

# Перезапустите Docker
sudo systemctl restart docker

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

Храните credentials в безопасном месте
Используйте docker login перед началом работы
Проверяйте доступность registry перед обновлениями

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

Симптомы¶

docker: Error response from daemon: ...
Container exits immediately after start
docker ps shows no running orbita container

Причина¶

Неправильная конфигурация в .env
Отсутствие необходимых volume директорий
Конфликт портов
Недостаточно ресурсов (память/CPU)
Ошибка в командной строке docker run

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

# Проверьте логи контейнера
docker logs orbita

# Проверьте что файл .env существует
ls -la .env

# Проверьте синтаксис .env
cat .env

# Проверьте что директории существуют
ls -la domains/

# Проверьте занятость портов
sudo lsof -i :8000

# Проверьте доступные ресурсы
docker stats --no-stream

# Попробуйте запустить в интерактивном режиме для диагностики
docker run -it --rm --env-file .env your-registry.company.com/orbita:latest /bin/bash

Решение¶

Проблема: Файл .env не найден¶

# Создайте .env файл
nano .env

# Минимальная конфигурация:
cat > .env << 'EOF'
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your-api-key-here
LLM_MODEL=gpt-4
CLICKHOUSE_HOST=clickhouse-server
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
METADATA_DB_URL=sqlite:///~/.orbita/metadata.db
EOF

Проблема: Отсутствуют volume директории¶

# Создайте необходимые директории
mkdir -p ~/orbita/domains
mkdir -p ~/orbita/logs

# Если domains пустой, скопируйте примеры
# (должны быть предоставлены отдельно)
cp -r /path/to/sample-domains/*.yaml ~/orbita/domains/

Проблема: Порт занят¶

# Найдите процесс на порту 8000
sudo lsof -i :8000

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

# Или используйте другой порт
docker run -d \
  --name orbita \
  -p 8001:8000 \  # Изменить на 8001
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:latest

Проблема: Недостаточно памяти¶

# Увеличьте лимит памяти для контейнера
docker run -d \
  --name orbita \
  --memory="2g" \  # 2GB RAM
  --memory-swap="3g" \  # 3GB swap
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:latest

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

Всегда создавайте .env перед запуском
Проверяйте доступность портов
Используйте docker-compose для управления зависимостями
Мониторьте ресурсы Docker

Конфигурация некорректна¶

Симптомы¶

ERROR: Invalid configuration
KeyError: 'LLM_API_KEY'
ValueError: Invalid URL format

Причина¶

Отсутствуют обязательные переменные окружения
Неправильный формат значений
Синтаксическая ошибка в .env файле

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

# Проверьте что все обязательные переменные присутствуют
cat .env | grep -E "LLM_API_KEY|LLM_BASE_URL|CLICKHOUSE_HOST"

# Проверьте формат (нет лишних кавычек, пробелов)
cat .env

# Проверьте логи контейнера для конкретной ошибки
docker logs orbita 2>&1 | grep -i error

Решение¶

Обязательные переменные¶

Минимальный набор переменных для запуска:

# .env
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...  # Ваш API ключ
LLM_MODEL=gpt-4
CLICKHOUSE_HOST=clickhouse.company.com
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
METADATA_DB_URL=postgresql://user:pass@postgres:5432/orbita

Правила форматирования .env¶

# ✅ Правильно
LLM_API_KEY=sk-abc123
CLICKHOUSE_HOST=localhost

# ❌ Неправильно
LLM_API_KEY="sk-abc123"  # Не используйте кавычки
CLICKHOUSE_HOST = localhost  # Нет пробелов вокруг =

Проверка конфигурации¶

# Тест конфигурации без запуска сервера
docker run --rm --env-file .env \
  your-registry.company.com/orbita:latest \
  python -c "from orbita_core.config import get_config; c = get_config(); print('Config OK')"

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

Используйте шаблон .env файла
Храните reference .env в документации
Используйте валидацию конфигурации при старте

Health check не проходит¶

Симптомы¶

curl http://localhost:8000/health
curl: (7) Failed to connect to localhost port 8000: Connection refused

# Или
curl http://localhost:8000/health
curl: (52) Empty reply from server

Причина¶

API сервер не запустился внутри контейнера
Ошибка при инициализации приложения
Проблемы с подключением к зависимостям (ClickHouse, БД)

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

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

# Проверьте логи запуска
docker logs orbita | head -50

# Проверьте процессы внутри контейнера
docker exec orbita ps aux

# Проверьте порты
docker port orbita

# Попробуйте подключиться изнутри контейнера
docker exec orbita curl http://localhost:8000/health

Решение¶

Проблема: API сервер не запустился¶

# Проверьте логи для конкретной ошибки
docker logs orbita 2>&1 | grep -i "error\|failed\|exception"

# Запустите в интерактивном режиме для диагностики
docker run -it --rm \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:latest \
  /bin/bash

# Внутри контейнера попробуйте запустить вручную
uvicorn orbita_api.main:app --host 0.0.0.0 --port 8000

Проблема: Подключение к зависимостям¶

# Проверьте подключение к ClickHouse
docker exec orbita curl http://clickhouse:8123
# Если ошибка - проверьте CLICKHOUSE_HOST в .env

# Проверьте подключение к PostgreSQL
docker exec orbita psql -h postgres -U orbita_user -d orbita -c "SELECT 1"
# Если ошибка - проверьте METADATA_DB_URL в .env

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

Всегда проверяйте health check после запуска
Настройте monitoring для health endpoint
Используйте healthcheck в docker-compose.yml

Docker Compose не запускается¶

Симптомы¶

ERROR: yaml.parser.ParserError: ...
ERROR: Service 'orbita' failed to build: ...
ERROR: for orbita  Cannot start service orbita: ...

Причина¶

Синтаксическая ошибка в docker-compose.yml
Отсутствие образа
Конфликт имен контейнеров или сетей
Недоступность зависимых сервисов

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

# Проверьте синтаксис YAML
docker-compose config

# Проверьте какие сервисы не запустились
docker-compose ps

# Проверьте логи конкретного сервиса
docker-compose logs orbita
docker-compose logs postgres-metadata
docker-compose logs clickhouse

# Проверьте сети
docker network ls

Решение¶

# 1. Остановите все сервисы
docker-compose down

# 2. Удалите старые контейнеры с конфликтующими именами
docker ps -a | grep orbita
docker rm -f <container_id>

# 3. Пересоздайте сервисы
docker-compose up -d

# 4. Если проблемы с сетью
docker-compose down
docker network prune -f
docker-compose up -d

# 5. Если проблемы с volumes
docker-compose down -v  # ВНИМАНИЕ: удалит данные!
docker-compose up -d

Пример правильного docker-compose.yml¶

version: '3.8'

services:
  orbita:
    image: your-registry.company.com/orbita:latest
    container_name: orbita
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./domains:/app/domains
      - ./logs:/app/logs
    depends_on:
      - postgres-metadata
      - clickhouse
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres-metadata:
    image: postgres:15
    container_name: postgres-metadata
    restart: unless-stopped
    environment:
      POSTGRES_DB: orbita
      POSTGRES_USER: orbita_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: clickhouse
    restart: unless-stopped
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/var/lib/clickhouse

volumes:
  postgres_data:
  clickhouse_data:

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

Используйте docker-compose config для проверки синтаксиса
Всегда используйте docker-compose down перед обновлением
Задавайте явные версии образов (не latest)

Нет доступа к Swagger UI¶

Симптомы¶

http://localhost:8000/docs returns 404 Not Found
или
Unable to load API definition

Причина¶

API не запустился
FastAPI docs отключены в production
CORS настройки блокируют доступ

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

# Проверьте health endpoint (если health работает, API запущен)
curl http://localhost:8000/health

# Проверьте конкретно /docs
curl -I http://localhost:8000/docs

# Проверьте логи
docker logs orbita | grep -i "docs\|swagger"

Решение¶

# Проверьте что DOCS_ENABLED=true в .env
echo "DOCS_ENABLED=true" >> .env

# Перезапустите контейнер
docker restart orbita

# Попробуйте доступ через localhost и через IP
curl http://localhost:8000/docs
curl http://127.0.0.1:8000/docs
curl http://<server-ip>:8000/docs

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

В production можно отключить Swagger UI из соображений безопасности
Используйте альтернативные API клиенты (Postman, curl)

Следующие шаги¶

Проблемы подключения - если установка прошла, но есть проблемы с БД или LLM
Диагностика - инструменты для сбора диагностической информации
Конфигурация - правильная настройка системы