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

%APPDATA%\saba-chan\
  • 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 nomsContenuOù il est modifié
guiComportement de la GUI, thème, langue, port du démonParamètres de la GUI
relayIntégration Discord (préfixe, alias, paramètres par serveur Discord)Page Discord de la GUI
updatesIntervalle de vérification des mises à jour, téléchargement automatique, canal de mise à jour (channel)Paramètres de la GUI
remoteDaemon distant : port distant et PC appairésParamètres de la GUI → Connexion → Daemon distant
bootDernier mode de démarrage choisi (GUI / CLI / démon seul)Sélecteur de démarrage
extensionsListe des extensions activées enabled, paramètres par extension settingsParamètres de la GUI → Extensions
chatbotParamètres de Saba-chan qui parle (chat IA)Page Discord de la GUI
sandboxConsentement à exécuter sans isolation des composants non vérifiésInvite de lancement bloqué, Paramètres → Avancé
cli, etc.Paramètres propres à chaque clientLe 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.json est corrompu et illisible, le démon le met de côté sous config.json.corrupt-<horodatage> et restaure à partir de .bak.
  • Les clés inconnues placées dans gui ou relay sont 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éTypeDéfautDescription
ipcPortnumber57474Port de l'API HTTP du démon (toujours ouvert uniquement sur 127.0.0.1)
autoRefreshbooleantrueActualisation automatique de l'état dans la GUI
refreshIntervalnumber (ms)2000Intervalle de polling de l'état dans la GUI. Une valeur trop basse augmente l'utilisation du CPU
consoleBufferSizenumber2000Nombre de lignes conservées par la console de la GUI
portConflictCheckbooleantrueVérifie les conflits de ports avant de démarrer un serveur
languagestringdéduite de l'OSLangue (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Utilisée aussi pour les modules et les réponses Discord
themestringaucune (la GUI utilise auto)"dark" / "light" / "auto"
osNotificationsbooleantrueEnvoie aussi les crashs et les démarrages ou arrêts inattendus en notifications système
daemonViewstringaucune (switch)Affichage de la liste des serveurs quand il y a des daemons distants. "switch" daemon choisi uniquement, "unified" tous les daemons combinés
mainDaemonstringaucune (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éTypeDéfautDescription
prefixesstring[]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
serverWordsobject{}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
newGuildInstancesstring"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)
nodeSettingsobject{}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.)
cloudobjectrelayUrl, hostId. Renseignés lors de l'appairage

Les paramètres de permission et Discord contenus dans nodeSettings ne 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 vers serverWords au démarrage du démon, puis vidés.

Syntaxe des commandes

Saba-chan <nom ou alias du serveur> <commande> [arguments…]
  • Saba-chan minecraft start
  • Saba-chan mc stop (alias)
  • Saba-chan palworld status
  • Saba-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éTypeDéfautDescription
enabledbooleantrueOuvre le port distant
portnumber57480Port distant (TLS)
addressstringaucuneIP publique ou nom d'hôte que vos autres PC peuvent joindre. Vide signifie qu'ils se connectent seulement via le relais
transportstring"direct"Mode de connexion. Seul "direct" existe pour l'instant ; laissez-le tel quel
clientsarray[]PC appairés avec ce daemon (les jetons ne sont stockés que sous forme de hachage)
daemonsarray[]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_data est 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 erreur unknown_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\) et backups\.

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)

FichierFormatCréationUtilisé par
.ipc_tokenUUID v4 (une seule ligne)Régénéré à chaque démarrage du démonGUI / CLI / modules et extensions (appels à l'API locale)
.node_tokensbn_<hostId>.<secret>Enregistré par le démon à la fin de l'appairage DiscordConnexion 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émon PUT /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 avec saba-chan-cli sandbox revoke <component>.

8. Principales variables d'environnement

VariableCibleDescription
SABA_IPC_PORTDémon / CLIRemplace gui.ipcPort
SABA_DAEMONCLIDaemon distant qui reçoit les commandes, comme --daemon <nom>
SABA_DATA_DIRDémonRedirige la racine des données elle-même (avancé)
SABA_TOKEN_PATHDémonChemin du fichier de jeton IPC
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATHDémonRedirigent les dossiers des modules, des extensions et des instances
RUST_LOGDémonFiltre de log (par défaut info)
SABA_IPC_URLSous-processus des modules/extensionsAdresse de l'API du démon. Injectée par le démon dans les processus enfants
SABA_LANGSous-processus des modules/extensionsLangue actuelle (gui.language)
PYTHONPATHSous-processus des modules/extensionsChemins des modules et des extensions combinés et injectés
SABA_ENABLED_EXTENSIONSSous-processus des modules/extensionsListe des ID d'extensions actives (séparés par ,)
PYTHONIOENCODINGSous-processus des modules/extensionsToujours utf-8
PYTHONUNBUFFEREDSous-processus des modules/extensions1 : 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.