Workflows

Was Workflows sind

Workflows sind YAML-Dateien, die der Serverhost während der Vorbereitung oder beim Cleanup eines Servers ausführt. Sie kopieren Template-Dateien, laden konfigurierte Plugins herunter, wenden Configurators an, verwalten Cache-Dateien und entfernen temporäre Laufzeitverzeichnisse. Workflow-Dateien liegen in workflows/. Die Workflow-ID besteht aus Namespace und Dateiname ohne .yml, zum Beispiel internal/setup für workflows/internal/setup.yml.

Standard-Workflows

Jeder Serverhost erstellt beim ersten Start die Standard-Workflow-Dateien:

Workflow	Zweck
`internal/setup`	Bereitet ein Serververzeichnis vor, bevor der Prozess startet
`internal/cleanup`	Kopiert Cache- und Log-Daten und entfernt temporäre Verzeichnisse dynamischer Server

Servergruppen und persistente Server speichern ihre Workflows in der Basiskonfiguration:

workflows:
  when:
    start:
      - internal/setup
    stop:
      - internal/cleanup

Das Dashboard verwaltet die üblichen Standardwerte für dich. Bearbeite Workflow-Dateien direkt nur, wenn du eigene Vorbereitung, Backups, Uploads oder Cleanup-Schritte brauchst.

Workflow-Struktur

Ein Workflow hat einen lesbaren name, optionale variables und eine steps-Liste. Jeder Step hat einen name, einen uses-Action-Identifier, optionale if- und async-Einstellungen und Action-Parameter unter with.

# workflows/default/backup.yml
name: Backup Workflow

steps:
  - name: copy-running-to-backup
    uses: simplecloud/copy
    with:
      from: "{{ runtime.server-dir }}"
      to: "{{ runtime.templates }}/.backup/{{ runtime.name }}/{{ time.now.date }}/{{ time.now.dateTime }}-{{ runtime.nice-id }}"
      init-dir-if-missing: true

Variablen sind hilfreich, wenn mehrere Steps denselben Pfad oder Wert verwenden:

name: Archive World

variables:
  backup-dir: "{{ runtime.templates }}/.backup/{{ runtime.name }}/{{ time.now.date }}"

steps:
  - name: compress-world
    uses: simplecloud/compress
    with:
      from: "{{ runtime.server-dir }}/world"
      to: "{{ vars.backup-dir }}/world.zip"

Runtime-Werte

Workflow-Ausdrücke verwenden {{ ... }}-Syntax. Die wichtigsten Werte sind:

Wert	Beschreibung
`{{ runtime.name }}`	Gruppenname oder Name des persistenten Servers
`{{ runtime.nice-id }}`	Laufzeitname, zum Beispiel `lobby-1`
`{{ runtime.type }}`	Gemappter Servertyp, zum Beispiel `server` oder `proxy`
`{{ runtime.persistent }}`	Ob es ein persistenter Server ist
`{{ runtime.numerical-id }}`	Numerische ID bei Gruppenservern
`{{ runtime.server-dir }}`	Verzeichnis des Servers, der vorbereitet wird
`{{ runtime.templates }}`	Template-Wurzelverzeichnis
`{{ runtime.port }}`	Zugewiesener Server-Port
`{{ runtime.software }}`	Server-Software aus dem Blueprint
`{{ runtime.mapped-software }}`	Plattformgemappter Software-Name
`{{ runtime.minecraft-version }}`	Minecraft-Version aus dem Blueprint
`{{ runtime.configurator }}`	Configurator aus dem Blueprint
`{{ runtime.tags }}`	Tags der Gruppe oder des persistenten Servers
`{{ runtime.properties.<key> }}`	Eigene Property aus der Basiskonfiguration
`{{ vars.<key> }}`	Variable aus dem Workflow oder einem `foreach`-Step
`{{ time.now.date }}`	Aktuelles lokales Datum, hilfreich für Backup-Ordner

Häufige Actions

`simplecloud/copy`

Kopiert eine Datei oder ein Verzeichnis.

- name: copy-template
  uses: simplecloud/copy
  with:
    from: "{{ runtime.templates }}/{{ runtime.name }}"
    to: "{{ runtime.server-dir }}"
    init-dir-if-missing: true
    replace: false

Feld	Beschreibung
`from`	Quelldatei oder Quellverzeichnis
`to`	Zieldatei oder Zielverzeichnis
`replace`	Ob vorhandene Dateien überschrieben werden. Standard ist `true`
`init-dir-if-missing`	Erstellt ein fehlendes Quellverzeichnis und fährt fort. Standard ist `false`
`exclude`	Optionaler Pfad oder Liste von Pfaden/Globs, die übersprungen werden

`simplecloud/delete`

Löscht eine Datei oder ein Verzeichnis.

