Mik azok a környezeti változók és titkok? Érthető útmutató

Egy környezeti változó egy elnevezett beállítás — például a DATABASE_URL vagy a STRIPE_SECRET_KEY —, amelyet az alkalmazásodnak a futtatáskor adnak át, ahelyett hogy a kódba írnák. A titok olyan környezeti változó, amelynek értékét privátan kell tartani: egy API-kulcs, egy jelszó, egy aláíró kulcs. Ha ezeket az értékeket a kódon kívül tartjuk, az alkalmazást a kód szerkesztése nélkül is át lehet állítani, a teszteléshez és az éles ügyfelekhez más-más értékek használhatók, és nem szivárognak ki, amikor megosztjuk vagy közzétesszük a kódot.

Miért fontos ez, ha MI-val építesz

Amint az alkalmazásod valami hasznosat tesz egy másik szolgáltatással — fizetést fogad, e-mailt küld, MI-modellt hív —, szüksége lesz egy kulcsra. Az MI-alkalmazás-építők rendszeresen kérnek ilyen kulcsokat, és az dönti el, hogy az alkalmazás biztonságos-e, hogy a kulcs hova kerül.

Az MI-vel épített alkalmazásoknál két dolog gyakran félremegy:

• A kulcsot beillesztik a csetbe vagy a kódba. Ekkor a csetelőzményben, a projektfájlokban és minden exportban vagy tárolóban ott marad. Aki látja, használhatja a fiókodat.
• A kulcsot a böngészőben használják. Ha a Stripe-ot vagy az OpenAI-t hívó kód az oldalon fut, a kulcs minden látogatóhoz eljut. Az emberek néznek, az automata szkennerek pedig folyamatosan keresik a kiszivárgott kulcsokat.

A környezeti változók megértése segít mindkettőt felismerni, és a javítást is pontosan kérni.

Mindennapi hasonlat: a szállodai széf

Az alkalmazásod kódja olyan, mint a szobánk. A vendégek (és a takarítók, meg mindenki, akinek kulcskártyát adtál) sétálnak benne. Az útleveled sem hagynád az asztalon.

A környezeti változók a szobai széfhez hasonlítanak. A szoba tudja, hogy van széf, és azt is, hogyan kell kinyitni, ha szükséges, de az útlevél nincs kint. És ha másik szobába költözöl — a teszt-beállításból az éles oldalra —, egy másik útlevelet teszel a széfbe, a berendezést nem kell átalakítani.

Hogyan működik

A kódod egy nevet hivatkoz, nem egy értéket. Szerveren, JavaScriptben ez így néz ki: process.env.STRIPE_SECRET_KEY. Amikor az alkalmazás elindul, a futtató platform kitölti az értéket ehhez a névhez. Ha megváltoztatod az értéket a platform beállításai között, és újraindítod vagy újra telepíted, az alkalmazás az új értéket használja — kódmódosítás nélkül.

Az értékek forrása attól függ, hol fut az alkalmazás:

Nyilvános és titkos változók

Nem minden környezeti változó titkos. Érdemes két csoportba sorolni őket:

A webes keretrendszerek ezt a felosztást kifejezetten jelölik. A Vite-ban csak a VITE_ előtagú változók kerülnek a böngészőkódba; a Next.js-ben az előtag NEXT_PUBLIC_. Ez biztonsági funkció: minden ilyen előtagú adat bekerül a látogatók által letöltött fájlokba, ezért titkot soha nem szabad ilyen előtaggal ellátni.

Kidolgozott példa: egy MI-összefoglaló gomb

Egy „Jegyzet összefoglalása” gombot szeretnél, amely egy MI-modellt hív.

A nem biztonságos változat: a gomb kódja, a böngészőben futva, közvetlenül hívja az MI-szolgáltatót, a kulcsot pedig beleírva. Az előnézetben működik. Ez azt is jelenti, hogy bárki megnyithatja a böngésző fejlesztői eszközeit, kimásolhatja a kulcsot, és a te fiókodra terhelheti a számlát.

A biztonságos változat:

1. Létrehozod a kulcsot az MI-szolgáltatónál, és titokként mented a projektbeállításaidban, például OPENAI_API_KEY néven (vagy hasonlóan).
2. A backendben lesz egy útvonal, POST /api/summarise, amely beolvassa a process.env.OPENAI_API_KEY értékét, ellenőrzi, hogy a felhasználó be van-e jelentkezve, majd hívja a szolgáltatót.
3. A gomb a te útvonaladat hívja, nem a szolgáltatót. A böngésző soha nem látja a kulcsot.
4. Ugyanezt a titkot hozzáadod a közzétett alkalmazás beállításaihoz, és újra telepíted, hogy az élő oldal is megkapja.

