Guía de archivos de configuración

Explica la carpeta de datos de Saba-chan, el archivo de ajustes config.json, las carpetas de instancia y los archivos de token según lo que hace realmente el código.

Guía de archivos de configuración

Los ajustes y el estado de Saba-chan se encuentran en la carpeta de datos %APPDATA%\saba-chan (= C:\Users\<su-nombre>\AppData\Roaming\saba-chan). Este documento resume cómo usa realmente el código los archivos que contiene y distingue entre los archivos que puede editar a mano con seguridad y los que no debe tocar.

El demonio (saba-core) hace todo el trabajo; la GUI y la CLI solo llaman a la API HTTP local del demonio. Por eso lo más seguro es cambiar los ajustes desde la GUI o la CLI: el demonio comprueba su formato al guardarlos.


1. Estructura de carpetas

%APPDATA%\saba-chan\
  • config.jsonTodos los ajustes del usuario (por espacio de nombres)Todos los ajustes del usuario (por espacio de nombres)
  • config.json.bakÚltima copia válida (para la recuperación automática)Última copia válida (para la recuperación automática)
  • .ipc_tokenToken de autenticación demonio ↔ GUI/CLI (se regenera cada vez que arranca el demonio)Token de autenticación demonio ↔ GUI/CLI (se regenera cada vez que arranca el demonio)
  • .node_tokenToken de conexión con Discord (relay en la nube). Lo guarda el demonio al emparejarToken de conexión con Discord (relay en la nube). Lo guarda el demonio al emparejar
  • instances\Instancias de servidorInstancias de servidor
  • order.jsonOrden de la listaOrden de la lista
  • <id>\
  • instance.jsonInformación de la instanciaInformación de la instancia
  • settings.jsonValores de ajustes del juego propios del móduloValores de ajustes del juego propios del módulo
  • logs\Logs de consola del servidorLogs de consola del servidor
  • backups\Copias de seguridadCopias de seguridad
  • server\Ubicación de instalación predeterminada (archivos del servidor de juego)Ubicación de instalación predeterminada (archivos del servidor de juego)
  • modules\Módulos de juego instaladosMódulos de juego instalados
  • extensions\Extensiones instaladasExtensiones instaladas
  • logs\Logs de la GUI (saba-chan-<marca de tiempo>.log)Logs de la GUI (saba-chan-<marca de tiempo>.log)
  • audit.logRegistro de inicios/paradas/comandos de servidores (secretos ocultos)Registro de inicios/paradas/comandos de servidores (secretos ocultos)
  • updates\Zona de preparación de actualizacionesZona de preparación de actualizaciones
  • installed-manifest.jsonVersiones de los componentes instaladosVersiones de los componentes instalados
  • El runtime de Python portable (python-standalone\, python-env\) se crea en la carpeta de instalación si se puede escribir en ella; si no, en esta carpeta de datos.
  • También hay archivos que el demonio gestiona por su cuenta (daemon.lock, scan-verdicts.json, sandbox-temp\, etc.). No los toque.
  • Puede redefinir la propia raíz de datos con la variable de entorno SABA_DATA_DIR, pero en general no se recomienda.

2. config.json: el archivo que contiene todos los ajustes

Los ajustes del usuario se guardan en un único archivo, config.json, agrupados por espacio de nombres (clave de primer nivel).

Espacio de nombresContenidoDónde se cambia
guiComportamiento de la GUI, tema, idioma, puerto del demonioAjustes de la GUI
relayIntegración con Discord (prefijo, alias, ajustes por servidor de Discord)Página de Discord de la GUI
updatesIntervalo de comprobación de actualizaciones, descarga automática, canal de actualizaciones (channel)Ajustes de la GUI
remoteDaemon remoto: puerto remoto y PC emparejadosAjustes de la GUI → Conexión → Daemon remoto
bootÚltimo modo de arranque elegido (GUI / CLI / solo demonio)Selector de arranque
extensionsLista de extensiones activadas enabled, ajustes por extensión settingsAjustes de la GUI → Extensiones
chatbotAjustes de Saba-chan parlante (chat con IA)Página de Discord de la GUI
sandboxConsentimiento para ejecutar sin aislamiento componentes no verificadosAviso de ejecución bloqueada, Ajustes → Avanzado
cli, etc.Ajustes propios de cada clienteEl cliente correspondiente

Guardado y recuperación automática

  • Los guardados son atómicos (se escribe en un archivo temporal y luego se reemplaza), y la última copia válida justo antes del reemplazo se conserva como config.json.bak.
  • Si config.json está dañado y no se puede leer, el demonio lo aparta como config.json.corrupt-<marca de tiempo> y restaura a partir de .bak.
  • Las claves desconocidas añadidas a gui o relay se descartan al guardar.

3. gui: ajustes compartidos GUI / demonio

Al arrancar el demonio, si no está definida la variable de entorno SABA_IPC_PORT, lee gui.ipcPort; si tampoco existe, usa el valor predeterminado 57474. Las demás claves las lee sobre todo la GUI.

