Какво са променливите на средата и тайните? Ясно ръководство

Една променлива на средата (environment variable) е именована настройка — като DATABASE_URL или STRIPE_SECRET_KEY — която се предава на приложението ви при стартиране, вместо да бъде записана в кода. Тайната е променлива на средата, чиято стойност трябва да остане скрита: API ключ, парола или ключ за подписване. Ако държите тези стойности извън кода, можете да ги смените, без да редактирате приложението, да използвате различни за тестване и за реални клиенти и да предотвратите изтичането им, когато споделяте или публикувате кода си.

Защо е важно, когато строите с AI

В мига, в който приложението ви прави нещо полезно с друга услуга — приема плащане, изпраща имейл, извиква AI модел — му е нужен ключ. AI платформите за строене често питат за такива ключове и от това къде попада ключът зависи дали приложението ви е защитено.

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

• Ключът се поставя в чата или в кода. Тогава той остава в историята на чата, във файловете на проекта и във всеки експорт или хранилище. Всеки, който го види, може да ползва акаунта ви.
• Ключът се използва в браузъра. Ако кодът, който извиква Stripe или OpenAI, се изпълнява в страницата, ключът се изпраща на всеки посетител. Хората гледат, а автоматични сканери търсят изложени ключове непрекъснато.

Разбирането на променливите на средата ви помага да забележите и двете и да поискате корекция.

Ежедневна аналогия: хотелският сейф

Кодът на приложението ви е като хотелската стая. Гостите (и чистачите, и всеки, на когото дадете картата си) минават през нея. Не бихте оставили паспорта си на бюрото.

Променливите на средата са сейфът в стаята. Стаята знае, че има сейф, и как да го отвори при нужда, но паспортът не стои навсякъде. А ако се преместите в друга стая — от тестовата среда към сайта за реални клиенти — слагате друг паспорт в сейфа на тази стая, без да преобзавеждате нищо.

Как работи

Кодът ви препраща към име, а не към стойност. В JavaScript на сървър това изглежда така: process.env.STRIPE_SECRET_KEY. Когато приложението стартира, платформата, на която работи, попълва стойността за това име. Смените ли стойността в настройките на платформата и рестартирате или пуснете отново приложението, то ще използва новата — без промяна в кода.

От къде идват стойностите, зависи от мястото, където работи приложението:

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

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

Уеб фреймуърците правят това разделение явно. В Vite в браузърния код се включват само променливи, чиито имена започват с VITE_; в Next.js префиксът е NEXT_PUBLIC_. Това е защитна функция: всичко с тези префикси попада във файловете, които всеки посетител изтегля, затова тайна никога не трябва да получава такъв префикс.

Пример: бутон за AI резюме

Искате бутон „Резюмирай тази бележка“, който извиква AI модел.

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

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

1. Създавате ключа при AI доставчика и го записвате като тайна с име OPENAI_API_KEY (или подобно) в настройките на проекта.
2. Бекендът получава маршрут POST /api/summarise, който чете process.env.OPENAI_API_KEY, проверява дали потребителят е влязъл и извиква доставчика.
3. Бутонът извиква вашия маршрут, а не доставчика. Браузърът никога не вижда ключа.
4. Добавяте същата тайна в настройките на публикуваното приложение и го пускате отново, за да има ключа и публичният сайт.

Този модел — браузърът извиква вашия сървър, а сървърът пази ключа и извиква услугата — важи за плащания, имейл, карти и всеки друг платен API. Ръководството за използване на LLM API разглежда AI случая по-подробно.

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

• Файл .env: текстов файл с редове ИМЕ=стойност, използван при локална разработка. Добавете го в .gitignore, за да не се качва в git.
• .env.example: копие с имената, но без реални стойности, което се качва в git, за да знаят другите кои променливи да зададат.
• Ротация: заменяне на тайна с нова и отмяна на старата.
• Обхват / права: много доставчици позволяват ключове, които могат да правят само определени неща. Ключ, който може само да изпраща имейли, е по-малко опасен от такъв, който може всичко.
• Тестови и реални ключове: доставчици като Stripe дават отделни ключове за тестване и за реални пари. Използвайте тестовите до старта.
• Тайна за подписване: тайна, с която се проверява дали съобщение, например webhook, наистина идва от изпращача.

Чести грешки и заблуди

• „Хранилището е частно, значи ключовете в него са наред.“ Частните хранилища се споделят, разклоняват, експортират и клонират на лаптопи. Ключовете пак не трябва да са там. Ако свържете проект с GitHub, проверете дали в него няма .env файл.
• „Изтрих го, значи го няма.“ Git пази историята, а чатовете пазят съобщенията. Ако ключ някога е бил изложен, сменете го.
• Използване на публичен префикс за тайна. VITE_OPENAI_KEY слага ключа ви в браузърния пакет.
• Забравено повторно пускане. Промяна на променлива в настройките обикновено влиза в сила, след като приложението се рестартира или се публикува отново.
• Един ключ за всичко. Отделните ключове за тест и реална среда и за всяко приложение позволяват да отмените един, без да счупите останалите.
• Без лимит на разходите. При платените API задайте бюджет или лимит в таблото на доставчика, в случай че ключ изтече.

Какво да поискате от AI платформата

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

Нашият контролен списък за сигурност на приложения, строени с AI, обхваща тайните заедно с останалите проверки преди старт.

Тайни в Mythex

В Mythex тайните са променливи на средата на проекта, които се подават както в предварителния преглед, така и в публикуваното ви приложение. Добавяте ги в настройки на проекта → Тайни или с /secrets в чата, а когато агентът има нужда от ключ, показва карта за тайна в чата, така че стойността се въвежда в поле на формуляр, а не в текста на разговора. Ако промените тайна за живо приложение, публикувайте отново, за да я вземе новото внедряване. Експортите на проекти не включват тайни, а импортираните .env файлове се изчистват, така че ги добавяте отново в настройките. Вижте променливите на средата и тайните и тайните в чата в документацията.

Въпроси