Zum Hauptinhalt springen

Geheimnisverwaltung

API-Schlüssel und Tokens liegen ausschließlich in der Umgebungsvariablendatei. Die Konfigurationsdatei (settings.json) ist Klartext; wenn die Datei nach außen gelangt, sind die Schlüssel sofort offengelegt.

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

Es gibt nur eine Stelle für die Konfigurations-Wahrheit: /etc/kopens/plantpulse-studio.env

Der Pfad zur Umgebungsvariablendatei ist /etc/kopens/plantpulse-studio.env. Er liegt außerhalb des Repo-Baums – nicht im Installationsverzeichnis (/opt/kopens/plantpulse-studio-docker) –, und die Berechtigung beträgt 0600. Die drei Produkte platform · ai · studio verwenden dieselbe Konvention für /etc/kopens/plantpulse-<product>.env.

Der .env im Installationsverzeichnis-Root ist ein alter Pfad. Er wird heute von niemandem mehr gelesen; Änderungen dort beeinflussen den Stack nicht. Selbst wenn die alte Datei noch existiert, dient sie nach der Migration nur noch zu Vergleichszwecken.

Sechs Geheimnisse – was, wann​

Werte, die in .env gehören. Schlüssel für ungenutzte Funktionen können leer bleiben.

UmgebungsvariableZweckWann erforderlichOhne sie
PP_API_TOKENPlantPulse-Plattformdienst-SchlüsselFür den gesamten Abruf von Echtdaten (Standort · Anlage · Tag · Alarm)🔴 Bei Leere wird der Start abgelehnt
PI_LLM_API_KEYOpenAI-kompatibler Gateway-SchlüsselBei Nutzung des internen AI-Gateways (Standardpfad)🔴 Bei Leere wird der Start abgelehnt
PS_ANTHROPIC_API_KEYAnthropic-SchlüsselWenn der AI-Anbieter anthropic istAgent funktioniert nicht wirklich (Stub-Antworten)
OPENAI_API_KEYOpenAI-SchlüsselWenn der AI-Anbieter openai ist〃
GIT_TOKENRemote-Git-Zugriffstoken (PAT)Beim Pushing des App-Codes in das GitLab/GitHub des KundenNur die Git-Push-Funktion ist nicht verfügbar
APP_REGISTRY_TOKENApp-Image-Registry-TokenBeim Pushing der bereitgestellten Apps als Docker-ImageNur die Image-Push-Funktion ist nicht verfügbar
Andere Namen innerhalb des Containers

In Logs und Quelltext erscheinen sie als PLATFORM_API_KEY · AI_API_KEY · ANTHROPIC_API_KEY, aber der Name, den Sie in .env eintragen, ist der oben genannte. Die Zuordnungstabelle finden Sie in der Umgebungsvariablen-Referenz unter „Die zwei Ebenen der Namen".

Nur einen der AI-Schlüssel

Es genügt der Schlüssel für den im Konfigurationsbildschirm → AI-Tab gewählten Anbieter. Für Vor-Ort-Standorte, die das interne Gateway (OpenAI-kompatibel) nutzen, ist das PI_LLM_API_KEY.

Schlüssel eintragen​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PP_API_TOKEN=...
PI_LLM_API_KEY=...
# PS_ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_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 den Schlüssel nicht

docker restart plantpulse-studio-server liest .env nicht erneut. Beim Containerstart werden die zuvor injizierten Umgebungsvariablen unverändert übernommen und beim Neustart beibehalten. Nach einer Schlüsseländerung fragt man sich lange „Warum ist das noch da?" – das ist die typische Falle.

Der Container muss neu erstellt werden.

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
Nicht alles landet im Container, nur weil es in .env steht

An den Container werden nur die Variablen übergeben, die in der environment:-Liste von docker-compose.yml stehen. Die oben genannten 6 Arten sind bereits verdrahtet. Wenn Sie jedoch eine Variable neu hinzufügen, die nicht in der Tabelle steht, müssen Sie sie auch in der compose-Datei ergänzen. (Es gab einen realen Fall, in dem eine fehlende Übergabe dazu führte, dass die AI inaktiv angezeigt wurde.)

Prüfung der Übernahme​

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

Im Bildschirm erscheint in den Schlüsseleingabefeldern des Tabs Konfiguration → AI / Plattform das Badge 환경변수 기본값, und wenn im leeren Feld „Umgebungsvariablenwert wird verwendet – Eingabe überschreibt" erscheint, ist alles normal. Das Eingabefeld selbst ist nicht gesperrt – die Umgebungsvariable ist der Standardwert, der im Bildschirm überschrieben werden kann.

Priorität und Migration bestehender Installationen​

RangQuelleHinweis
1Im Bildschirm eingegebener Wert(settings.json)Wenn ein Wert vorhanden ist, gewinnt dieser
2Umgebungsvariable(/etc/kopens/plantpulse-studio.env)Standardwert, der von der Installation eingepflegt wird
Diese Reihenfolge wurde am 2026-08-23 «umgedreht»

