Ce sunt variabilele de mediu și secretele? Un ghid simplu

O variabilă de mediu este o setare cu nume — precum DATABASE_URL sau STRIPE_SECRET_KEY — care este transmisă aplicației tale la rulare, în loc să fie scrisă direct în cod. Un secret este o variabilă de mediu a cărei valoare trebuie să rămână privată: o cheie API, o parolă, o cheie de semnare. Ținând aceste valori în afara codului, le poți schimba fără să editezi aplicația, poți folosi valori diferite pentru testare și pentru clienții reali și eviți scurgerea lor atunci când împărtășești sau publici codul.

De ce contează când construiești cu AI

În momentul în care aplicația ta face ceva util cu un alt serviciu — procesează o plată, trimite un e-mail, apelează un model AI — are nevoie de o cheie. Constructorii de aplicații AI cer aceste chei în mod regulat, iar locul în care ajunge cheia decide dacă aplicația ta este sigură.

Două lucruri greșesc frecvent în aplicațiile construite cu AI:

• Cheia este lipită în chat sau în cod. Atunci ajunge în istoricul conversației, în fișierele proiectului și în orice export sau depozit. Oricine o vede îți poate folosi contul.
• Cheia este folosită în browser. Dacă codul care apelează Stripe sau OpenAI rulează în pagină, cheia este trimisă fiecărui vizitator. Oamenii se uită, iar scanerele automate caută constant chei expuse.

Înțelegerea variabilelor de mediu te ajută să observi ambele probleme și să ceri remedierea.

O analogie din viața de zi cu zi: seiful din cameră

Codul aplicației tale este ca o cameră de hotel. Oaspeții (și curățenia, și oricine căruia i-ai dat cardul de acces) trec prin ea. Nu ai lăsa pașaportul pe birou.

Variabilele de mediu sunt seiful din cameră. Camera știe că există un seif și cum să-l deschidă atunci când este nevoie, dar pașaportul nu stă pe masă. Iar dacă te muți dintr-o cameră în alta — de la configurația de test la site-ul live — pui un alt pașaport în seiful acelei camere, fără să redecorezi nimic.

Cum funcționează

Codul tău se referă la un nume, nu la o valoare. În JavaScript pe server, asta arată ca process.env.STRIPE_SECRET_KEY. Când pornește aplicația, platforma pe care rulează completează valoarea pentru acel nume. Schimbi valoarea în setările platformei, repornești sau redeploiezi, iar aplicația folosește una nouă — fără nicio modificare de cod.

De unde vin valorile depinde de locul în care rulează aplicația:

Variabile publice și variabile secrete

Nu fiecare variabilă de mediu este secretă. Ajută să le împarți în două grupuri:

Cadrele de lucru web fac această împărțire explicită. În Vite, doar variabilele al căror nume începe cu VITE_ sunt incluse în codul din browser; în Next.js, prefixul este NEXT_PUBLIC_. Este o măsură de siguranță: tot ce are aceste prefixe ajunge în fișierele pe care le descarcă fiecare vizitator, deci un secret nu trebuie să primească niciodată unul dintre ele.

Un exemplu practic: un buton de rezumat cu AI

Vrei un buton „Rezumă această notiță” care apelează un model AI.

Varianta nesigură: codul butonului, rulat în browser, apelează direct furnizorul de AI, cu cheia API scrisă în el. Funcționează în previzualizare. Dar înseamnă că oricine poate deschide instrumentele de dezvoltator ale browserului, poate copia cheia și poate consuma din bugetul contului tău.

Varianta sigură:

1. Creezi cheia la furnizorul de AI și o salvezi ca secret numit OPENAI_API_KEY (sau similar) în setările proiectului.
2. Backend-ul primește o rută, POST /api/summarise, care citește process.env.OPENAI_API_KEY, verifică dacă utilizatorul este autentificat și apelează furnizorul.
3. Butonul apelează ruta ta, nu furnizorul. Browserul nu vede niciodată cheia.
4. Adaugi același secret în setările aplicației publicate și redeploiezi, astfel încât site-ul live să îl aibă și el.

