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
- 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).
| Namespace | Inhalt | Wo er geändert wird |
|---|---|---|
gui | GUI-Verhalten, Design, Sprache, Daemon-Port | GUI-Einstellungen |
relay | Discord-Anbindung (Präfix, Aliasse, Einstellungen pro Discord-Server) | Discord-Seite der GUI |
updates | Intervall der Update-Prüfung, automatischer Download, Update-Kanal (channel) | GUI-Einstellungen |
remote | Remote-Daemon: Remote-Port und gekoppelte PCs | GUI-Einstellungen → Verbindung → Remote-Daemon |
boot | Zuletzt gewählter Startmodus (GUI / CLI / nur Daemon) | Startauswahl |
extensions | Liste aktivierter Erweiterungen enabled, Einstellungen pro Erweiterung settings | GUI-Einstellungen → Erweiterungen |
chatbot | Einstellungen für Sprechende Saba-chan (KI-Chat) | Discord-Seite der GUI |
sandbox | Zustimmung, nicht verifizierte Komponenten ohne Isolation auszuführen | Die Abfrage bei blockiertem Start, Einstellungen → Erweitert |
cli usw. | Eigene Einstellungen des jeweiligen Clients | Der 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.bakaufbewahrt. - Ist
config.jsonbeschädigt und nicht lesbar, verschiebt der Daemon sie alsconfig.json.corrupt-<timestamp>beiseite und stellt aus.bakwieder her. - Unbekannte Schlüssel in
guioderrelaywerden 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üssel | Typ | Standard | Beschreibung |
|---|---|---|---|
ipcPort | number | 57474 | Port der Daemon-HTTP-API (immer nur auf 127.0.0.1 geöffnet) |
autoRefresh | boolean | true | Automatische Statusaktualisierung der GUI |
refreshInterval | number (ms) | 2000 | Abfrageintervall des GUI-Status. Ein zu niedriger Wert erhöht die CPU-Last |
consoleBufferSize | number | 2000 | Anzahl der Zeilen, die die GUI-Konsole vorhält |
portConflictCheck | boolean | true | Vor dem Serverstart auf Portkonflikte prüfen |
language | string | vom Betriebssystem abgeleitet | Sprache (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Wird auch für Modul- und Discord-Antworten verwendet |
theme | string | keiner (GUI verwendet auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | Abstürze und unerwartete Starts oder Stopps auch als Systembenachrichtigung senden |
daemonView | string | keiner (switch) | Darstellung der Serverliste bei Remote-Daemons. "switch" nur gewählter Daemon, "unified" alle Daemons kombiniert |
mainDaemon | string | keiner (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üssel | Typ | Standard | Beschreibung |
|---|---|---|---|
prefixes | string | [] | 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 |
serverWords | object | {} | Pro Server (Instanz-ID) die Rufnamen für diesen Server und seine Befehle {words, commands}. Änderung im Tab Discord der Serveransicht |
newGuildInstances | string | "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) |
nodeSettings | object | {} | Einstellungen pro Discord-Server (erlaubte Instanzen, Befehlsberechtigungen, Sprache, Präfix, Aussehen der Slash-Befehle, singende Saba-chan, vorlesende Saba-chan, Rückfragen usw.) |
cloud | object | relayUrl, hostId. Beim Pairing ausgefüllt |
Die früheren globalen Aliasse (
moduleAliases,commandAliases,instanceAliases) überträgt der Daemon beim Start nachserverWordsund 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 startSaba-chan mc stop(Alias)Saba-chan palworld statusSaba-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üssel | Typ | Standard | Beschreibung |
|---|---|---|---|
enabled | boolean | true | Öffnet den Remote-Port |
port | number | 57480 | Remote-Port (TLS) |
address | string | keiner | Öffentliche IP oder Hostname, den Ihre anderen PCs erreichen. Leer heißt, sie verbinden sich nur über das Relay |
transport | string | "direct" | Verbindungsart. Derzeit gibt es nur "direct"; lassen Sie den Wert so |
clients | array | [] | Mit diesem Daemon gekoppelte PCs (Tokens werden nur als Hash gespeichert) |
daemons | array | [] | 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_dataist 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 Fehlerunknown_settingabgelehnt. - Beim Löschen einer Instanz wird der gesamte Ordner
instances\<id>\gelöscht, einschließlich der Spieleserver-Dateien am Standard-Installationsort (server\) undbackups\.
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)
| Datei | Format | Wann erstellt | Verwendet von |
|---|---|---|---|
.ipc_token | UUID v4 (eine Zeile) | Bei jedem Daemon-Start neu erzeugt | GUI / CLI / Module und Erweiterungen (lokale API-Aufrufe) |
.node_token | sbn_<hostId>.<secret> | Vom Daemon gespeichert, wenn das Discord-Pairing abgeschlossen ist | Die 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-APIPUT /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 mitsaba-chan-cli sandbox revoke <component>widerrufen.
8. Wichtige Umgebungsvariablen
| Variable | Ziel | Beschreibung |
|---|---|---|
SABA_IPC_PORT | Daemon / CLI | Überschreibt gui.ipcPort |
SABA_DAEMON | CLI | Remote-Daemon, an den Befehle gehen, wie --daemon <Name> |
SABA_DATA_DIR | Daemon | Legt den Datenstamm selbst neu fest (fortgeschritten) |
SABA_TOKEN_PATH | Daemon | Pfad der IPC-Token-Datei |
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH | Daemon | Legen die Ordner für Module, Erweiterungen und Instanzen neu fest |
RUST_LOG | Daemon | Protokollfilter (Standard info) |
SABA_IPC_URL | Modul-/Erweiterungs-Unterprozesse | Adresse der Daemon-API. Vom Daemon in Kindprozesse injiziert |
SABA_LANG | Modul-/Erweiterungs-Unterprozesse | Aktuelle Sprache (gui.language) |
PYTHONPATH | Modul-/Erweiterungs-Unterprozesse | Modul- und Erweiterungspfade zusammengeführt und injiziert |
SABA_ENABLED_EXTENSIONS | Modul-/Erweiterungs-Unterprozesse | Liste der aktiven Erweiterungs-IDs (durch , getrennt) |
PYTHONIOENCODING | Modul-/Erweiterungs-Unterprozesse | Immer utf-8 |
PYTHONUNBUFFERED | Modul-/Erweiterungs-Unterprozesse | 1: 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.