Leitfaden zu Konfigurationsdateien

Erläutert den Datenordner von Saba-chan, die Einstellungsdatei config.json, die Instanzordner und die Token-Dateien – auf Basis dessen, was der Code tatsächlich tut.

Leitfaden zu Konfigurationsdateien

Die Einstellungen und der Zustand von Saba-chan liegen im Datenordner %APPDATA%\saba-chan (= C:\Users\<Ihr-Name>\AppData\Roaming\saba-chan). Dieses Dokument fasst zusammen, wie der tatsächliche Code die darin enthaltenen Dateien verwendet, und unterscheidet zwischen Dateien, die Sie gefahrlos von Hand bearbeiten können, und Dateien, die Sie nicht anfassen sollten.

Der Daemon (saba-core) erledigt die gesamte Arbeit; GUI und CLI rufen nur die lokale HTTP-API des Daemons auf. Deshalb ist es am sichersten, Einstellungen über GUI oder CLI zu ändern: Der Daemon prüft beim Speichern das Format.


1. Ordnerstruktur

%APPDATA%\saba-chan\
  • config.jsonAlle Benutzereinstellungen (nach Namespace)Alle Benutzereinstellungen (nach Namespace)
  • config.json.bakLetzte funktionierende Kopie (für automatische Wiederherstellung)Letzte funktionierende Kopie (für automatische Wiederherstellung)
  • .ipc_tokenAuth-Token Daemon ↔ GUI/CLI (bei jedem Daemon-Start neu erzeugt)Auth-Token Daemon ↔ GUI/CLI (bei jedem Daemon-Start neu erzeugt)
  • .node_tokenVerbindungstoken für Discord (Cloud-Relay). Vom Daemon beim Pairing gespeichertVerbindungstoken für Discord (Cloud-Relay). Vom Daemon beim Pairing gespeichert
  • instances\Server-InstanzenServer-Instanzen
  • order.jsonReihenfolge der ListeReihenfolge der Liste
  • <id>\
  • instance.jsonInstanzinformationenInstanzinformationen
  • settings.jsonModulspezifische SpieleinstellungswerteModulspezifische Spieleinstellungswerte
  • logs\Serverkonsolen-ProtokolleServerkonsolen-Protokolle
  • backups\BackupsBackups
  • server\Standard-Installationsort (Spieleserver-Dateien)Standard-Installationsort (Spieleserver-Dateien)
  • modules\Installierte SpielmoduleInstallierte Spielmodule
  • extensions\Installierte ErweiterungenInstallierte Erweiterungen
  • logs\GUI-Protokolle (saba-chan-<timestamp>.log)GUI-Protokolle (saba-chan-<timestamp>.log)
  • audit.logAufzeichnung von Serverstart/-stopp/-befehlen (Geheimnisse maskiert)Aufzeichnung von Serverstart/-stopp/-befehlen (Geheimnisse maskiert)
  • updates\Staging-Bereich für UpdatesStaging-Bereich für Updates
  • installed-manifest.jsonInstallierte KomponentenversionenInstallierte Komponentenversionen
  • Die portable Python-Laufzeit (python-standalone\, python-env\) wird im Installationsordner angelegt, sofern dieser beschreibbar ist, andernfalls in diesem Datenordner.
  • Daneben gibt es Dateien, die der Daemon selbst verwaltet (daemon.lock, scan-verdicts.json, sandbox-temp\ usw.). Fassen Sie diese nicht an.
  • Den Datenstamm selbst können Sie mit der Umgebungsvariable SABA_DATA_DIR überschreiben, das wird aber im Allgemeinen nicht empfohlen.

2. config.json: die Datei mit allen Einstellungen

Benutzereinstellungen landen in einer Datei, config.json, gruppiert nach Namespace (Schlüssel der obersten Ebene).

NamespaceInhaltWo er geändert wird
guiGUI-Verhalten, Design, Sprache, Daemon-PortGUI-Einstellungen
relayDiscord-Anbindung (Präfix, Aliasse, Einstellungen pro Discord-Server)Discord-Seite der GUI
updatesIntervall der Update-Prüfung, automatischer Download, Update-Kanal (channel)GUI-Einstellungen
remoteRemote-Daemon: Remote-Port und gekoppelte PCsGUI-Einstellungen → Verbindung → Remote-Daemon
bootZuletzt gewählter Startmodus (GUI / CLI / nur Daemon)Startauswahl
extensionsListe aktivierter Erweiterungen enabled, Einstellungen pro Erweiterung settingsGUI-Einstellungen → Erweiterungen
chatbotEinstellungen für Sprechende Saba-chan (KI-Chat)Discord-Seite der GUI
sandboxZustimmung, nicht verifizierte Komponenten ohne Isolation auszuführenDie Abfrage bei blockiertem Start, Einstellungen → Erweitert
cli usw.Eigene Einstellungen des jeweiligen ClientsDer jeweilige Client

