====== Установка LiteLLM Proxy с Docker и Nginx Proxy Manager ======

===== Описание =====

LiteLLM Proxy - это унифицированный шлюз для работы с различными LLM провайдерами (OpenAI, Claude, Gemini и др.) через единый API. Система позволяет:

  * Управлять множественными API ключами через веб-интерфейс
  * Автоматическое переключение между ключами при превышении лимитов
  * Балансировка нагрузки между ключами
  * Детальная аналитика и мониторинг использования
  * Кеширование ответов для экономии
  * Установка бюджетов и лимитов

===== Требования =====

  * Ubuntu Server 22.04 LTS
  * Docker и Docker Compose
  * Nginx Proxy Manager (NPM)
  * Домен с возможностью управления DNS
  * Внешняя сеть Docker ''webproxy''

===== Подготовка сервера =====

==== Установка Docker и Docker Compose ====

<code bash>
# Обновление системы
apt update && apt upgrade -y

# Установка Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Установка Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Проверка установки
docker --version
docker-compose --version
</code>

==== Создание рабочей директории ====

<code bash>
# Создание директории проекта
mkdir /opt/litellm
cd /opt/litellm

# Создание структуры папок
mkdir -p config logs data postgres_data redis_data
</code>

===== Настройка DNS алиасов =====

Создайте следующие DNS записи для домена digitizepro.tech:

^ Алиас ^ Назначение ^ Описание ^
| ''api.digitizepro.tech'' | Основной API + UI | Главный эндпоинт для API запросов и веб-интерфейса |
| ''ai.digitizepro.tech'' | Альтернативный API | Короткий алиас для AI сервисов |
| ''openai.digitizepro.tech'' | OpenAI совместимый API | Указывает на совместимость с OpenAI API |
| ''llm.digitizepro.tech'' | LLM Gateway | Общий алиас для языковых моделей |

==== Преимущества использования алиасов ====

  * **Логическое разделение** - разные домены для разных сервисов
  * **Гибкость конфигурации** - можно настроить разные правила доступа
  * **Масштабируемость** - легко добавить новые сервисы
  * **Безопасность** - можно ограничить доступ к UI отдельно от API
  * **Мониторинг** - отдельная статистика по каждому домену

===== Установка LiteLLM =====

==== Создание файла переменных окружения ====

<code bash>
nano .env
</code>

<code bash>
# PostgreSQL Database
POSTGRES_PASSWORD=PgSQL_9Kx7mN2vB8qF3wR5tY6uI0oP1aS4dF7gH

# LiteLLM Master Key (главный ключ для API доступа)
LITELLM_MASTER_KEY=sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k

# LiteLLM Salt Key (ключ для шифрования)
LITELLM_SALT_KEY=sk-salt-Q9w2E5r8T1y4U7i0O3p6A9s2D5f8G1h4J7k0L3z6X9c2V5b8N1m

# UI Dashboard Password
UI_PASSWORD=UI_Admin_7mK2qF9xR5tG8nP1wS4vY3bC6eZ0hL9jM
</code>

<code bash>
# Установка прав доступа
chmod 600 .env
</code>

==== Создание docker-compose.yml ====

<code bash>
nano docker-compose.yml
</code>

<code yaml>
services:
  # PostgreSQL для LiteLLM
  litellm_postgres:
    image: postgres:15-alpine
    container_name: litellm_postgres
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
      - ./logs:/logs
    restart: unless-stopped
    networks:
      - webproxy
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Redis для кеширования
  litellm_redis:
    image: redis:7-alpine
    container_name: litellm_redis
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - ./redis_data:/data
    restart: unless-stopped
    networks:
      - webproxy
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Основной сервис LiteLLM
  litellm_proxy:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm_proxy
    environment:
      # База данных
      DATABASE_URL: "postgresql://litellm:${POSTGRES_PASSWORD}@litellm_postgres:5432/litellm"
      
      # Redis
      REDIS_HOST: litellm_redis
      REDIS_PORT: 6379
      
      # Безопасность
      LITELLM_MASTER_KEY: "${LITELLM_MASTER_KEY}"
      LITELLM_SALT_KEY: "${LITELLM_SALT_KEY}"
      
      # Настройки UI
      UI_USERNAME: admin
      UI_PASSWORD: ${UI_PASSWORD}
      
      # Настройки через переменные окружения
      GENERAL_SETTINGS_MASTER_KEY: "${LITELLM_MASTER_KEY}"
      GENERAL_SETTINGS_DATABASE_URL: "postgresql://litellm:${POSTGRES_PASSWORD}@litellm_postgres:5432/litellm"
      GENERAL_SETTINGS_UI: "true"
      GENERAL_SETTINGS_UI_USERNAME: "admin"
      GENERAL_SETTINGS_UI_PASSWORD: "${UI_PASSWORD}"
      GENERAL_SETTINGS_SET_VERBOSE: "true"
      GENERAL_SETTINGS_JSON_LOGS: "true"
      
      # Логирование
      LITELLM_LOG: INFO
      SET_VERBOSE: "true"
      
      # Другие настройки
      STORE_MODEL_IN_DB: "true"
      
    volumes:
      - ./config/litellm_config.yaml:/app/config.yaml:ro
      - ./logs:/app/logs
    expose:
      - "4000"
    depends_on:
      litellm_postgres:
        condition: service_healthy
      litellm_redis:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - webproxy
    command: ["--config", "/app/config.yaml", "--port", "4000", "--host", "0.0.0.0"]
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

