Erste Schritte

Installations-, Einrichtungs- und Betriebsleitfaden für Saba-chan, einschließlich Laufzeitarchitektur und Betriebsverhalten.

Erste Schritte

Dieses Dokument beschreibt die grundlegende Installation, Einrichtung und das Erstellen eines Servers mit Saba-chan. Zur Fernanbindung und zur Problemlösung lesen Sie die Dokumente Discord-Bot und Fehlerbehebung.


1. Download & Installation

Voraussetzungen: Windows 10 oder 11 (64 Bit), die Microsoft Edge WebView2 Runtime (in Windows 11 und aktuellen Windows-10-Versionen enthalten) und eine Internetverbindung. Daemon und CLI können Sie auch auf einem Linux-Server ohne Bildschirm installieren (x86_64, siehe 1.1 unten). Unter macOS (Apple Silicon) laden Sie die .dmg auf der Startseite herunter und ziehen die App in den Ordner „Programme“. Die App ist nicht von Apple notarisiert: Wird sie beim ersten Start blockiert, erlauben Sie das Öffnen in den Systemeinstellungen unter „Datenschutz & Sicherheit“.

  1. Laden Sie das Installationsprogramm saba-chan-installer.exe über den Download-Button auf der Website oder von GitHub Releases herunter.
  2. Führen Sie das Installationsprogramm aus, wählen Sie den Installationsort, die zuerst zu installierenden Spielmodule und die Verknüpfungsoptionen, und klicken Sie dann auf Installieren.
    • Der Standard-Installationsort ist C:\Program Files\Saba-chan. Wenn Sie einen Ordner wählen, der bereits andere Dateien enthält, legt das Installationsprogramm darin einen Ordner Saba-chan an.
    • Spielmodule können Sie auch später in der App hinzufügen.
  3. Das Installationsprogramm richtet die folgenden Komponenten ein. Je nach Netzwerkverbindung kann das einige Minuten dauern.
    • Prüft das neueste signierte Release, lädt dann Daemon, GUI, CLI, Sprachdateien und weitere Komponenten herunter und stellt sie bereit (jede Datei wird per Hash geprüft). Das Installationsprogramm legt auch sich selbst im Installationsordner ab, um später Updates anzuwenden und Saba-chan zu entfernen
    • Installiert die ausgewählten Spielmodule und die Erweiterungen, die sie benötigen (z. B. SteamCMD)
    • Lädt ein portables Python herunter und erstellt eine venv-Umgebung (im Saba-chan-Ordner installiert; der System-PATH wird nicht verändert)
    • Hält die installierten Komponentenversionen in installed-manifest.json fest
  4. Wenn die Installation abgeschlossen ist, klicken Sie auf Saba-chan starten, um die GUI zu öffnen. Sie können sie auch über die Verknüpfung auf dem Desktop oder im Startmenü starten.

Einstellungen, Spieleserver-Dateien, Welten und Backups werden in %APPDATA%\saba-chan gespeichert. Wenn Sie den Programmordner löschen, bleiben Ihre Serverdaten erhalten.

Neuinstallation: Wenn die Installation unterwegs fehlgeschlagen ist oder Dateien beschädigt sind, führen Sie das Installationsprogramm erneut aus. Es lädt die Programmdateien erneut herunter und löscht eine beschädigte Python-Laufzeit, um sie neu herunterzuladen. Ihre Einstellungen und Serverdaten bleiben erhalten. Ein Installationsprogramm, das älter als das aktuelle Release ist, wird blockiert; laden Sie daher immer das neueste Installationsprogramm herunter.

1.1 Linux-Server

Auf einem Linux-Server ohne Bildschirm (x86_64) installieren Sie nur Daemon und CLI, ohne App-Oberfläche. Sie brauchen curl, unzip, sha256sum und python3.

curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
  • Das Installationsprogramm lädt das neueste stabile Release, prüft die Dateien gegen die Release-Hashes und das signierte Manifest, installiert es, legt ~/.local/bin/saba-chan-cli an und startet den Daemon als systemd-Benutzerdienst (saba-chan.service). Installationsordner und Module wählen Sie mit sh -s -- --dir <Ordner> --modules <Modul…>.
  • Damit er beim Booten ohne Anmeldung startet, führen Sie einmal sudo loginctl enable-linger $USER aus.
  • Der Datenordner ist ~/.config/saba-chan.
  • Den Linux-Server steuern Sie aus der App auf einem Windows-PC als Remote-Daemon. Die Verbindung mit Discord und das Einschalten der Remote-Verbindungen beschreibt Remote-Daemon.

2. Die Architektur von Saba-chan verstehen

Das Diagramm unten zeigt, wie die Komponenten von Saba-chan zusammenhängen und miteinander kommunizieren:

