Čo sú premenné prostredia a tajomstvá? Jednoduchý sprievodca

Premenná prostredia je pomenované nastavenie — ako DATABASE_URL alebo STRIPE_SECRET_KEY — ktoré sa vaši aplikácii odovzdá pri spustení namiesto toho, aby bolo napísané priamo do kódu. Tajomstvo je premenná prostredia, ktorej hodnota musí zostať súkromná: API kľúč, heslo alebo podpisový kľúč. Ak tieto hodnoty držíte mimo kódu, môžete ich meniť bez úpravy aplikácie, používať iné pre testovanie a iné pre skutočných zákazníkov a zabrániť ich úniku pri zdieľaní alebo publikovaní kódu.

Prečo na tom záleží pri tvorbe s AI

Keď vaša aplikácia urobí niečo užitočné s inou službou — prijme platbu, pošle e-mail, zavolá AI model — potrebuje kľúč. Tvorcovia aplikácií s AI o tieto kľúče pravidelne žiadajú a od toho, kam kľúč skončí, závisí, či je aplikácia bezpečná.

V aplikáciách vytvorených s AI sa bežne stávajú dve veci zle:

• Kľúč sa vloží do chatu alebo do kódu. Potom žije v histórii chatu, v súboroch projektu a v každom exporte alebo repozitári. Každý, kto ho uvidí, môže použiť váš účet.
• Kľúč sa používa v prehliadači. Ak kód, ktorý volá Stripe alebo OpenAI, beží na stránke, kľúč sa odošle každému návštevníkovi. Ľudia sa na to pozerajú — a automatické skenery hľadajú vystavené kľúče neustále.

Ak rozumiete premenným prostredia, dokážete obidva problémy odhaliť a požiadať o nápravu.

Každodenné prirovnanie: hotelový trezor

Kód vašej aplikácie je ako hotelová izba. Hostia (aj upratovačky a každý, komu dáte kartu do izby) ňou prechádzajú. Pas by ste na stole nenechali.

Premenné prostredia sú trezor v izbe. Izba vie, že trezor existuje, a vie, ako ho v prípade potreby otvoriť, ale pas tam neleží na očiach. A ak sa presuniete do inej izby — z testovacieho nastavenia na živú stránku — dáte do jej trezoru iný pas, bez prerábania izby.

Ako to funguje

Váš kód odkazuje na názov, nie na hodnotu. V JavaScripte na serveri to vyzerá takto: process.env.STRIPE_SECRET_KEY. Keď sa aplikácia spustí, platforma, na ktorej beží, dosadí hodnotu pre tento názov. Zmeníte hodnotu v nastaveniach platformy, reštartujete alebo znovu nasadíte a aplikácia použije novú — bez zmeny kódu.

Odkiaľ sa hodnoty berú, závisí od toho, kde aplikácia beží:

Verejné a tajné premenné

Nie každá premenná prostredia je tajná. Pomáha rozdeliť ich do dvoch skupín:

Webové frameworky toto rozdelenie robia výslovné. Vo Vite sa do kódu prehliadača zahrnú iba premenné, ktorých názov začína na VITE_; v Next.js je prefix NEXT_PUBLIC_. Je to bezpečnostná funkcia: všetko s týmito prefixmi skončí v súboroch, ktoré si stiahne každý návštevník, preto tajomstvu nikdy nesmie byť dané.

Praktický príklad: tlačidlo AI zhrnutia

Chcete tlačidlo „Zhrň túto poznámku“, ktoré volá AI model.

Nebezpečná verzia: kód tlačidla bežiaci v prehliadači volá poskytovateľa AI priamo, s API kľúčom napísaným priamo v kóde. V náhľade to funguje. Znamená to však, že ktokoľvek môže otvoriť nástroje pre vývojárov v prehliadači, skopírovať kľúč a spôsobiť účet za vaše použitie.

Bezpečná verzia:

1. Kľúč vytvoríte u poskytovateľa AI a uložíte ho ako tajomstvo s názvom OPENAI_API_KEY (alebo podobným) v nastaveniach projektu.
2. Backend dostane cestu POST /api/summarise, ktorá načíta process.env.OPENAI_API_KEY, overí, že je používateľ prihlásený, a zavolá poskytovateľa.
3. Tlačidlo volá vašu cestu, nie poskytovateľa. Prehliadač kľúč nikdy nevidí.
4. Rovnaké tajomstvo pridáte do nastavení publikovanej aplikácie a znovu nasadíte, aby ho mala aj živá stránka.

