Kaj so okoljske spremenljivke in skrivnosti? Preprost vodnik

Okoljska spremenljivka je poimenovana nastavitev — na primer DATABASE_URL ali STRIPE_SECRET_KEY — ki se aplikaciji preda ob zagonu, namesto da bi bila zapisana v kodi. Skrivnost je okoljska spremenljivka, katere vrednost mora ostati zasebna: API ključ, geslo ali podpisni ključ. Če te vrednosti hranite zunaj kode, jih lahko spremenite brez urejanja aplikacije, za testiranje in za prave stranke uporabite različne vrednosti ter preprečite, da bi se uhajale, ko kodo delite ali objavite.

Zakaj je to pomembno, ko gradite z umetno inteligenco

Trenutek, ko vaša aplikacija za koristno delo uporabi drugo storitev — sprejme plačilo, pošlje e-pošto, pokliče model umetne inteligence — potrebuje ključ. Gradniki aplikacij z umetno inteligenco te ključe redno zahtevajo, kam pa ključ konča, odloči, ali je aplikacija varna.

V aplikacijah, zgrajenih z umetno inteligenco, se pogosto zgodita dve napaki:

• Ključ se prilepi v klepet ali v kodo. Nato ostane v zgodovini klepeta, v datotekah projekta in v kakršnemkoli izvozu ali repozitoriju. Kdorkoli ga vidi, lahko uporablja vaš račun.
• Ključ se uporablja v brskalniku. Če koda, ki kliče Stripe ali OpenAI, teče na strani, se ključ pošlje vsakemu obiskovalcu. Ljudje to res pregledujejo, avtomatski skenerji pa iščejo izpostavljene ključe nenehno.

Razumevanje okoljskih spremenljivk vam omogoča, da prepoznate obe napaki in zahtevate popravek.

Vsakdanja primerjava: hotelski trezor

Koda vaše aplikacije je kot hotelska soba. Gosti (in čistilke ter vsi, ki jim date kartico za vstop) hodijo skozi njo. Potnega lista ne bi pustili na mizi.

Okoljske spremenljivke so trezor v sobi. Soba ve, da obstaja trezor in kako ga odpreti, kadar je to treba, potni list pa ni nikjer na vidnem mestu. In če se preselite iz ene sobe v drugo — iz testnega okolja na pravo spletno mesto — v trezor te sobe položite drug potni list, ne da bi sobo prenavljali.

Kako deluje

Vaša koda se sklicuje na ime, ne na vrednost. V JavaScriptu na strežniku je to videti kot process.env.STRIPE_SECRET_KEY. Ko se aplikacija zažene, platforma, na kateri teče, za to ime vstavi vrednost. Če vrednost spremenite v nastavitvah platforme in aplikacijo znova zaženete ali ponovno objavite, aplikacija uporabi novo vrednost — brez spremembe kode.

Od tega, kje aplikacija teče, je odvisno, od kod prihajajo vrednosti:

Javne in skrivne spremenljivke

Ni vsaka okoljska spremenljivka skrivna. Pomaga, če jih razvrstite v dve skupini:

Spletna ogrodja to delitev jasno določajo. V Vite so v kodo brskalnika vključene samo spremenljivke, katerih imena se začnejo z VITE_; v Next.js je predpona NEXT_PUBLIC_. To je varnostna lastnost: vse s temi predponami konča v datotekah, ki si jih prenese vsak obiskovalec, zato skrivnost nikoli ne sme dobiti takšne predpone.

Delovni primer: gumb za povzetek z umetno inteligenco

Želite gumb »Povzemi to opombo«, ki pokliče model umetne inteligence.

Nevarna različica: koda gumba, ki teče v brskalniku, neposredno kliče ponudnika umetne inteligence, API ključ pa je zapisan v njej. V predogledu deluje. Pomeni pa tudi, da lahko kdorkoli odpre orodja za razvijalce v brskalniku, kopira ključ in porabi vaš račun.

Varna različica:

1. Ključ ustvarite pri ponudniku umetne inteligence in ga v nastavitvah projekta shranite kot skrivnost z imenom OPENAI_API_KEY (ali podobno).
2. Zaledje dobi pot POST /api/summarise, ki prebere process.env.OPENAI_API_KEY, preveri, ali je uporabnik prijavljen, in pokliče ponudnika.
3. Gumb kliče vašo pot, ne ponudnika. Brskalnik ključa nikoli ne vidi.
4. Enako skrivnost dodate v nastavitve objavljene aplikacije in ponovno objavite, da jo ima tudi živo spletno mesto.

