LiteLLM прокси настройка: свой шлюз с вашими API-ключами

LiteLLM прокси настройка собирает API-ключи, которые у вас уже есть от поставщиков моделей, за одной OpenAI-совместимой точкой доступа, доступной только вашим приложениям. Шлюз запускается через Docker Compose на закрепленном выпуске, каждое приложение получает виртуальный ключ со своим бюджетом, а сам шлюз остается вне публичного интернета.

Ключевые выводы:

• Используйте только собственные официальные API-ключи поставщиков; не перепродавайте и не раздавайте доступ к шлюзу.
• Закрепите образ на теге выпуска и храните секреты в защищенном файле .env.
• Виртуальные ключи, бюджеты и лимиты по ключам требуют базы Postgres.
• Публикуйте порт на 127.0.0.1 и подключайтесь через SSH или обратный прокси с TLS.
• Резервируйте .env вместе с базой: потеря salt-ключа делает сохраненные учетные данные нечитаемыми.

Что шлюз LiteLLM умеет, а чего нет?

Шлюз LiteLLM предоставляет OpenAI-совместимый API, поэтому на него можно направить любой OpenAI SDK. Виртуальные ключи выдаются приложениям вместо исходных ключей поставщиков, и у каждого может быть свой бюджет, лимиты запросов и доступ к моделям.［1］ Инструкция основана на перечисленных ниже официальных источниках; полный сквозной тест не выполнялся. Она рассчитана на LiteLLM v1.105.1, в примечаниях к выпуску которого указан образ ghcr.io/berriai/litellm:v1.105.1.［2］

Шлюз не создаст доступ к поставщику, которого у вас нет, не снимет его лимиты и не изменит его условия. Это и не способ добраться до ИИ-инструментов из сети с ограничениями: если Cursor или Copilot вообще не подключаются, сначала найдите причину сбоя подключения, а не добавляйте еще один слой.

Держите рамки узкими. Используйте только API-ключи, выданные лично вам через официальную платформу разработчиков каждого поставщика, — для своих приложений или своей организации. Не перепродавайте доступ, не передавайте виртуальные ключи посторонним и не превращайте веб-сеанс потребительского чата в API; запросы через шлюз остаются вашим использованием по правилам каждого поставщика, например по правилам использования OpenAI.［3］

Какое место выбрать, если нужна LiteLLM прокси настройка?

Сервер, который вы обслуживаете, остается сервером: здесь действуют компромиссы самостоятельного хостинга, а арендованный VPS — не то же самое, что VPN-сервис, как объясняет материал о различиях VPS и VPN-сервиса.

Место	Подходит для	Главный риск
Ваша рабочая машина	Один разработчик, локальные инструменты	Шлюз останавливается, когда машина спит
Домашний сервер в локальной сети	Несколько ваших устройств	Ошибки проброса портов открывают его
VPS	Постоянно работающие ваши приложения	Публичный IP: никогда не открывайте порт 4000

Шаг 1: Подготовьте узел и защищенные секреты

Установите Docker Engine с плагином Compose и создайте рабочий каталог. Официальное быстрое руководство генерирует мастер-ключ и salt-ключ командой openssl rand -hex 32; этот вариант дополнительно генерирует пароль базы данных:［1］

mkdir -p ~/litellm && cd ~/litellm
umask 077
printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\nPOSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" > .env
ls -l .env

Откройте .env в редакторе и добавьте строки OPENAI_API_KEY= и ANTHROPIC_API_KEY= со своими ключами; ввод в редакторе не оставляет их в истории оболочки. Мастер-ключ — это корневые учетные данные, которые разрешают управляющие вызовы и вход в Admin UI, поэтому обращайтесь с ним как с паролем root.［1］ Руководство по эксплуатации требует, чтобы он начинался с sk-.［4］

Шаг 2: Напишите закрепленный файл LiteLLM Docker Compose

