Resolución de problemas

Problemas habituales al operar Saba-chan, con pasos de solución basados en el comportamiento real del código.

Resolución de problemas

Este documento se organiza según los síntomas que encuentran realmente los usuarios y explica cómo se comporta el código del demonio junto con los pasos para solucionarlo. Los ejemplos de comandos y las rutas son para Windows. En Linux, la carpeta de datos es ~/.config/saba-chan.


1. El demonio no arranca / la GUI no se conecta

1.1 Conflicto de puerto / el demonio ya está en ejecución

El demonio (saba-core) escucha por defecto en el puerto 57474, solo en 127.0.0.1.

  • Solo se ejecuta un demonio por PC. Si ya hay un demonio en ejecución, uno recién lanzado termina de inmediato, y la GUI y la CLI se conectan al que ya está en marcha.
  • Si otro programa ocupa el puerto, el demonio lo reintenta 10 veces a intervalos de 2 segundos y luego termina.
# Windows: ver quién lo está usando
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • Puede comprobar si el demonio está vivo, sin token, en http://127.0.0.1:57474/health. saba-chan-cli daemon status muestra la misma información.
  • Si sigue habiendo un demonio que no responde, deténgalo con saba-chan-cli daemon stop. Si aun así no desaparece, ejecute Stop-Process -Name saba-core -Force.
  • Si necesita cambiar el puerto, edite gui.ipcPort en config.json y reinicie. O defina una variable de entorno como SABA_IPC_PORT=57480.

1.2 Discrepancia del token IPC

El demonio crea un .ipc_token nuevo cada vez que arranca. Cuando falla la autenticación (401), la GUI y la CLI vuelven a leer el archivo de token y lo reintentan una vez, así que normalmente se resuelve solo.

Si «autenticación fallida» se repite una y otra vez:

  • Compruebe que la GUI y el demonio usan la misma carpeta de datos. Si definió SABA_DATA_DIR o SABA_TOKEN_PATH solo para uno de ellos, las ubicaciones del archivo de token difieren.
  • Cierre la GUI por completo y vuelva a abrirla.

2. El inicio/parada del servidor se comporta de forma extraña

2.1 Hice clic en Detener y no pasa nada durante un rato

Puede ser normal. El demonio actúa en este orden:

  1. En los servidores con consola, envía el stop_command del módulo a la consola (stdin). En los juegos sin consola, como Palworld, el módulo pide al servidor por REST que guarde y se apague.
  2. Espera a que el servidor termine por sí mismo. Por defecto son 30 segundos; un módulo puede cambiarlo con [config] stop_timeout en module.toml, y usted puede cambiarlo por servidor con el tiempo de espera de parada de la pestaña Saba-chan de la pantalla del servidor. Aumente el valor si el mundo es grande y guardar tarda.
  3. Si sigue vivo, se fuerza su cierre.
  4. Durante 30 segundos tras la parada, se suspende la detección de fallos.

Si siempre acaba cerrándose a la fuerza, el servidor no está recibiendo el comando de parada. Compruebe si el comando de parada aparece en la consola del servidor. Ejemplos: stop en Minecraft, quit en Zomboid.

2.2 El servidor vuelve a arrancar una y otra vez

Cuando un servidor termina, el demonio clasifica la causa como detenido por usted / detenido en el juego / fallo / desconocido. Por defecto, el reinicio automático solo se produce en caso de fallo; la espera empieza en 5 segundos y se duplica cada vez, y deja de reiniciar tras más de 3 reinicios en 10 minutos.

Solución:

  • Compruebe la clasificación en «Salidas recientes» en la pantalla del servidor.
  • Para detener los reinicios, desactive «Reiniciar tras un fallo» en «Reinicio automático» dentro de la pestaña Saba-chan de la pantalla del servidor. Si activó «Reiniciar también en salidas desconocidas», revíselo también.
  • Revise los logs de consola del servidor (instances\<id>\logs\) para ver la causa del fallo. Si es un OOM de Java (OutOfMemoryError), aumente el ajuste de memoria.

