> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Halte Passwörter und Tokens aus Templates und Workflow-Dateien heraus

## Datenbankpasswort in einer Plugin-Konfiguration verwenden

Dieses Beispiel verwendet ein Template. SimpleCloud lässt die Referenz im Template stehen und setzt das Passwort in die Kopie des laufenden Servers ein, bevor der Prozess startet.

<Steps>
  <Step title="Secret erstellen">
    Öffne im Dashboard **[Settings > Secrets](https://dash.simplecloud.app/redirect?target=%2Fsettings%2Fsecrets)** und wähle **Add secret**. Trage `DATABASE_PASSWORD` als Key und das Passwort als Wert ein. Wähle danach **Encrypt & save**.

    Mindestens ein Serverhost muss verbunden sein, bevor du ein Secret hinzufügen kannst. Nach dem Speichern zeigt das Dashboard nur noch den Key an. Der Wert lässt sich dort nicht erneut anzeigen.
  </Step>

  <Step title="Referenz in das Template einfügen">
    Öffne **Files**, wähle den Serverhost aus und bearbeite die Plugin-Konfiguration im passenden [Template](/docs/de/manual/setup/templates). Lege diese Datei beispielsweise unter `templates/lobby/plugins/DatabasePlugin/config.yml` ab:

    ```yaml templates/lobby/plugins/DatabasePlugin/config.yml theme={null}
    database:
      host: "db.internal.example"
      port: 3306
      name: "minecraft"
      username: "simplecloud"
      password: "{{ secrets.DATABASE_PASSWORD }}"
    ```

    Passe den Pfad und die übrigen Einstellungen an dein Plugin an. Übernimm die Secret-Referenz genau wie gezeigt.

    Stoppe einen persistenten Server, auf dem diese Datei bereits vorhanden ist, und bearbeite seine bestehende Konfiguration über die Seite **Files** des Servers. Ein Template ersetzt keine vorhandene Datei eines persistenten Servers.
  </Step>

  <Step title="Server mit dem neuen Wert starten">
    Starte einen neuen `lobby`-Server. Wenn du einen persistenten Server bearbeitet hast, starte ihn wieder. SimpleCloud kopiert bei Bedarf das Template, ersetzt die Referenz in der laufenden Datei und startet danach den Serverprozess.

    Bereits laufende Server behalten den Wert, mit dem sie gestartet wurden.
  </Step>

  <Step title="Ergebnis prüfen">
    Prüfe, ob das Plugin die Verbindung erfolgreich herstellt. Wenn du die laufende Datei im Dashboard öffnest, zeigt der Editor weiterhin `{{ secrets.DATABASE_PASSWORD }}` statt des Passworts. Das ist beabsichtigt.
  </Step>
</Steps>

## Secrets in Configurators und Workflows verwenden

Dieselbe Referenz `{{ secrets.KEY }}` funktioniert in einem [Configurator](/docs/de/manual/configuration/configurators). Verwende sie als Wert, nicht als Teil des Pfads zur Zieldatei:

```yaml theme={null}
paths:
  - path: "plugins/DatabasePlugin/config.yml"
    type: "YML"
    data:
      database:
        password: "{{ secrets.DATABASE_PASSWORD }}"
```

Auch Workflow-Parameter können Secrets verwenden. Dieser Upload-Step liest sein Bearer-Token erst während der Ausführung. Das Token steht dadurch nicht in der [Workflow-Datei](/docs/de/manual/configuration/workflows):

```yaml theme={null}
- name: upload-backup
  uses: simplecloud/upload
  with:
    from: "{{ runtime.server-dir }}/backups/latest.zip"
    to: "https://backups.example.com/upload"
    method: "PUT"
    authorization-bearer: "{{ secrets.BACKUP_TOKEN }}"
```

Erstelle `BACKUP_TOKEN` unter **Settings > Secrets**, bevor du diesen Workflow ausführst. Die hochzuladende Datei muss bereits vorhanden sein.

## Secret rotieren oder löschen

Öffne unter **Settings > Secrets** das Aktionsmenü neben einem Key und wähle **Rotate secret**, um seinen Wert zu ersetzen. Der Key bleibt gleich, daher musst du seine Referenzen nicht ändern.

Starte alle betroffenen Server neu, damit sie den neuen Wert verwenden. Während eines Rolling Restarts können alte und neue Instanzen vorübergehend unterschiedliche Werte verwenden.

Entferne alle Referenzen, bevor du ein Secret löschst. Ein Server startet nicht, wenn eine seiner Konfigurationsdateien ein fehlendes Secret benötigt. Auch ein Workflow mit einer solchen Referenz erhält keinen Wert.

<Warning>
  SimpleCloud erstellt und verwaltet `VELOCITY_SECRET` für die sichere Proxy-Weiterleitung. Rotiere oder lösche dieses Secret nicht manuell.

  Ein geändertes Forwarding-Secret muss gleichzeitig den Proxy und alle Backend-Server erreichen. Andernfalls schlagen die Verbindungen zwischen ihnen fehl.
</Warning>

## So schützt SimpleCloud Secrets

Jeder Serverhost des Netzwerks kann jeden Key verwenden. Verwende getrennte Netzwerke, wenn Werte nicht zwischen Serverhosts geteilt werden dürfen.

Beim Speichern verschlüsselt das Dashboard den Wert in deinem Browser mit dem öffentlichen Schlüssel des Netzwerks. Der Controller speichert den verschlüsselten Wert und kann ihn nicht entschlüsseln.

Die verbundenen Serverhosts teilen sich den zugehörigen privaten Schlüssel. Sie entschlüsseln Secrets im Arbeitsspeicher, wenn ein Server oder Workflow sie benötigt.

Beim Serverstart führt SimpleCloud zuerst die konfigurierten Start-Workflows aus. Danach ersetzt es Secret-Referenzen in kopierten oder konfigurierten Textdateien und startet den Serverprozess.

Das ursprüngliche Template behält seine Referenz. SimpleCloud speichert nur die verwalteten Dateipositionen, nicht die Secret-Werte. Dadurch kann eine spätere Rotation dieselben Stellen aktualisieren.

Der laufende Server benötigt den echten Wert, daher schreibt SimpleCloud ihn in die laufende Konfigurationsdatei. Benutzer und Prozesse mit direktem Zugriff auf den Serverhost oder das Serververzeichnis können ihn lesen.

Secrets halten den Wert aus Templates und Workflow-Dateien heraus. Der Controller speichert nur verschlüsselten Text, aber die Software, die das Secret verwendet, erhält den echten Wert.

Für Keys und Werte gelten diese Grenzen:

* Ein Key beginnt mit einem Buchstaben oder Unterstrich und enthält höchstens 64 Buchstaben, Zahlen, Unterstriche oder Bindestriche. Das Dashboard wandelt neue Keys in Großbuchstaben um.
* Ein Wert darf nicht leer sein und höchstens 16 KB umfassen. Leerzeichen und Zeilenumbrüche bleiben erhalten.
* Referenzen unterscheiden zwischen Groß- und Kleinschreibung. Kopiere die unter **Settings > Secrets** angezeigte Referenz, um Abweichungen zu vermeiden.
* Verwende Referenzen in textbasierten Konfigurationsdateien. Füge sie nicht in JAR-Dateien, Welten, Datenbanken oder Archive ein.

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="Die Secrets-Seite verlangt einen Serverhost">
    Starte oder verbinde einen Serverhost erneut. Der erste verbundene Serverhost registriert den Verschlüsselungsschlüssel des Netzwerks. Danach aktiviert das Dashboard die Secret-Verwaltung.
  </Accordion>

  <Accordion title="Der Editor markiert eine Referenz als fehlend">
    Öffne **Settings > Secrets** und vergleiche den Key mit dem Text innerhalb von `{{ secrets.KEY }}`. Keys unterscheiden zwischen Groß- und Kleinschreibung. Füge den fehlenden Key hinzu oder korrigiere die Referenz, bevor du den Server startest.
  </Accordion>

  <Accordion title="Ein rotierter Wert wird nicht verwendet">
    Eine Rotation ändert keinen bereits laufenden Prozess. Starte alle betroffenen Server neu und führe alle manuellen Workflows erneut aus, die den neuen Wert verwenden sollen.
  </Accordion>

  <Accordion title="Die laufende Datei zeigt weiterhin eine Referenz">
    Der Datei-Editor und Downloads im Dashboard ersetzen verwaltete Klartextwerte durch ihre Referenz, bevor die Datei an deinen Browser gesendet wird. Prüfe stattdessen das Verhalten oder den Verbindungsstatus der Anwendung.
  </Accordion>

  <Accordion title="Ein Server startet nicht">
    Suche im Serverhost-Log nach `Missing secret` oder `Failed to apply secrets`. Erstelle den genannten Key oder entferne seine Referenz.

    Starte den Server danach erneut. Wenn ein benötigtes Secret fehlt, lässt SimpleCloud alle Secret-verwalteten Dateien unverändert.
  </Accordion>
</AccordionGroup>