Démarrage
Guide d'installation, de configuration et d'exploitation de Saba-chan, couvrant l'architecture d'exécution et le comportement en fonctionnement.
Démarrage
Ce document couvre les procédures de base d'installation, de configuration et de création de serveur pour Saba-chan. Pour l'intégration à distance et la résolution de problèmes, reportez-vous aux documents Bot Discord et Dépannage.
1. Téléchargement et installation
Prérequis : Windows 10 ou 11 (64 bits), le runtime Microsoft Edge WebView2 (inclus dans Windows 11 et dans les versions récentes de Windows 10) et une connexion Internet. Vous pouvez aussi installer le daemon et la CLI sur un serveur Linux sans écran (x86_64, voir 1.1 plus bas). Sous macOS (puce Apple), téléchargez le .dmg depuis la page d'accueil et faites glisser l'app dans Applications. L'app n'est pas notarisée par Apple : si macOS la bloque au premier lancement, autorisez son ouverture dans Réglages Système > Confidentialité et sécurité.
- Téléchargez l'installateur
saba-chan-installer.exedepuis le bouton de téléchargement du site ou depuis les GitHub Releases. - Lancez l'installateur, choisissez l'emplacement d'installation, les modules de jeu à installer d'emblée et les options de raccourcis, puis cliquez sur
Installer.- L'emplacement par défaut est
C:\Program Files\Saba-chan. Si vous choisissez un dossier qui contient déjà d'autres fichiers, l'installateur crée un dossierSaba-chanà l'intérieur. - Vous pouvez aussi ajouter des modules de jeu plus tard depuis l'application.
- L'emplacement par défaut est
- L'installateur configure les composants suivants. Selon votre connexion réseau, cela peut prendre quelques minutes.
- Vérifie la dernière version signée, puis télécharge et déploie le démon, la GUI, la CLI, les fichiers de langue et les autres composants (chaque fichier est contrôlé par hachage). L'installateur est aussi placé dans le dossier d'installation ; il servira plus tard à appliquer les mises à jour et à désinstaller Saba-chan
- Installe les modules de jeu sélectionnés et les extensions dont ils ont besoin (p. ex. SteamCMD)
- Télécharge un Python portable et crée un environnement
venv(installé dans un dossier de Saba-chan ; lePATHdu système n'est pas modifié) - Enregistre les versions des composants installés dans
installed-manifest.json
- Une fois l'installation terminée, cliquez sur
Lancer Saba-chanpour ouvrir la GUI. Vous pouvez aussi la démarrer depuis le raccourci du bureau ou du menu Démarrer.
Les paramètres, les fichiers des serveurs de jeu, les mondes et les sauvegardes sont stockés dans %APPDATA%\saba-chan. Supprimer le dossier du programme ne supprime pas les données de vos serveurs.
Réinstallation : si l'installation a échoué en cours de route ou si des fichiers sont endommagés, relancez l'installateur. Il retélécharge les fichiers du programme, et supprime puis retélécharge un runtime Python endommagé. Vos paramètres et les données de vos serveurs sont conservés. Un installateur plus ancien que la version actuelle est bloqué ; téléchargez donc toujours le dernier installateur.
1.1 Serveur Linux
Sur un serveur Linux sans écran (x86_64), vous n'installez que le daemon et la CLI, sans les écrans de l'app. Il faut curl, unzip, sha256sum et python3.
curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
- L'installateur télécharge la dernière version stable, vérifie les fichiers avec les hachages de la version et son manifeste signé, l'installe, crée
~/.local/bin/saba-chan-cliet lance le daemon comme service utilisateur systemd (saba-chan.service). Choisissez le dossier d'installation et les modules avecsh -s -- --dir <dossier> --modules <module…>. - Pour qu'il démarre au boot sans ouvrir de session, lancez une fois
sudo loginctl enable-linger $USER. - Le dossier de données est
~/.config/saba-chan. - Le serveur Linux se gère depuis l'app d'un PC Windows comme daemon distant. La connexion à Discord et l'activation des connexions distantes sont décrites dans Daemon distant.
2. Comprendre l'architecture de Saba-chan
Le diagramme ci-dessous montre comment les composants de Saba-chan sont liés et communiquent :
- Démon (
saba-core.exe) : Le cœur qui exécute toutes les fonctionnalités de Saba-chan. Il lance et gère les processus des serveurs, collecte les logs et expose une API HTTP uniquement sur l'adresse locale127.0.0.1:57474. - GUI : L'application de bureau qui appelle l'API du démon.
- CLI : L'outil en ligne de commande qui appelle l'API du démon. Lancé sans argument, il ouvre un shell interactif.
- Runner (
saba-runner) : Un petit processus de surveillance attaché à chaque serveur. Il assure la continuité de la console et des logs du serveur même lorsque le démon redémarre. - Serveur relais : Le service cloud sur lequel tourne le bot Discord. Après l'appairage, le démon se connecte vers l'extérieur (long-polling) pour recevoir les commandes de gestion Discord, et chaque requête est authentifiée en HTTPS avec le jeton de nœud reçu lors de l'appairage. Le relais ne transporte que les commandes Discord, leurs résultats et des résumés des serveurs, jamais le trafic de jeu ; l'accès réseau des joueurs qui rejoignent la partie doit donc être configuré séparément.
Les serveurs de jeu tournent sur votre propre PC. La GUI et la CLI ne font qu'envoyer des requêtes au démon ; elles ne modifient jamais de fichiers et ne lancent jamais de processus elles-mêmes.
Fermer la fenêtre avec « Fermer l'interface » laisse le démon et les serveurs de jeu tourner en arrière-plan. Rouvrir la GUI la reconnecte au démon et récupère l'état des serveurs et les logs de console existants. Si le démon redémarre, il se rattache aux processus de serveur encore en cours d'exécution pour reprendre la surveillance (les processus terminés par une coupure de courant ou un redémarrage du système ne sont pas restaurés). Pour arrêter un serveur de jeu en particulier, cliquez sur
Arrêterdans l'interface.
3. Créer votre premier serveur (avec la GUI)
Au premier lancement de Saba-chan, la liste des serveurs est vide et une carte « Étape suivante » vous guide pour installer un module de jeu et créer votre premier serveur. Si aucun module de jeu n'est encore installé, installez-en d'abord un depuis Saba Storage dans l'application. Suivez ensuite ces étapes pour créer un serveur :
- Ajouter un serveur : Cliquez sur
Ajouter un serveuret choisissezAjouter comme nouveau serveur. Pour lier un dossier de serveur que vous utilisez déjà, choisissez plutôtMigration d'un serveur existant. - Choisir un jeu : Sélectionnez l'un des modules de jeu installés (modules officiels : Minecraft, Palworld, Project Zomboid et Terraria).
- Configurer le serveur : Saisissez un nom de serveur et renseignez les options demandées par le module (p. ex. le type de serveur Minecraft) ainsi que la configuration recommandée. Le port (le numéro qu'un jeu utilise pour accepter les joueurs) est attribué automatiquement pour ne pas entrer en conflit avec d'autres serveurs.
- Accepter les conditions : Pour les jeux qui exigent l'acceptation de conditions (EULA), comme Minecraft, vous devez lire les conditions et cocher la case vous-même avant de pouvoir créer le serveur. Saba-chan n'accepte jamais de conditions automatiquement.
- Lancer l'installation : Un clic sur
Ajouter un serveurfait exécuter au démon les tâches de configuration dans l'ordre suivant :- Vérifie les extensions requises par le module (p. ex. Palworld et Project Zomboid ont besoin de SteamCMD). Si une extension requise est désactivée, vous êtes invité à l'activer dans Paramètres → Extensions.
- Enregistre les données de l'instance dans le dossier
%APPDATA%\saba-chan\instances\<ID d'instance>\ - Exécute le hook
server.post_create - Télécharge la dernière version des fichiers du serveur de jeu dans le répertoire
server\du dossier de l'instance (téléchargement officiel du serveur pour Minecraft et Terraria, SteamCMD pour Palworld et Project Zomboid). La progression s'affiche dans la barre de progression.
- Démarrer : Lorsque vous cliquez sur
Démarrer, le démon vérifie que les conditions requises sont acceptées et exécute les vérifications de pré-démarrage, exécute le hookserver.pre_start, puis lance le processus avec la commande de lancement du module (get_launch_command). La sortie de la console du serveur s'affiche en direct dans la console de la GUI.
Toutes les commandes de jeu passent par le démon, dans l'ordre stdin (console du serveur) → REST → RCON. Les jeux dotés d'une console ou d'une API REST (comme Palworld) tournent avec RCON désactivé. Seul un jeu qui ne prend en charge que RCON l'utilise, avec un port et un mot de passe aléatoire par instance attribués par le démon, et uniquement en loopback (127.0.0.1).
4. Comportements à connaître en fonctionnement
4.1 Délai d'arrêt
Pour les processus gérés directement par le démon, lorsque l'utilisateur clique sur Arrêter, le démon tente l'arrêt dans l'ordre suivant. Les valeurs de configuration sont définies dans src/supervisor/mod.rs.
- Arrêt propre : envoie la
stop_commanddu module (p. ex.stoppour Minecraft,quitpour Zomboid) à la console du serveur (stdin). Pour un jeu sans entrée console (Palworld), le module demande au serveur de sauvegarder et de s'arrêter via l'API REST. Le démon attend ensuite le délai d'arrêt (la valeur définie dans l'onglet Saba-chan du serveur ; à défaut,[config].stop_timeoutdansmodule.toml; à défaut, 30 secondes). Si le délai est dépassé, le démon termine le processus de force et attend 2 secondes supplémentaires. - Arrêt forcé : lors d'une terminaison forcée, l'arbre de processus est tué immédiatement, puis le démon attend jusqu'à 5 secondes.
- Période de refroidissement : pendant 30 secondes après un arrêt, la détection automatique des crashs est suspendue. Cela évite qu'un arrêt normal soit enregistré comme un crash.
4.2 Gestion des crashs
Lorsqu'un serveur s'arrête, le démon classe la cause en Arrêté par vous, Arrêté en jeu, Crash ou Inconnu, et l'enregistre dans la liste « Arrêts récents » du serveur. Un arrêt n'est classé comme crash que s'il existe des éléments probants, comme un code de sortie anormal ou un fichier de crash déclaré par le module ; sans élément probant, il n'est pas traité comme un crash.
- Redémarrage automatique : activez-le ou désactivez-le sous « Redémarrage auto » dans l'onglet Saba-chan de l'écran du serveur.
Redémarrer après un crashest activé par défaut, etRedémarrer aussi sur les arrêts inconnusest désactivé par défaut. Les serveurs que vous avez arrêtés vous-même ou depuis le jeu ne sont jamais redémarrés. - Intervalle de redémarrage : le premier redémarrage a lieu après 5 secondes, et l'attente double à chaque redémarrage. Au-delà de 3 redémarrages en 10 minutes, Saba-chan ne redémarre plus le serveur. Consultez les logs et démarrez le serveur manuellement.
4.3 Emplacement des logs
- Logs de la GUI :
%APPDATA%\saba-chan\logs\(la sortie d'un démon lancé par la GUI y est aussi enregistrée). Vous pouvez également consulter les logs du démon avecsaba-chan-cli daemon logs. - Logs de console des serveurs :
%APPDATA%\saba-chan\instances\<ID d'instance>\logs\. Les serveurs exécutés via le runner créent un fichier soussessions\à chaque exécution et en conservent 20 par défaut. - Affichage de la console : le démon conserve en mémoire les 10 000 dernières lignes par instance. La GUI interroge l'endpoint
GET /api/instance/:id/console?since=…avec un curseur, jusqu'à sa limite d'affichageconsoleBufferSize(2000 lignes par défaut).
5. Étapes suivantes
- Opérations quotidiennes comme le démarrage et l'arrêt des serveurs, les sauvegardes et les tâches planifiées : Gérer vos serveurs
- Gérer vos serveurs à distance par des commandes Discord : Bot Discord & relais cloud
- Configurer le fichier de paramètres (
config.json) : Guide des fichiers de configuration - Résoudre les erreurs courantes : Dépannage
- Développer vos propres modules de jeu : Guide de développement de modules