Was sind Umgebungsvariablen und Secrets? Ein einfacher Leitfaden

Eine Umgebungsvariable ist eine benannte Einstellung, etwa DATABASE_URL oder STRIPE_SECRET_KEY, die deiner App beim Start übergeben wird, statt im Code zu stehen. Ein Secret ist eine Umgebungsvariable, deren Wert privat bleiben muss: ein API-Schlüssel, ein Passwort oder ein Signierschlüssel. Wenn du diese Werte außerhalb des Codes hältst, kannst du sie ändern, ohne die App anzufassen, für Tests und echte Kundschaft unterschiedliche Werte verwenden und verhinderst, dass sie beim Teilen oder Veröffentlichen deines Codes durchsickern.

Warum das beim Bauen mit KI wichtig ist

Sobald deine App etwas Sinnvolles mit einem anderen Dienst macht, also eine Zahlung abwickelt, eine E-Mail verschickt oder ein KI-Modell aufruft, braucht sie einen Schlüssel. KI-App-Builder fragen regelmäßig danach, und wo der Schlüssel landet, entscheidet darüber, ob deine App sicher ist.

Bei KI-gebauten Apps gehen zwei Dinge häufig schief:

• Der Schlüssel wird in den Chat oder in den Code eingefügt. Dann liegt er im Chatverlauf, in den Projektdateien und in jedem Export oder Repository. Wer ihn sieht, kann dein Konto nutzen.
• Der Schlüssel wird im Browser verwendet. Läuft der Code, der Stripe oder OpenAI aufruft, auf der Seite, wird der Schlüssel an jede Besucherin und jeden Besucher gesendet. Das passiert tatsächlich, und automatische Scanner suchen ständig nach offenliegenden Schlüsseln.

Wer Umgebungsvariablen versteht, erkennt beide Probleme und kann die Korrektur gezielt anfordern.

Ein Alltagsvergleich: der Hotelsafe

Der Code deiner App ist wie das Hotelzimmer. Gäste, Reinigungskräfte und alle, denen du eine Keycard gibst, gehen hindurch. Du würdest deinen Reisepass auch nicht auf dem Schreibtisch liegen lassen.

Umgebungsvariablen sind der Safe im Zimmer. Das Zimmer weiß, dass es einen Safe gibt und wie er sich öffnen lässt, aber der Pass liegt nicht herum. Und wenn du von einem Zimmer in ein anderes wechselst, etwa von deinem Testaufbau auf deine Live-Seite, legst du einfach einen anderen Pass in den Safe dieses Zimmers, ohne neu einzurichten.

So funktioniert es

Dein Code verweist auf einen Namen, nicht auf einen Wert. In JavaScript auf einem Server sieht das so aus: process.env.STRIPE_SECRET_KEY. Beim Start der App setzt die Plattform, auf der sie läuft, den Wert für diesen Namen ein. Änderst du den Wert in den Einstellungen der Plattform und startest neu oder veröffentlichst erneut, verwendet die App den neuen Wert, ganz ohne Codeänderung.

Woher die Werte kommen, hängt davon ab, wo die App läuft:

Öffentliche und geheime Variablen

Nicht jede Umgebungsvariable ist geheim. Es hilft, sie in zwei Gruppen einzuteilen:

Web-Frameworks machen diese Trennung ausdrücklich. In Vite werden nur Variablen, deren Name mit VITE_ beginnt, in den Browser-Code aufgenommen. In Next.js lautet das Präfix NEXT_PUBLIC_. Das ist eine Sicherheitsfunktion: Alles mit diesen Präfixen landet in den Dateien, die jede Besucherin und jeder Besucher herunterlädt. Ein Secret darf deshalb niemals ein solches Präfix bekommen.

Ein Beispiel: ein KI-Zusammenfassungs-Button

Du möchtest einen Button „Notiz zusammenfassen“, der ein KI-Modell aufruft.

Die unsichere Variante: Der Code des Buttons läuft im Browser und ruft den KI-Anbieter direkt auf, mit dem API-Schlüssel fest im Code. In der Vorschau funktioniert das. Gleichzeitig kann jeder die Entwicklertools des Browsers öffnen, den Schlüssel kopieren und deine Rechnung hochtreiben.

Die sichere Variante:

1. Du erstellst den Schlüssel beim KI-Anbieter und speicherst ihn in deinen Projekteinstellungen als Secret, etwa mit dem Namen OPENAI_API_KEY.
2. Das Backend bekommt eine Route, POST /api/summarise, die process.env.OPENAI_API_KEY liest, prüft, ob die Nutzerin oder der Nutzer angemeldet ist, und den Anbieter aufruft.
3. Der Button ruft deine Route auf, nicht den Anbieter. Der Browser sieht den Schlüssel nie.
4. Du trägst dasselbe Secret in den Einstellungen der veröffentlichten App ein und veröffentlichst erneut, damit auch die Live-Seite es hat.

