Что такое переменные окружения и секреты: простое руководство

Переменная окружения — это именованная настройка, например DATABASE_URL или STRIPE_SECRET_KEY, которую передают приложению при запуске, а не записывают прямо в код. Секрет — это переменная окружения, значение которой должно оставаться закрытым: ключ API, пароль, ключ подписи. Когда такие значения хранятся вне кода, их можно менять, не редактируя приложение, использовать разные значения для тестов и для реальных клиентов и не допустить их утечки при передаче или публикации кода.

Почему это важно при создании с ИИ

Как только приложение начинает делать что-то полезное с другим сервисом — принимает оплату, отправляет письма, обращается к модели ИИ, — ему нужен ключ. Конструкторы приложений на основе ИИ регулярно запрашивают такие ключи, и от того, где окажется ключ, зависит безопасность приложения.

В приложениях, созданных с ИИ, обычно случаются две ошибки:

• Ключ вставлен в чат или в код. Тогда он попадает в историю чата, в файлы проекта и в любой экспорт или репозиторий. Любой, кто его увидит, может пользоваться вашим аккаунтом.
• Ключ используется в браузере. Если код, который обращается к Stripe или OpenAI, выполняется на странице, ключ отправляется каждому посетителю. Люди действительно это проверяют, а автоматические сканеры постоянно ищут открытые ключи.

Понимание переменных окружения помогает заметить обе ошибки и попросить об исправлении.

Бытовая аналогия: сейф в гостиничном номере

Код вашего приложения — это гостиничный номер. По нему ходят гости (и уборщики, и все, кому вы дали карту-ключ). Паспорт на столе вы бы не оставили.

Переменные окружения — это сейф в номере. Номер знает, что сейф есть и как его открыть, когда нужно, но паспорт не лежит на виду. А если вы переезжаете из одного номера в другой, например из тестовой среды на живой сайт, вы кладёте в сейф другой паспорт и не перестраиваете сам номер.

Как это работает

Ваш код обращается к имени, а не к значению. На сервере на JavaScript это выглядит как process.env.STRIPE_SECRET_KEY. Когда приложение запускается, платформа, на которой оно работает, подставляет значение для этого имени. Вы меняете значение в настройках платформы, перезапускаете или выпускаете приложение заново — и оно начинает использовать новое значение без изменения кода.

Откуда берутся значения, зависит от того, где работает приложение:

Публичные и секретные переменные

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

Веб-фреймворки делают это разделение явным. В Vite в код для браузера попадают только переменные, имена которых начинаются с VITE_; в Next.js префикс — NEXT_PUBLIC_. Это защитная функция: всё с такими префиксами оказывается в файлах, которые загружает каждый посетитель, поэтому секрету ни в коем случае нельзя давать такой префикс.

Практический пример: кнопка «Кратко изложить»

Вам нужна кнопка «Кратко изложить эту заметку», которая обращается к модели ИИ.

Небезопасный вариант: код кнопки, работающий в браузере, напрямую обращается к провайдеру ИИ, а ключ API прописан прямо в коде. В превью всё работает. Но любой может открыть инструменты разработчика, скопировать ключ и потратить деньги с вашего аккаунта.

Безопасный вариант:

1. Вы создаёте ключ у провайдера ИИ и сохраняете его как секрет с именем OPENAI_API_KEY (или похожим) в настройках проекта.
2. В бэкенде появляется маршрут POST /api/summarise, который читает process.env.OPENAI_API_KEY, проверяет, что пользователь вошёл в систему, и обращается к провайдеру.
3. Кнопка обращается к вашему маршруту, а не к провайдеру. Браузер никогда не видит ключ.
4. Вы добавляете тот же секрет в настройки опубликованного приложения и выпускаете его заново, чтобы у живого сайта тоже был ключ.

Этот шаблон — браузер обращается к вашему серверу, а сервер хранит ключ и обращается к сервису — подходит для платежей, почты, карт и любого другого платного API. Руководство по использованию LLM API подробнее разбирает случай с ИИ.

Ключевые термины

• Файл .env: текстовый файл со строками вида ИМЯ=значение, который используется при локальной разработке. Добавьте его в .gitignore, чтобы он не попадал в коммиты.
• .env.example: копия без настоящих значений — только имена; её коммитят, чтобы другие знали, какие переменные нужно задать.
• Ротация: замена секрета новым и отзыв старого.
• Область действия (scope) / права: многие провайдеры позволяют создавать ключи, которые умеют делать только определённые вещи. Ключ, который может только отправлять письма, менее опасен, чем ключ с полным доступом.
• Тестовые и боевые ключи: провайдеры вроде Stripe выдают отдельные ключи для тестов и для реальных денег. До запуска используйте тестовые ключи.
• Секрет подписи: секрет, с помощью которого проверяют, что сообщение, например вебхук, действительно пришло от отправителя.

Частые ошибки и заблуждения

• «Репозиторий приватный, значит, ключи в нём безопасны». Приватные репозитории тоже передают, форкают, экспортируют и клонируют на ноутбуки. Ключам там не место. Если вы подключаете проект к GitHub, проверьте, что в него не попал файл .env.
• «Я удалил, значит, его больше нет». Git хранит историю, а чаты хранят сообщения. Если ключ когда-либо попадал наружу, его нужно заменить.
• Публичный префикс у секрета. VITE_OPENAI_KEY помещает ваш ключ в сборку для браузера.
• Забыли выпустить приложение заново. Изменение переменной в настройках обычно вступает в силу только после перезапуска приложения или его новой публикации.
• Один ключ на всё. Отдельные ключи для тестов и боевого режима и для каждого приложения позволяют отозвать один ключ, не сломав остальные.
• Нет лимита расходов. Для платных API задайте бюджет или лимит в панели провайдера на случай утечки ключа.

Что попросить у конструктора на основе ИИ

• «Считывай секретный ключ Stripe из переменной окружения STRIPE_SECRET_KEY. Используй его только на сервере.»
• «Убедись, что ни один секрет не используется в клиентском коде и не получает префикс VITE_ или NEXT_PUBLIC_.»
• «Создай .env.example со всеми переменными, которые нужны приложению, без значений, и убедись, что .env игнорируется git.»
• «Проверь собранные файлы фронтенда на строки, которые похожи на ключи API.»

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

Секреты в Mythex

В Mythex секреты — это переменные окружения проекта, которые передаются и в превью-песочницу, и в опубликованное приложение. Их добавляют в настройках проекта → Secrets или командой /secrets в чате. Когда агенту нужен ключ, он показывает в чате карточку секретов, так что значение вводится в поле формы и не попадает в текст переписки. Если вы меняете секрет для живого приложения, опубликуйте его заново, чтобы деплой его подхватил. Экспорт проекта секреты не включает, а импортированные файлы .env очищаются, поэтому их нужно добавить заново в настройках. Подробнее в документации: переменные окружения и секреты и секреты в чате.

Вопросы