Što su varijable okruženja i tajne? Jednostavan vodič

Varijabla okruženja (environment variable) je imenovana postavka, poput DATABASE_URL ili STRIPE_SECRET_KEY, koja se aplikaciji predaje pri pokretanju umjesto da bude upisana u kod. Tajna (secret) je varijabla okruženja čija vrijednost mora ostati privatna: API ključ, lozinka ili ključ za potpisivanje. Kad te vrijednosti držite izvan koda, možete ih mijenjati bez uređivanja aplikacije, koristiti različite za testiranje i za stvarne kupce te spriječiti da procure kad dijelite ili objavljujete kod.

Zašto je to važno kad gradite uz AI

Čim vaša aplikacija učini nešto korisno s drugom uslugom, primjerice naplati plaćanje, pošalje e-mail ili pozove AI model, treba joj ključ. AI graditelji aplikacija redovito traže te ključeve, a gdje ključ završi odlučuje hoće li aplikacija biti sigurna.

U aplikacijama izgrađenima uz AI često se pogriješi na dva načina:

• Ključ se zalijepi u chat ili u kod. Tada živi u povijesti razgovora, u datotekama projekta i u svakom izvozu ili repozitoriju. Tko ga vidi, može koristiti vaš račun.
• Ključ se koristi u pregledniku. Ako kod koji poziva Stripe ili OpenAI radi na stranici, ključ se šalje svakom posjetitelju. Ljudi to provjeravaju, a automatski skeneri stalno traže izložene ključeve.

Razumijevanje varijabli okruženja pomaže vam da prepoznate oba problema i zatražite ispravak.

Svakodnevna usporedba: sef u hotelskoj sobi

Kod vaše aplikacije je poput hotelske sobe. Gosti (i čistačice, i svi kojima dajete karticu za sobu) prolaze kroz nju. Putovnicu ne biste ostavili na stolu.

Varijable okruženja su sef u sobi. Soba zna da sef postoji i kako se otvara kad zatreba, ali putovnica ne leži naokolo. A ako se preselite iz jedne sobe u drugu, s testnog postava na živu stranicu, u sef stavite drugu putovnicu, bez preuređivanja sobe.

Kako to funkcionira

Vaš kod upućuje na naziv, a ne na vrijednost. U JavaScriptu na poslužitelju to izgleda kao process.env.STRIPE_SECRET_KEY. Kad se aplikacija pokrene, platforma na kojoj radi popuni vrijednost za taj naziv. Promijenite vrijednost u postavkama platforme, ponovno pokrenite ili ponovno objavite aplikaciju, i ona koristi novu vrijednost, bez promjene koda.

Odakle dolaze vrijednosti ovisi o tome gdje aplikacija radi:

Javne i tajne varijable

Nisu sve varijable okruženja tajne. Korisno ih je razvrstati u dvije skupine:

Web okviri tu podjelu čine vidljivom. U Viteu se u kod preglednika uključuju samo varijable čiji naziv počinje s VITE_, a u Next.js-u je prefiks NEXT_PUBLIC_. To je sigurnosna značajka: sve s tim prefiksima završava u datotekama koje svaki posjetitelj preuzima, pa tajna nikad ne smije dobiti takav prefiks.

Primjer: gumb za AI sažetak

Želite gumb „Sažmi ovu bilješku” koji poziva AI model.

Nesigurna verzija: kod gumba, koji se izvršava u pregledniku, poziva AI pružatelja izravno, s upisanim API ključem. Na pregledu radi. Ali svatko može otvoriti alate za razvojne programere u pregledniku, kopirati ključ i potrošiti sredstva s vašeg računa.

Sigurna verzija:

1. U AI pružatelju stvorite ključ i u postavkama projekta spremite ga kao tajnu s nazivom OPENAI_API_KEY (ili sličnim).
2. Poslužitelj dobiva rutu POST /api/summarise koja čita process.env.OPENAI_API_KEY, provjerava je li korisnik prijavljen i poziva pružatelja.
3. Gumb poziva vašu rutu, a ne pružatelja. Preglednik nikad ne vidi ključ.
4. Istu tajnu dodajte u postavke objavljene aplikacije i ponovno je objavite, kako bi i živa stranica imala ključ.