Ez a minta — a böngésző a saját szervereddel beszél, a szervered tartja a kulcsot, és hívja a szolgáltatást — fizetésekre, e-mailre, térképekre és minden más fizetős API esetén is érvényes. Az LLM API-k használatáról szóló útmutató mélyebben tárgyalja az MI-esetet.

Fontos kifejezések

• .env fájl: NÉV=érték sorokból álló szöveges fájl, helyi fejlesztéshez. Vedd fel a .gitignore fájlba, hogy ne kerüljön commitolásra.
• .env.example: másolat a nevekkel, de valódi értékek nélkül; commitolva, hogy mások tudják, mely változókat kell beállítaniuk.
• Rotálás: egy titok lecserélése újra, és a régi visszavonása.
• Hatókör / jogosultságok: sok szolgáltató engedi, hogy csak bizonyos műveletekre szóló kulcsokat hozz létre. Az a kulcs, amely csak e-mailt tud küldeni, kevésbé veszélyes, mint az, amelyik mindent megtehet.
• Teszt- és éles kulcsok: a szolgáltatók, mint a Stripe, külön kulcsokat adnak a teszteléshez és a valódi pénzmozgáshoz. Az indulásig teszt kulcsokat használj.
• Aláíró titok: olyan titok, amellyel ellenőrizhető, hogy egy üzenet, például egy webhook, valóban a küldőtől érkezett.

Gyakori hibák és tévhitek

• „A repó privát, tehát a kulcsok benne rendben vannak.” A privát repókat is megosztják, forkolják, exportálják és laptopokra klónozzák. A kulcsoknak ott sincs helyük. Ha a projektet GitHubhoz kapcsolod, ellenőrizd, hogy nincs-e benne .env fájl.
• „Töröltem, tehát nincs többé.” A git megőrzi az előzményeket, a csetnaplók pedig az üzeneteket. Ha egy kulcs egyszer kiszivárgott, rotáld.
• Nyilvános előtag titokra. A VITE_OPENAI_KEY a kulcsodat a böngészőcsomagba teszi.
• Az újratelepítés elfelejtése. Egy változó módosítása a beállításokban általában csak az alkalmazás újraindítása vagy újbóli közzététele után lép életbe.
• Egy kulcs mindenre. A teszthez és az élőhöz, valamint alkalmazásonként külön kulcsok lehetővé teszik, hogy egyet visszavonj anélkül, hogy a többit megtörnéd.
• Nincs költségkorlát. Fizetős API-knál állíts be keretet vagy limitet a szolgáltató irányítópultján, arra az esetre, ha a kulcs kiszivárogna.

Mit kérj az MI-építődtől

• „Olvasd be a Stripe titkos kulcsát a STRIPE_SECRET_KEY nevű környezeti változóból. Csak a szerveren használd.”
• „Gondoskodj róla, hogy egyetlen titok se legyen kliensoldali kódban, és ne kapjon VITE_ vagy NEXT_PUBLIC_ előtagot.”
• „Készíts .env.example fájlt, amely felsorolja az alkalmazáshoz szükséges összes változót érték nélkül, és gondoskodj róla, hogy a .env git-ignorált legyen.”
• „Nézd át a lefordított frontend fájlokat, nincs-e bennük API-kulcsra hasonlító szöveg.”

Az AI-val épített alkalmazások biztonsági ellenőrzőlistája a titkokat a többi, indulás előtti ellenőrzéssel együtt tárgyalja.

Titkok a Mythexen

A Mythexen a titkok olyan projekt-környezeti változók, amelyek bekerülnek mind az előnézeti homokozóba, mind a közzétett alkalmazásodba. A projektbeállítások → Titkok menüpontban vagy a csetben a /secrets paranccsal adhatod hozzá őket. Ha az ügynöknek kulcsra van szüksége, a csetben titokkártyát mutat, így az érték egy beviteli mezőbe kerül, nem a beszélgetésbe. Ha egy élő alkalmazás titkát módosítod, publikálj újra, hogy a telepítés átvegye. A projektexportok nem tartalmazzák a titkokat, az importált .env fájlokból pedig a titkok törlődnek, így a beállításokban kell újra felvenned őket. Lásd a környezeti változók és titkok és a titkok a csetben oldalakat a dokumentációban.

Kérdések