ClaveTipoPredeterminadoDescripción
ipcPortnumber57474Puerto de la API HTTP del demonio (siempre abierto solo en 127.0.0.1)
autoRefreshbooleantrueActualización automática del estado en la GUI
refreshIntervalnumber (ms)2000Intervalo de sondeo del estado en la GUI. Bajarlo demasiado aumenta el uso de CPU
consoleBufferSizenumber2000Número de líneas que conserva la consola de la GUI
portConflictCheckbooleantrueComprueba conflictos de puertos antes de iniciar un servidor
languagestringdeducido del SOIdioma (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). También se usa para los módulos y las respuestas de Discord
themestringninguno (la GUI usa auto)"dark" / "light" / "auto"
osNotificationsbooleantrueEnvía también los fallos y los inicios o paradas inesperados como notificaciones del sistema
daemonViewstringninguno (switch)Presentación de la lista de servidores cuando hay daemons remotos. "switch" solo el daemon elegido, "unified" todos los daemons combinados
mainDaemonstringninguno (este PC)ID del PC del daemon remoto que se ve primero al abrir la app (daemon principal)

También hay claves de apariencia, como colores, escala de fuente y tamaño de ventana; lo que cambie en los ajustes de la GUI se guarda tal cual.


4. relay: integración con Discord

El bot de Discord solo se ejecuta en el relay en la nube, así que en su PC no hay ni proceso de bot ni token de bot. Este espacio de nombres guarda el prefijo, los nombres con que se llama a cada servidor y los ajustes por servidor de Discord que edita en la GUI; tras el emparejamiento, el demonio los sincroniza con el relay.

ClaveTipoPredeterminadoDescripción
prefixesstring[]Lista de prefijos de los comandos de chat que se usa cuando no se ha fijado un prefijo propio para un servidor de Discord (hasta 10, cada uno de 1 a 32 caracteres sin espacios). Si la lista está vacía, se usa el predeterminado del idioma del bot de ese servidor de Discord (si no se ha fijado, el idioma de la app del PC) (coreano 사바쨩, japonés サバちゃん, en otro caso Saba-chan). Tras un prefijo que termina en letra debe haber un espacio (o una coma o dos puntos) para que el mensaje cuente como comando
serverWordsobject{}Por servidor (ID de instancia), las palabras con que se llama a ese servidor y a sus comandos: {words, commands}. Se cambian en la pestaña Discord de la pantalla del servidor
newGuildInstancesstring"auto"Si, en un servidor de Discord recién conectado con un código de emparejamiento, se abren de inmediato todos los servidores de este PC (auto) o se eligen más tarde (manual)
nodeSettingsobject{}Ajustes por servidor de Discord (instancias permitidas, permisos de comandos, idioma, prefijo, aspecto de los slash commands, Saba-chan cantante, Saba-chan lectora, repreguntas, etc.)
cloudobjectrelayUrl, hostId. Se rellenan al emparejar

Los alias globales anteriores (moduleAliases, commandAliases, instanceAliases) se pasan a serverWords y se vacían cuando el demonio arranca.

Los ajustes de permisos y de Discord dentro de nodeSettings solo cambian a través de sus pantallas (API) dedicadas; guardar la configuración completa del bot no los sobrescribe.

Sintaxis de los comandos

Saba-chan <nombre o alias del servidor> <comando> [argumentos…]
  • Saba-chan minecraft start
  • Saba-chan mc stop (alias)
  • Saba-chan palworld status
  • Saba-chan list: lista de servidores, Saba-chan help: ayuda

Todos los servidores tienen los comandos predeterminados start, stop y status; los demás comandos los define el módulo. Las funciones adicionales, como la música, las proporciona el bot en el lado del servidor relay.

remote: daemon remoto

El puerto remoto al que se conectan sus otros PC y la lista de daemons remotos a los que se conecta este PC. Se cambia en la app en Ajustes → Conexión → Daemon remoto o con saba-chan-cli remote. No se incluye al exportar los ajustes. Uso: Daemon remoto. Es una clave de primer nivel de config.json, aparte de relay.

ClaveTipoPredeterminadoDescripción
enabledbooleantrueAbre el puerto remoto
portnumber57480Puerto remoto (TLS)
addressstringningunoIP pública o nombre de host al que llegan sus otros PC. Vacío significa que solo se conectan a través del relay
transportstring"direct"Método de conexión. Por ahora solo existe "direct"; déjelo así
clientsarray[]PC emparejados con este daemon (los tokens se guardan solo como hash)
daemonsarray[]Daemons remotos a los que se conecta este PC

5. instances\: instancias de servidor

Cada servidor que crea en la GUI se guarda en su propia carpeta instances\<id>\. <id> es un UUID.

  • instance.json: Nombre, módulo, ejecutable/carpeta de trabajo, puerto, datos de conexión REST, tareas programadas, datos de extensiones (extension_data), etc.
  • settings.json: Valores de los ajustes de juego que declara el módulo (p. ej., número máximo de jugadores, dificultad).
  • order.json: Orden de la lista de la GUI.