Taj obrazac, u kojem preglednik poziva vaš poslužitelj, a poslužitelj čuva ključ i poziva uslugu, vrijedi za plaćanja, e-poštu, karte i svaki drugi plaćeni API. Vodič o korištenju LLM API-ja detaljnije obrađuje AI slučaj.

Ključni pojmovi

• Datoteka .env: tekstualna datoteka s recima NAZIV=vrijednost koja se koristi u lokalnom razvoju. Dodajte je u .gitignore da se ne bi predala u git.
• .env.example: kopija s nazivima, ali bez stvarnih vrijednosti, koja se predaje u repozitorij kako drugi znaju koje varijable treba postaviti.
• Rotirati: zamijeniti tajnu novom i poništiti staru.
• Opseg / dozvole: mnogi pružatelji dopuštaju ključeve koji smiju raditi samo određene stvari. Ključ koji može samo slati e-poštu manje je opasan od onoga koji može sve.
• Testni i živi ključevi: pružatelji poput Stripea daju zasebne ključeve za testiranje i za stvarni novac. Do lansiranja koristite testne ključeve.
• Ključ za potpisivanje: tajna kojom se provjerava je li poruka, primjerice webhook, stvarno došla od pošiljatelja.

Česte pogreške i zablude

• „Repozitorij mi je privatan, pa su ključevi u njemu u redu.” Privatni repozitoriji dijele se, forkaju, izvoze i kloniraju na laptope. Ključevi tamo ne pripadaju. Ako povežete projekt s GitHubom, provjerite da nije uključena datoteka .env.
• „Obrisao sam ga, pa ga više nema.” Git čuva povijest, a zapisi chata čuvaju poruke. Ako je ključ ikad bio izložen, rotirajte ga.
• Javni prefiks na tajni. VITE_OPENAI_KEY stavlja vaš ključ u paket koji preglednik preuzima.
• Zaboravljeno ponovno objavljivanje. Promjena varijable u postavkama obično djeluje tek nakon ponovnog pokretanja ili ponovnog objavljivanja aplikacije.
• Jedan ključ za sve. Zasebni ključevi za testiranje i za živi rad te po aplikaciji omogućuju poništavanje jednog bez kvarenja ostalih.
• Nema ograničenja potrošnje. Za plaćene API-je postavite proračun ili limit na nadzornoj ploči pružatelja, za slučaj da ključ procuri.

Što tražiti od AI graditelja

• „Pročitaj Stripe tajni ključ iz varijable okruženja STRIPE_SECRET_KEY. Koristi ga samo na poslužitelju.”
• „Pobrini se da se nijedna tajna ne koristi u kodu na strani klijenta i da nema prefiks VITE_ ni NEXT_PUBLIC_.”
• „Napravi datoteku .env.example s popisom svih varijabli koje aplikacija treba, bez vrijednosti, i provjeri da je .env ignoriran u gitu.”
• „Provjeri izgrađene frontend datoteke za svaki niz znakova koji liči na API ključ.”

Naš sigurnosni popis za aplikacije izgrađene uz AI pokriva tajne uz ostale provjere prije lansiranja.

Tajne na Mythexu

Na Mythexu su tajne varijable okruženja projekta koje se ubacuju i u pregled u sandboxu i u objavljenu aplikaciju. Dodajete ih pod postavke projekta → Secrets ili naredbom /secrets u chatu. Kad agent treba ključ, u chatu prikaže karticu za tajne, pa vrijednost ide u polje obrasca, a ne u tekst razgovora. Ako promijenite tajnu za živu aplikaciju, ponovno je objavite da se deploy pokupi. Izvozi projekta ne sadrže tajne, a uvezene .env datoteke se čiste, pa ih ponovno dodajte u postavkama. Pogledajte varijable okruženja i tajne i tajne u chatu u dokumentaciji.

Pitanja