Co jsou proměnné prostředí a tajné klíče? Srozumitelný průvodce

Proměnná prostředí je pojmenované nastavení, například DATABASE_URL nebo STRIPE_SECRET_KEY, které se aplikaci předá při spuštění, místo aby bylo zapsané přímo v kódu. Tajný klíč je proměnná prostředí, jejíž hodnota musí zůstat soukromá: API klíč, heslo nebo podpisový klíč. Když tyto hodnoty držíte mimo kód, můžete je změnit bez úpravy aplikace, používat jiné pro testování a jiné pro skutečné zákazníky a zabránit tomu, aby unikly při sdílení nebo zveřejnění kódu.

Proč na tom záleží, když stavíte s AI

V okamžiku, kdy vaše aplikace začne dělat něco užitečného s jinou službou, například přijímat platbu, posílat e-mail nebo volat AI model, potřebuje klíč. Nástroje pro tvorbu aplikací s AI o tyto klíče žádají běžně a rozhoduje se podle toho, kam klíč skončí, jestli bude aplikace bezpečná.

U aplikací postavených s AI se často pokazí dvě věci:

• Klíč se vloží do chatu nebo do kódu. Pak zůstane v historii chatu, v souborech projektu a v každém exportu nebo repozitáři. Kdokoli ho uvidí, může použít váš účet.
• Klíč se používá v prohlížeči. Pokud kód, který volá Stripe nebo OpenAI, běží na stránce, dostane klíč každý návštěvník. Lidé se dívají a automatické skenery hledají odhalené klíče neustále.

Porozumění proměnným prostředí vám umožní obojí poznat a požádat o nápravu.

Každodenní přirovnání: hotelový trezor

Kód vaší aplikace je jako hotelový pokoj. Hosté (a uklízeči a každý, komu dáte kartu do zámku) jím procházejí. Pas nenecháte ležet na stole.

Proměnné prostředí jsou jako trezor v pokoji. Pokoj ví, že trezor existuje, a ví, jak se otevírá, když je potřeba, ale pas tam nikdo nenechá. A když se přestěhujete z jednoho pokoje do druhého, z testovacího prostředí na živý web, vložíte do trezoru jiný pas, aniž byste pokoj předělávali.

Jak to funguje

Váš kód odkazuje na název, ne na hodnotu. V JavaScriptu na serveru to vypadá jako process.env.STRIPE_SECRET_KEY. Když se aplikace spustí, platforma, na které běží, doplní hodnotu pro tento název. Změníte-li hodnotu v nastavení platformy a aplikaci restartujete nebo znovu nasadíte, použije novou, bez změny kódu.

Odkud hodnoty pocházejí, závisí na tom, kde aplikace běží:

Veřejné a tajné proměnné

Ne každá proměnná prostředí je tajná. Pomáhá rozdělit je do dvou skupin:

Webové frameworky toto rozdělení vyjadřují explicitně. Ve Vite se do kódu pro prohlížeč zahrnují jen proměnné, jejichž názvy začínají na VITE_; v Next.js je předpona NEXT_PUBLIC_. Je to bezpečnostní prvek: cokoli s těmito předponami skončí v souborech, které si stáhne každý návštěvník, takže tajný údaj jí nikdy nesmí dostat.

Příklad: tlačítko pro shrnutí pomocí AI

Chcete tlačítko „Shrň tuto poznámku“, které volá AI model.

Nebezpečná verze: kód tlačítka, běžící v prohlížeči, volá poskytovatele AI přímo a API klíč je v něm napsaný natvrdo. V náhledu to funguje. Znamená to ale, že kdokoli může otevřít vývojářské nástroje prohlížeče, zkopírovat klíč a spustit účty na váš úkor.

Bezpečná verze:

1. Klíč vytvoříte u poskytovatele AI a uložíte ho jako tajný údaj, například OPENAI_API_KEY (nebo podobně), do nastavení projektu.
2. Backend dostane trasu POST /api/summarise, která načte process.env.OPENAI_API_KEY, ověří, že je uživatel přihlášený, a zavolá poskytovatele.
3. Tlačítko volá vaši trasu, ne poskytovatele. Prohlížeč klíč nikdy nevidí.
4. Stejný tajný údaj přidáte do nastavení publikované aplikace a znovu nasadíte, aby ho měl i živý web.