networks:
  webproxy:
    external: true
</code>

==== Создание минимального конфига ====

<code bash>
nano config/litellm_config.yaml
</code>

<code yaml>
# Минимальная конфигурация для запуска системы
model_list:
  # Тестовая модель - замените на реальный ключ через веб-интерфейс!
  - model_name: gpt-3.5-turbo
    litellm_params:
      model: openai/gpt-3.5-turbo
      api_key: sk-test-key-replace-with-real-openai-key
      api_base: https://api.openai.com/v1
    model_info:
      id: test-gpt35-1
      mode: chat

# Настройки логирования
litellm_settings:
  drop_params: true
  set_verbose: false
  json_logs: true
</code>

==== Настройка прав доступа ====

<code bash>
# Установка правильных прав
chmod 600 config/litellm_config.yaml
chmod 700 /opt/litellm
chown -R root:root /opt/litellm
</code>

==== Запуск сервисов ====

<code bash>
cd /opt/litellm

# Запуск всех сервисов
docker-compose up -d

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

# Просмотр логов
docker-compose logs -f litellm_proxy
</code>

===== Настройка Nginx Proxy Manager =====

==== Создание Proxy Hosts ====

=== 1. Основной API + UI - api.digitizepro.tech ===

  * **Domain Names:** ''api.digitizepro.tech''
  * **Forward Hostname/IP:** ''litellm_proxy''
  * **Forward Port:** ''4000''
  * **Block Common Exploits:** ✓
  * **Websockets Support:** ✓
  * **SSL:** Request a new SSL Certificate

=== 2. Дополнительные алиасы (опционально) ===

Создайте аналогичные Proxy Hosts для:
  * ''ai.digitizepro.tech''
  * ''openai.digitizepro.tech''
  * ''llm.digitizepro.tech''

Все указывают на ''litellm_proxy:4000''

===== Проверка работоспособности =====

==== Тестирование API ====

<code bash>
# Проверка здоровья сервиса
curl https://api.digitizepro.tech/health

# Просмотр доступных моделей
curl https://api.digitizepro.tech/v1/models

# Тест чат-запроса
curl -X POST https://api.digitizepro.tech/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello from LiteLLM!"}],
    "max_tokens": 50
  }'
</code>

==== Доступ к веб-интерфейсу ====

  * **URL:** https://api.digitizepro.tech/ui или https://ui.digitizepro.tech/ui
  * **Логин:** admin
  * **Пароль:** UI_Admin_7mK2qF9xR5tG8nP1wS4vY3bC6eZ0hL9jM

===== Управление системой через веб-интерфейс =====

==== Добавление OpenAI ключей ====

  - Войдите в веб-интерфейс
  - Перейдите в **Models** → **Add Model**
  - Заполните поля:
    * **Model Name:** ''gpt-3.5-turbo-main''
    * **LiteLLM Model:** ''openai/gpt-3.5-turbo''
    * **API Key:** Ваш реальный OpenAI ключ
    * **API Base:** ''https://api.openai.com/v1''
  - Сохраните модель

==== Создание групп ключей ====

  - **Models** → **Model Groups**
  - Создайте группы:
    * "Main" - основные ключи
    * "Project1" - ключи проекта 1
    * "Client" - клиентские ключи
  - Назначьте модели в соответствующие группы

==== Управление пользователями ====

  - **Users** → **Add User**
  - **API Keys** → создание ключей для разных проектов
  - **Budgets** → установка лимитов расходов

==== Мониторинг и аналитика ====

  - **Dashboard** → общая статистика использования
  - **Logs** → журнал всех запросов
  - **Analytics** → детальный анализ трафика

===== Интеграция с n8n =====

==== Создание креденшла в n8n ====

  - Перейдите в **Settings** → **Credentials** → **Add Credential**
  - Выберите **"OpenAI"**
  - Заполните поля:

<code>
Credential Name: LiteLLM Proxy digitizepro.tech
API Key: sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k
Base URL: https://api.digitizepro.tech/v1
Organization: [оставьте пустым]
</code>

  - Нажмите **"Test Connection"**
  - При успешном тесте нажмите **"Save"**

