Primeros pasos

Guía de instalación, configuración y operación de Saba-chan que cubre la arquitectura de ejecución y el comportamiento durante el funcionamiento.

Primeros pasos

Este documento cubre los procedimientos básicos de instalación, configuración y creación de servidores de Saba-chan. Para la integración remota y la resolución de incidencias, consulte los documentos Bot de Discord y Resolución de problemas.


1. Descarga e instalación

Requisitos: Windows 10 u 11 (64 bits), el runtime Microsoft Edge WebView2 (incluido en Windows 11 y en las versiones recientes de Windows 10) y conexión a Internet. También puede instalar el daemon y la CLI en un servidor Linux sin pantalla (x86_64, vea 1.1 más abajo). En macOS (Apple silicon), descargue el .dmg desde la página de inicio y arrastre la app a Aplicaciones. La app no está notarizada por Apple: si macOS la bloquea al abrirla por primera vez, permita abrirla en Ajustes del Sistema > Privacidad y seguridad.

  1. Descargue el instalador saba-chan-installer.exe desde el botón de descarga del sitio web o desde GitHub Releases.
  2. Ejecute el instalador, elija la ubicación de instalación, los módulos de juego que quiere instalar de entrada y las opciones de accesos directos, y haga clic en Instalar.
    • La ubicación predeterminada es C:\Program Files\Saba-chan. Si elige una carpeta que ya contiene otros archivos, el instalador crea dentro una carpeta Saba-chan.
    • También puede añadir módulos de juego más tarde desde la aplicación.
  3. El instalador configura los siguientes componentes. Según su conexión de red, puede tardar unos minutos.
    • Comprueba la última versión firmada y, a continuación, descarga y despliega el demonio, la GUI, la CLI, los archivos de idioma y otros componentes (cada archivo se comprueba mediante hash). El instalador también se deja en la carpeta de instalación, porque se usa más tarde para aplicar actualizaciones y para desinstalar Saba-chan
    • Instala los módulos de juego seleccionados y las extensiones que necesitan (p. ej., SteamCMD)
    • Descarga un Python portable y crea un entorno venv (instalado en una carpeta de Saba-chan; el PATH del sistema no se modifica)
    • Registra las versiones de los componentes instalados en installed-manifest.json
  4. Cuando termine la instalación, haga clic en Iniciar Saba-chan para abrir la GUI. También puede iniciarla desde el acceso directo del escritorio o del menú Inicio.

Los ajustes, los archivos de los servidores de juego, los mundos y las copias de seguridad se guardan en %APPDATA%\saba-chan. Eliminar la carpeta del programa no borra los datos de sus servidores.

Reinstalación: si la instalación falló a medias o hay archivos dañados, vuelva a ejecutar el instalador. Vuelve a descargar los archivos del programa y elimina y vuelve a descargar un runtime de Python dañado. Sus ajustes y los datos de sus servidores se conservan. Un instalador más antiguo que la versión actual queda bloqueado, así que descargue siempre el instalador más reciente.

1.1 Linux

En Linux (x86_64) se instala con una sola línea de comando. Necesita curl, unzip, sha256sum y python3.

curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
  • En un escritorio con pantalla, instala también la app (GUI), añade Saba-chan al menú de aplicaciones y abre la app. Como en Windows, la app inicia el daemon. La ventana de la app necesita WebKitGTK; si falta, el instalador le indica el comando para instalarlo (por ejemplo, sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1).
  • En un servidor sin pantalla instala solo el daemon y la CLI, y inicia el daemon como servicio de usuario de systemd. También puede decidirlo usted con --gui o --no-gui.
  • El instalador descarga la última versión estable, comprueba los archivos con los hashes de la versión y su manifiesto firmado, la instala y crea ~/.local/bin/saba-chan-cli. En un servidor sin pantalla inicia el daemon como servicio de usuario de systemd (saba-chan.service). Elija la carpeta de instalación y los módulos con sh -s -- --dir <carpeta> --modules <módulo…>.
  • En un servidor sin pantalla, para que arranque con el sistema sin iniciar sesión, ejecute una vez sudo loginctl enable-linger $USER.
  • La carpeta de datos es ~/.config/saba-chan.
  • Un servidor Linux sin pantalla se maneja como daemon remoto desde la app de otro PC. La conexión con Discord y la activación de las conexiones remotas están en Daemon remoto.