Tento vzor, kdy prohlížeč volá váš server a server drží klíč a volá službu, platí pro platby, e-maily, mapy i každé další placené API. Podrobněji případ AI popisuje průvodce použitím LLM API.

Klíčové pojmy

• Soubor .env: textový soubor s řádky NÁZEV=hodnota používaný při lokálním vývoji. Uveďte ho v .gitignore, aby se necommitoval.
• .env.example: kopie se seznamem názvů, ale bez skutečných hodnot. Commituje se, aby ostatní věděli, které proměnné nastavit.
• Rotace: nahrazení tajného údaje novým a zrušení starého.
• Rozsah / oprávnění: mnoho poskytovatelů umožňuje vytvářet klíče, které smějí dělat jen určité věci. Klíč, který umí jen posílat e-maily, je méně nebezpečný než ten, který umí všechno.
• Testovací a živé klíče: poskytovatelé jako Stripe dávají oddělené klíče pro testování a pro skutečné peníze. Dokud nespustíte, používejte testovací klíče.
• Podpisový klíč: tajný údaj, kterým se ověřuje, že zpráva, například webhook, skutečně přišla od odesílatele.

Časté chyby a mylné představy

• „Můj repozitář je soukromý, takže klíče v něm jsou v pořádku.“ Soukromé repozitáře se sdílejí, forkují, exportují a klonují na notebooky. Klíče tam stejně nepatří. Pokud projekt propojíte s GitHubem, zkontrolujte, že v něm není žádný soubor .env.
• „Smazal jsem ho, takže je pryč.“ Git si ponechává historii a chatové logy si ponechávají zprávy. Pokud byl klíč kdy vystaven, zrotujte ho.
• Použití veřejné předpony u tajného údaje. VITE_OPENAI_KEY dostane váš klíč do balíčku pro prohlížeč.
• Zapomenutí na nové nasazení. Změna proměnné v nastavení obvykle začne platit až po restartu aplikace nebo jejím novém publikování.
• Jeden klíč pro všechno. Oddělené klíče pro testování a produkci a pro každou aplikaci umožní zrušit jeden, aniž se rozbijí ostatní.
• Žádný limit výdajů. U placených API nastavte rozpočet nebo limit v panelu poskytovatele pro případ, že by klíč unikl.

Co žádat po svém nástroji pro tvorbu s AI

• „Načti tajný klíč Stripe z proměnné prostředí STRIPE_SECRET_KEY. Používej ho jen na serveru.“
• „Ujisti se, že se žádný tajný údaj nepoužívá v kódu na straně klienta a že nemá předponu VITE_ ani NEXT_PUBLIC_.“
• „Vytvoř .env.example se seznamem všech proměnných, které aplikace potřebuje, bez hodnot, a ujisti se, že .env je ignorovaný gitem.“
• „Zkontroluj zkompilované soubory frontendu, jestli neobsahují řetězec, který vypadá jako API klíč.“

Náš bezpečnostní kontrolní seznam pro aplikace postavené s AI pokrývá tajné údaje spolu s dalšími kontrolami před spuštěním.

Tajné údaje na Mythexu

Na Mythexu jsou tajné údaje proměnnými prostředí projektu, které se vkládají jak do náhledové sandboxu, tak do vaší publikované aplikace. Přidáte je v nastavení projektu → Secrets nebo příkazem /secrets v chatu. Když agent potřebuje klíč, zobrazí v chatu kartu s tajnými údaji, takže se hodnota vloží do formulářového pole a nezůstane v přepisu zpráv. Změníte-li tajný údaj u živé aplikace, publikujte znovu, aby se nasazení načetlo. Exporty projektů tajné údaje vynechávají a importované soubory .env se zbaví, takže je znovu přidáte v nastavení. Viz proměnné prostředí a tajné údaje a tajné údaje v chatu v dokumentaci.

Otázky