2.3 Error de «conflicto de puerto» al iniciar

La comprobación previa al arranque detectó que el puerto del servidor lo está usando otra instancia en ejecución u otro programa. Normalmente sigue vivo un proceso anterior, u otro servidor de juego usa el mismo puerto.

  • Busque el proceso que usa ese puerto y deténgalo.
  • Si no es posible, cambie el puerto en los ajustes de la instancia e inícielo de nuevo.
  • Puede desactivar la propia comprobación con «Detección de conflicto de puertos» en los ajustes de la GUI (gui.portConflictCheck), pero no se recomienda.

2.4 «Se requiere aceptación» (EULA de Minecraft, etc.)

En los juegos cuyo módulo declara condiciones (p. ej., el EULA de Minecraft), debe leerlas y aceptarlas antes de que el servidor pueda arrancar. Mientras no lo haga, el inicio se bloquea con agreement_required.

  • Cuando inicie el servidor en la GUI, lea las condiciones en el diálogo que aparece, marque la casilla e inícielo.
  • No se pueden aceptar condiciones desde Discord. Una vez aceptadas en Saba-chan en su PC, también podrá iniciar el servidor desde Discord.

2.5 Se rechaza el guardado de los ajustes del servidor

  • unknown_setting: La clave no es ni un campo común de instancia ni un ajuste declarado por el módulo. Es una errata o un ajuste de otro juego.
  • validation_failed / invalid_format: El rango o el formato del valor no coincide con la declaración del módulo. Corrija el campo indicado en el error.
  • «Se guardaron los ajustes, pero no se pudo actualizar el archivo de configuración del juego»: Los ajustes se guardaron, pero el módulo no pudo editar el archivo de configuración del juego. Asegúrese de que el archivo del juego no esté bloqueado por otro programa y vuelva a guardar.

2.6 Un componente no verificado no se ejecuta

Los módulos y extensiones que no se instalaron desde el catálogo oficial, o cuyos archivos cambiaron después, se marcan como «no verificados». Saba-chan no los analiza con antivirus. En Windows se ejecutan aislados con AppContainer y en Linux con bubblewrap; donde no se puede aislar (Linux sin bubblewrap o donde no se puede usar, y macOS), solo se ejecutan después de que des tu consentimiento para sus archivos actuales. Si se bloquea la ejecución, se muestra uno de estos códigos.

CódigoSignificadoSolución
launch_outside_instanceEl módulo intentó ejecutar un programa fuera de la carpeta del servidorCompruebe de dónde procede el módulo
sandbox_unavailableNo se pudo preparar el entorno aislado en este PCVea más abajo

Con sandbox_unavailable, la GUI pregunta «¿Ejecutar sin aislamiento?». Permítalo solo para componentes de confianza. Si lo permite, ese componente puede acceder a todos los archivos y a la red con los permisos de su cuenta. El consentimiento solo puede darse en este PC, y se vuelve a pedir si cambian los archivos del componente. Puede retirar el consentimiento en Ajustes → Seguridad → «Ejecutar sin aislamiento».

La solución más segura es reinstalar el módulo o la extensión desde el catálogo oficial. Los componentes verificados se saltan estas comprobaciones.


3. Problemas de instalación / actualización

3.1 La instalación falla a medias

  • Cuando el instalador se detiene, la pantalla de error muestra un código de causa (fetch_failed, download_failed, extract_failed, elevation_failed, installer_outdated) y la ruta del log. El log se escribe en %TEMP%\saba-chan-installer.log.
  • installer_outdated significa que el instalador es más antiguo que la última versión. Descargue y ejecute el instalador más reciente.
  • Si es un problema de red, compruebe su conexión y luego haga clic en Reintentar o vuelva a ejecutar el instalador.
  • Un fallo al preparar el runtime de Python no detiene la instalación. El demonio lo vuelve a preparar en el primer arranque, y volver a ejecutar el instalador elimina un runtime dañado y lo descarga de nuevo.