==== Дополнительные креденшлы для разных проектов ====

Создайте несколько креденшлов для различных нужд:

=== 1. Основной креденшл ===
<code>
Credential Name: LiteLLM Main - digitizepro.tech
API Key: sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k
Base URL: https://api.digitizepro.tech/v1
</code>

=== 2. AI алиас ===
<code>
Credential Name: LiteLLM AI - digitizepro.tech
API Key: sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k
Base URL: https://ai.digitizepro.tech/v1
</code>

=== 3. OpenAI совместимый ===
<code>
Credential Name: LiteLLM OpenAI Compatible - digitizepro.tech
API Key: sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k
Base URL: https://openai.digitizepro.tech/v1
</code>

==== Использование в нодах ====

**В OpenAI Chat Model ноде:**
  * **Credentials:** выберите "LiteLLM Proxy digitizepro.tech"
  * **Model:** выберите модель из созданных в веб-интерфейсе

**Альтернативный способ через HTTP Request:**

<code json>
Method: POST
URL: https://api.digitizepro.tech/v1/chat/completions
Headers:
  Content-Type: application/json
  Authorization: Bearer sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k

Body:
{
  "model": "gpt-3.5-turbo",
  "messages": [{"role": "user", "content": "{{ $json.prompt }}"}],
  "max_tokens": 1000
}
</code>

==== Проверка подключения n8n ====

  - В n8n создайте простой workflow с OpenAI нодой
  - Используйте созданный креденшл
  - Отправьте тестовое сообщение
  - Проверьте результат в веб-интерфейсе LiteLLM (Logs)

===== Обслуживание и мониторинг =====

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

<code bash>
# Просмотр логов
docker-compose logs -f litellm_proxy
docker-compose logs litellm_postgres
docker-compose logs litellm_redis

# Перезапуск сервиса
docker-compose restart litellm_proxy

# Резервное копирование базы данных
docker exec litellm_postgres pg_dump -U litellm litellm > backup_$(date +%Y%m%d).sql

# Мониторинг ресурсов
docker stats
df -h

# Полная остановка
docker-compose down

# Запуск с пересборкой
docker-compose up -d --force-recreate
</code>

==== Автоматическое обновление ====

<code bash>
# Добавить в crontab
crontab -e

# Еженедельное обновление (воскресенье в 2:00)
0 2 * * 0 cd /opt/litellm && docker-compose pull && docker-compose up -d
</code>

===== Безопасность =====

==== Статические пароли системы ====

**Пароли уже настроены в .env файле:**
  * **PostgreSQL:** PgSQL_9Kx7mN2vB8qF3wR5tY6uI0oP1aS4dF7gH
  * **LiteLLM Master Key:** sk-litellm-E4j8mK9nP2qR5sT7vX0yZ3bC6eG9hL1oM4rU8wA5dF2gJ7k
  * **UI Пароль:** UI_Admin_7mK2qF9xR5tG8nP1wS4vY3bC6eZ0hL9jM

==== Дополнительные меры ====

<code bash>
# Настройка UFW firewall
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
</code>

===== Преимущества системы =====

  * **Централизованное управление** всеми OpenAI ключами
  * **Автоматическое переключение** между ключами при лимитах
  * **Балансировка нагрузки** между доступными ключами
  * **Детальная аналитика** использования по проектам
  * **Кеширование ответов** для экономии средств
  * **Установка бюджетов** и лимитов для контроля расходов
  * **Единый API** для работы с разными LLM провайдерами
  * **Веб-интерфейс** для управления без редактирования конфигов

===== Устранение неисправностей =====

==== Проблемы с запуском ====

<code bash>
# Проверка статуса контейнеров
docker-compose ps

# Проверка логов на ошибки
docker-compose logs litellm_proxy | grep -i error

# Проверка подключения к базе данных
docker exec litellm_postgres pg_isready -U litellm

# Проверка Redis
docker exec litellm_redis redis-cli ping

# Проверка переменных окружения
docker exec litellm_proxy env | grep LITELLM
</code>

==== Проблемы с доступом ====

  - Убедитесь, что DNS записи digitizepro.tech настроены правильно
  - Проверьте настройки Nginx Proxy Manager
  - Убедитесь, что контейнеры находятся в сети ''webproxy''
  - Проверьте SSL сертификаты

==== Проблемы с n8n ====

  - Убедитесь, что используете правильный Base URL
  - Проверьте Master Key в креденшле
  - Убедитесь, что модель существует в LiteLLM
  - Проверьте логи в веб-интерфейсе LiteLLM

===== Контакты поддержки =====

  * **GitHub Issues:** https://github.com/BerriAI/litellm/issues
  * **Документация:** https://docs.litellm.ai/
  * **Community:** https://discord.gg/litellm