Tento vzor — prehliadač volá váš server, váš server drží kľúč a volá službu — platí pre platby, e-mail, mapy a každé ďalšie platené API. Sprievodca používaním LLM API rozoberá prípad AI podrobnejšie.

Kľúčové pojmy

• Súbor .env: textový súbor riadkov NAZOV=hodnota používaný pri lokálnom vývoji. Uveďte ho v .gitignore, aby sa necommitoval.
• .env.example: kópia s názvami, ale bez skutočných hodnôt, ktorú commitnete, aby ostatní vedeli, aké premenné nastaviť.
• Rotovať: nahradiť tajomstvo novým a starý zrušiť.
• Rozsah / oprávnenia: mnohí poskytovatelia umožňujú vytvárať kľúče, ktoré smú robiť len určité veci. Kľúč, ktorý môže iba posielať e-maily, je menej nebezpečný ako ten, ktorý môže všetko.
• Testovacie vs. živé kľúče: poskytovatelia ako Stripe dávajú oddelené kľúče na testovanie a na skutočné peniaze. Až do spustenia používajte testovacie kľúče.
• Podpisové tajomstvo: tajomstvo, ktoré overí, že správa, napríklad webhook, naozaj pochádza od odosielateľa.

Časté chyby a mylné predstavy

• „Repozitár je súkromný, takže kľúče v ňom sú v poriadku.“ Súkromné repozitáre sa zdieľajú, forkujú, exportujú a klonujú na notebooky. Kľúče tam stále nepatria. Ak pripojíte projekt na GitHub, skontrolujte, že v ňom nie je žiadny súbor .env.
• „Zmazal som ho, takže je preč.“ Git si uchováva históriu a chat si uchováva správy. Ak sa kľúč niekedy dostal na verejnosť, rotujte ho.
• Verejný prefix na tajomstve. VITE_OPENAI_KEY dá váš kľúč do balíka pre prehliadač.
• Zabudnutý nový deploy. Zmena premennej v nastaveniach zvyčajne platí až po reštarte alebo novom publikovaní aplikácie.
• Jeden kľúč na všetko. Oddelené kľúče pre test a živú prevádzku a pre každú aplikáciu umožnia zrušiť jeden bez porušenia ostatných.
• Žiadny limit výdavkov. Pri platených API nastavte v paneli poskytovateľa rozpočet alebo limit, pre prípad úniku kľúča.

Čo žiadať od svojho tvorcu s AI

• „Načítaj tajný kľúč Stripe z premennej prostredia STRIPE_SECRET_KEY. Používaj ho iba na serveri.“
• „Zabezpeč, aby žiadne tajomstvo nebolo použité v kóde na strane klienta a aby nemalo prefix VITE_ ani NEXT_PUBLIC_.“
• „Vytvor .env.example, ktorý uvedie každú premennú, ktorú aplikácia potrebuje, bez hodnôt, a over, že .env je ignorovaný gitom.“
• „Skontroluj zostavené súbory frontendu, či neobsahujú reťazce, ktoré vyzerajú ako API kľúče.“

Náš bezpečnostný kontrolný zoznam pre aplikácie vytvorené s AI rieši tajomstvá spolu s ďalšími kontrolami pred spustením.

Tajomstvá v Mythexe

V Mythexe sú tajomstvá premenné prostredia projektu, ktoré sa vkladajú do náhľadu v sandboxe aj do publikovanej aplikácie. Pridávate ich v nastaveniach projektu → Secrets alebo príkazom /secrets v chate a keď agent potrebuje kľúč, zobrazí v chate kartu tajomstiev, takže hodnota sa vloží do formulára a nie do prepisu správ. Ak zmeníte tajomstvo pre živú aplikáciu, publikujte znovu, aby ho nasadenie prevzalo. Exporty projektu tajomstvá vynechávajú a importované súbory .env sa čistia, takže ich znovu pridajte v nastaveniach. Pozrite premenné prostredia a tajomstvá a tajomstvá v chate v dokumentácii.

Otázky