Speichern und automatische Wiederherstellung

  • Das Speichern erfolgt atomar (in eine temporäre Datei schreiben, dann ersetzen), und die letzte funktionierende Kopie unmittelbar vor dem Ersetzen wird als config.json.bak aufbewahrt.
  • Ist config.json beschädigt und nicht lesbar, verschiebt der Daemon sie als config.json.corrupt-<timestamp> beiseite und stellt aus .bak wieder her.
  • Unbekannte Schlüssel in gui oder relay werden beim Speichern verworfen.

3. gui: gemeinsame Einstellungen von GUI und Daemon

Beim Start liest der Daemon gui.ipcPort, sofern keine Umgebungsvariable SABA_IPC_PORT gesetzt ist; fehlt auch dieser Wert, gilt der Standard 57474. Die übrigen Schlüssel werden überwiegend von der GUI gelesen.

SchlüsselTypStandardBeschreibung
ipcPortnumber57474Port der Daemon-HTTP-API (immer nur auf 127.0.0.1 geöffnet)
autoRefreshbooleantrueAutomatische Statusaktualisierung der GUI
refreshIntervalnumber (ms)2000Abfrageintervall des GUI-Status. Ein zu niedriger Wert erhöht die CPU-Last
consoleBufferSizenumber2000Anzahl der Zeilen, die die GUI-Konsole vorhält
portConflictCheckbooleantrueVor dem Serverstart auf Portkonflikte prüfen
languagestringvom Betriebssystem abgeleitetSprache (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Wird auch für Modul- und Discord-Antworten verwendet
themestringkeiner (GUI verwendet auto)"dark" / "light" / "auto"
osNotificationsbooleantrueAbstürze und unerwartete Starts oder Stopps auch als Systembenachrichtigung senden
daemonViewstringkeiner (switch)Darstellung der Serverliste bei Remote-Daemons. "switch" nur gewählter Daemon, "unified" alle Daemons kombiniert
mainDaemonstringkeiner (dieser PC)PC-ID des Remote-Daemons, der beim Öffnen der App zuerst angezeigt wird (Haupt-Daemon)

Außerdem gibt es Darstellungsschlüssel wie Farben, Schriftskalierung und Fenstergröße; was Sie in den GUI-Einstellungen ändern, wird unverändert gespeichert.


4. relay: Discord-Anbindung

Der Discord-Bot läuft ausschließlich auf dem Cloud-Relay, daher gibt es auf Ihrem PC weder einen Bot-Prozess noch ein Bot-Token. Dieser Namespace speichert Präfix, Rufnamen und Einstellungen pro Discord-Server, die Sie in der GUI bearbeiten; nach dem Pairing synchronisiert der Daemon sie mit dem Relay.

SchlüsselTypStandardBeschreibung
prefixesstring[]Präfixe für Chat-Befehle, die gelten, wenn für einen Discord-Server kein eigenes Präfix festgelegt ist (bis zu 10, jeweils 1–32 Zeichen ohne Leerzeichen). Präfixe pro Discord-Server stehen in nodeSettings und werden in der App unter Discord-Server → Tab Bot-Einstellungen geändert. Ist die Liste leer, gilt der Standard der Bot-Sprache dieses Discord-Servers (ohne eigene Einstellung die Sprache der PC-App) (Koreanisch 사바쨩, Japanisch サバちゃん, sonst Saba-chan). Auf ein Präfix, das mit einem Buchstaben endet, muss ein Leerzeichen (oder Komma bzw. Doppelpunkt) folgen, damit die Nachricht als Befehl gilt
serverWordsobject{}Pro Server (Instanz-ID) die Rufnamen für diesen Server und seine Befehle {words, commands}. Änderung im Tab Discord der Serveransicht
newGuildInstancesstring"auto"Ob alle Server dieses PCs für einen per Pairing-Code neu verbundenen Discord-Server sofort freigegeben werden (auto) oder später ausgewählt werden (manual)
nodeSettingsobject{}Einstellungen pro Discord-Server (erlaubte Instanzen, Befehlsberechtigungen, Sprache, Präfix, Aussehen der Slash-Befehle, singende Saba-chan, vorlesende Saba-chan, Rückfragen usw.)
cloudobjectrelayUrl, hostId. Beim Pairing ausgefüllt

Die früheren globalen Aliasse (moduleAliases, commandAliases, instanceAliases) überträgt der Daemon beim Start nach serverWords und leert sie.

Berechtigungs- und Discord-Einstellungen innerhalb von nodeSettings ändern sich nur über ihre eigenen Bildschirme (APIs); das Speichern der gesamten Bot-Konfiguration überschreibt sie nicht.

Befehlssyntax

Saba-chan <server name or alias> <command> [arguments…]
  • Saba-chan minecraft start
  • Saba-chan mc stop (Alias)
  • Saba-chan palworld status
  • Saba-chan list: Serverliste, Saba-chan help: Hilfe

Jeder Server hat die Standardbefehle start, stop und status; weitere Befehle definiert das Modul. Zusatzfunktionen wie Musik stellt der Bot auf der Relay-Server-Seite bereit.

remote: Remote-Daemon

Der Remote-Port, mit dem sich Ihre anderen PCs verbinden, und die Liste der Remote-Daemons, mit denen sich dieser PC verbindet. Ändern Sie ihn in der App unter Einstellungen → Verbindung → Remote-Daemon oder mit saba-chan-cli remote. Er ist nicht im Einstellungsexport enthalten. Nutzung: Remote-Daemon. Er ist ein eigener Schlüssel der obersten Ebene in config.json, getrennt von relay.

SchlüsselTypStandardBeschreibung
enabledbooleantrueÖffnet den Remote-Port
portnumber57480Remote-Port (TLS)
addressstringkeinerÖffentliche IP oder Hostname, den Ihre anderen PCs erreichen. Leer heißt, sie verbinden sich nur über das Relay
transportstring"direct"Verbindungsart. Derzeit gibt es nur "direct"; lassen Sie den Wert so
clientsarray[]Mit diesem Daemon gekoppelte PCs (Tokens werden nur als Hash gespeichert)
daemonsarray[]Remote-Daemons, mit denen sich dieser PC verbindet

5. instances\: Server-Instanzen

Jeder Server, den Sie in der GUI erstellen, wird als eigener Ordner instances\<id>\ gespeichert. <id> ist eine UUID.

  • instance.json: Name, Modul, ausführbare Datei/Arbeitsordner, Port, REST-Verbindungsdaten, geplante Aufgaben, Erweiterungsdaten (extension_data) usw.
  • settings.json: Spieleinstellungswerte, die das Modul deklariert (z. B. maximale Spielerzahl, Schwierigkeit).
  • order.json: Reihenfolge der GUI-Liste.
// instances\<id>\instance.json (Auszug)
{
  "id": "3f6c…",
  "name": "My Minecraft Server",
  "module_name": "minecraft",
  "working_dir": null,
  "port": 25565,
  "extension_data": {}
}
  • RCON wird nur für ein Spiel verwendet, dessen Modul supported = ["rcon"] deklariert (keine Konsole und keine REST-API); der Daemon vergibt dann pro Instanz einen Port und ein zufälliges Passwort und verbindet sich nur über Loopback (127.0.0.1). Andere Spielbefehle gehen an die Serverkonsole (stdin), und Palworld nutzt seine REST-API. Übrig gebliebene RCON-Schlüssel in alten Dateien werden beim Laden entfernt.
  • extension_data ist reservierter Speicher für Erweiterungen. Bei Modulen, die über SteamCMD installiert wurden, stehen hier etwa die Installationsmethode und App-Informationen.
  • Beim Speichern von Servereinstellungen (GUI-Servereinstellungen, PATCH /api/instance/:id) werden Schlüssel, die weder allgemeine Instanzfelder noch vom Modul deklarierte Einstellungen sind, mit dem Fehler unknown_setting abgelehnt.
  • Beim Löschen einer Instanz wird der gesamte Ordner instances\<id>\ gelöscht, einschließlich der Spieleserver-Dateien am Standard-Installationsort (server\) und backups\.

Bearbeiten Sie diese Dateien nur von Hand, wenn der Daemon nicht läuft. Wenn Sie sie während des Betriebs bearbeiten, weichen sie vom Zustand im Speicher des Daemons ab, und beim nächsten Speichern wird Ihre Änderung überschrieben.


6. Token-Dateien (.ipc_token / .node_token)

DateiFormatWann erstelltVerwendet von
.ipc_tokenUUID v4 (eine Zeile)Bei jedem Daemon-Start neu erzeugtGUI / CLI / Module und Erweiterungen (lokale API-Aufrufe)
.node_tokensbn_<hostId>.<secret>Vom Daemon gespeichert, wenn das Discord-Pairing abgeschlossen istDie Relay-Verbindung des Daemons

IPC-Token

Die Daemon-API lauscht nur auf 127.0.0.1, und jede Anfrage außer /health benötigt den Header X-Saba-Token.

GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <contents of the .ipc_token file>
  • Das Token ändert sich bei jedem Neustart des Daemons. GUI und CLI lesen die Token-Datei erneut ein, wenn die Authentifizierung fehlschlägt; Sie müssen also nichts tun.
  • Der Speicherort der Token-Datei lässt sich mit SABA_TOKEN_PATH ändern.

Node-Token

.node_token ist das Geheimnis, das diesen PC mit dem Discord-Bot (Cloud-Relay) verbindet. Der Daemon sendet es zur Authentifizierung über HTTPS an das Relay. Zeigen Sie es niemandem; wenn Sie vermuten, dass es durchgesickert ist, pairen Sie erneut über die GUI. Ein erneutes Pairing macht das alte Token ungültig.


7. Erweiterungs- und Isolationseinstellungen (extensions / sandbox)

  • extensions.enabled: Liste der IDs aktivierter Erweiterungen.
  • extensions.settings: Einstellungswerte pro Erweiterung { "<id>": { "<key>": value } }. Geändert über die Daemon-API PUT /api/extensions/:id/config.
  • sandbox.unisolated: Zustimmung, eine Komponente, für die keine isolierte Umgebung vorbereitet werden konnte, ohne Isolation auszuführen. Sie wird als Fingerabdruck der Komponentendateien gespeichert und erneut abgefragt, wenn sich eine Datei ändert. Sie können sie in der GUI unter Einstellungen → Sicherheit → „Ohne Isolation ausführen“ oder mit saba-chan-cli sandbox revoke <component> widerrufen.

8. Wichtige Umgebungsvariablen

VariableZielBeschreibung
SABA_IPC_PORTDaemon / CLIÜberschreibt gui.ipcPort
SABA_DAEMONCLIRemote-Daemon, an den Befehle gehen, wie --daemon <Name>
SABA_DATA_DIRDaemonLegt den Datenstamm selbst neu fest (fortgeschritten)
SABA_TOKEN_PATHDaemonPfad der IPC-Token-Datei
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATHDaemonLegen die Ordner für Module, Erweiterungen und Instanzen neu fest
RUST_LOGDaemonProtokollfilter (Standard info)
SABA_IPC_URLModul-/Erweiterungs-UnterprozesseAdresse der Daemon-API. Vom Daemon in Kindprozesse injiziert
SABA_LANGModul-/Erweiterungs-UnterprozesseAktuelle Sprache (gui.language)
PYTHONPATHModul-/Erweiterungs-UnterprozesseModul- und Erweiterungspfade zusammengeführt und injiziert
SABA_ENABLED_EXTENSIONSModul-/Erweiterungs-UnterprozesseListe der aktiven Erweiterungs-IDs (durch , getrennt)
PYTHONIOENCODINGModul-/Erweiterungs-UnterprozesseImmer utf-8
PYTHONUNBUFFEREDModul-/Erweiterungs-Unterprozesse1: stdout sofort leeren

Wenn Sie vermuten, etwas kaputt gemacht zu haben, stoppen Sie zuerst den Daemon, löschen Sie dann die betreffende Datei und starten Sie erneut; die meisten Dateien werden mit Standardwerten neu erzeugt. Das Löschen von config.json setzt alle Einstellungen zurück, einschließlich Ihrer Discord-Anbindung; versuchen Sie daher zuerst, config.json.bak wiederherzustellen. Löschen Sie nicht den Ordner instances\: Ihre Serverliste und alle am Standardort installierten Spieldateien gehen sonst mit verloren.