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
- 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 nombres | Contenido | Dónde se cambia |
|---|---|---|
gui | Comportamiento de la GUI, tema, idioma, puerto del demonio | Ajustes de la GUI |
relay | Integración con Discord (prefijo, alias, ajustes por servidor de Discord) | Página de Discord de la GUI |
updates | Intervalo de comprobación de actualizaciones, descarga automática, canal de actualizaciones (channel) | Ajustes de la GUI |
remote | Daemon remoto: puerto remoto y PC emparejados | Ajustes de la GUI → Conexión → Daemon remoto |
boot | Último modo de arranque elegido (GUI / CLI / solo demonio) | Selector de arranque |
extensions | Lista de extensiones activadas enabled, ajustes por extensión settings | Ajustes de la GUI → Extensiones |
chatbot | Ajustes de Saba-chan parlante (chat con IA) | Página de Discord de la GUI |
sandbox | Consentimiento para ejecutar sin aislamiento componentes no verificados | Aviso de ejecución bloqueada, Ajustes → Avanzado |
cli, etc. | Ajustes propios de cada cliente | El 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.jsonestá dañado y no se puede leer, el demonio lo aparta comoconfig.json.corrupt-<marca de tiempo>y restaura a partir de.bak. - Las claves desconocidas añadidas a
guiorelayse 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.
| Clave | Tipo | Predeterminado | Descripción |
|---|---|---|---|
ipcPort | number | 57474 | Puerto de la API HTTP del demonio (siempre abierto solo en 127.0.0.1) |
autoRefresh | boolean | true | Actualización automática del estado en la GUI |
refreshInterval | number (ms) | 2000 | Intervalo de sondeo del estado en la GUI. Bajarlo demasiado aumenta el uso de CPU |
consoleBufferSize | number | 2000 | Número de líneas que conserva la consola de la GUI |
portConflictCheck | boolean | true | Comprueba conflictos de puertos antes de iniciar un servidor |
language | string | deducido del SO | Idioma (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 |
theme | string | ninguno (la GUI usa auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | Envía también los fallos y los inicios o paradas inesperados como notificaciones del sistema |
daemonView | string | ninguno (switch) | Presentación de la lista de servidores cuando hay daemons remotos. "switch" solo el daemon elegido, "unified" todos los daemons combinados |
mainDaemon | string | ninguno (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.
| Clave | Tipo | Predeterminado | Descripción |
|---|---|---|---|
prefixes | string | [] | 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 |
serverWords | object | {} | 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 |
newGuildInstances | string | "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) |
nodeSettings | object | {} | 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.) |
cloud | object | relayUrl, hostId. Se rellenan al emparejar |
Los alias globales anteriores (
moduleAliases,commandAliases,instanceAliases) se pasan aserverWordsy se vacían cuando el demonio arranca.
Los ajustes de permisos y de Discord dentro de
nodeSettingssolo 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 startSaba-chan mc stop(alias)Saba-chan palworld statusSaba-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.
| Clave | Tipo | Predeterminado | Descripción |
|---|---|---|---|
enabled | boolean | true | Abre el puerto remoto |
port | number | 57480 | Puerto remoto (TLS) |
address | string | ninguno | IP pública o nombre de host al que llegan sus otros PC. Vacío significa que solo se conectan a través del relay |
transport | string | "direct" | Método de conexión. Por ahora solo existe "direct"; déjelo así |
clients | array | [] | PC emparejados con este daemon (los tokens se guardan solo como hash) |
daemons | array | [] | 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_dataes 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 errorunknown_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\) ybackups\.
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)
| Archivo | Formato | Cuándo se crea | Quién lo usa |
|---|---|---|---|
.ipc_token | UUID v4 (una sola línea) | Se regenera cada vez que arranca el demonio | GUI / CLI / módulos y extensiones (llamadas a la API local) |
.node_token | sbn_<hostId>.<secret> | Lo guarda el demonio al completarse el emparejamiento con Discord | La 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 demonioPUT /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 consaba-chan-cli sandbox revoke <component>.
8. Variables de entorno principales
| Variable | Destino | Descripción |
|---|---|---|
SABA_IPC_PORT | Demonio / CLI | Sustituye a gui.ipcPort |
SABA_DAEMON | CLI | Daemon remoto al que se envían los comandos, igual que --daemon <nombre> |
SABA_DATA_DIR | Demonio | Redirige la propia raíz de datos (avanzado) |
SABA_TOKEN_PATH | Demonio | Ruta del archivo de token IPC |
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH | Demonio | Redirigen las carpetas de módulos, extensiones e instancias |
RUST_LOG | Demonio | Filtro de logs (por defecto info) |
SABA_IPC_URL | Subprocesos de módulos/extensiones | Dirección de la API del demonio. El demonio la inyecta en los procesos hijo |
SABA_LANG | Subprocesos de módulos/extensiones | Idioma actual (gui.language) |
PYTHONPATH | Subprocesos de módulos/extensiones | Rutas de módulos y extensiones combinadas e inyectadas |
SABA_ENABLED_EXTENSIONS | Subprocesos de módulos/extensiones | Lista de ID de extensiones activas (separados por ,) |
PYTHONIOENCODING | Subprocesos de módulos/extensiones | Siempre utf-8 |
PYTHONUNBUFFERED | Subprocesos de módulos/extensiones | 1: 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.