Самостоятельный хостинг AI-шлюз Docker Эксплуатация Совместимость с OpenAI

Самостоятельно размещаемый LLM API-шлюз: архитектура и эксплуатация

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

AveMujica API 15 июл. 2026 г. 8 мин чтения

Самостоятельно размещаемый LLM API-шлюз — это программное обеспечение, которое вы запускаете в собственной сети или облачной учётной записи. Оно принимает OpenAI-совместимые запросы, аутентифицирует вызывающие приложения, направляет трафик к одному или нескольким upstream-провайдерам моделей и записывает использование для эксплуатации и контроля затрат. В отличие от простого обратного прокси, это контрольная плоскость: ключи, псевдонимы моделей, учётные данные каналов, квоты и история запросов находятся рядом с путём обработки запросов. В статье объясняется, когда самостоятельный хостинг оправдан, какой архитектуры ожидать от Go-шлюза наподобие этого репозитория и как эксплуатировать его, не превращая доступ к моделям в бесхозный чёрный ящик.

Если вы всё ещё выбираете между тонким промежуточным узлом и контрольной плоскостью, сначала прочитайте статью LLM-прокси и AI-шлюз. Далее предполагается, что вам уже нужны обязанности полноценного шлюза и развёртываемая базовая конфигурация.

Когда самостоятельный хостинг следует выбирать по умолчанию

Размещайте шлюз самостоятельно, если выполняются как минимум два из следующих условий:

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

Самостоятельный хостинг — неверный выбор по умолчанию, если единственный прототип использует один ключ и одну модель и не имеет требований к аудиту. В таком случае обращайтесь к провайдеру напрямую или используйте тонкий прокси, пока не возникнет потребность в контрольной плоскости.

Эталонная архитектура

Clients (apps, agents, eval jobs)
        |
        |  HTTPS + Bearer gateway key
        v
 Self-hosted AI gateway
   - OpenAI-compatible API (/v1/chat/completions, /v1/responses, ...)
   - Admin API for users, tokens, channels
   - Usage logs, dashboard, pricing context
        |
        +--> Channel: OpenAI
        +--> Channel: Anthropic / Claude (native Messages adaptation)
        +--> Channel: Gemini
        +--> Channel: Azure / Bedrock / others
        |
        v
 Your datastore (SQLite / MySQL / PostgreSQL)
 optional Redis for cache and rate limiting

Клиенты продолжают использовать OpenAI SDK или обычный HTTP. Разнообразие upstream-провайдеров становится конфигурацией, а не новым SDK для каждого из них. Это то же преимущество, что даёт OpenAI-совместимый API-шлюз, но дополнительно вы отвечаете за доступность и резервные копии.

Что обычно включает шлюз с архитектурой этого репозитория

Этот проект представляет собой самостоятельно размещаемый Go-шлюз и систему управления AI-ресурсами. Для планирования важны следующие возможности, видимые в репозитории:

OpenAI-совместимые relay-endpoint для чата и связанных поверхностей
настройка каналов для нескольких провайдеров
управление пользователями и токенами с ограниченной областью доступа
журналы использования и операционные панели
встроенный в сервис веб-интерфейс администрирования
SQLite для простых развёртываний; MySQL или PostgreSQL для долговечной многопользовательской production-среды
пути развёртывания через Docker с опубликованным образом calciumion/new-api

Не приписывайте проекту сертификаты соответствия или SLA, которые нигде не заявлены. Перед обещаниями заинтересованным сторонам проверьте нужный набор функций в UI и API именно той версии, которую запускаете.

Проверенный минимальный путь с Docker

Репозиторий содержит настоящий docker-compose.yml, который запускает шлюз вместе с PostgreSQL и Redis. Это предпочтительная отправная точка для многопользовательского staging-окружения. Краткий путь из README проекта:

docker pull calciumion/new-api:latest
# from a checkout that includes docker-compose.yml
docker compose up -d
# gateway listens on http://localhost:3000 by default

Основная форма сервиса выглядит так (фрагмент compose-файла репозитория; используйте полный файл с сервисами Redis/Postgres, healthcheck и комментариями):

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    command: --log-dir /app/logs
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      # Change passwords before any shared or production use.
      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://:123456@redis:6379
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true
      - BATCH_UPDATE_ENABLED=true
      - NODE_NAME=new-api-node-1
    depends_on:
      - redis
      - postgres

Замечания по эксплуатации, которые не дают этому примеру создать ложное ощущение безопасности:

Пароли compose по умолчанию (123456) предназначены только для локального запуска. Смените их до использования в любой общей среде.
В регулируемых окружениях предпочитайте закреплённые digest образов плавающему тегу :latest, который используется в документации.
Для одноузлового эксперимента с SQLite README также описывает запуск контейнера с подключённым томом /data и без SQL_DSN. Считайте это компактным вариантом, а не production-конфигурацией с несколькими писателями.
Размещайте завершение TLS на входном уровне: nginx, Caddy, облачном балансировщике нагрузки или Traefik. Не открывайте пути административного UI в публичный интернет без дополнительного контроля доступа.
После первого входа храните ключи API провайдеров в настройках каналов или менеджере секретов, а не в git.

Если Docker Compose нельзя использовать без изменений из-за изолированных реестров или собственного оркестратора, рассматривайте фрагмент как проверенную основу для переноса, а не как необязательный псевдокод. Имя образа, порт, том и переменные SQL_DSN выше соответствуют опубликованной документации по развёртыванию этого репозитория.

Контрольный список настроек на первую неделю

1. Идентификация и ключи

создайте административных пользователей с надёжной аутентификацией
выдавайте каждому сервису отдельный токен с минимальной областью моделей
разделяйте ключи staging и production
документируйте владельца ротации

2. Каналы

В разделе настройки каналов административного UI:

создавайте один канал на каждую границу upstream-учётных данных
указывайте явные базовые URL для Azure и региональных endpoint
после смены учётных данных выполняйте healthcheck или ручной smoke-тест
никогда не используйте один неограниченный upstream-ключ для недоверяющих друг другу арендаторов

3. Каталог и контекст цен

публикуйте стабильные псевдонимы моделей (claude-sonnet, gemini-flash, gpt-...), от которых зависят приложения
сопоставляйте псевдонимы с текущими upstream ID, например с моделями класса Claude Sonnet 5 / Opus 4.8 и Gemini 3.5 Flash, указанными поставщиками на момент переключения
пересматривайте контекст цен при изменении псевдонимов по умолчанию

4. Наблюдаемость

включите журналы использования для тарифицируемых маршрутов
подтвердите сроки хранения журналов и пути экспорта
создайте оповещения по частоте ошибок и скорости расходов, а не только по CPU

5. Резервные копии

автоматизируйте резервное копирование базы данных: дампы PostgreSQL/MySQL или снимки томов
до первого настоящего инцидента проверьте восстановление на пустом хосте
храните ключи шифрования резервных копий вне контейнера шлюза

Модель безопасности самостоятельно размещаемой контрольной плоскости

Угрозы, которые нужно учитывать при проектировании

кража ключей шлюза, позволяющих расходовать бюджет провайдеров
открытый в публичный интернет административный UI
журналы промптов и инструментов, содержащие секреты клиентов
SSRF-подобные базовые URL каналов, если операторы могут направлять каналы на внутренние endpoint метаданных
фиксация сессии между несколькими узлами, если в кластере оставлено значение SESSION_SECRET по умолчанию

Средства контроля, которые действительно помогают

TLS на границе и частный административный доступ через VPN, SSO или списки разрешённых IP
отдельные ключи для каждого приложения и списки разрешённых моделей для пакетных ключей
секреты провайдеров только на шлюзе
квоты для каждого ключа, способного запускать инструменты или длинные контексты
политики маскирования для экспорта журналов использования
заданный SESSION_SECRET при многозвенном развёртывании; см. комментарии compose в репозитории

Если агенты могут автоматически вызывать инструменты, ознакомьтесь с OWASP Top 10 для LLM-приложений. Самостоятельный хостинг не устраняет риск чрезмерной самостоятельности, а лишь меняет место применения контроля.

Политика маршрутизации как конфигурация

Описывайте политику маршрутизации в конфигурации:

псевдоним модели по умолчанию для каждого продукта
резервный псевдоним для временных upstream-ошибок
закреплённый псевдоним для регулируемых или чувствительных к оценке потоков
явный запрет моделей, к которым конкретный ключ не должен обращаться никогда

Сочетайте маршрутизацию со стратегией failover для LLM API, чтобы не повторять наивно запросы после сбоев посреди потока. Для агентов с инструментами сохраняйте портативность схем, как описано в статье о портативном вызове инструментов между провайдерами.

Ресурсы, базы данных и Redis

Масштаб	База данных	Примечания
Один пользователь / небольшая команда	SQLite	Просто, подключите постоянный том
Production для нескольких команд	MySQL ≥ 5.7.8 или PostgreSQL ≥ 9.6	Лучшая параллельность и инструменты эксплуатации
Горячие пути rate-limit / cache	Redis по желанию	Используйте, когда ограничений внутри процесса недостаточно

Рассчитывайте CPU и память по числу одновременных потоков, а не по нагрузке простаивающего административного UI. Потоковые ответы долго удерживают соединения открытыми; если клиенты используют streaming, нагрузочные тесты должны включать трафик в стиле SSE.