2. Comprender la arquitectura de Saba-chan

El diagrama siguiente muestra cómo se relacionan los componentes de Saba-chan y cómo se comunican:

Tu PC
App GUIApp de escritorio · opcional
CLIComandos y shell interactiva · opcional
Daemon de Saba-chan (saba-core)Gestiona servidores, ajustes y la conexión con Discord por su cuenta
Servidores de juegoEl daemon los inicia y vigila
MódulosManuales por juego · Python
ExtensionesFunciones extra · Python
Nube
Relé de DiscordBot de Saba-chan · une Discord y tu PC
DiscordComandos por chat
Los servidores de juego corren en tu PC. Con el relé solo se intercambian comandos de Discord, sus resultados y un resumen como la lista y el estado de los servidores, y no se abre ningún puerto para el control remoto.
  • Demonio (saba-core.exe): El núcleo que ejecuta todas las funciones de Saba-chan. Lanza y gestiona los procesos de los servidores, recopila logs y expone una API HTTP únicamente en la dirección local 127.0.0.1:57474.
  • GUI: La aplicación de escritorio que llama a la API del demonio.
  • CLI: La herramienta de línea de comandos que llama a la API del demonio. Si se ejecuta sin argumentos, abre un shell interactivo.
  • Runner (saba-runner): Un pequeño proceso vigilante asociado a cada servidor. Mantiene la continuidad de la consola y los logs del servidor incluso cuando el demonio se reinicia.
  • Servidor relay: El servicio en la nube donde se ejecuta el bot de Discord. Tras el emparejamiento, el demonio se conecta hacia fuera (long-polling) para recibir los comandos de gestión de Discord, y cada solicitud se autentica por HTTPS con el token de nodo recibido durante el emparejamiento. El relay solo transporta comandos de Discord, sus resultados y resúmenes de los servidores, nunca el tráfico del juego, así que el acceso de red de los jugadores que se unen a la partida debe configurarse aparte.

Los servidores de juego se ejecutan en su propio PC. La GUI y la CLI solo envían solicitudes al demonio; nunca editan archivos ni inician procesos por sí mismas.

Cerrar la ventana con «Solo cerrar interfaz» mantiene el demonio y los servidores de juego en segundo plano. Al volver a abrir la GUI, esta se reconecta al demonio y recupera el estado de los servidores y los logs de consola existentes. Si el demonio se reinicia, se vuelve a asociar a los procesos de servidor que siguen en ejecución para reanudar la supervisión (los procesos terminados por un corte de corriente o un reinicio del sistema no se restauran). Para detener un servidor de juego concreto, haga clic en Detener en la interfaz.


3. Crear su primer servidor (con la GUI)

La primera vez que se inicia Saba-chan, la lista de servidores está vacía y una tarjeta «Siguiente paso» le guía para instalar un módulo de juego y crear su primer servidor. Si todavía no hay ningún módulo de juego instalado, instale primero uno desde Saba Storage en la aplicación. Después, siga estos pasos para crear un servidor:

  1. Añadir un servidor: Haga clic en Añadir servidor y elija Agregar como nuevo servidor. Para vincular una carpeta de servidor que ya utiliza, elija en su lugar Migración de servidor existente.
  2. Elegir un juego: Seleccione uno de los módulos de juego instalados (módulos oficiales: Minecraft, Palworld, Project Zomboid y Terraria).
  3. Configurar el servidor: Introduzca un nombre de servidor y rellene las opciones que pida el módulo (p. ej., el tipo de servidor de Minecraft) y la configuración recomendada. El puerto (el número que usa un juego para aceptar jugadores) se asigna automáticamente para que no choque con otros servidores.
  4. Aceptar las condiciones: En los juegos que exigen aceptar condiciones (EULA), como Minecraft, debe leer las condiciones y marcar la casilla usted mismo antes de poder crear el servidor. Saba-chan nunca acepta condiciones automáticamente.
  5. Iniciar la instalación: Al hacer clic en Agregar Servidor, el demonio ejecuta las tareas de configuración en el siguiente orden:
    • Comprueba las extensiones que requiere el módulo (p. ej., Palworld y Project Zomboid necesitan SteamCMD). Si una extensión necesaria está desactivada, se le pedirá que la active en Ajustes → Extensiones.
    • Guarda los datos de la instancia en la carpeta %APPDATA%\saba-chan\instances\<ID de instancia>\
    • Ejecuta el hook server.post_create
    • Descarga la última versión de los archivos del servidor de juego en el directorio server\ de la carpeta de la instancia (descarga oficial del servidor para Minecraft y Terraria, SteamCMD para Palworld y Project Zomboid). El progreso se muestra en la barra de progreso.
  6. Iniciar: Cuando hace clic en Iniciar, el demonio comprueba que se hayan aceptado las condiciones necesarias y ejecuta las comprobaciones previas al arranque, ejecuta el hook server.pre_start y, por último, lanza el proceso con el comando de inicio del módulo (get_launch_command). La salida de la consola del servidor se muestra en directo en la consola de la GUI.

