Passwort · API-Schlüssel ändern
PlantPulse AI nutzt ein Graphspeicher-Konto (Neo4j) und einige API-Schlüssel, die interne Services verbinden.
Ab 2026.09 erzeugt der Installer interne API-Schlüssel bei jeder Installation neu (nur wenn ein Platzhalter vorliegt). Ab 2026.10 werden auch die beiden Verschlüsselungsschlüssel für gespeicherte Zugangsdaten (PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY) bei der Erstinstallation miterzeugt. Das
Neo4j-Passwort wird nicht automatisch erzeugt, es muss bei der Installation gesetzt werden (bleibt der Platzhalter stehen, verweigert START=1 den Start).
Danach ändert man sie gemäß diesem Dokument, wenn ein Leck vermutet wird oder Personalwechsel stattfindet.
Das Werkzeug zum Ändern ist einheitlich bin/passwd.sh. Die drei Produkte platform · ai · studio verwenden es mit demselben Namen,
derselben Bedienung.
/etc/kopens/plantpulse-ai.envDie Geheimnisse dieses Produkts liegen in /etc/kopens/plantpulse-ai.env. Nicht im Installationsverzeichnis, sondern
außerhalb des Repo-Baums, mit den Rechten 0600.
🔴 Bearbeiten Sie compose/.env nicht. Das liest niemand — der Stack ändert sich dadurch nicht.
Die Datei, in die passwd.sh schreibt, und die Datei, die das Skript zum Hochfahren des Stacks liest, sind ein und dieselbe.
Deshalb wirken rotierte Werte sofort.
Das ist etwas anderes als Anwendungskonten
Diese beiden Dinge sollten Sie nicht vermischen.
| Was | Wo ändern | |
|---|---|---|
| Anwendungskonto | Konto, mit dem sich Menschen anmelden | Wird im Admin-Bildschirm der jeweiligen App verwaltet |
| Infrastruktur · API-Schlüssel | DB-Konten, Authentifizierungsschlüssel zwischen Services | Dieses Dokument — bin/passwd.sh |
Dieses Dokument behandelt nur den zweiten Teil, die Infrastruktur-Credentials.
Was lässt sich ändern
Zunächst die Liste ansehen. Ohne Argumente ausgeführt zeigt es dasselbe.
cd /opt/kopens/plantpulse-ai-docker
bin/passwd.sh --list
Angezeigt werden Schlüssel · ID · aktueller Wert (nur die ersten 3 Zeichen) · Ziel · wo dieser Wert liegt.
Wenn Sie den vollständigen Wert sehen müssen, ist das --list --show.
| Schlüssel | Was | Wie geändert wird |
|---|---|---|
PI_NEO4J_PASSWORD | Neo4j — LightRAG-Wissensgraph und Spiegel des Werksgraphen, beide Instanzen | Das Serverkonto ist maßgeblich — bei beiden Instanzen via ALTER USER (cypher-shell) |
PI_RAG_API_KEY | RAG-API-Schlüssel — gemeinsam genutzt von copliot-web · lightrag · rag-api | Datei |
PI_VLLM_API_KEY | vLLM-API-Schlüssel — gemeinsam genutzt von lightrag · insight-api | Datei |
PI_LLM_API_KEY | LiteLLM-Master-Key | Datei |
PI_LITELLM_SALT_KEY | LiteLLM-Salt-Key — 🔴 nicht rotieren (siehe unten) | Datei |
PI_INBOUND_API_KEY | Eingehender Backend-Schlüssel — empfangen von rag · insight · parser · vision · Digital Thread (ist er leer, verweigern alle fünf den Start), aufgerufen von Copilot · Admin-Console-Backend mit demselben Wert | Datei |
Die Schlüsselnamen entsprechen genau den Namen der Umgebungsvariablen. Es gibt keine Aliasnamen wie neo4j oder rag — denn mit Aliasen
müsste man eine separate Tabelle pflegen, die Namen und Variablen verknüpft, und diese Tabelle würde zwangsläufig von der Realität abweichen.
PI_Die Namensgebung wurde einmalig bereinigt (2026-08-27). Es gibt keinen Fallback — wird ein alter Name übergeben,
wird er mit unknown key abgelehnt — wie ein Tippfehler behandelt (bei ähnlichen Namen wird ein Vorschlag gemacht).
| Alter Name | Neuer Name |
|---|---|
DOCKER_NEO4J_PASSWORD | PI_NEO4J_PASSWORD |
RAG_API_KEY | PI_RAG_API_KEY |
VLLM_API_KEY | PI_VLLM_API_KEY |
LITELLM_MASTER_KEY | PI_LLM_API_KEY |
LITELLM_SALT_KEY | PI_LITELLM_SALT_KEY |
PP_INBOUND_API_KEY | PI_INBOUND_API_KEY |
Innerhalb der Container erscheinen sie unter unterschiedlichen, servicespezifischen Namen (CO_INBOUND_API_KEY · TS_INBOUND_API_KEY …),
aber der Betreiber hat es nur mit den sechs oben genannten Werten zu tun. Compose verteilt einen Wert auf mehrere Namen.
Ist er leer, greift eine doppelte Sperre. Die Vorab-Prüfung beim Start (bin/lint-env.sh) fährt den Stack dann nicht hoch mit PI_INBOUND_API_KEY is empty …,
und auch die Backend-Services (rag · insight · parser · vision · Digital Thread) verweigern den Start, wenn ihr eigener Schlüssel leer ist (früher ließ man sie ohne Authentifizierung
durchlaufen). Ein Start ohne Authentifizierung ist nur möglich, wenn absichtlich der Entwicklungsschalter PI_INBOUND_AUTH_DISABLED=true gesetzt wird, und ist ein Schlüssel vorhanden,
wird dieser Schalter ignoriert → Umgebungsvariablen konfigurieren
Der Platzhalter CHANGE_ME_… gilt jedoch nicht als leerer Wert und besteht diese Prüfung, und dieser String ist bei jeder Installation identisch. Beim Ändern
unbedingt einen neuen Wert eintragen (empfohlen: --generate), und mit --list prüfen, ob der Wert übernommen wurde. passwd.sh fährt nach dem Ändern der Datei den gesamten
Stack neu hoch, sodass Empfänger und Aufrufer dieses Schlüssels gleichzeitig auf den neuen Wert umgestellt werden.
PP_* gehört nicht hierherPP_PG_PASSWORD · PP_CASSANDRA_PASSWORD · PP_REDIS_PASSWORD sind PP_*, also Plattform-Credentials, und können in diesem
Produkt nicht geändert werden (es fehlt die Berechtigung, die Serverseite zu ändern). Sie stehen auch nicht in der Liste, und werden sie übergeben,
werden sie wie ein Tippfehler abgelehnt. Das Präfix zeigt den Eigentümer — PP_ = Plattform, PI_ = AI.
Ab 2026.10 erhalten Container Plattformkonto · Passwort beim Start von der Plattform → Umgebungsvariablen
konfigurieren. Nach einer Änderung auf Plattformseite mit bin/passwd.sh genügt es daher, den entsprechenden
AI-Container neu zu starten (bin/restart.sh), damit der neue Wert übernommen wird. Auch Host-Skripte wie die DB-Provisionierung vor dem Start
holen sich den Wert bei jeder Ausführung neu von der Plattform, es gibt also auf AI-Seite nichts anzupassen — in der Host-env stehen keine Zeilen
für Plattformkonto · Passwort. Finden sich bei alten Installationen noch Zeilen mit PP_PG_* · PP_CASSANDRA_* · PP_REDIS_PASSWORD, werden sie nicht gelesen, und die Vorab-Prüfung
weist darauf hin, sie zu löschen.
Die beiden Plattform-Geheimnisse, die in der Host-env verbleiben, sind PP_DATALAKE_ADMIN_API_KEY (Schlüssel zum Beziehen der Credentials) und PP_API_TOKEN (Plattform-V5-API).
Ändert sich einer dieser Werte auf Plattformseite, muss die entsprechende Zeile in /etc/kopens/plantpulse-ai.env von Hand angepasst und mit bin/restart.sh
neu erzeugt werden.
Admin Console (PI_ADMIN_USER · PI_ADMIN_PASSWORD) und der LiteLLM-Admin-Bildschirm (PI_LITELLM_UI_USERNAME ·
PI_LITELLM_UI_PASSWORD) stehen nicht in der passwd.sh-Liste. Ändern Sie die Umgebungsdatei und erzeugen Sie
mit bin/up.sh neu → Erstes Passwort ändern
Durchführung
Empfohlen ist, den Wert wegzulassen und ihn per Prompt einzugeben. So bleibt das Passwort nicht in der ps-Ausgabe oder
der Shell-History stehen. Die Eingabe erfolgt zweifach zum Abgleich.
bin/passwd.sh PI_INBOUND_API_KEY
Der Wert kann auch direkt als Argument übergeben werden.
bin/passwd.sh PI_RAG_API_KEY=<new-value>
Werden mehrere Schlüssel auf einmal übergeben, erfolgt nur ein Neustart. Nutzen Sie diese Form bei der Inbetriebnahme.
bin/passwd.sh PI_VLLM_API_KEY=<new-value> PI_LLM_API_KEY=<new-value>
Werte vom Tool erzeugen lassen — --generate
Bei Schlüsseln, deren Wert nicht von Menschenhand festgelegt werden muss, ist es am sichersten, das Tool sie erzeugen zu lassen. Da nichts eingegeben
wird, bleibt nichts in Shell-History · ps zurück, und es wird nach denselben Regeln erzeugt wie beim Installer (Länge · Serien-Präfix).
bin/passwd.sh --generate PI_INBOUND_API_KEY PI_RAG_API_KEY
Der erzeugte Wert verrät am Anfang, zu welcher Schlüsselserie er gehört. Selbst wenn in Logs oder Konfigurationsbildschirmen nur ein Fragment sichtbar ist, lässt sich erkennen, worum es sich handelt, und ein versehentlich falsch eingefügter Wert fällt auf. Das Präfix ist kein Geheimnis, und die Länge des darauffolgenden Zufallsteils wird dadurch nicht verkürzt.
| Schlüssel | Präfix |
|---|---|
PI_INBOUND_API_KEY | ppin_ |
PI_VLLM_API_KEY | ppvl_ |
PI_RAG_API_KEY | pprg_ |
PI_LLM_API_KEY | sk-pplm_ |
PI_ADMIN_SESSION_SECRET | ppss_ (nur der Installer erzeugt ihn — steht nicht in der passwd.sh-Liste) |
Bei manchen Schlüsseln verweigert --generate die Erzeugung.
PI_LITELLM_SALT_KEY— ist kein Schlüssel, sondern ein Salt (siehe unten)PI_NEO4J_PASSWORDu. a. — Schlüssel ohne Erzeugungsregel: Wert direkt angeben oder per Prompt eingebenPI_ADMIN_PASSWORD·PP_*— Menschen melden sich mit diesem Wert an, oder er muss mit einem von der Plattform vorgegebenen Wert übereinstimmenPI_COPILOT_SECRET_KEY·PI_DT_SECRET_KEY— stehen nicht in der Liste. Ein zufälliger Austausch entspricht dem Verwerfen der gespeicherten Werte (siehe unten „Verschlüsselungsschlüssel für gespeicherte Credentials")
Um nur zu sehen, was sich ändern würde, ohne etwas zu berühren, nutzen Sie --dry-run.
bin/passwd.sh --dry-run PI_RAG_API_KEY=<new-value>
Bei Ausführung werden zunächst die zu ändernden Punkte und ihre Auswirkungen angezeigt, und die Bestätigung erfolgt über [y/N]. Um die
Bestätigung in Automatisierungen zu überspringen, nutzen Sie --yes.
In Umgebungen ohne Terminal, etwa Skripte oder Cron, endet es bei fehlendem Wert mit einem Fehler, da kein Prompt angezeigt werden kann.
Übergeben Sie den Wert in diesem Fall im Format KEY=<value>.
PI_LITELLM_SALT_KEY bricht bei Rotation «lautlos»Dieser Wert ist der Schlüssel, mit dem die im Admin-Console-Bildschirm Modellregistrierung eingegebenen API-Schlüssel externer Anbieter in der
Gateway-DB verschlüsselt werden. Eine Änderung verschlüsselt bereits gespeicherte Werte nicht erneut — der Container startet als healthy, die Modellliste
bleibt unverändert, aber nur die Aufrufe dieser Modelle schlagen fehl. passwd.sh zeigt vor der Bestätigung eine Warnung an, wenn Sie versuchen, diesen
Schlüssel zu ändern. Legen Sie ihn einmal bei der Installation fest und nehmen Sie ihn ins Backup auf.
Was bei der Ausführung passiert
Die Reihenfolge ist festgelegt.
| Schritt | Was passiert |
|---|---|
| 1 | Zuerst das maßgebliche Serverkonto — bei PI_NEO4J_PASSWORD wird das Konto zuerst bei beiden Neo4j-Instanzen geändert. Vor der Änderung wird geprüft, ob beide mit dem aktuellen Wert erreichbar sind; ist auch nur eine nicht erreichbar, wird nichts geändert und abgebrochen |
| 2 | /etc/kopens/plantpulse-ai.env wird mit dem neuen Wert aktualisiert (Rechte 0600 bleiben erhalten) |
| 3 | docker compose up -d --wait — Services werden neu erzeugt, um den neuen Wert zu übernehmen (compose-Datei und Umgebungsdatei werden explizit angegeben, daher funktioniert es unabhängig vom Ausführungsverzeichnis gleich) |
Die Reihenfolge ist: zuerst Serverseite ändern, dann Dateien angleichen. Umgekehrt bliebe die Authentifizierung bis zum Neustart defekt, da der Server noch den alten, die Datei aber bereits den neuen Wert hätte.
Während dieser Zeit ist der AI-Pfad unterbrochen. Führen Sie dies in einem Wartungsfenster durch.
Bei Fehlschlag mittendrin
| Wo | Zustand | Was zu tun ist |
|---|---|---|
| Schritt 1 (Neo4j-Kontoänderung) | Dateien werden nicht angefasst, Abbruch. Wurde bei der ersten Instanz geändert, bei der zweiten aber fehlgeschlagen, wird der Name der bereits geänderten Instanz ausgegeben | Mit bin/status.sh prüfen, ob plantpulse-neo4j · plantpulse-digital-thread-neo4j erreichbar sind. Wurde nur eine Seite geändert, diese auf den alten Wert zurücksetzen (ALTER CURRENT USER) und erneut ausführen |
| Schritt 3 (Neustart) | Die Dateien enthalten bereits den neuen Wert | Mit bin/status.sh den Status prüfen und die Ursache des Startfehlers beheben |
Verschlüsselungsschlüssel für gespeicherte Credentials — Austausch über _PREVIOUS
PI_COPILOT_SECRET_KEY (Copilot) · PI_DT_SECRET_KEY (Digital-Thread-Connector-Registry) sind die Schlüssel, mit denen im Bildschirm eingegebene
Credentials (Authentifizierungswerte externer Connectoren · LLM-Schlüssel · SMTP-Passwort · Slack-Webhook · Web-Push-Private-Key, Connector-Credentials)
in der DB versiegelt werden. Sie stehen nicht in der passwd.sh-Liste — wird nur der neue Wert eingetragen, lässt sich das mit dem alten Wert
Versiegelte nicht mehr entschlüsseln. Der Austausch erfolgt über ein Verfahren, bei dem der alte Wert mitgegeben wird, um «neu zu versiegeln».
| Schritt | Was passiert |
|---|---|
| 1 | Den alten Wert in PI_COPILOT_SECRET_KEY_PREVIOUS ablegen (mehrere, kommagetrennt, möglich), den neuen Wert (openssl rand -base64 32) in PI_COPILOT_SECRET_KEY |
| 2 | bin/restart.sh plantpulse-copilot-web — beim Start werden die gespeicherten Werte mit dem neuen Schlüssel neu versiegelt. Die Anzahl lässt sich im Log an [SECRETS] sealed at rest … ablesen |
| 3 | PI_COPILOT_SECRET_KEY_PREVIOUS leeren und erneut neu erzeugen |
PI_DT_SECRET_KEY funktioniert ebenso — alten Wert in PI_DT_SECRET_KEY_PREVIOUS ablegen, plantpulse-digital-thread-api
neu erzeugen und danach leeren.
Wurde der Schlüssel geändert, aber der alte Wert fehlt, verweigert Copilot den Start mit Stored secrets cannot be decrypted
und protokolliert die versiegelten Zeilen sowie das SQL, um sie zu leeren — es startet nicht stillschweigend ohne Authentifizierung. Ist der Schlüssel
verloren, bleibt nur, die Credentials erneut im Bildschirm einzugeben. Prüfen Sie, ob diese beiden Werte im env-Backup enthalten sind.
Prüfung
bin/passwd.sh --list
Haben sich die ersten 3 Zeichen des aktuellen Werts geändert, wurde die Änderung übernommen. Die ersten 3 Zeichen werden angezeigt, damit auf einen Blick erkennbar ist, ob noch der Standardwert gilt.
Zugehörige Dokumente
- Umgebungsvariablen konfigurieren — vollständige Liste der Konfigurationsvariablen
- Servicebetrieb — Start · Stopp · Statusprüfung
- Datenbankverwaltung — Betrieb von Neo4j · PostgreSQL · Qdrant