Czym są zmienne środowiskowe i sekrety? Prosty przewodnik

Zmienna środowiskowa to nazwane ustawienie, na przykład DATABASE_URL albo STRIPE_SECRET_KEY, które jest przekazywane aplikacji podczas jej działania, zamiast być wpisane bezpośrednio w kodzie. Sekret to zmienna środowiskowa, której wartość musi pozostać prywatna: klucz API, hasło albo klucz do podpisywania. Trzymanie tych wartości poza kodem pozwala je zmieniać bez edytowania aplikacji, używać innych do testów i dla prawdziwych klientów oraz zapobiega ich wyciekowi, gdy udostępniasz lub publikujesz kod.

Dlaczego to ważne, gdy budujesz z AI

W chwili, gdy aplikacja robi coś użytecznego z inną usługą — przyjmuje płatność, wysyła e-mail, wywołuje model AI — potrzebuje klucza. Kreatory aplikacji z AI często o nie proszą, a to, gdzie klucz ląduje, decyduje o tym, czy aplikacja jest bezpieczna.

W aplikacjach budowanych z AI zwykle psują się dwie rzeczy:

• Klucz zostaje wklejony w czat lub w kod. Trafia wtedy do historii czatu, plików projektu i każdego eksportu lub repozytorium. Każdy, kto go zobaczy, może użyć Twojego konta.
• Klucz jest używany w przeglądarce. Jeśli kod wywołujący Stripe albo OpenAI działa na stronie, klucz jest wysyłany do każdego odwiedzającego. Ludzie zaglądają do takiego kodu, a automatyczne skanery bez przerwy szukają odsłoniętych kluczy.

Zrozumienie zmiennych środowiskowych pozwala zauważyć oba problemy i poprosić o ich naprawę.

Codzienna analogia: sejf w hotelu

Kod Twojej aplikacji jest jak pokój hotelowy. Goście (oraz sprzątaczki i każdy, komu dasz kartę do drzwi) przez niego przechodzą. Nie zostawiasz paszportu na biurku.

Zmienne środowiskowe to sejf w pokoju. Pokój wie, że sejf istnieje i jak go otworzyć, gdy trzeba, ale paszport nie leży na wierzchu. A jeśli przenosisz się do innego pokoju — z konfiguracji testowej na żywą stronę — wkładasz do sejfu inny paszport, nie przemeblowując pokoju.

Jak to działa

Twój kod odwołuje się do nazwy, a nie do wartości. W JavaScripcie po stronie serwera wygląda to tak: process.env.STRIPE_SECRET_KEY. Gdy aplikacja startuje, platforma, na której działa, wypełnia wartość dla tej nazwy. Zmieniasz wartość w ustawieniach platformy, restartujesz lub wdrażasz ponownie — i aplikacja używa nowej wartości, bez zmiany kodu.

Skąd pochodzą wartości, zależy od miejsca, w którym aplikacja działa:

Zmienne publiczne a sekretne

Nie każda zmienna środowiskowa jest sekretem. Warto podzielić je na dwie grupy:

Frameworki webowe robią ten podział wyraźnym. W Vite do kodu przeglądarki trafiają tylko zmienne, których nazwy zaczynają się od VITE_; w Next.js prefiks to NEXT_PUBLIC_. To zabezpieczenie: wszystko z tymi prefiksami trafia do plików pobieranych przez każdego odwiedzającego, więc sekret nigdy nie może dostać takiego prefiksu.

Przykład krok po kroku: przycisk podsumowania AI

Chcesz przycisk „Podsumuj tę notatkę”, który wywołuje model AI.

Wersja niebezpieczna: kod przycisku, działający w przeglądarce, wywołuje dostawcę AI bezpośrednio, z kluczem API wpisanym w kod. Działa w podglądzie. Oznacza jednak, że każdy może otworzyć narzędzia deweloperskie przeglądarki, skopiować klucz i obciążyć Twoje konto.

Wersja bezpieczna:

1. Tworzysz klucz u dostawcy AI i zapisujesz go jako sekret o nazwie OPENAI_API_KEY (lub podobnej) w ustawieniach projektu.
2. Backend ma trasę POST /api/summarise, która czyta process.env.OPENAI_API_KEY, sprawdza, czy użytkownik jest zalogowany, i wywołuje dostawcę.
3. Przycisk wywołuje Twoją trasę, a nie dostawcę. Przeglądarka nigdy nie widzi klucza.
4. Dodajesz ten sam sekret do ustawień opublikowanej aplikacji i wdrażasz ponownie, żeby żywa strona też go miała.