Todos los comandos de juego pasan por el demonio, en el orden stdin (consola del servidor) → REST → RCON. Los juegos con consola o API REST (como Palworld) se ejecutan con RCON desactivado. Solo un juego que únicamente admite RCON lo usa, con un puerto y una contraseña aleatoria por instancia asignados por el demonio, y solo por loopback (127.0.0.1).


4. Comportamientos que conviene conocer durante el funcionamiento

4.1 Tiempo de espera de parada

Para los procesos que gestiona directamente el demonio, cuando el usuario hace clic en Detener, el demonio intenta el apagado en el siguiente orden. Los valores de configuración están definidos en src/supervisor/mod.rs.

  1. Parada ordenada: envía el stop_command del módulo (p. ej., stop en Minecraft, quit en Zomboid) a la consola del servidor (stdin). En un juego sin entrada de consola (Palworld), el módulo pide al servidor que guarde y se apague mediante la API REST. A continuación, el demonio espera el tiempo de espera de parada (el valor fijado en la pestaña Saba-chan del servidor; si no hay, el [config].stop_timeout de module.toml; y si tampoco, 30 segundos). Si se supera el tiempo, el demonio termina el proceso a la fuerza y espera 2 segundos más.
  2. Terminación forzada: en una terminación forzada, el árbol de procesos se elimina de inmediato y luego se espera hasta 5 segundos.
  3. Periodo de enfriamiento: durante 30 segundos tras una parada, la detección automática de fallos se pausa. Así una terminación normal no se registra como un fallo.

4.2 Gestión de fallos

Cuando un servidor termina, el demonio clasifica la causa como Detenido por ti, Detenido en el juego, Fallo o Desconocido, y la registra en la lista «Salidas recientes» del servidor. Una salida solo se clasifica como fallo cuando hay pruebas, como un código de salida anómalo o un archivo de fallo que declara el módulo; sin pruebas no se trata como fallo.

  • Reinicio automático: actívelo o desactívelo en «Reinicio automático» dentro de la pestaña Saba-chan de la pantalla del servidor. Reiniciar tras un fallo está activado por defecto y Reiniciar también en salidas desconocidas está desactivado por defecto. Los servidores que haya detenido usted mismo o desde el juego nunca se reinician.
  • Intervalo de reinicio: el primer reinicio se produce a los 5 segundos y la espera se duplica en cada reinicio. Si se producen más de 3 reinicios en 10 minutos, Saba-chan deja de reiniciarlo. Revise los logs e inicie el servidor manualmente.

4.3 Ubicación de los logs

  • Logs de la GUI: %APPDATA%\saba-chan\logs\ (la salida de un demonio iniciado por la GUI también se registra aquí). También puede ver los logs del demonio con saba-chan-cli daemon logs.
  • Logs de consola de los servidores: %APPDATA%\saba-chan\instances\<ID de instancia>\logs\. Los servidores ejecutados mediante el runner crean un archivo en sessions\ en cada ejecución y conservan 20 por defecto.
  • Vista de consola: el demonio conserva en memoria las 10 000 líneas más recientes por instancia. La GUI consulta el endpoint GET /api/instance/:id/console?since=… con un cursor, hasta su límite de visualización consoleBufferSize (2000 líneas por defecto).

5. Siguientes pasos