Dieses Muster, bei dem der Browser deinen Server aufruft und dein Server den Schlüssel hält und den Dienst aufruft, gilt für Zahlungen, E-Mails, Kartendienste und jede andere kostenpflichtige API. Der Leitfaden zur Nutzung von LLM-APIs behandelt den KI-Fall ausführlicher.

Wichtige Begriffe

• .env-Datei: eine Textdatei mit Zeilen der Form NAME=wert, die in der lokalen Entwicklung verwendet wird. Trage sie in .gitignore ein, damit sie nicht committet wird.
• .env.example: eine Kopie mit den Namen, aber ohne echte Werte, die committet wird, damit andere wissen, welche Variablen sie setzen müssen.
• Rotieren: ein Secret durch ein neues ersetzen und das alte widerrufen.
• Umfang / Berechtigungen: Viele Anbieter lassen dich Schlüssel erstellen, die nur bestimmte Aktionen dürfen. Ein Schlüssel, der nur E-Mails versenden kann, ist weniger gefährlich als einer, der alles darf.
• Test- vs. Live-Schlüssel: Anbieter wie Stripe geben dir getrennte Schlüssel für Tests und für echtes Geld. Nutze bis zum Start die Testschlüssel.
• Signierschlüssel: ein Secret, mit dem geprüft wird, dass eine Nachricht, etwa ein Webhook, tatsächlich vom Absender stammt.

Häufige Fehler und Missverständnisse

• „Mein Repository ist privat, also sind Schlüssel darin in Ordnung.“ Private Repositories werden geteilt, geforkt, exportiert und auf Laptops geklont. Schlüssel gehören trotzdem nicht hinein. Wenn du ein Projekt mit GitHub verbindest, prüfe, dass keine .env-Datei enthalten ist.
• „Ich habe ihn gelöscht, also ist er weg.“ Git speichert die Historie, und Chatprotokolle speichern Nachrichten. Wenn ein Schlüssel jemals offengelegt wurde, rotiere ihn.
• Ein öffentliches Präfix bei einem Secret. VITE_OPENAI_KEY legt deinen Schlüssel ins Browser-Bundle.
• Vergessen, neu zu veröffentlichen. Eine Änderung einer Variable in den Einstellungen wirkt meist erst, wenn die App neu startet oder erneut veröffentlicht wird.
• Ein Schlüssel für alles. Getrennte Schlüssel für Test und Live sowie pro App machen es möglich, einen zu widerrufen, ohne die anderen zu brechen.
• Kein Ausgabenlimit. Stelle für kostenpflichtige APIs im Dashboard des Anbieters ein Budget oder Limit ein, falls ein Schlüssel durchsickert.

Was du von deinem KI-Builder verlangen solltest

• „Lies den geheimen Stripe-Schlüssel aus einer Umgebungsvariable namens STRIPE_SECRET_KEY. Verwende ihn nur auf dem Server.“
• „Stelle sicher, dass kein Secret im clientseitigen Code verwendet wird und keines ein Präfix VITE_ / NEXT_PUBLIC_ bekommt.“
• „Erstelle eine .env.example, die jede Variable auflistet, die die App braucht, ohne Werte, und stelle sicher, dass .env von Git ignoriert wird.“
• „Prüfe die gebauten Frontend-Dateien auf Zeichenketten, die wie API-Schlüssel aussehen.“

Unsere Sicherheitscheckliste für KI-gebaute Apps behandelt Secrets zusammen mit den anderen Prüfungen, die sich vor dem Start lohnen.

Secrets bei Mythex

Bei Mythex sind Secrets Umgebungsvariablen des Projekts, die sowohl in die Vorschau-Sandbox als auch in deine veröffentlichte App eingespielt werden. Du fügst sie unter Projekteinstellungen → Secrets hinzu oder mit /secrets im Chat. Braucht der Agent einen Schlüssel, zeigt er eine Secrets-Karte im Chat, sodass der Wert in ein Formularfeld geht und nicht in den Nachrichtenverlauf. Änderst du ein Secret für eine Live-App, veröffentliche erneut, damit die Bereitstellung es übernimmt. Projektexporte lassen Secrets aus, und importierte .env-Dateien werden bereinigt, sodass du die Werte in den Einstellungen erneut eintragen musst. Siehe Umgebungsvariablen und Secrets und Secrets im Chat in der Dokumentation.

Fragen