Безопасность интеграции

OpenAI API key в Docker Compose: безопасная настройка

OpenAI API key в Docker Compose следует передавать контейнеру только при запуске, а не записывать в образ, исходный код или браузер. Для OpenAI-совместимого API принцип тот же: собственный ключ RussiaAPI хранится в защищённой переменной или менеджере секретов, приложение читает его на сервере, а журнал содержит лишь безопасные метаданные.

Опубликовано 21 августа 2026 · 11 минут чтения · Ключевой запрос: OpenAI API key в Docker Compose

Короткий ответ: секрет приходит на runtime

Compose удобен тем, что описывает запуск приложения рядом с инфраструктурой. Он опасен, когда удобство превращают в публикацию секрета: вставляют ключ после environment:, добавляют его в Dockerfile или оставляют в примере для команды. Любой из этих способов может оказаться в Git, в истории образа, в резервной копии, в выводе CI или на скриншоте. Нужный принцип проще: compose-файл указывает имя переменной, а значение поставляет защищённый контур запуска.

Это не обещание, что любой механизм Docker сам по себе делает секрет безопасным. Риски зависят от того, кто имеет доступ к хосту, журналам, CI и резервным копиям. Но отделение конфигурации от значения уменьшает область утечки и позволяет заменить ключ без переписывания образа. Отдельный ключ для development, staging и production помогает локализовать инцидент. Не используйте один production-ключ на ноутбуке «для быстрого теста».

Чего не должно быть в репозитории и образе

Не добавляйте значение API key в docker-compose.yml, compose.yaml, Dockerfile, аргументы сборки, frontend-конфигурацию, README или пример curl. Build argument особенно коварен: он может сохраниться в истории сборки или диагностике. Base64 тоже не помогает — это кодирование, а не шифрование. Удаление строки в последнем коммите не отменяет копии в истории и кэшах; если секрет уже попал туда, его отзывают.

Не передавайте ключ клиентскому JavaScript. Браузер пользователя, мобильный клиент и расширение редактора не являются секретным хранилищем. Пусть интерфейс обращается к вашему серверному маршруту, где есть аутентификация, ограничение входных данных, тайм-аут и понятная обработка ошибок. Общая архитектура OpenAI-совместимого подключения разобрана в руководстве по первому запросу; детали 401 и 403 — в безопасной диагностике доступа.

Минимальный compose-файл без значения ключа

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

services:
  api:
    image: registry.example.invalid/my-api:2026-08-21
    environment:
      RUSSIAAPI_API_KEY: ${RUSSIAAPI_API_KEY:?set at runtime}
      RUSSIAAPI_BASE_URL: ${RUSSIAAPI_BASE_URL:-https://russiaapi.com/v1}
      RUSSIAAPI_MODEL: ${RUSSIAAPI_MODEL:?select from current catalog}
    ports:
      - "127.0.0.1:3000:3000"

Строка с ${RUSSIAAPI_API_KEY} не хранит секрет, но её безопасность зависит от источника переменной. На рабочей машине значение можно кратко задать в сессии терминала или в исключённом из Git локальном файле. В production источник должен быть управляемым секретным хранилищем вашей платформы или оркестратора. Перед запуском убедитесь, что shell history, CI trace и диагностика не печатают окружение целиком.

Почему .env — не универсальное решение

Файл .env сокращает ручной ввод, но не превращается от этого в менеджер секретов. Для локальной разработки допустим отдельный .env, если он перечислен в .gitignore, защищён правами файловой системы и никогда не вкладывается в архив проекта. Добавьте рядом только .env.example без значений: например, RUSSIAAPI_API_KEY= и RUSSIAAPI_MODEL=. Тогда коллега видит обязательные имена, но не получает чей-то доступ.

На сервере проверьте цепочку целиком: provisioner, CI, compose, процесс приложения, логи, бэкап томов и support bundle. Нельзя считать файл безопасным, если его забирает автоматический бэкап или он доступен всем пользователям хоста. Docker Compose поддерживает несколько способов задания переменных, однако удобство не заменяет модель доступа. Для особо чувствительных сред применяйте нативный механизм секретов выбранной платформы и документируйте владельца, срок ротации и аварийный отзыв.

Приложение должно падать безопасно

В коде проверьте наличие обязательных переменных до первого сетевого вызова. Не подставляйте тестовый ключ по умолчанию и не пишите объект конфигурации целиком при ошибке. Логируйте только окружение как метку, версию приложения, время, код ответа, длительность и request ID, если он доступен. Полный заголовок Authorization, prompt, cookie и экспорт переменных не должны попасть в наблюдаемость.

const key = process.env.RUSSIAAPI_API_KEY;
const model = process.env.RUSSIAAPI_MODEL;
if (!key || !model) throw new Error('API configuration is incomplete');

// key is passed only to the server-side client; never log it
logger.info({ env: process.env.NODE_ENV, model }, 'AI client configured');

Не включайте бесконечный retry ради «надёжности». Ошибка конфигурации, 401 или 403 обычно требуют исправления доступа, а не повторения с тем же секретом. Для временного ограничения частоты применяйте ограниченные повторы с backoff и budget — это отдельная задача, описанная в статье про 429 и retry. При нескольких провайдерах заранее тестируйте контракт и rollback, а не предполагаете одинаковость моделей и форматов.

Проверка запуска без раскрытия секрета

1. Проверьте, что compose-файл содержит лишь имена переменных, а .env не отслеживается Git.
2. Запускайте health-check с отдельным собственным ключом нужного окружения; не копируйте его в команду, тикет или скриншот.
3. Сверьте доступные модели и параметры по текущим данным каталога, затем выполните минимальный серверный запрос с синтетическим текстом.
4. Убедитесь, что журналы содержат код результата и request ID, но не Authorization и не полный ввод пользователя.
5. Проверьте, что перезапуск с обновлённым секретом не требует пересборки образа и старый ключ можно отозвать.

Нельзя подтвердить безопасность одной успешной командой. Нужна повторяемая процедура: владелец знает, где хранится значение, кто может его изменить, как выглядит безопасная проверка и как остановить доступ. Документируйте эти факты без самого секрета. Для более широкой модели хранения и CI/CD используйте наш материал «Как хранить API Key для нейросетей».

Ротация и инцидент

Если ключ появился в CI-логе, pull request, образе или чужом чате, рассматривайте его как скомпрометированный. Сначала отзовите этот конкретный собственный ключ в консоли. Затем создайте замену для затронутого окружения, обновите секретное хранилище, перезапустите только необходимый сервис и сделайте короткую серверную проверку. Сохраните для расследования время, окружение, владельца и request ID — не значение ключа.

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

FAQ

Читайте также

• Как безопасно хранить API Key
• Ротация API Key без простоя
• Подключение OpenAI-совместимого API
• Документы RussiaAPI