Ta vzorec — brskalnik kliče vaš strežnik, strežnik hrani ključ in kliče storitev — velja za plačila, e-pošto, zemljevide in vse druge plačljive API-je. Vodnik o uporabi LLM API-jev podrobneje obravnava primer z umetno inteligenco.

Ključni pojmi

• Datoteka .env: besedilna datoteka z vrsticami IME=vrednost, uporabljena pri lokalnem razvoju. Vpišite jo v .gitignore, da ne bo dodana v git.
• .env.example: kopija z imeni, a brez pravih vrednosti; se shrani v repozitorij, da drugi vedo, katere spremenljivke morajo nastaviti.
• Zamenjava (rotacija): skrivnost zamenjate z novo in staro prekličete.
• Obseg / dovoljenja: mnogi ponudniki omogočajo ključe, ki lahko opravijo le določena dejanja. Ključ, ki lahko pošilja le e-pošto, je manj nevaren kot ključ, ki lahko počne vse.
• Testni in produkcijski ključi: ponudniki, kot je Stripe, za testiranje in za pravi denar dajo ločene ključe. Do objave uporabljajte testne ključe.
• Podpisna skrivnost: skrivnost, s katero preverite, da je sporočilo, na primer webhook, res prišlo od pošiljatelja.

Pogoste napake in zmote

• »Repozitorij je zaseben, zato so ključi v njem v redu.« Zasebni repozitoriji se delijo, forkajo, izvažajo in kloniranje na prenosnike. Ključi tja ne sodijo. Če projekt povežete z GitHubom, preverite, da v njem ni datoteke .env.
• »Izbrisal sem ga, zato ga ni več.« Git hrani zgodovino, dnevniki klepeta pa hranijo sporočila. Če je bil ključ kdaj izpostavljen, ga zamenjajte.
• Javna predpona na skrivnosti. VITE_OPENAI_KEY da ključ v paket kode brskalnika.
• Pozabljena ponovna objava. Sprememba spremenljivke v nastavitvah običajno začne veljati šele, ko se aplikacija znova zažene ali ponovno objavi.
• En ključ za vse. Ločeni ključi za testiranje in produkcijo ter za vsako aplikacijo omogočajo preklic enega brez prekinitve ostalih.
• Brez omejitve porabe. Pri plačljivih API-jih v nadzorni plošči ponudnika nastavite proračun ali omejitev, za primer, da ključ uide.

Kaj zahtevati od gradnika z umetno inteligenco

• »Preberi Stripe skrivni ključ iz okoljske spremenljivke STRIPE_SECRET_KEY. Uporabljaj ga samo na strežniku.«
• »Poskrbi, da se nobena skrivnost ne uporablja v kodi na strani odjemalca in da ne dobi predpone VITE_ / NEXT_PUBLIC_.«
• »Ustvari .env.example, ki našteva vse spremenljivke, ki jih aplikacija potrebuje, brez vrednosti, in poskrbi, da je .env izključen iz gita.«
• »Preveri zgrajene datoteke frontenda, ali vsebujejo kakšen niz, ki je videti kot API ključ.«

Naš kontrolni seznam varnosti za aplikacije, zgrajene z umetno inteligenco, obravnava skrivnosti skupaj z drugimi preverjanji pred objavo.

Skrivnosti na Mythexu

Na Mythexu so skrivnosti okoljske spremenljivke projekta, ki se vnesejo tako v predogledni peskovnik kot v objavljeno aplikacijo. Dodate jih pod nastavitve projekta → Skrivnosti ali z ukazom /secrets v klepetu. Kadar agent potrebuje ključ, v klepetu prikaže kartico za skrivnosti, tako da se vrednost vnese v polje obrazca in ne ostane v zapisu pogovora. Če spremenite skrivnost za živo aplikacijo, jo znova objavite, da jo postavitev upošteva. Izvozi projektov skrivnosti izpustijo, uvoženi datoteke .env pa se očistijo, zato jih v nastavitvah dodate znova. Več o tem si preberite v dokumentaciji: okoljske spremenljivke in skrivnosti in skrivnosti v klepetu.

Vprašanja