3.2 El progreso de instalación del servidor no aparece o se queda atascado (para desarrolladores de módulos)

El progreso de instalación del servidor está disponible en GET /api/provision-progress/:name.

  • Compruebe que el módulo/la extensión escribe el progreso en stderr con el formato PROGRESS:{json}.
  • Compruebe que el JSON es válido (escape las comillas dobles y los saltos de línea dentro de message).
  • El progreso correcto se elimina 5 segundos después de terminar, así que si sondea demasiado tarde lo verá ya vacío. El progreso fallido permanece hasta que el usuario lo descarta y, si era un servidor recién creado, al descartarlo se elimina esa instancia.

3.3 Una actualización no se aplica

Las actualizaciones se comprueban contra la información de versiones firmada que proporciona el relay de Saba-chan, y el hash de cada archivo se verifica antes de aplicarla. Si la firma o un hash no coinciden, no se aplica nada.

  • Si tras una actualización ve un aviso de que algunos elementos no se pudieron actualizar, haga clic en él para ver cuáles fallaron.
  • Vuelva a buscar actualizaciones en los ajustes de la GUI y aplíquelas.
  • Las actualizaciones que reemplazan el demonio, la GUI o el propio instalador las aplica saba-chan-installer después de que el demonio termine. No vuelva a abrir Saba-chan mientras se aplican.
  • Si aun así no se resuelve, cierre Saba-chan, vacíe la carpeta updates\ e inténtelo de nuevo.

4. Bot de Discord / emparejamiento en la nube

4.1 El bot no responde

  • Escriba el prefijo (por defecto Saba-chan), un espacio y luego el nombre del servidor y el comando. Ejemplo: Saba-chan minecraft status.
  • El emparejamiento debe haberse completado en la GUI para que se guarde .node_token.
  • Saba-chan (el demonio) debe estar en ejecución. El bot funciona en la nube, pero los comandos los ejecuta el demonio de este PC.
  • Si el demonio no puede conectarse al relay, revise las advertencias recientes en Ajustes → Solución de problemas → «Diagnóstico» de la GUI. Si ve «older than relay minimum», actualice Saba-chan.
  • Asegúrese de que el bot oficial está invitado a su servidor de Discord y no está en reposo. Si lo está, despiértelo con /saba wake.

4.2 El código de emparejamiento aparece como «caducado»

Un código de emparejamiento solo es válido durante 5 minutos. Genere un código nuevo desde la GUI.

4.3 Conexión con el relay rechazada con 401

ErrorCausaSolución
TOKEN_REPLACEDAl emparejar en otro sitio se eligió este PC con Volver a conectar, lo que reemplazó el token de este PCVuelva a emparejar si quiere seguir usando este PC
INVALID_TOKEN / NODE_NOT_FOUND.node_token es incorrecto o se eliminó en el servidorVuelva a emparejar (invalida el token existente)
MISSING_TOKEN / INVALID_TOKEN_FORMATFalta el archivo de token o tiene un formato incorrectoVuelva a emparejar

4.4 Los comandos de música no funcionan

  • En la página de Discord de la GUI, compruebe que la música está activada en los ajustes de ese servidor de Discord.
  • Quien da el comando debe estar ya en un canal de voz de Discord. Si el bot no puede unirse al canal de voz, revise los permisos del bot en ese canal.
  • La reproducción la gestiona el servidor de música oficial, así que no necesita ffmpeg ni yt-dlp en su PC.

4.5 No se puede conectar a un daemon remoto