Ten wzorzec — przeglądarka wywołuje Twój serwer, a serwer trzyma klucz i wywołuje usługę — dotyczy płatności, e-maili, map i każdego innego płatnego API. Przewodnik po używaniu LLM API opisuje przypadek AI dokładniej.

Kluczowe pojęcia

• Plik .env: plik tekstowy z liniami NAZWA=wartość, używany podczas lokalnego programowania. Wpisz go do .gitignore, żeby nie trafił do commita.
• .env.example: kopia zawierająca same nazwy bez prawdziwych wartości, commitowana po to, by inni wiedzieli, jakie zmienne ustawić.
• Rotacja: zastąpienie sekretu nowym i unieważnienie starego.
• Zakres / uprawnienia: wielu dostawców pozwala tworzyć klucze działające tylko w określonym zakresie. Klucz, który może wyłącznie wysyłać e-maile, jest mniej groźny niż taki, który może wszystko.
• Klucze testowe a produkcyjne: dostawcy, tacy jak Stripe, dają osobne klucze do testów i do prawdziwych pieniędzy. Używaj kluczy testowych, dopóki nie wystartujesz.
• Sekret podpisu: sekret służący do sprawdzenia, czy wiadomość, na przykład webhook, naprawdę pochodzi od nadawcy.

Typowe błędy i nieporozumienia

• „Repozytorium jest prywatne, więc klucze w nim są w porządku”. Prywatne repozytoria bywają udostępniane, forkowane, eksportowane i klonowane na laptopy. Klucze nie powinny się tam znajdować. Jeśli podłączasz projekt do GitHuba, sprawdź, czy nie ma w nim pliku .env.
• „Usunąłem to, więc zniknęło”. Git zachowuje historię, a historia czatu zachowuje wiadomości. Jeśli klucz kiedykolwiek wyciekł, zrotuj go.
• Użycie publicznego prefiksu dla sekretu. VITE_OPENAI_KEY wkłada Twój klucz do paczki kodu w przeglądarce.
• Zapomnienie o ponownym wdrożeniu. Zmiana zmiennej w ustawieniach zwykle działa dopiero po restarcie aplikacji lub ponownym opublikowaniu.
• Jeden klucz do wszystkiego. Osobne klucze do testów i produkcji oraz dla każdej aplikacji pozwalają unieważnić jeden, nie psując reszty.
• Brak limitu wydatków. Dla płatnych API ustaw budżet lub limit w panelu dostawcy na wypadek wycieku klucza.

O co poprosić kreatora AI

• „Odczytaj klucz sekretny Stripe ze zmiennej środowiskowej STRIPE_SECRET_KEY. Używaj go tylko na serwerze.”
• „Upewnij się, że żaden sekret nie jest używany w kodzie po stronie klienta i nie ma prefiksu VITE_ ani NEXT_PUBLIC_.”
• „Utwórz plik .env.example z listą wszystkich zmiennych potrzebnych aplikacji, bez wartości, i upewnij się, że .env jest ignorowany przez git.”
• „Sprawdź zbudowane pliki frontendu pod kątem ciągów znaków przypominających klucze API.”

Nasza lista kontrolna bezpieczeństwa dla aplikacji budowanych z AI obejmuje sekrety razem z innymi sprawdzeniami przed startem.

Sekrety w Mythex

W Mythex sekrety to zmienne środowiskowe projektu, wstrzykiwane zarówno do podglądu w sandboksie, jak i do opublikowanej aplikacji. Dodajesz je w ustawieniach projektu → Secrets albo poleceniem /secrets na czacie. Gdy agent potrzebuje klucza, pokazuje w czacie kartę sekretu, więc wartość trafia do pola formularza, a nie do zapisu rozmowy. Jeśli zmienisz sekret dla działającej aplikacji, opublikuj ją ponownie, żeby wdrożenie go uwzględniło. Eksporty projektów nie zawierają sekretów, a importowane pliki .env są czyszczone, więc dodajesz je ponownie w ustawieniach. Zobacz zmienne środowiskowe i sekrety oraz sekrety w czacie w dokumentacji.

Pytania