Kas yra aplinkos kintamieji ir slaptieji raktai? Paprastas vadovas

Aplinkos kintamasis – tai pavadinimu pažymėtas nustatymas, pavyzdžiui DATABASE_URL arba STRIPE_SECRET_KEY, kuris perduodamas jūsų programai, kai ji paleidžiama, o ne įrašomas tiesiai į kodą. Slaptasis raktas – tai aplinkos kintamasis, kurio reikšmė turi likti privati: API raktas, slaptažodis, pasirašymo raktas. Šias reikšmes laikant už kodo ribų, galima jas keisti nekeičiant programos, naudoti skirtingas reikšmes bandymams ir tikriems klientams bei neleisti joms nutekėti, kai dalijatės kodu ar jį publikuojate.

Kodėl tai svarbu kuriant su DI

Vos tik jūsų programa pradeda daryti ką nors naudingo su kita paslauga – priima mokėjimą, siunčia el. laišką, kviečia DI modelį – jai reikia rakto. DI programų kūrimo įrankiai nuolat prašo šių raktų, o nuo to, kur raktas galiausiai patenka, priklauso, ar jūsų programa saugi.

DI kuriamose programose dažniausiai nutinka dvi klaidos:

• Raktas įklijuojamas į pokalbį ar kodą. Tada jis atsiduria pokalbio istorijoje, projekto failuose ir bet kokiame eksporte ar saugykloje. Kas tik juos pamato, gali naudotis jūsų paskyra.
• Raktas naudojamas naršyklėje. Jei kodas, kuris kreipiasi į Stripe ar OpenAI, veikia puslapyje, raktas siunčiamas kiekvienam lankytojui. Žmonės tikrai tai tikrina, o automatiniai skeneriai nuolat ieško atskleistų raktų.

Supratę aplinkos kintamuosius galite pastebėti abi šias klaidas ir paprašyti jas ištaisyti.

Kasdienis palyginimas: viešbučio seifas

Jūsų programos kodas – tai viešbučio kambarys. Pro jį praeina svečiai (ir valytojai, ir visi, kuriems duodate kortelę). Paso ant stalo nepaliktumėte.

Aplinkos kintamieji – tai kambario seifas. Kambarys žino, kad seifas yra, ir moka jį atidaryti, kai reikia, bet pasas nevaikšto po kambarį. Jei persikeliate į kitą kambarį – iš bandymų aplinkos į tikrą svetainę – į to kambario seifą dedate kitą pasą, nereikia perdažyti sienų.

Kaip tai veikia

Jūsų kode nurodomas pavadinimas, o ne reikšmė. Serverio JavaScript kode tai atrodo taip: process.env.STRIPE_SECRET_KEY. Programai paleidžiant platforma, kurioje ji veikia, įrašo reikšmę tam pavadinimui. Pakeiskite reikšmę platformos nustatymuose, paleiskite iš naujo arba publikuokite dar kartą – ir programa naudos naują reikšmę be kodo pakeitimų.

Reikšmės laikomos skirtingose vietose, priklausomai nuo to, kur programa veikia:

Vieši ir slapti kintamieji

Ne kiekvienas aplinkos kintamasis yra slaptas. Naudinga juos suskirstyti į dvi grupes:

Web karkasai šį skirtumą nurodo aiškiai. Vite aplinkoje į naršyklės kodą įtraukiami tik kintamieji, kurių pavadinimai prasideda VITE_; Next.js – priešdėlis NEXT_PUBLIC_. Tai saugumo funkcija: viskas su šiais priešdėliais atsiduria failuose, kuriuos parsisiunčia kiekvienas lankytojas, todėl slaptam raktui niekada negalima duoti tokio priešdėlio.

Darbo pavyzdys: DI santraukos mygtukas

Norite mygtuko „Apibendrinti šią pastabą“, kuris kviečia DI modelį.

Nesaugi versija: mygtuko kodas, veikiantis naršyklėje, tiesiogiai kreipiasi į DI teikėją, o API raktas įrašytas į patį kodą. Peržiūroje tai veikia. Bet kas gali atidaryti naršyklės kūrėjo įrankius, nukopijuoti raktą ir pakelti sąskaitą jūsų paskyroje.

Saugi versija:

1. Raktą sukuriate DI teikėjo paskyroje ir išsaugote kaip slaptąjį kintamąjį, pavyzdžiui OPENAI_API_KEY (ar panašų), projekto nustatymuose.
2. Serverio dalyje sukuriamas maršrutas POST /api/summarise, kuris nuskaito process.env.OPENAI_API_KEY, patikrina, ar vartotojas prisijungęs, ir kreipiasi į teikėją.
3. Mygtukas kreipiasi į jūsų maršrutą, o ne į teikėją. Naršyklė rakto niekada nemato.
4. Tą patį slaptąjį kintamąjį pridedate prie publikuotos programos nustatymų ir programą iš naujo publikuojate, kad tiesioginė svetainė jį turėtų.