Acest model — browserul apelează serverul tău, iar serverul ține cheia și apelează serviciul — se aplică la plăți, e-mail, hărți și la orice alt API plătit. Ghidul despre utilizarea API-urilor LLM acoperă cazul AI mai în detaliu.

Termeni cheie

• Fișierul .env: un fișier text cu linii de forma NUME=valoare, folosit în dezvoltarea locală. Include-l în .gitignore ca să nu fie trimis în git.
• .env.example: o copie cu numele, dar fără valori reale, care se trimite în git ca să știe ceilalți ce variabile trebuie setate.
• Rotire: înlocuirea unui secret cu unul nou și revocarea celui vechi.
• Domeniu / permisiuni: mulți furnizori îți permit să creezi chei care pot face doar anumite lucruri. O cheie care poate doar trimite e-mailuri este mai puțin periculoasă decât una care poate face orice.
• Chei de test vs. chei live: furnizori precum Stripe oferă chei separate pentru testare și pentru bani reali. Folosește cheile de test până la lansare.
• Secret de semnare: un secret folosit ca să verifici că un mesaj, cum ar fi un webhook, chiar vine de la expeditor.

Greșeli frecvente și idei greșite

• „Repozitoriul meu este privat, deci cheile din el sunt în regulă.” Repozitoriile private ajung să fie partajate, derivate, exportate și clonate pe laptopuri. Cheile tot nu au ce căuta acolo. Dacă conectezi un proiect la GitHub, verifică să nu fie inclus niciun fișier .env.
• „L-am șters, deci nu mai există.” Git păstrează istoricul, iar jurnalele de chat păstrează mesajele. Dacă o cheie a fost vreodată expusă, rotește-o.
• Folosirea unui prefix public pentru un secret. VITE_OPENAI_KEY pune cheia ta în pachetul din browser.
• Uitarea redeploiării. Schimbarea unei variabile în setări de obicei se aplică abia după ce aplicația repornește sau este publicată din nou.
• O singură cheie pentru tot. Chei separate pentru test și live, precum și pentru fiecare aplicație, îți permit să revoci una fără să strici restul.
• Lipsa unei limite de cheltuieli. Pentru API-urile plătite, setează un buget sau o limită în panoul furnizorului, pentru cazul în care o cheie se scurge.

Ce să ceri constructorului tău AI

• „Citește cheia secretă Stripe dintr-o variabilă de mediu numită STRIPE_SECRET_KEY. Folosește-o doar pe server.”
• „Asigură-te că niciun secret nu este folosit în codul de pe client și că nu primește prefixul VITE_ sau NEXT_PUBLIC_.”
• „Creează un .env.example care listează fiecare variabilă de care are nevoie aplicația, fără valori, și asigură-te că .env este ignorat de git.”
• „Verifică fișierele frontend construite pentru orice șir care arată ca o cheie API.”

Lista noastră de verificare de securitate pentru aplicațiile construite cu AI acoperă secretele alături de celelalte verificări utile înainte de lansare.

Secrete pe Mythex

Pe Mythex, secretele sunt variabile de mediu ale proiectului, injectate atât în sandbox-ul de previzualizare, cât și în aplicația ta publicată. Le adaugi la setări proiect → Secrete sau cu /secrets în chat, iar când agentul are nevoie de o cheie afișează un card de secrete în chat, astfel încât valoarea intră într-un câmp de formular și nu în transcriptul mesajelor. Dacă schimbi un secret pentru o aplicație live, publică din nou ca publicarea să îl preia. Exporturile proiectului lasă secretele afară, iar fișierele .env importate sunt curățate, așa că le adaugi din nou în setări. Vezi variabilele de mediu și secretele și secretele în chat în documentație.

Întrebări