Zum Hauptinhalt springen

Geheimnisse verwalten

API-Schlüssel und Token gehören ausschließlich in die Umgebungsvariablendatei. Konfigurationsdateien (settings.json) sind Klartext, daher würden Schlüssel bei einem Datenleck direkt offengelegt.

Dieses Prinzip gilt ab Release 2026.07; bestehende Installationen funktionieren weiterhin (siehe unten „Migration bestehender Installationen").

Die Quelle der Wahrheit ist /etc/kopens/plantpulse-studio.env

Der Pfad der Umgebungsvariablendatei ist /etc/kopens/plantpulse-studio.env. Sie liegt außerhalb des Repo-Baums, nicht im Installationsverzeichnis (/opt/kopens/plantpulse-studio-docker), und die Berechtigung ist 0600. Die drei Produkte Platform, AI und Studio verwenden nach derselben Konvention /etc/kopens/plantpulse-<product>.env.

.env im Stammverzeichnis der Installation ist der alte Pfad. Derzeit liest ihn niemand mehr, daher ändern Sie dort nichts — der Stack wird nicht beeinflusst. Wenn die alte Datei noch vorhanden ist, dient sie nach der Migration nur noch zum Abgleich.

Sechs Geheimnistypen — was, wann​

Werte, die in .env eingegeben werden. Sie können Schlüssel für ungenutzte Funktionen leer lassen.

UmgebungsvariableZweckWann erforderlichOhne diese
PLATFORM_API_KEYPlantPulse Platform-DienstschlüsselVor dem Abrufen von Live-Daten (Standort, Anlage, Tag, Alarm)Echte Daten werden in Chat-Abfragen und Bereitstellungs-Apps nicht abgerufen
ANTHROPIC_API_KEYAnthropic-SchlüsselWenn der AI-Anbieter anthropic istAgent funktioniert nicht wirklich (Stub-Antwort)
OPENAI_API_KEYOpenAI-SchlüsselWenn der AI-Anbieter openai istIdem
AI_API_KEYOpenAI-kompatibler Gateway-SchlüsselWenn Sie ein unternehmensinternes AI-Gateway verwendenIdem
GIT_TOKENRemote-Git-Zugriffstoken (PAT)Beim Pushen von App-Quellen zu unternehmenseigenem GitLab/GitHubNur die Git-Push-Funktion ist nicht verfügbar
APP_REGISTRY_TOKENToken für App-Image-RegistryBeim Pushen bereitgestellter Apps als Docker-ImageNur die Image-Push-Funktion ist nicht verfügbar
Nur einer von drei AI-Schlüsseln

Sie benötigen nur einen Schlüssel für den Anbieter, den Sie in Einstellungen → AI-Registerkarte auswählen. Wenn Ihr Vor-Ort-Einsatz ein unternehmensinternes Gateway (OpenAI-kompatibel) verwendet, ist es AI_API_KEY.

Schlüssel eingeben​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PLATFORM_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# AI_API_KEY=
# GIT_TOKEN=
# APP_REGISTRY_TOKEN=
sudo chmod 600 /etc/kopens/plantpulse-studio.env
cd /opt/kopens/plantpulse-studio-docker && bash bin/restart.sh
docker restart ändert die Schlüssel nicht

docker restart pp-studio-server liest .env nicht erneut. Beim Erstellen des Containers werden die alte Umgebungsvariablen, die beim Injizieren gespeichert wurden, einfach bei Neustart beibehalten. Das ist ein klassischer Fallstrick: Sie ändern die Schlüssel und fragen sich lange, warum sich nichts ändert.

Sie müssen den Container neu erstellen.

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
Was in .env eingegeben wird, gelangt nicht automatisch in den Container

Der Container erhält nur die Variablen, die in der environment:-Liste von docker-compose.yml aufgeführt sind. Die sechs oben genannten Schlüssel sind bereits verbunden, aber wenn Sie eine neue Variable hinzufügen, die nicht in der Tabelle aufgeführt ist, müssen Sie sie auch in der Compose-Datei hinzufügen. (Es gibt echte Beispiele, bei denen AI aufgrund fehlender Übertragung inaktiv war.)

Bestätigung der Anwendung​

# 서버가 인식한 키 출처 확인 — 부팅 로그
docker logs pp-studio-server 2>&1 | head -40

Auf dem Bildschirm sollte das Schlüsseleingabefeld unter Einstellungen → AI / Platform deaktiviert sein und „Wird durch Umgebungsvariablen verwaltet" angezeigt werden.

Priorität und Migration bestehender Installationen​

PrioritätQuelleAnmerkung
1Umgebungsvariablen (/etc/kopens/plantpulse-studio.env)Wenn vorhanden, gewinnt diese immer
2settings.jsonLegacy-Fallback — für Kompatibilität alter Installationen

Nach einem Upgrade brechen bestehende Installationen nicht plötzlich zusammen. Wenn jedoch noch Geheimnisse in Dateien vorhanden sind, informiert Sie das Boot-Protokoll über die zu migrierenden Werte (Werte werden niemals protokolliert, nur welche Elemente in welche Umgebungsvariablen verschoben werden müssen).

settings.json 에 비밀이 남아 있습니다 — … platform.apiKey → PLATFORM_API_KEY

Die Migration erfolgt in drei Schritten:

  1. Verschieben Sie den Wert in die entsprechende Umgebungsvariable in /etc/kopens/plantpulse-studio.env
  2. bash bin/restart.sh
  3. Überprüfen Sie auf dem Einstellungsbildschirm, dass das Element mit „Wird durch Umgebungsvariablen verwaltet" gekennzeichnet ist, löschen Sie dann den alten Wert in settings.json → Die Boot-Warnung verschwindet
Position von settings.json

<DATA_ROOT>/state/settings.json (Standard: /var/lib/pp-studio/state/settings.json). Sicherung vor der Bearbeitung empfohlen; nach der Bearbeitung ist ein Neustart erforderlich.

Schlüsselaustausch (Rotation)​

Für ANTHROPIC_API_KEY und AI_API_KEY gibt es ein dediziertes Tool. Es aktualisiert Dateien und erstellt Container in einem Arbeitsschritt neu, und Werte werden nicht in der Shell-Verlauf gespeichert.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                    # ① 되돌릴 지점 확보
bin/passwd.sh ANTHROPIC_API_KEY       # ② 값 생략 → 프롬프트로 입력
bash bin/status.sh                    # ③ 헬스 확인

Die detaillierte Anleitung finden Sie unter Passwort · API-Schlüssel ändern.

Die verbleibenden Schlüssel (PLATFORM_API_KEY · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN) sind kein Tool-Ziel — Sie bearbeiten die Datei direkt.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                              # ① 되돌릴 지점 확보
sudo vi /etc/kopens/plantpulse-studio.env       # ② 새 키로 교체
bash bin/restart.sh                             # ③ 컨테이너 재생성
bash bin/status.sh                              # ④ 헬스 확인

Nach dem Austausch ist es sinnvoll, die Funktionalität mit einer Chat-Abfrage (Plattformschlüssel überprüfen) und einem App-Build (AI-Schlüssel überprüfen) zu überprüfen.

Automatisch angewendete Schutzmaßnahmen​

ElementVerhalten
DateiberechtigungenDer Server erzwingt beim Booten settings.json und die Umgebungsvariablendatei auf 0600, das Zustandsverzeichnis auf 0700
Audit-LogWenn Einstellungen geändert werden, wird das geänderte Feld protokolliert — das Geheimnis wird nur als Fingerabdruck (erste 8 Zeichen des Hash) statt Wert erfasst
BildschirmVon Umgebungsvariablen verwaltete Schlüssel sind deaktiviert und können nicht versehentlich überschrieben werden
SchlüsselvermittlungDer Platform-Schlüssel befindet sich nur auf dem Server und wird nur an Anfragen authentifizierter Benutzer angehängt (nicht an anonyme Anfragen)

Ausnahme — MCP-Token für externe Server​

Token für externe MCP-Server, die Benutzer beliebig oft im Tab Einstellungen → MCP hinzufügen, können nicht durch Umgebungsvariablen ausgedrückt werden, da die Anzahl variabel ist; sie werden in settings.json gespeichert. (Dies sind weniger sensible Werte als Platform- und AI-Schlüssel.)

Was Sie beachten sollten​

Was Sie nicht tun sollten
  • Committen Sie die Umgebungsvariablendatei oder settings.json nicht in die Versionskontrolle (Git). Der Grund, warum die Quelle der Wahrheit außerhalb des Repo-Baums liegt (/etc/kopens/), ist genau dieser.
  • Fügen Sie Schlüssel nicht in Chat-, Email- oder Ticketmeldungen ein.
  • Teilen Sie Backup-Archive nicht ohne Berechtigung — siehe Sicherung und Wiederherstellung für den Umgang damit.
Falls es sich um Offenlegung handelt

Löschen Sie den Schlüssel zuerst bei der Ausstellungsstelle (Platform, AI-Anbieter, Git, Registry) und geben Sie einen neuen Schlüssel aus. Führen Sie dann das obige Verfahren „Schlüsselaustausch" durch. Der alte Schlüssel verbleibt im Speicher bis zum Server-Neustart.

Verwandte Dokumentation​