Guide des fichiers de configuration
Description, basée sur le comportement réel du code, du dossier de données de Saba-chan, du fichier de paramètres config.json, des dossiers d'instance et des fichiers de jeton.
Guide des fichiers de configuration
Les paramètres et l'état de Saba-chan se trouvent dans le dossier de données %APPDATA%\saba-chan (= C:\Users\<votre-nom>\AppData\Roaming\saba-chan). Ce document résume la façon dont le code utilise réellement les fichiers qu'il contient, et distingue les fichiers que vous pouvez modifier à la main sans risque de ceux auxquels il ne faut pas toucher.
Le démon (saba-core) fait tout le travail ; la GUI et la CLI ne font qu'appeler l'API HTTP locale du démon. C'est pourquoi il est plus sûr de modifier les paramètres depuis la GUI ou la CLI : le démon vérifie leur format à l'enregistrement.
1. Arborescence du dossier
- config.jsonTous les paramètres utilisateur (par espace de noms)Tous les paramètres utilisateur (par espace de noms)
- config.json.bakDernière copie valide (pour la récupération automatique)Dernière copie valide (pour la récupération automatique)
- .ipc_tokenJeton d'authentification démon ↔ GUI/CLI (régénéré à chaque démarrage du démon)Jeton d'authentification démon ↔ GUI/CLI (régénéré à chaque démarrage du démon)
- .node_tokenJeton de connexion Discord (relais cloud). Enregistré par le démon lors de l'appairageJeton de connexion Discord (relais cloud). Enregistré par le démon lors de l'appairage
- instances\Instances de serveurInstances de serveur
- order.jsonOrdre de la listeOrdre de la liste
- <id>\
- instance.jsonInformations de l'instanceInformations de l'instance
- settings.jsonValeurs des paramètres de jeu propres au moduleValeurs des paramètres de jeu propres au module
- logs\Logs de console du serveurLogs de console du serveur
- backups\SauvegardesSauvegardes
- server\Emplacement d'installation par défaut (fichiers du serveur de jeu)Emplacement d'installation par défaut (fichiers du serveur de jeu)
- modules\Modules de jeu installésModules de jeu installés
- extensions\Extensions installéesExtensions installées
- logs\Logs de la GUI (saba-chan-<horodatage>.log)Logs de la GUI (saba-chan-<horodatage>.log)
- audit.logHistorique des démarrages/arrêts/commandes des serveurs (secrets masqués)Historique des démarrages/arrêts/commandes des serveurs (secrets masqués)
- updates\Zone de préparation des mises à jourZone de préparation des mises à jour
- installed-manifest.jsonVersions des composants installésVersions des composants installés
- Le runtime Python portable (
python-standalone\,python-env\) est créé dans le dossier d'installation s'il est accessible en écriture, sinon dans ce dossier de données. - Il existe aussi des fichiers que le démon gère lui-même (
daemon.lock,scan-verdicts.json,sandbox-temp\, etc.). N'y touchez pas. - Vous pouvez remplacer la racine des données elle-même avec la variable d'environnement
SABA_DATA_DIR, mais ce n'est généralement pas recommandé.
2. config.json : le fichier qui contient tous les paramètres
Les paramètres utilisateur sont regroupés dans un seul fichier, config.json, par espace de noms (clé de premier niveau).
| Espace de noms | Contenu | Où il est modifié |
|---|---|---|
gui | Comportement de la GUI, thème, langue, port du démon | Paramètres de la GUI |
relay | Intégration Discord (préfixe, alias, paramètres par serveur Discord) | Page Discord de la GUI |
updates | Intervalle de vérification des mises à jour, téléchargement automatique, canal de mise à jour (channel) | Paramètres de la GUI |
remote | Daemon distant : port distant et PC appairés | Paramètres de la GUI → Connexion → Daemon distant |
boot | Dernier mode de démarrage choisi (GUI / CLI / démon seul) | Sélecteur de démarrage |
extensions | Liste des extensions activées enabled, paramètres par extension settings | Paramètres de la GUI → Extensions |
chatbot | Paramètres de Saba-chan qui parle (chat IA) | Page Discord de la GUI |
sandbox | Consentement à exécuter sans isolation des composants non vérifiés | Invite de lancement bloqué, Paramètres → Avancé |
cli, etc. | Paramètres propres à chaque client | Le client concerné |
Enregistrement et récupération automatique
- Les enregistrements sont atomiques (écriture dans un fichier temporaire, puis remplacement), et la dernière copie valide juste avant le remplacement est conservée sous
config.json.bak. - Si
config.jsonest corrompu et illisible, le démon le met de côté sousconfig.json.corrupt-<horodatage>et restaure à partir de.bak. - Les clés inconnues placées dans
guiourelaysont supprimées à l'enregistrement.
3. gui : paramètres partagés GUI / démon
Au démarrage du démon, si aucune variable d'environnement SABA_IPC_PORT n'est définie, il lit gui.ipcPort ; si cette clé est elle aussi absente, il utilise la valeur par défaut 57474. Les autres clés sont principalement lues par la GUI.
| Clé | Type | Défaut | Description |
|---|---|---|---|
ipcPort | number | 57474 | Port de l'API HTTP du démon (toujours ouvert uniquement sur 127.0.0.1) |
autoRefresh | boolean | true | Actualisation automatique de l'état dans la GUI |
refreshInterval | number (ms) | 2000 | Intervalle de polling de l'état dans la GUI. Une valeur trop basse augmente l'utilisation du CPU |
consoleBufferSize | number | 2000 | Nombre de lignes conservées par la console de la GUI |
portConflictCheck | boolean | true | Vérifie les conflits de ports avant de démarrer un serveur |
language | string | déduite de l'OS | Langue (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Utilisée aussi pour les modules et les réponses Discord |
theme | string | aucune (la GUI utilise auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | Envoie aussi les crashs et les démarrages ou arrêts inattendus en notifications système |
daemonView | string | aucune (switch) | Affichage de la liste des serveurs quand il y a des daemons distants. "switch" daemon choisi uniquement, "unified" tous les daemons combinés |
mainDaemon | string | aucune (ce PC) | ID du PC du démon distant à afficher en premier à l'ouverture de l'application (démon principal) |
Il existe aussi des clés d'apparence comme les couleurs, l'échelle de police et la taille de la fenêtre ; ce que vous modifiez dans les paramètres de la GUI est enregistré tel quel.
4. relay : intégration Discord
Le bot Discord ne tourne que sur le relais cloud ; il n'y a donc ni processus de bot ni jeton de bot sur votre PC. Cet espace de noms stocke le préfixe, les mots d'appel et les paramètres par serveur Discord que vous modifiez dans la GUI ; après l'appairage, le démon les synchronise avec le relais.
| Clé | Type | Défaut | Description |
|---|---|---|---|
prefixes | string | [] | Préfixes des commandes de chat utilisés quand aucun préfixe n'est défini pour un serveur Discord (10 au plus, chacun de 1 à 32 caractères sans espace). Les préfixes par serveur Discord sont stockés dans nodeSettings et se modifient dans l'application, onglet Serveurs Discord → Paramètres du bot. Si la liste est vide, la valeur par défaut de la langue du bot de ce serveur Discord (à défaut, la langue de l'application PC) s'applique (coréen 사바쨩, japonais サバちゃん, sinon Saba-chan). Un préfixe qui se termine par une lettre doit être suivi d'une espace (ou d'une virgule ou de deux-points) pour que le message soit considéré comme une commande |
serverWords | object | {} | Pour chaque serveur (ID d'instance), les mots qui désignent ce serveur et ses commandes, {words, commands}. Se modifie dans l'onglet Discord de l'écran du serveur |
newGuildInstances | string | "auto" | Pour un serveur Discord nouvellement connecté par code d'appairage : ouvrir d'emblée tous les serveurs de ce PC (auto) ou les choisir plus tard (manual) |
nodeSettings | object | {} | Paramètres par serveur Discord (instances autorisées, permissions des commandes, langue, préfixe, forme des commandes slash, Saba-chan qui chante, Saba-chan qui lit, paramètres de demande de précision, etc.) |
cloud | object | relayUrl, hostId. Renseignés lors de l'appairage |
Les paramètres de permission et Discord contenus dans
nodeSettingsne changent que via leurs écrans (API) dédiés ; enregistrer l'ensemble de la configuration du bot ne les écrase pas.
Les anciens alias globaux (
moduleAliases,commandAliases,instanceAliases) sont transférés versserverWordsau démarrage du démon, puis vidés.
Syntaxe des commandes
Saba-chan <nom ou alias du serveur> <commande> [arguments…]
Saba-chan minecraft startSaba-chan mc stop(alias)Saba-chan palworld statusSaba-chan list: liste des serveurs,Saba-chan help: aide
Chaque serveur dispose des commandes par défaut start, stop et status ; les autres commandes sont définies par le module. Les fonctionnalités supplémentaires comme la musique sont fournies par le bot côté serveur relais.
remote : daemon distant
Le port distant auquel se connectent vos autres PC, et la liste des daemons distants auxquels ce PC se connecte. Modifiez-le dans l'app sous Paramètres → Connexion → Daemon distant ou avec saba-chan-cli remote. Il n'est pas inclus dans l'export des paramètres. Utilisation : Daemon distant. C'est une clé de premier niveau de config.json, distincte de relay.
| Clé | Type | Défaut | Description |
|---|---|---|---|
enabled | boolean | true | Ouvre le port distant |
port | number | 57480 | Port distant (TLS) |
address | string | aucune | IP publique ou nom d'hôte que vos autres PC peuvent joindre. Vide signifie qu'ils se connectent seulement via le relais |
transport | string | "direct" | Mode de connexion. Seul "direct" existe pour l'instant ; laissez-le tel quel |
clients | array | [] | PC appairés avec ce daemon (les jetons ne sont stockés que sous forme de hachage) |
daemons | array | [] | Daemons distants auxquels ce PC se connecte |
5. instances\ : instances de serveur
Chaque serveur que vous créez dans la GUI est stocké dans son propre dossier instances\<id>\. <id> est un UUID.
instance.json: Nom, module, exécutable/dossier de travail, port, informations de connexion REST, tâches planifiées, données d'extension (extension_data), etc.settings.json: Valeurs des paramètres de jeu déclarés par le module (p. ex. nombre maximal de joueurs, difficulté).order.json: Ordre de la liste de la GUI.
// instances\<id>\instance.json (extrait)
{
"id": "3f6c…",
"name": "My Minecraft Server",
"module_name": "minecraft",
"working_dir": null,
"port": 25565,
"extension_data": {}
}
- RCON n'est utilisé que pour un jeu dont le module déclare
supported = ["rcon"](ni console ni API REST) ; le démon attribue alors un port et un mot de passe aléatoire par instance et se connecte uniquement en loopback (127.0.0.1). Les autres commandes de jeu sont envoyées à la console du serveur (stdin), et Palworld utilise son API REST. Les clés RCON restantes dans les anciens fichiers sont supprimées au chargement. extension_dataest un espace de stockage réservé aux extensions. Par exemple, pour les modules installés via SteamCMD, la méthode d'installation et les informations de l'application y sont placées.- Lorsque vous enregistrez les paramètres d'un serveur (paramètres du serveur dans la GUI,
PATCH /api/instance/:id), les clés qui ne sont ni des champs d'instance communs ni des paramètres déclarés par le module sont rejetées avec une erreurunknown_setting. - Supprimer une instance supprime tout le dossier
instances\<id>\, y compris les fichiers du serveur de jeu situés à l'emplacement d'installation par défaut (server\) etbackups\.
Ne modifiez ces fichiers à la main que lorsque le démon n'est pas en cours d'exécution. Les modifier pendant qu'il tourne crée un écart avec l'état en mémoire du démon, et le prochain enregistrement écrase votre modification.
6. Fichiers de jeton (.ipc_token / .node_token)
| Fichier | Format | Création | Utilisé par |
|---|---|---|---|
.ipc_token | UUID v4 (une seule ligne) | Régénéré à chaque démarrage du démon | GUI / CLI / modules et extensions (appels à l'API locale) |
.node_token | sbn_<hostId>.<secret> | Enregistré par le démon à la fin de l'appairage Discord | Connexion du démon au relais |
Jeton IPC
L'API du démon n'écoute que sur 127.0.0.1, et chaque requête, à l'exception de /health, nécessite l'en-tête X-Saba-Token.
GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <contenu du fichier .ipc_token>
- Le jeton change à chaque redémarrage du démon. La GUI et la CLI relisent le fichier de jeton en cas d'échec d'authentification ; vous n'avez donc rien à faire.
- L'emplacement du fichier de jeton peut être modifié avec
SABA_TOKEN_PATH.
Jeton de nœud
.node_token est le secret qui relie ce PC au bot Discord (relais cloud). Le démon l'envoie au relais en HTTPS pour s'authentifier. Ne le montrez jamais à personne ; si vous soupçonnez une fuite, appairez à nouveau depuis la GUI. Un nouvel appairage invalide l'ancien jeton.
7. Paramètres d'extension et d'isolation (extensions / sandbox)
extensions.enabled: Liste des ID d'extensions activées.extensions.settings: Valeurs des paramètres par extension{ "<id>": { "<key>": value } }. Modifiées via l'API du démonPUT /api/extensions/:id/config.sandbox.unisolated: Consentement à exécuter sans isolation un composant dont l'environnement isolé n'a pas pu être préparé. Il est stocké sous forme d'empreinte des fichiers du composant et redemandé si un fichier change. Vous pouvez le retirer dans Paramètres → Sécurité → « Exécuter sans isolation » dans la GUI, ou avecsaba-chan-cli sandbox revoke <component>.
8. Principales variables d'environnement
| Variable | Cible | Description |
|---|---|---|
SABA_IPC_PORT | Démon / CLI | Remplace gui.ipcPort |
SABA_DAEMON | CLI | Daemon distant qui reçoit les commandes, comme --daemon <nom> |
SABA_DATA_DIR | Démon | Redirige la racine des données elle-même (avancé) |
SABA_TOKEN_PATH | Démon | Chemin du fichier de jeton IPC |
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH | Démon | Redirigent les dossiers des modules, des extensions et des instances |
RUST_LOG | Démon | Filtre de log (par défaut info) |
SABA_IPC_URL | Sous-processus des modules/extensions | Adresse de l'API du démon. Injectée par le démon dans les processus enfants |
SABA_LANG | Sous-processus des modules/extensions | Langue actuelle (gui.language) |
PYTHONPATH | Sous-processus des modules/extensions | Chemins des modules et des extensions combinés et injectés |
SABA_ENABLED_EXTENSIONS | Sous-processus des modules/extensions | Liste des ID d'extensions actives (séparés par ,) |
PYTHONIOENCODING | Sous-processus des modules/extensions | Toujours utf-8 |
PYTHONUNBUFFERED | Sous-processus des modules/extensions | 1 : vide stdout immédiatement |
Si vous pensez avoir cassé quelque chose, arrêtez d'abord le démon, puis supprimez le fichier en cause et relancez ; la plupart des fichiers sont régénérés avec les valeurs par défaut. Supprimer config.json réinitialise tous les paramètres, y compris ceux de l'intégration Discord ; essayez donc d'abord de restaurer config.json.bak. Ne supprimez pas le dossier instances\ : votre liste de serveurs et les fichiers de jeu installés à l'emplacement par défaut disparaîtraient avec lui.