Dein PC
GUI-AppDesktop-App · optional
CLIBefehle und interaktive Shell · optional
Saba-chan Daemon (saba-core)Kümmert sich selbst um Server, Einstellungen und die Discord-Verbindung
SpielserverVom Daemon gestartet und überwacht
ModuleAnleitungen pro Spiel · Python
ErweiterungenZusatzfunktionen · Python
Cloud
Discord-RelaySaba-chan Bot · verbindet Discord und deinen PC
DiscordBefehle per Chat
Spielserver laufen auf deinem PC. Mit dem Relay werden nur Discord-Befehle, Ergebnisse und eine Übersicht wie Serverliste und Status ausgetauscht, und für die Fernsteuerung wird kein Port geöffnet.
  • Daemon (saba-core.exe): Der Kern, der alle Funktionen von Saba-chan ausführt. Er startet und verwaltet Serverprozesse, sammelt Protokolle und stellt eine HTTP-API ausschließlich auf der lokalen Adresse 127.0.0.1:57474 bereit.
  • GUI: Die Desktop-App, die die Daemon-API aufruft.
  • CLI: Das Kommandozeilenwerkzeug, das die Daemon-API aufruft. Ohne Argumente gestartet, öffnet es eine interaktive Shell.
  • Runner (saba-runner): Ein kleiner Überwachungsprozess, der an jeden Server angehängt wird. Er sorgt dafür, dass Serverkonsole und Protokolle auch bei einem Neustart des Daemons durchgehend erhalten bleiben.
  • Relay-Server: Der Cloud-Dienst, auf dem der Discord-Bot läuft. Nach dem Pairing verbindet sich der Daemon nach außen (Long-Polling), um Discord-Verwaltungsbefehle zu empfangen, und authentifiziert jede Anfrage über HTTPS mit dem beim Pairing erhaltenen Node-Token. Das Relay überträgt nur Discord-Befehle, ihre Ergebnisse und Serverübersichten, keinen Spielverkehr; den Netzwerkzugang für Spieler, die dem Spiel beitreten, müssen Sie daher separat einrichten.

Die Spieleserver laufen auf Ihrem eigenen PC. GUI und CLI senden nur Anfragen an den Daemon; sie bearbeiten nie selbst Dateien und starten keine Prozesse.

Wenn Sie das Fenster mit „Nur Oberfläche beenden“ schließen, laufen Daemon und Spieleserver im Hintergrund weiter. Beim erneuten Öffnen verbindet sich die GUI wieder mit dem Daemon und übernimmt den bestehenden Serverzustand und die Konsolenprotokolle. Startet der Daemon neu, verbindet er sich wieder mit noch laufenden Serverprozessen, um die Überwachung fortzusetzen (Prozesse, die durch Stromausfall oder einen Systemneustart beendet wurden, werden nicht wiederhergestellt). Um einen einzelnen Spieleserver zu stoppen, klicken Sie in der Oberfläche auf Stoppen.


3. Den ersten Server erstellen (mit der GUI)

Beim ersten Start von Saba-chan ist die Serverliste leer, und eine Karte „Nächster Schritt“ führt Sie durch die Installation eines Spielmoduls und das Erstellen Ihres ersten Servers. Ist noch kein Spielmodul installiert, installieren Sie zuerst eines über Saba Storage in der App. Folgen Sie dann diesen Schritten, um einen Server zu erstellen:

  1. Server hinzufügen: Klicken Sie auf Server hinzufügen und wählen Sie Als neuer Server hinzufügen. Um einen bereits genutzten Serverordner einzubinden, wählen Sie stattdessen Vorhandenen Server migrieren.
  2. Spiel wählen: Wählen Sie eines der installierten Spielmodule (offizielle Module: Minecraft, Palworld, Project Zomboid und Terraria).
  3. Server einrichten: Geben Sie einen Servernamen ein und füllen Sie die Optionen aus, die das Modul abfragt (z. B. den Minecraft-Servertyp), sowie die empfohlene Einrichtung. Der Port (die Nummer, über die ein Spiel Spieler annimmt) wird automatisch so zugewiesen, dass er nicht mit anderen Servern kollidiert.
  4. Bedingungen zustimmen: Bei Spielen, die eine Zustimmung zu Bedingungen (EULA) erfordern, etwa Minecraft, müssen Sie die Bedingungen selbst lesen und das Kontrollkästchen aktivieren, bevor der Server erstellt werden kann. Saba-chan stimmt Bedingungen niemals automatisch zu.
  5. Installation starten: Ein Klick auf Server hinzufügen veranlasst den Daemon, die Einrichtungsschritte in folgender Reihenfolge auszuführen:
    • Prüft die Erweiterungen, die das Modul benötigt (z. B. benötigen Palworld und Project Zomboid SteamCMD). Ist eine benötigte Erweiterung deaktiviert, werden Sie aufgefordert, sie unter Einstellungen → Erweiterungen zu aktivieren.
    • Speichert die Instanzdaten im Ordner %APPDATA%\saba-chan\instances\<Instanz-ID>\
    • Führt den Hook server.post_create aus
    • Lädt die neueste Version der Spieleserver-Dateien in das Verzeichnis server\ des Instanzordners herunter (offizieller Server-Download für Minecraft und Terraria, SteamCMD für Palworld und Project Zomboid). Der Fortschritt wird in der Fortschrittsleiste angezeigt.
  6. Starten: Wenn Sie auf Starten klicken, prüft der Daemon, ob alle nötigen Bedingungen akzeptiert sind, und führt Prüfungen vor dem Start durch, führt den Hook server.pre_start aus und startet dann den Prozess mit dem Startbefehl des Moduls (get_launch_command). Die Ausgabe der Serverkonsole wird live in der GUI-Konsole angezeigt.