Tas modelis – naršyklė kreipiasi į jūsų serverį, o serveris saugo raktą ir kreipiasi į paslaugą – tinka mokėjimams, el. paštui, žemėlapiams ir visoms kitoms mokamoms API paslaugoms. Išsamiau DI atvejį aprašo vadovas apie LLM API naudojimą.

Pagrindinės sąvokos

• .env failas: PAVADINIMAS=reikšmė eilučių tekstinis failas, naudojamas vietiniam kūrimui. Įtraukite jį į .gitignore, kad jis nebūtų įkeltas į git.
• .env.example: kopija be tikrų reikšmių, tik su pavadinimais. Ją įkeliate į git, kad kiti žinotų, kokius kintamuosius nustatyti.
• Keisti (rotate): pakeisti slaptą raktą nauju ir senąjį panaikinti.
• Apimtis / leidimai: daugelis teikėjų leidžia kurti raktus, kurie gali atlikti tik tam tikrus veiksmus. Raktas, galintis tik siųsti el. laiškus, yra mažiau pavojingas nei raktas, kuris gali viską.
• Bandymų ir tikrieji raktai: teikėjai, pavyzdžiui Stripe, duoda atskirus raktus bandymams ir tikriems pinigams. Iki paleidimo naudokite bandymų raktus.
• Pasirašymo raktas: slaptas raktas, naudojamas patikrinti, ar pranešimas, pavyzdžiui webhook, tikrai atkeliavo iš siuntėjo.

Dažniausios klaidos ir klaidingi įsitikinimai

• „Mano repozitorija privati, todėl raktai joje yra saugūs.“ Privačios repozitorijos vis tiek bendrinamos, šakojamos, eksportuojamos ir klonuojamos į nešiojamuosius kompiuterius. Raktai ten nepriklauso. Jei projektą jungiate prie GitHub, patikrinkite, kad joje nėra .env failo.
• „Ištryniau, vadinasi, dingo.“ Git išsaugo istoriją, o pokalbių įrašai – žinutes. Jei raktas kada nors buvo atskleistas, jį reikia pakeisti.
• Viešo priešdėlio naudojimas slaptam raktui. VITE_OPENAI_KEY įdeda jūsų raktą į naršyklės paketą.
• Pamiršta publikuoti iš naujo. Pakeitus kintamąjį nustatymuose, paprastai jis įsigalioja tik po to, kai programa paleidžiama iš naujo arba publikuojama dar kartą.
• Vienas raktas viskam. Atskiri raktai bandymams ir tikrai versijai bei kiekvienai programai leidžia panaikinti vieną nepaveikiant kitų.
• Jokio išlaidų limito. Mokamiems API nustatykite biudžetą ar limitą teikėjo skydelyje, jei raktas nutekėtų.

Ko prašyti DI kūrimo įrankio

• „Nuskaityk Stripe slaptąjį raktą iš aplinkos kintamojo STRIPE_SECRET_KEY. Naudok jį tik serveryje.“
• „Užtikrink, kad joks slaptas raktas nenaudojamas kliento pusės kode ir nedavai jam VITE_ / NEXT_PUBLIC_ priešdėlio.“
• „Sukurk .env.example, kuriame būtų visi programai reikalingi kintamieji be reikšmių, ir įsitikink, kad .env ignoruojamas git.“
• „Patikrink sukurtus frontend failus, ar nėra eilučių, panašių į API raktus.“

Mūsų saugumo kontrolinis sąrašas DI kuriamoms programoms aptaria slaptus raktus kartu su kitais patikrinimais prieš paleidimą.

Slaptieji raktai Mythex platformoje

Mythex platformoje slaptieji raktai yra projekto aplinkos kintamieji, įdedami tiek į peržiūros smėliadėžę, tiek į publikuotą programą. Juos pridedate projekto nustatymai → Secrets arba pokalbyje su /secrets. Kai agentui reikia rakto, jis pokalbyje parodo slapto rakto kortelę, todėl reikšmė įvedama į formos lauką, o ne patenka į pokalbio įrašus. Pakeitus slaptą raktą veikiančiai programai, publikuokite dar kartą, kad diegimas jį perimtų. Projektų eksportuose slaptieji raktai neįtraukiami, o importuoti .env failai išvalomi, todėl raktus pridedate iš naujo nustatymuose. Žr. aplinkos kintamuosius ir slaptuosius raktus ir slaptuosius raktus pokalbyje dokumentacijoje.

Klausimai