Zuvor hatte die Umgebungsvariable Vorrang. Das führte dazu, dass ein toter Schlüssel in der env-Datei dazu führte, dass im Konfigurationsbildschirm eingegebene Werte ignoriert wurden – und es gab keinerlei Möglichkeit, das im Bildschirm zu korrigieren. Die Anforderung, den AI-Anbieter jederzeit wechseln zu können, erzwang diese neue Reihenfolge.

Deshalb müssen Sie bei einem toten Schlüssel nicht auf dem Server einloggen – geben Sie einfach den neuen Wert im Konfigurationsbildschirm ein, er überschreibt sofort. Wenn Sie die alte Reihenfolge gewohnt waren, denken Sie hier um.

Der Preis ist, dass settings.json im Klartext vorliegt (der Server erzwingt 0600, auch Backup-Archive 600/700). Wenn Sie Geheimnisse nicht in Dateien legen möchten, lassen Sie den Bildschirm leer und nutzen Sie nur die Umgebungsvariablen – dann verhält es sich wie bisher.

Auch nach einem Upgrade bricht eine bestehende Installation nicht plötzlich. Wenn jedoch Geheimnisse in der Datei verbleiben, zeigt das Boot-Log die zu verschiebenden Elemente an (Werte erscheinen nie im Log, es wird nur angezeigt, welches Element in welche Umgebungsvariable verschoben werden soll).

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

Die Migration erfolgt in drei Schritten.

  1. Den Wert in die entsprechende Umgebungsvariable von /etc/kopens/plantpulse-studio.env verschieben.
  2. bash bin/restart.sh
  3. Im Konfigurationsbildschirm prüfen, ob das Badge des Elements zu 환경변수 기본값 wechselt. Danach den alten Wert in settings.json löschen → die Boot-Warnung verschwindet.
Speicherort der settings.json

<DATA_ROOT>/state/settings.json (Standard: /var/lib/pp-studio/state/settings.json). Ein Backup vor dem Bearbeiten wird empfohlen; nach dem Bearbeiten ist ein Neustart erforderlich.

Schlüsselwechsel (Rotation)​

Für Anthropic-Schlüssel und Gateway-Schlüssel gibt es ein spezielles Tool. Es aktualisiert die Datei und erstellt den Container neu in einem Schritt, und die Werte landen nicht in der Shell-History.

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

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

Die übrigen Schlüssel (PP_API_TOKEN · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN) sind nicht im Tool enthalten; hier müssen Sie die Datei direkt bearbeiten.

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 Wechsel empfiehlt es sich, die Funktion mit einer Chat-Anfrage (Plattform-Schlüssel) und einem App-Build (AI-Schlüssel) zu überprüfen.

Automatisch angewendete Schutzmaßnahmen​

PunktVerhalten
DateiberechtigungDer Server erzwingt bei jedem Start: settings.json · Umgebungsvariablendatei auf 0600, Statusverzeichnis auf 0700.
Audit-LogBei Konfigurationsänderungen wird das geänderte Feld protokolliert – Geheimnisse erscheinen nicht als Wert, sondern nur als Fingerabdruck (erste 8 Zeichen des Hash).
BildschirmSchlüssel, die über Umgebungsvariablen verwaltet werden, sind in der Eingabe deaktiviert, um versehentliches Überschreiben zu verhindern.
Schlüssel-DienstDer Plattform-Schlüssel liegt nur im Server und wird ausschließlich für die Anfragen angemeldeter Benutzer verwendet (nicht für anonyme Anfragen).

Ausnahme – Externe MCP-Server-Tokens​

Tokens für externe MCP-Server, die der Benutzer im Konfigurationsbildschirm → MCP-Tab in beliebiger Anzahl hinzufügt, sind in ihrer Anzahl variabel und lassen sich nicht über Umgebungsvariablen ausdrücken. Sie werden daher in settings.json gespeichert. (Sie sind weniger sensibel als Plattform- oder AI-Schlüssel.)

Was zu beachten ist​

Nicht zu tun
  • Die Umgebungsvariablendatei · settings.json nicht in die Versionsverwaltung (Git) committen. Genau dafür liegt die Wahrheit außerhalb des Repo-Baums (/etc/kopens/).
  • Schlüssel nicht in Chat, E-Mail oder Tickettexte einfügen.
  • Backup-Archive nicht ohne Berechtigung teilen – siehe die Hinweise zu Backup und Wiederherstellung.
Falls ein Schlüssel kompromittiert wurde

Zuerst bei der ausgebenden Stelle (Plattform · AI-Anbieter · Git · Registry) den Schlüssel widerrufen, dann einen neuen ausstellen und anschließend die obige Prozedur „Schlüsselwechsel" durchführen. Bis zum Serverneustart bleibt der alte Schlüssel im Speicher.

Zugehörige Dokumentation​