MensajeQué hacer
Ese PC no está abierto a conexiones remotasEn el PC servidor, Permitir conexiones remotas está desactivado en Ajustes → Conexión → Daemon remoto. Actívelo y guarde
No se pudo llegar al daemon remotoCompruebe que el PC servidor y su Saba-chan estén encendidos y con internet. Si no se puede llegar directamente, la conexión pasa por la nube de Saba-chan, así que no hace falta abrir puertos
Este PC no está conectado a DiscordEmpareje los dos PC con la misma cuenta de Discord
El daemon remoto ya no acepta este PCEl PC servidor lo desconectó. Pulse Conectar de nuevo en su PC
El puerto ya está en usoOtro programa usa el mismo puerto. Cambie el puerto
Esto solo se puede hacer en ese PCCosas como las actualizaciones o el inicio al iniciar sesión no se pueden hacer en remoto

4.6 Un enlace de Saba-chan web no se abre

  • Un enlace se abre una sola vez, dentro de 5 minutos. Pida otro con /saba web.
  • Si ve No se pudo conectar con tu PC, compruebe que Saba-chan esté en marcha en el PC y que sea la última versión.
  • En un enlace abierto sin PC, los menús de servidores, módulos y PC están bloqueados. Instale la app, ejecute /saba connect y pida un enlace nuevo.
  • Cerrar la pestaña o recargar termina la sesión. Es lo normal.

5. Recuperación de datos / configuración

5.1 config.json está dañado

  • El demonio aparta un config.json dañado como config.json.corrupt-<marca de tiempo> y restaura automáticamente a partir de config.json.bak (la última copia válida).
  • Si .bak también falta o está dañado, arranca con los valores predeterminados. Se restablecen todos los ajustes, incluidos los de la integración con Discord, así que vuelva a introducir en la GUI los valores que necesite tomando como referencia el archivo .corrupt- apartado.
  • La lista de servidores (instances\) y .node_token son independientes de config.json, así que se conservan.

5.2 Restablecimiento completo

1. Cierre la GUI, la CLI y el demonio de Saba-chan
2. Haga una copia de seguridad de toda la carpeta %APPDATA%\saba-chan y elimínela
3. Inicie Saba-chan → se reconstruye con los valores predeterminados

Atención: si instaló servidores en la ubicación predeterminada, los archivos de los servidores de juego y las copias de seguridad están dentro de %APPDATA%\saba-chan\instances\ y se eliminan con ella. Los archivos de juego solo sobreviven si eligió una carpeta de servidor fuera de esta carpeta.


6. ¿Dónde encuentro los logs?

UbicaciónContenido
%APPDATA%\saba-chan\logs\saba-chan-*.logLog de la GUI. También contiene la salida de un demonio iniciado por la GUI
Ventana de consola del demonio en la GUILog del demonio (búfer en memoria, últimas 10 000 líneas)
GUI Ajustes → Solución de problemas → DiagnósticoEstado del demonio y advertencias/errores recientes. No contiene contraseñas ni tokens
%APPDATA%\saba-chan\instances\<id>\logs\Logs de consola del servidor (console.log, sessions\)
Pestaña Consola de la GUISalida del servidor de juego por instancia
%APPDATA%\saba-chan\audit.logRegistro de inicios/paradas/comandos de servidores (con origen, secretos ocultos)
%TEMP%\saba-chan-installer.logLog del instalador

Puede cambiar el nivel de log del demonio con la variable de entorno RUST_LOG cuando ejecuta el demonio directamente (por defecto info).


7. Lista de comprobación para informar de un problema

Antes de abrir una incidencia nueva, compruebe y adjunte lo siguiente.

  1. Versión de Saba-chan (saba-chan-cli version, o el Diagnóstico de la GUI).
  2. Pasos para reproducirlo.
  3. Logs relevantes (fragmentos recortados por marca de tiempo). La salida de «Copiar» en el Diagnóstico de la GUI también ayuda.
  4. SO / compilación (p. ej., Windows 10 x64 21H2).
  5. No adjunte nunca los archivos de token (.ipc_token, .node_token) ni su contenido.

Repositorios: