Що таке змінні середовища та секрети? Простий посібник

Змінна середовища — це іменоване налаштування, як-от 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: текстовий файл із рядками NAME=value, який використовується під час локальної розробки. Додайте його до .gitignore, щоб він не потрапляв у коміти.
• .env.example: копія без реальних значень, лише з іменами, яку комітять, щоб інші знали, які змінні треба задати.
• Ротація: заміна секрету новим із відкликанням старого.
• Область дії / дозволи: багато провайдерів дозволяють створювати ключі, які можуть робити лише певні речі. Ключ, що може лише надсилати листи, менш небезпечний, ніж той, що може все.
• Тестові та бойові ключі: провайдери на кшталт 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 очищуються, тож їх треба додати знову в налаштуваннях. Див. змінні середовища та секрети і секрети в чаті у документації.

Запитання