Што се променливи на околината и тајни? Едноставен водич

Една променлива на околината (environment variable) е именувана поставка — како DATABASE_URL или STRIPE_SECRET_KEY — која се предава на вашата апликација при нејзино извршување, наместо да биде запишана во кодот. Тајна е променлива на околината чија вредност мора да остане приватна: API клуч, лозинка или клуч за потпишување. Со чување на овие вредности надвор од кодот можете да ги менувате без уредување на апликацијата, да користите различни за тестирање и за вистинските корисници и да спречите да процуреат кога го споделувате или објавувате вашиот код.

Зошто е важно кога градите со вештачка интелигенција

Во мигот кога вашата апликација прави нешто корисно со друга услуга — прима плаќање, испраќа е-пошта, повикува модел на вештачка интелигенција — ѝ треба клуч. Градителите на апликации со вештачка интелигенција редовно бараат такви клучеви, а каде завршува клучот ја одредува безбедноста на вашата апликација.

Две работи најчесто одат наопаку кај апликациите изградени со вештачка интелигенција:

• Клучот е залепен во разговорот или во кодот. Тогаш живее во историјата на разговорот, во датотеките на проектот и во секој извоз или репозиториум. Секој што ќе ги види може да ја користи вашата сметка.
• Клучот се користи во прелистувачот. Ако кодот што ги повикува 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: текстуална датотека со редови NAME=value, која се користи при локален развој. Додајте ја во .gitignore за да не се додава во git.
• .env.example: копија со имињата, но без вистински вредности, која се додава во репозиториумот за другите да знаат кои променливи да ги постават.
• Ротирај: замени тајна со нова и повлечи ја старата.
• Опсег / дозволи: многу провајдери дозволуваат создавање клучеви кои можат да прават само одредени работи. Клуч кој може само да испраќа е-пошта е помалку опасен од оној кој може сè.
• Тест наспроти живи клучеви: провајдери како Stripe даваат одделни клучеви за тестирање и за вистински пари. Користете тест клучеви додека не ја лансирате апликацијата.
• Тајна за потпишување: тајна што се користи за проверка дали порака, како webhook, навистина доаѓа од испраќачот.

Чести грешки и погрешни претстави

• „Репозиториумот ми е приватен, па клучевите во него се во ред.“ Приватните репозиториуми се споделуваат, се форкуваат, се извезуваат и се клонираат на лаптопи. Клучевите и таму не припаѓаат. Ако го поврзете проектот со GitHub, проверете дали се вклучува некоја датотека .env.
• „Ја избришав, значи нема ја повеќе.“ Git-от ја чува историјата, а записите од разговорот ги чуваат пораките. Ако клучот некогаш бил изложен, ротирајте го.
• Користење јавен префикс на тајна. VITE_OPENAI_KEY го става вашиот клуч во пакетот за прелистувачот.
• Заборавање на повторно објавување. Промената на променлива во поставките обично стапува на сила откако апликацијата ќе се рестартира или повторно објави.
• Еден клуч за сè. Одделни клучеви за тест и за живо, и по апликација, овозможуваат да се повлече еден без да се прекине остатокот.
• Без лимит на трошење. За платени API-ја, поставете буџет или лимит во контролната табла на провајдерот, за случај клучот да процуре.

Што да побарате од вашиот AI градител

• „Прочитај го тајниот клуч на Stripe од променлива на околината именувана STRIPE_SECRET_KEY. Користи го само на серверот.“
• „Осигурај се дека ниедна тајна не се користи во кодот на клиентската страна и не добива префикс VITE_ / NEXT_PUBLIC_.“
• „Создај .env.example со сите променливи што ги бара апликацијата, без вредности, и осигурај се дека .env е игнориран од git.“
• „Провери ги изградените фронтенд датотеки за секоја низа што личи на API клуч.“

Нашата листа за безбедност за апликации изградени со вештачка интелигенција ги опфаќа тајните заедно со другите проверки што вредат пред лансирање.

Тајни на Mythex

Во Mythex, тајните се променливи на околината на проектот кои се вметнуваат и во прегледот на sandbox и во вашата објавена апликација. Ги додавате под поставки на проектот → Тајни или со /secrets во разговорот, а кога агентот ќе има потреба од клуч, прикажува картичка со тајни во разговорот, па вредноста оди во поле на формуларот, а не во текстот на пораката. Ако промените тајна за жива апликација, повторно објавете ја за да ја земе промената. Извозите на проектот ги исклучуваат тајните, а увезените .env датотеки се исчистуваат, па ги додавате повторно во поставките. Видете променливи на околината и тајни и тајни во разговор во документацијата.

Прашања