Jeder Spielbefehl geht über den Daemon, in der Reihenfolge stdin (Serverkonsole) → REST → RCON. Spiele mit Konsole oder REST-API (wie Palworld) laufen mit deaktiviertem RCON. Nur ein Spiel, das ausschließlich RCON unterstützt, nutzt es – mit einem Port und zufälligen Passwort pro Instanz, die der Daemon vergibt, und nur über Loopback (127.0.0.1).


4. Wissenswertes zum Verhalten im Betrieb

4.1 Stopp-Timeout

Bei Prozessen, die der Daemon direkt verwaltet, versucht der Daemon nach einem Klick auf Stoppen das Herunterfahren in folgender Reihenfolge. Die Konfigurationswerte sind in src/supervisor/mod.rs definiert.

  1. Ordnungsgemäßer Stopp: Sendet den stop_command des Moduls (z. B. Minecraft stop, Zomboid quit) an die Serverkonsole (stdin). Bei einem Spiel ohne Konsoleneingabe (Palworld) fordert das Modul den Server über die REST-API auf, zu speichern und herunterzufahren. Anschließend wartet der Daemon die Stopp-Wartezeit ab (der im Tab Saba-chan des Servers festgelegte Wert, sonst [config].stop_timeout in module.toml, sonst 30 Sekunden). Wird das Timeout überschritten, beendet der Daemon den Prozess zwangsweise und wartet weitere 2 Sekunden.
  2. Zwangsbeendigung: Bei einer Zwangsbeendigung wird der Prozessbaum sofort beendet, gefolgt von einer Wartezeit von bis zu 5 Sekunden.
  3. Stopp-Abklingzeit: Für 30 Sekunden nach einem Stopp ist die automatische Absturzerkennung pausiert. So wird ein normales Beenden nicht als Absturz erfasst.

4.2 Umgang mit Abstürzen

Wenn ein Server beendet wird, ordnet der Daemon die Ursache als Von dir gestoppt, Im Spiel gestoppt, Absturz oder Unbekannt ein und hält sie in der Liste „Letzte Beendigungen“ des Servers fest. Ein Beenden wird nur dann als Absturz eingestuft, wenn es Belege gibt, etwa einen ungewöhnlichen Exit-Code oder eine vom Modul deklarierte Absturzdatei; ohne Belege gilt es nicht als Absturz.

  • Automatischer Neustart: Schalten Sie ihn im Tab Saba-chan der Serveransicht unter „Automatischer Neustart“ ein oder aus. Nach einem Absturz neu starten ist standardmäßig aktiviert, Auch bei unbekanntem Beenden neu starten standardmäßig deaktiviert. Server, die Sie selbst oder im Spiel gestoppt haben, werden nie neu gestartet.
  • Neustartintervall: Der erste Neustart erfolgt nach 5 Sekunden, und die Wartezeit verdoppelt sich mit jedem Neustart. Nach mehr als 3 Neustarts innerhalb von 10 Minuten startet Saba-chan nicht mehr neu. Prüfen Sie die Protokolle und starten Sie den Server manuell.

4.3 Speicherort der Protokolle

  • GUI-Protokolle: %APPDATA%\saba-chan\logs\ (auch die Ausgabe eines von der GUI gestarteten Daemons wird hier aufgezeichnet). Daemon-Protokolle können Sie auch mit saba-chan-cli daemon logs ansehen.
  • Serverkonsolen-Protokolle: %APPDATA%\saba-chan\instances\<Instanz-ID>\logs\. Server, die über den Runner laufen, legen für jeden Lauf eine Datei unter sessions\ an; standardmäßig werden 20 aufbewahrt.
  • Konsolenansicht: Der Daemon hält pro Instanz die letzten 10.000 Zeilen im Speicher. Die GUI fragt den Endpunkt GET /api/instance/:id/console?since=… mit einem Cursor ab, bis zu ihrem Anzeigelimit consoleBufferSize (standardmäßig 2000 Zeilen).

5. Nächste Schritte