Файл compose из быстрого руководства использует плавающий тег и, если не указано иное, публикует порт 4000 на всех интерфейсах; за пределами локальной пробы руководство советует закрепить тег выпуска.［1］ Сохраните это как compose.yaml:

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.105.1
    command: ["--config", "/app/config.yaml"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    environment:
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?set in .env}
      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?set in .env}
      DATABASE_URL: postgresql://litellm:${POSTGRES_PASSWORD:?set in .env}@db:5432/litellm
      OPENAI_API_KEY: ${OPENAI_API_KEY:?set in .env}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?set in .env}
      LITELLM_MODE: PRODUCTION
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Docker предупреждает, что опубликованные порты по умолчанию доступны извне узла; указание 127.0.0.1 ограничивает порт самим узлом Docker.［5］ Значение PRODUCTION в LITELLM_MODE не дает LiteLLM самостоятельно загружать локальный .env.［4］ Удалите строку поставщика, которым не пользуетесь.

Шаг 3: Перечислите модели в config.yaml

В config.yaml поле model_name — это имя, которое отправляют ваши приложения, а litellm_params.model — модель поставщика, которую вызывает шлюз.［6］ Замените заполнители идентификаторами моделей из актуальной документации ваших поставщиков:

model_list:
  - model_name: openai-main
    litellm_params:
      model: openai/<openai-model-id>
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-main
    litellm_params:
      model: anthropic/<anthropic-model-id>
      api_key: os.environ/ANTHROPIC_API_KEY
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  trusted_proxy_ranges: []

Форма os.environ/ читает ключ из окружения контейнера, а модели Anthropic используют префикс anthropic/.［6］［7］ При выключенном store_model_in_db файл остается единственным источником настроек.［6］ Пустой trusted_proxy_ranges подходит, когда клиенты подключаются напрямую; если позже добавите обратный прокси, укажите его диапазон.［4］

docker compose up -d
docker compose ps
docker compose logs --tail 50 litellm

Шаг 4: Выдайте виртуальные ключи LiteLLM с лимитами

Виртуальные ключи требуют базы данных и создаются вызовом /key/generate с мастер-ключом.［8］ Считайте мастер-ключ в переменную без вывода на экран:

read -rs LITELLM_ADMIN && export LITELLM_ADMIN
curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_ADMIN" \
  -H 'Content-Type: application/json' \
  -d '{"models": ["openai-main"], "max_budget": 5, "budget_duration": "30d", "rpm_limit": 20}'

После превышения max_budget запросы по ключу перестают проходить, а budget_duration обнуляет расходы в конце каждого периода; лимит запросов в минуту тоже задается для ключа.［9］ Бюджеты действуют только при наличии базы, поэтому задайте и лимиты расходов в консоли каждого поставщика.［1］ Скопируйте полученный ключ в хранилище секретов приложения; каждому приложению — свой ключ.

Шаг 5: Проверьте обычные вызовы и отказы

read -rs APP_KEY && export APP_KEY
curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "openai-main", "messages": [{"role": "user", "content": "Say hello in five words."}]}'

Эта таблица описывает, что проверять; это не протокол результатов тестирования.

Способ проверки	Ожидаемый результат	Если не получилось
Вызов openai-main с виртуальным ключом	Возвращается ответ чата	Проверьте ключ поставщика и идентификатор модели в журнале
Тот же вызов с выдуманным ключом	Ошибка аутентификации, ответа нет	Убедитесь, что задан master_key и ключ не переиспользуется
Вызов claude-main с этим ключом	Отказ: модели нет в списке ключа	Создайте ключ заново с явным списком models
Превышение лимита запросов ключа	Ошибки до окончания окна	Проверьте, что база подключена
curl на порт 4000 с другого устройства	Соединение отклонено	Исправьте строку ports, оставьте 127.0.0.1

Чтобы отключить утекший ключ, не удаляя его, отправьте его на /key/block с мастер-ключом; /key/unblock отменяет блокировку.［8］

Шаг 6: Подключайтесь к шлюзу с других устройств

Оставьте привязку к localhost. С ноутбука локальный проброс SSH доставляет запросы на loopback-порт сервера: ssh -L 4000:127.0.0.1:4000 user@server. Если не уверены, чем проброс SSH отличается от VPN-туннеля, сравните туннели SSH и VPN.

Для нескольких устройств в локальной сети поставьте перед шлюзом обратный прокси с действительным TLS-сертификатом и ограничьте его межсетевым экраном; никогда не переключайте публикацию на все интерфейсы. Направляйте SDK на проброшенный или проксируемый адрес с виртуальным ключом каждого приложения.

Шаг 7: Обновление, резервное копирование и остановка

Прочитайте примечания к следующему выпуску, смените тег образа, затем выполните docker compose pull и docker compose up -d. В примечаниях к выпускам публикуются команды cosign для проверки подписи образа.［2］

Резервируйте .env и базу вместе, потому что последующая смена LITELLM_SALT_KEY делает сохраненные учетные данные нечитаемыми:［1］

docker compose exec -T db pg_dump -U litellm litellm > litellm-backup.sql
chmod 600 litellm-backup.sql

docker compose down останавливает стек и сохраняет том базы; docker compose down -v удаляет и его, без возможности отмены. Выводя шлюз из работы, отзовите ключи и в консоли каждого поставщика.

Итоги

• Используйте шлюз только для собственных официальных API-ключей и своих приложений.
• Закрепите образ, защитите .env и привяжите порт 4000 к localhost.
• Сопоставьте понятные имена моделей с моделями поставщиков в config.yaml.
• Выдайте каждому приложению виртуальный ключ с моделями, бюджетом и лимитами.
• Перед обновлением или остановкой резервируйте секреты вместе с базой.

Часто задаваемые вопросы (FAQ)

Бесплатно ли размещать LiteLLM у себя?

Шлюз с открытым исходным кодом распространяется по лицензии MIT и бесплатен; за использование API по вашим ключам вы по-прежнему платите поставщикам.

Нужен ли Postgres для простой установки?

Только если не нужны виртуальные ключи и бюджеты. Без базы единственными учетными данными остается мастер-ключ, а бюджеты не применяются.

Можно ли открыть шлюз друзьям?

Не стоит. Передача доступа к вашим ключам поставщиков может нарушать их условия и делает вас ответственным за чужое использование.

Почему мастер-ключ должен начинаться с sk-?

Руководства LiteLLM по виртуальным ключам и эксплуатации требуют префикс sk- для мастер-ключа, так что такой формат избавит от проблем при запуске.

Может ли шлюз обойти региональные ограничения ИИ-сервисов?

Нет. Шлюз пересылает ваши собственные API-запросы; он не меняет доступность поставщика, право на учетную запись и применимые к вам условия.

Что будет, если потерять LITELLM_SALT_KEY?

Учетные данные, сохраненные в базе, станут нечитаемыми, и их придется ввести заново; храните исходный .env вместе с резервными копиями.

Стоит ли открывать порт 4000 на VPS?

Нет. Оставьте его на 127.0.0.1 и используйте проброс SSH или обратный прокси с TLS, доступный только вашим устройствам.

Отказ от ответственности: Это руководство содержит общую техническую информацию по официальной документации и не является юридической консультацией или отчетом о завершенном тестировании. Соблюдайте условия каждого поставщика моделей для используемых API-ключей.

Источники:

1. LiteLLM Docker Quickstart — https://docs.litellm.ai/docs/proxy/docker_quick_start
2. LiteLLM v1.105.1 release — https://github.com/BerriAI/litellm/releases/tag/v1.105.1
3. OpenAI Usage Policies — https://openai.com/policies/usage-policies/
4. LiteLLM Production Best Practices — https://docs.litellm.ai/docs/proxy/prod
5. Docker Port Publishing and Mapping — https://docs.docker.com/engine/network/port-publishing/
6. LiteLLM Proxy Config.yaml — https://docs.litellm.ai/docs/proxy/configs
7. LiteLLM Anthropic Provider — https://docs.litellm.ai/docs/providers/anthropic
8. LiteLLM Virtual Keys — https://docs.litellm.ai/docs/proxy/virtual_keys
9. LiteLLM Budgets and Rate Limits — https://docs.litellm.ai/docs/proxy/users

Sources checked 14 октября 2026 г.

---

Рекомендуемые статьи:

• Разобраться, почему ИИ-инструменты для кода не подключаются
• Выбрать между арендой VPS и VPN
• Сравнить SSH-туннели и VPN