Обновления и управление изменениями

Прочитайте примечания к выпуску об изменениях каналов и биллинга.
Разверните версию на staging с конфигурацией каналов, близкой к production.
Выполните smoke-тесты через curl для /v1/chat/completions и всех используемых сценариев /v1/responses.
На canary-ключе проверьте приём журналов и поведение кошелька и квот.
Выполняйте обновление, сохранив известный предыдущий образ для отката.
После обновления повторно проверьте псевдонимы моделей на соответствие переименованиям upstream.

Никогда не объединяйте миграции базы данных, ротацию учётных данных провайдеров и изменение политики маршрутизации в одном необслуживаемом окне.

Smoke-тесты после каждого развёртывания

curl -sS https://gateway.example.com/v1/models \
  -H "Authorization: Bearer $GATEWAY_API_KEY" | head

curl -sS https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 16
  }'

Если эти каналы входят в область развёртывания, добавьте один псевдоним Claude, например claude-sonnet → текущий Claude ID, и один псевдоним Gemini: gemini-flash → gemini-3.5-flash или его преемник. До объявления развёртывания исправным убедитесь, что записи появились в журналах использования.

Контроль затрат без отказа от самостоятельного хостинга

Самостоятельный хостинг не означает отсутствие ограничений. Настройте:

квоты для каждого ключа и каждой группы
списки разрешённых моделей, запрещающие пакетным ключам флагманские модели
оповещения о скорости расходов на основе экспорта журналов или проверок панели
использование более дешёвых моделей по умолчанию в заданиях оценки

При изменении псевдонимов по умолчанию проверяйте публичный контекст цен. Самостоятельно размещаемый шлюз, который не может ответить на вопросы о стоимости, становится общей ответственностью и риском.

Когда вместо этого следует выбрать управляемый хостинг

Оставайтесь на управляемой или гибридной модели, если:

у вас нет дежурной команды для зависимости уровня tier-0
вы не можете выполнить обязательства по резервному копированию и восстановлению
закупочная политика предпочитает контрольную плоскость под управлением поставщика
команде нужен только промежуточный узел для секрета одного провайдера

В любом случае клиенты приложений могут оставаться OpenAI-совместимыми. Режим хостинга не должен вынуждать переписывать клиент.

Официальные источники и материалы проекта

Раздел развёртывания в README проекта (docker pull calciumion/new-api:latest, docker-compose.yml)
OWASP Top 10 для LLM-приложений
Справочник OpenAI API
Документация Docker

Последняя проверка: 2026-07-15. Проверяйте теги образов, переменные окружения и пути UI по версии, которую действительно развёртываете.

Частые вопросы

Самостоятельно размещаемый LLM-шлюз — это то же самое, что самостоятельный хостинг моделей?

Нет. Большинство самостоятельно размещаемых шлюзов по-прежнему обращаются к размещённым API провайдеров. Вы размещаете контрольную плоскость — аутентификацию, маршрутизацию и журналы, — но не обязательно веса моделей. Самостоятельный хостинг моделей с открытыми весами требует отдельного GPU-стека.

Можно ли начать с SQLite, а затем перейти на PostgreSQL?

Для многих развёртываний да, но планируйте миграцию заранее, а не обнаруживайте конкуренцию блокировок во время инцидента. Используйте SQLite для небольшого масштаба и переходите дальше, когда этого потребуют параллельные записи и инструменты резервного копирования.

Как выглядит минимальная безопасная конфигурация?

TLS на границе, частный административный доступ, отдельные ключи для каждого приложения, секреты провайдеров только на шлюзе, включённые журналы использования и квоты для каждого ключа, способного запускать инструменты или длинные контексты.

Как не превратить шлюз в единую точку отказа?

Когда важна доступность, запускайте как минимум два экземпляра приложения за балансировщиком нагрузки, используйте внешнюю базу данных, проверяйте восстановление и документируйте failover каналов. Шлюз должен уменьшать радиус воздействия сбоев провайдеров, а не создавать ещё более опасную точку отказа.

На какой endpoint следует направлять новые клиенты?

Для широкой совместимости клиентов предпочитайте OpenAI-совместимый корень /v1 шлюза и /v1/chat/completions. Используйте /v1/responses только тогда, когда продукт намеренно зависит от этой поверхности, а версия шлюза поддерживает нужные рабочие процессы.

Переключение на staging

Разверните staging-шлюз с compose-файлом репозитория или эквивалентными образом и SQL_DSN, выдайте ключ с ограниченной областью одному некритичному сервису и проверьте chat completions, журналы использования и восстановление резервной копии до подключения второго провайдера или production-трафика. После успешного первого canary используйте настройки каналов, каталог моделей и историю использования как ежедневный операционный цикл.