- name: delete-running-dir
  uses: simplecloud/delete
  if: "{{ runtime.persistent }} == false"
  with:
    path: "{{ runtime.server-dir }}"

Optionale Felder sind force und min-age, zum Beispiel 10m, 2h oder 7d.

`simplecloud/foreach`

Führt verschachtelte Steps für jedes Element einer Liste aus.

- name: copy-tagged
  uses: simplecloud/foreach
  with:
    items: "{{ runtime.tags }}"
    as: tag
    steps:
      - name: copy-tag-{{ vars.tag }}
        uses: simplecloud/copy
        with:
          from: "{{ runtime.templates }}/_tagged/{{ vars.tag }}"
          to: "{{ runtime.server-dir }}"
          replace: false

`simplecloud/load-plugins`

Lädt konfigurierte Plugins von Modrinth, Hangar, Spigot oder direkten URLs herunter und kopiert sie in das Plugin-Verzeichnis des Servers.

- name: load-plugins
  uses: simplecloud/load-plugins
  with:
    minecraft-version: "{{ runtime.minecraft-version }}"
    platform: "{{ runtime.software }}"
    plugins-dir: "{{ runtime.server-dir }}/plugins"
    cache-dir: "{{ runtime.cache-dir }}"
    type: "{{ runtime.type }}"

`simplecloud/configurate`

Wendet einen Configurator aus options/configurators/ an.

- name: configurate-server
  uses: simplecloud/configurate
  with:
    configurator: "{{ runtime.configurator }}"
    dir: "{{ runtime.server-dir }}"

Siehe Configurators für das Configurator-Dateiformat.

Archive und Uploads

Nutze simplecloud/compress, simplecloud/decompress und simplecloud/upload für Backups oder externe Speicher-Workflows.

- name: compress-world
  uses: simplecloud/compress
  with:
    from: "{{ runtime.server-dir }}/world"
    to: "{{ runtime.templates }}/.backup/{{ runtime.name }}/world.zip"

- name: upload-backup
  uses: simplecloud/upload
  with:
    from: "{{ runtime.templates }}/.backup/{{ runtime.name }}/world.zip"
    to: "https://example.com/backups/world.zip"
    method: PUT

Bedingungen und Async-Steps

Nutze if, um einen Step nur auszuführen, wenn eine Bedingung passt. Bedingungen unterstützen Vergleiche, &&, ||, exists(...), !exists(...) und value(path, default).

- name: copy-logs-to-archive
  uses: simplecloud/copy
  if: "{{ runtime.persistent }} == false"
  with:
    from: "{{ runtime.server-dir }}/logs/"
    to: "{{ runtime.templates }}/cache/logs/{{ runtime.name }}/{{ runtime.nice-id }}"

Setze async: true nur für unabhängige Steps. Der Workflow wartet auf asynchrone Arbeit, bevor er Erfolg oder Fehler meldet.

Fehlerbehebung

Ein Workflow läuft nicht

Prüfe die Workflow-Liste der Servergruppe oder des persistenten Servers. Die Workflow-ID muss zum Pfad unter workflows/ passen, zum Beispiel internal/setup.

Ein Workflow kann nicht geladen werden

Stelle sicher, dass die YAML-Datei name und steps enthält und dass jeder Step einen uses-Action-Identifier hat.

Ein Wert wird nicht ersetzt

Verwende Syntax wie {{ runtime.name }} oder {{ vars.name }}. Prozent-Platzhalter wie %server-dir% gehören zu Configurators, nicht zu Workflows.

Plugin- oder Template-Dateien fehlen

Prüfe den Quellpfad der betroffenen simplecloud/copy-Action und ob init-dir-if-missing für diesen Ordner aktiviert werden sollte.

Introduction

Setup

Configuration

Plugins

Was Workflows sind

Standard-Workflows

Workflow-Struktur

Runtime-Werte

Häufige Actions

`simplecloud/copy`

`simplecloud/delete`

`simplecloud/foreach`

`simplecloud/load-plugins`

`simplecloud/configurate`

Archive und Uploads

Bedingungen und Async-Steps

Fehlerbehebung

​Was Workflows sind

​Standard-Workflows

​Workflow-Struktur

​Runtime-Werte

​Häufige Actions

​simplecloud/copy

​simplecloud/delete

​simplecloud/foreach

​simplecloud/load-plugins

​simplecloud/configurate

​Archive und Uploads

​Bedingungen und Async-Steps

​Fehlerbehebung

Was Workflows sind

Standard-Workflows

Workflow-Struktur

Runtime-Werte

Häufige Actions

`simplecloud/copy`

`simplecloud/delete`

`simplecloud/foreach`

`simplecloud/load-plugins`

`simplecloud/configurate`

Archive und Uploads

Bedingungen und Async-Steps

Fehlerbehebung