// instances\<id>\instance.json (extracto)
{
  "id": "3f6c…",
  "name": "My Minecraft Server",
  "module_name": "minecraft",
  "working_dir": null,
  "port": 25565,
  "extension_data": {}
}
  • RCON solo se usa para un juego cuyo módulo declara supported = ["rcon"] (sin consola ni API REST); entonces el demonio asigna un puerto y una contraseña aleatoria por instancia y se conecta solo por loopback (127.0.0.1). Los demás comandos de juego se envían a la consola del servidor (stdin), y Palworld usa su API REST. Las claves RCON que queden en archivos antiguos se eliminan al cargarlos.
  • extension_data es un almacenamiento reservado para las extensiones. Por ejemplo, en los módulos instalados mediante SteamCMD, aquí se guardan el método de instalación y los datos de la aplicación.
  • Al guardar los ajustes de un servidor (ajustes del servidor en la GUI, PATCH /api/instance/:id), las claves que no son ni campos comunes de instancia ni ajustes declarados por el módulo se rechazan con un error unknown_setting.
  • Eliminar una instancia elimina toda la carpeta instances\<id>\, incluidos los archivos del servidor de juego de la ubicación de instalación predeterminada (server\) y backups\.

Edite estos archivos a mano solo cuando el demonio no esté en ejecución. Si los edita mientras se ejecuta, se desincronizan del estado en memoria del demonio, y el siguiente guardado sobrescribe su edición.


6. Archivos de token (.ipc_token / .node_token)

ArchivoFormatoCuándo se creaQuién lo usa
.ipc_tokenUUID v4 (una sola línea)Se regenera cada vez que arranca el demonioGUI / CLI / módulos y extensiones (llamadas a la API local)
.node_tokensbn_<hostId>.<secret>Lo guarda el demonio al completarse el emparejamiento con DiscordLa conexión del demonio con el relay

Token IPC

La API del demonio solo escucha en 127.0.0.1, y todas las solicitudes salvo /health necesitan la cabecera X-Saba-Token.

GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <contenido del archivo .ipc_token>
  • El token cambia cada vez que se reinicia el demonio. La GUI y la CLI vuelven a leer el archivo de token cuando falla la autenticación, así que no tiene que hacer nada.
  • La ubicación del archivo de token se puede cambiar con SABA_TOKEN_PATH.

Token de nodo

.node_token es el secreto que conecta este PC con el bot de Discord (relay en la nube). El demonio lo envía al relay por HTTPS para autenticarse. No se lo enseñe nunca a nadie; si sospecha que se ha filtrado, vuelva a emparejar desde la GUI. Volver a emparejar invalida el token anterior.


7. Ajustes de extensiones y de aislamiento (extensions / sandbox)

  • extensions.enabled: Lista de ID de extensiones activadas.
  • extensions.settings: Valores de ajustes por extensión { "<id>": { "<key>": value } }. Se cambian mediante la API del demonio PUT /api/extensions/:id/config.
  • sandbox.unisolated: Consentimiento para ejecutar sin aislamiento un componente cuyo entorno aislado no se pudo preparar. Se guarda como una huella de los archivos del componente y se vuelve a pedir si cambia algún archivo. Puede retirarlo en Ajustes → Seguridad → «Ejecutar sin aislamiento» en la GUI, o con saba-chan-cli sandbox revoke <component>.

8. Variables de entorno principales

VariableDestinoDescripción
SABA_IPC_PORTDemonio / CLISustituye a gui.ipcPort
SABA_DAEMONCLIDaemon remoto al que se envían los comandos, igual que --daemon <nombre>
SABA_DATA_DIRDemonioRedirige la propia raíz de datos (avanzado)
SABA_TOKEN_PATHDemonioRuta del archivo de token IPC
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATHDemonioRedirigen las carpetas de módulos, extensiones e instancias
RUST_LOGDemonioFiltro de logs (por defecto info)
SABA_IPC_URLSubprocesos de módulos/extensionesDirección de la API del demonio. El demonio la inyecta en los procesos hijo
SABA_LANGSubprocesos de módulos/extensionesIdioma actual (gui.language)
PYTHONPATHSubprocesos de módulos/extensionesRutas de módulos y extensiones combinadas e inyectadas
SABA_ENABLED_EXTENSIONSSubprocesos de módulos/extensionesLista de ID de extensiones activas (separados por ,)
PYTHONIOENCODINGSubprocesos de módulos/extensionesSiempre utf-8
PYTHONUNBUFFEREDSubprocesos de módulos/extensiones1: vacía stdout de inmediato

Si sospecha que ha roto algo, detenga primero el demonio, elimine el archivo en cuestión y vuelva a iniciarlo; la mayoría de los archivos se regeneran con los valores predeterminados. Eliminar config.json restablece todos los ajustes, incluidos los de la integración con Discord, así que intente antes restaurar config.json.bak. No elimine la carpeta instances\: con ella se irían su lista de servidores y los archivos de juego instalados en la ubicación predeterminada.