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

Решение проблем при подключении Р13.Орбита к внешним сервисам (ClickHouse, PostgreSQL, LLM провайдеры).

ClickHouse: Connection refused¶

Симптомы¶

ERROR: Connection refused: http://clickhouse:8123
clickhouse_driver.errors.NetworkError: Code: 210. Connection refused
HTTPConnectionPool: Max retries exceeded

Причина¶

ClickHouse не запущен
Неправильный хост или порт в конфигурации
Firewall блокирует подключение
ClickHouse еще не готов принимать подключения

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

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

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

# 3. Проверьте доступность из контейнера Р13.Орбита
docker exec orbita curl http://clickhouse:8123

# 4. Проверьте логи ClickHouse
docker logs clickhouse --tail 50

# 5. Проверьте конфигурацию в .env
cat .env | grep CLICKHOUSE

Решение¶

Проблема: ClickHouse не запущен¶

# Запустите ClickHouse (если используете Docker Compose)
docker-compose up -d clickhouse

# Или отдельный контейнер
docker start clickhouse

# Проверьте статус
docker ps | grep clickhouse

Проблема: Неправильный хост в конфигурации¶

# Проверьте CLICKHOUSE_HOST в .env
nano .env

# Если используете Docker Compose - используйте имя сервиса:
CLICKHOUSE_HOST=clickhouse  # НЕ localhost!
CLICKHOUSE_PORT=8123

# Если ClickHouse на отдельном сервере:
CLICKHOUSE_HOST=clickhouse.company.com
CLICKHOUSE_PORT=8123

# Перезапустите Р13.Орбита
docker restart orbita

Проблема: ClickHouse еще не готов¶

ClickHouse может требовать времени для запуска:

# Подождите 10-15 секунд и повторите попытку
sleep 15
curl http://localhost:8123

# Или используйте healthcheck в docker-compose.yml

Правильная конфигурация в docker-compose.yml:

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  orbita:
    depends_on:
      clickhouse:
        condition: service_healthy

Проблема: Firewall блокирует¶

# Проверьте правила firewall
sudo iptables -L | grep 8123

# Разрешите порт (если нужно)
sudo ufw allow 8123/tcp

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

Всегда запускайте зависимости (ClickHouse, PostgreSQL) перед Р13.Орбита
Используйте depends_on с condition: service_healthy в docker-compose.yml
Настройте monitoring для ClickHouse

ClickHouse: Authentication failed¶

Симптомы¶

ERROR: Authentication failed for user 'default'
Code: 516. DB::Exception: Authentication failed

Причина¶

Неправильный username или password
ClickHouse требует аутентификацию, а credentials не указаны

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

# Проверьте credentials в .env
cat .env | grep CLICKHOUSE_USER
cat .env | grep CLICKHOUSE_PASSWORD

# Проверьте подключение вручную
clickhouse-client --host localhost --port 9000 --user default --password ''

# Или через HTTP
curl http://localhost:8123/ --user default:your-password

Решение¶

# Добавьте credentials в .env
nano .env

# Добавьте строки:
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Если password пустой - оставьте пустым:
CLICKHOUSE_PASSWORD=

# Перезапустите Р13.Орбита
docker restart orbita

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

Используйте сильные пароли для ClickHouse в production
Храните credentials в .env, не в конфигурационных файлах
Используйте read-only пользователя для Р13.Орбита

ClickHouse: Database/Table not found¶

Симптомы¶

ERROR: Database 'ecommerce' doesn't exist
Code: 81. DB::Exception: Database ecommerce doesn't exist
ERROR: Table 'orders' doesn't exist

Причина¶

База данных не создана в ClickHouse
Таблица не существует
Неправильное имя БД в конфигурации домена
Права доступа пользователя ограничены

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

# Проверьте список баз данных
clickhouse-client --query "SHOW DATABASES"

# Проверьте список таблиц
clickhouse-client --query "SHOW TABLES FROM ecommerce"

# Проверьте схему таблицы
clickhouse-client --query "DESCRIBE TABLE ecommerce.orders"

# Проверьте CLICKHOUSE_DATABASE в .env
cat .env | grep CLICKHOUSE_DATABASE

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

Решение¶

Создать отсутствующую базу данных¶

# Создать БД
clickhouse-client --query "CREATE DATABASE IF NOT EXISTS ecommerce"

# Проверить
clickhouse-client --query "SHOW DATABASES" | grep ecommerce

Обновить конфигурацию домена¶

# domains/ecommerce.yaml
domain: ecommerce
database: ecommerce  # Должно соответствовать реальной БД в ClickHouse
tables:
  - name: orders  # Должна существовать в ClickHouse
    # ...

Предоставить права доступа¶

-- Для read-only пользователя
GRANT SELECT ON ecommerce.* TO orbita_ro;

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

Всегда создавайте БД и таблицы перед запуском Р13.Орбита
Используйте init scripts в Docker для автоматического создания структуры
Документируйте требования к схеме данных

PostgreSQL: Connection refused¶

Симптомы¶

ERROR: could not connect to server: Connection refused
psycopg2.OperationalError: could not connect to server
FATAL: password authentication failed for user "orbita_user"

Причина¶

PostgreSQL не запущен
Неправильный connection string в METADATA_DB_URL
PostgreSQL еще не готов принимать подключения
Firewall блокирует порт 5432

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

# 1. Проверьте что PostgreSQL запущен
docker ps | grep postgres

# 2. Проверьте подключение
docker exec postgres-metadata pg_isready -U orbita_user
# Должен вернуть: accepting connections

# 3. Попробуйте подключиться
docker exec postgres-metadata psql -U orbita_user -d orbita -c "SELECT 1"

# 4. Проверьте логи PostgreSQL
docker logs postgres-metadata --tail 50

# 5. Проверьте METADATA_DB_URL в .env
cat .env | grep METADATA_DB_URL

Решение¶

Проблема: PostgreSQL не запущен¶

# Запустите PostgreSQL
docker-compose up -d postgres-metadata

# Или
docker start postgres-metadata

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

Проблема: Неправильный connection string¶

# Правильный формат METADATA_DB_URL
nano .env

# Для Docker Compose (имя сервиса как хост):
METADATA_DB_URL=postgresql://orbita_user:password@postgres-metadata:5432/orbita

# Для внешнего PostgreSQL:
METADATA_DB_URL=postgresql://orbita_user:password@postgres.company.com:5432/orbita

# Для SQLite (альтернатива, dev/test only):
METADATA_DB_URL=sqlite:///~/.orbita/metadata.db

# Перезапустите Р13.Орбита
docker restart orbita

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

# Проверьте что БД существует
docker exec postgres-metadata psql -U postgres -c "\l" | grep orbita

# Создайте БД если отсутствует
docker exec postgres-metadata psql -U postgres -c "CREATE DATABASE orbita OWNER orbita_user;"

# Примените миграции
docker exec orbita alembic upgrade head

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

Используйте healthcheck для PostgreSQL в docker-compose.yml
Всегда проверяйте что БД создана перед первым запуском
Используйте connection pooling для стабильности

LLM Provider: Authentication failed¶

Симптомы¶

ERROR: OpenAI AuthenticationError: Incorrect API key provided
ERROR: GigaChat authorization failed
ERROR: 401 Unauthorized

Причина¶

Неправильный API ключ
API ключ истек или был отозван
Закончился баланс или лимиты
Неправильный base URL

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

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

# Проверьте base URL
cat .env | grep LLM_BASE_URL

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

# Проверьте логи Р13.Орбита для конкретной ошибки
docker logs orbita | grep -i "llm\|authentication\|api key"

Решение¶

Для OpenAI¶

# 1. Проверьте API ключ на https://platform.openai.com/api-keys

# 2. Обновите .env
nano .env

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...  # Ваш действующий ключ
LLM_MODEL=gpt-4

# 3. Проверьте баланс на https://platform.openai.com/account/usage

# 4. Перезапустите Р13.Орбита
docker restart orbita

Для GigaChat¶

nano .env

LLM_BASE_URL=https://gigachat.devices.sberbank.ru/api/v1
LLM_API_KEY=your-gigachat-credentials
LLM_MODEL=GigaChat

# Если проблемы с SSL
GIGACHAT_VERIFY_SSL=false

docker restart orbita

Для Ollama (локальный)¶

# 1. Убедитесь что Ollama запущен
curl http://localhost:11434/api/tags

# 2. Проверьте что модель скачана
ollama list

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

# 4. Настройте .env
nano .env

LLM_BASE_URL=http://host.docker.internal:11434  # Для Docker на macOS/Windows
# Или
LLM_BASE_URL=http://172.17.0.1:11434  # Для Docker на Linux
LLM_API_KEY=ollama  # Любое значение для совместимости
LLM_MODEL=llama3

docker restart orbita

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

Ротируйте API ключи регулярно
Настройте monitoring для баланса API
Используйте rate limiting для экономии токенов
Имейте fallback провайдера

LLM Provider: Connection timeout¶

Симптомы¶

ERROR: Request timeout after 60s
ERROR: ReadTimeout: HTTPSConnectionPool
ERROR: Connection to LLM provider failed

Причина¶

LLM API недоступен или перегружен
Сетевые проблемы
Слишком короткий timeout
Firewall блокирует исходящие запросы

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

# Проверьте доступность LLM API
curl -I https://api.openai.com/v1/models

# Проверьте из контейнера Р13.Орбита
docker exec orbita curl -I https://api.openai.com/v1/models

# Проверьте время ответа
time curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

# Проверьте DNS
docker exec orbita nslookup api.openai.com

Решение¶

# Увеличьте timeout в .env
nano .env

# Добавьте:
LLM_TIMEOUT=120  # 120 секунд вместо 60

# Если используете proxy
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080

# Перезапустите
docker restart orbita

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

Настройте retry logic с exponential backoff
Используйте несколько LLM провайдеров для failover
Мониторьте latency к LLM API

Redis: Connection refused (опционально)¶

Симптомы¶

ERROR: Connection refused: redis://localhost:6379
redis.exceptions.ConnectionError

Причина¶

Redis используется опционально для кеширования и rate limiting. Если Redis недоступен, Р13.Орбита продолжит работу без кеширования.

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

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

# Проверьте подключение
docker exec redis redis-cli ping
# Должен вернуть: PONG

# Проверьте из Р13.Орбита
docker exec orbita redis-cli -h redis ping

Решение¶

# Запустите Redis
docker-compose up -d redis

# Или отключите Redis в .env
nano .env

# Закомментируйте или удалите:
# REDIS_URL=redis://redis:6379/0

# Перезапустите Р13.Орбита
docker restart orbita

Сетевые проблемы между контейнерами¶

Симптомы¶

ERROR: Name or service not known: clickhouse
ERROR: Could not resolve hostname
Networks: network not found

Причина¶

Контейнеры в разных Docker networks
Network не создан
DNS resolution не работает между контейнерами

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

# Проверьте Docker networks
docker network ls

# Проверьте к какой сети подключен Р13.Орбита
docker inspect orbita | grep -A 10 Networks

# Проверьте к какой сети подключен ClickHouse
docker inspect clickhouse | grep -A 10 Networks

# Попробуйте ping между контейнерами
docker exec orbita ping -c 3 clickhouse

Решение¶

Подключите контейнеры к одной сети¶

# Создайте сеть
docker network create orbita-network

# Подключите контейнеры
docker network connect orbita-network orbita
docker network connect orbita-network clickhouse
docker network connect orbita-network postgres-metadata

# Перезапустите Р13.Орбита
docker restart orbita

Используйте Docker Compose (рекомендуется)¶

Docker Compose автоматически создает сеть для всех сервисов:

version: '3.8'

services:
  orbita:
    # ...
    networks:
      - orbita-net

  clickhouse:
    # ...
    networks:
      - orbita-net

  postgres-metadata:
    # ...
    networks:
      - orbita-net

networks:
  orbita-net:
    driver: bridge

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

Всегда используйте Docker Compose для multi-container приложений
Явно определяйте networks в docker-compose.yml
Используйте имена сервисов вместо IP адресов

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

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