Guia dos arquivos de configuração
Explica a pasta de dados do Saba-chan, o arquivo de configurações config.json, as pastas de instância e os arquivos de token com base no que o código realmente faz.
Guia dos arquivos de configuração
As configurações e o estado do Saba-chan ficam na pasta de dados %APPDATA%\saba-chan (= C:\Users\<seu-nome>\AppData\Roaming\saba-chan). Este documento resume como o código de fato usa os arquivos dentro dela e separa os arquivos que você pode editar à mão com segurança daqueles em que não deve mexer.
O daemon (saba-core) faz todo o trabalho; a GUI e a CLI apenas chamam a API HTTP local do daemon. Por isso, o mais seguro é alterar as configurações pela GUI ou pela CLI: o daemon confere o formato ao salvá-las.
1. Estrutura de pastas
- config.jsonTodas as configurações do usuário (por namespace)Todas as configurações do usuário (por namespace)
- config.json.bakÚltima cópia válida (para recuperação automática)Última cópia válida (para recuperação automática)
- .ipc_tokenToken de autenticação daemon ↔ GUI/CLI (regenerado a cada início do daemon)Token de autenticação daemon ↔ GUI/CLI (regenerado a cada início do daemon)
- .node_tokenToken de conexão com o Discord (relay em nuvem). Salvo pelo daemon no pareamentoToken de conexão com o Discord (relay em nuvem). Salvo pelo daemon no pareamento
- instances\Instâncias de servidorInstâncias de servidor
- order.jsonOrdem da listaOrdem da lista
- <id>\
- instance.jsonInformações da instânciaInformações da instância
- settings.jsonValores das configurações do jogo por móduloValores das configurações do jogo por módulo
- logs\Logs do console do servidorLogs do console do servidor
- backups\BackupsBackups
- server\Local de instalação padrão (arquivos do servidor de jogo)Local de instalação padrão (arquivos do servidor de jogo)
- modules\Módulos de jogo instaladosMódulos de jogo instalados
- extensions\Extensões instaladasExtensões instaladas
- logs\Logs da GUI (saba-chan-<timestamp>.log)Logs da GUI (saba-chan-<timestamp>.log)
- audit.logRegistro de início/parada/comandos dos servidores (segredos mascarados)Registro de início/parada/comandos dos servidores (segredos mascarados)
- updates\Área de preparação das atualizaçõesÁrea de preparação das atualizações
- installed-manifest.jsonVersões dos componentes instaladosVersões dos componentes instalados
- O runtime Python portátil (
python-standalone\,python-env\) é criado na pasta de instalação se ela tiver permissão de escrita; caso contrário, nesta pasta de dados. - Também há arquivos que o daemon gerencia sozinho (
daemon.lock,scan-verdicts.json,sandbox-temp\etc.). Não mexa neles. - É possível substituir a própria raiz de dados com a variável de ambiente
SABA_DATA_DIR, mas em geral isso não é recomendado.
2. config.json: o arquivo que guarda todas as configurações
As configurações do usuário vão para um único arquivo, config.json, agrupadas por namespace (chave de nível superior).
| Namespace | Conteúdo | Onde é alterado |
|---|---|---|
gui | Comportamento da GUI, tema, idioma, porta do daemon | Configurações da GUI |
relay | Integração com o Discord (prefixo, apelidos, configurações por servidor do Discord) | Página Discord da GUI |
updates | Intervalo de verificação de atualizações, download automático, canal de atualizações (channel) | Configurações da GUI |
remote | Daemon remoto: porta remota e PCs pareados | Configurações da GUI → Conexão → Daemon remoto |
boot | Último modo de inicialização escolhido (GUI / CLI / só o daemon) | Seletor de inicialização |
extensions | Lista de extensões ativadas enabled, configurações por extensão settings | Configurações da GUI → Extensões |
chatbot | Configurações da Saba-chan falante (chat com IA) | Página Discord da GUI |
sandbox | Consentimento para executar componentes não verificados sem isolamento | O aviso de execução bloqueada, Configurações → Avançado |
cli etc. | Configurações próprias de cada cliente | O respectivo cliente |
Salvamento e recuperação automática
- Os salvamentos são atômicos (gravação em um arquivo temporário e depois substituição), e a última cópia válida imediatamente anterior à substituição é mantida como
config.json.bak. - Se o
config.jsonestiver corrompido e não puder ser lido, o daemon o move paraconfig.json.corrupt-<timestamp>e restaura a partir do.bak. - Chaves desconhecidas colocadas em
guiourelaysão descartadas ao salvar.
3. gui: configurações compartilhadas da GUI / do daemon
Quando o daemon inicia, se a variável de ambiente SABA_IPC_PORT não estiver definida, ele lê gui.ipcPort; se ela também estiver ausente, ele usa o padrão 57474. As demais chaves são lidas principalmente pela GUI.
| Chave | Tipo | Padrão | Descrição |
|---|---|---|---|
ipcPort | number | 57474 | Porta da API HTTP do daemon (sempre aberta apenas em 127.0.0.1) |
autoRefresh | boolean | true | Atualização automática do status na GUI |
refreshInterval | number (ms) | 2000 | Intervalo de consulta do status na GUI. Baixá-lo demais aumenta o uso de CPU |
consoleBufferSize | number | 2000 | Número de linhas que o console da GUI mantém |
portConflictCheck | boolean | true | Verifica conflitos de porta antes de iniciar um servidor |
language | string | inferido do SO | Idioma (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Também usado nas respostas dos módulos e do Discord |
theme | string | nenhum (a GUI usa auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | Também envia crashes e inícios ou paradas inesperados como notificações do sistema |
daemonView | string | nenhum (switch) | Formato da lista de servidores quando há daemons remotos. "switch" só o daemon escolhido, "unified" todos os daemons combinados |
mainDaemon | string | nenhum (este PC) | ID do PC do daemon remoto a mostrar primeiro quando o app abre (daemon principal) |
Também há chaves de aparência, como cores, escala da fonte e tamanho da janela; o que você altera nas configurações da GUI é salvo como está.
4. relay: integração com o Discord
O bot do Discord roda apenas no relay em nuvem, então não há processo de bot nem token de bot no seu PC. Este namespace guarda o prefixo, as palavras de chamada e as configurações por servidor do Discord que você edita na GUI; após o pareamento, o daemon os sincroniza com o relay.
| Chave | Tipo | Padrão | Descrição |
|---|---|---|---|
prefixes | string | [] | Prefixos dos comandos de chat usados quando um servidor do Discord não tem prefixo próprio (até 10, cada um com 1 a 32 caracteres sem espaços). Os prefixos por servidor do Discord ficam em nodeSettings e mudam na aba Configurações do bot do servidor do Discord no app. Se a lista estiver vazia, vale o padrão do idioma do bot desse servidor do Discord (se não definido, o idioma do app no PC) (coreano 사바쨩, japonês サバちゃん, nos demais Saba-chan). Um prefixo que termina em letra precisa ser seguido de um espaço (ou vírgula ou dois-pontos) para a mensagem contar como comando |
serverWords | object | {} | Para cada servidor (ID da instância), as palavras que o chamam e chamam seus comandos, {words, commands}. Altere na aba Discord da tela do servidor |
newGuildInstances | string | "auto" | Se os servidores deste PC são abertos de imediato (auto) ou escolhidos depois (manual) em um servidor do Discord recém-conectado com um código de pareamento |
nodeSettings | object | {} | Configurações por servidor do Discord (instâncias permitidas, permissões de comando, idioma, prefixo, formato dos comandos de barra, Saba-chan cantora, Saba-chan leitora, confirmação etc.) |
cloud | object | relayUrl, hostId. Preenchidos no pareamento |
Os antigos apelidos globais (
moduleAliases,commandAliases,instanceAliases) são movidos paraserverWordse esvaziados quando o daemon inicia.
As configurações de permissão e do Discord dentro de
nodeSettingssó mudam pelas telas (APIs) dedicadas; salvar a configuração inteira do bot não as sobrescreve.
Sintaxe dos comandos
Saba-chan <server name or alias> <command> [arguments…]
Saba-chan minecraft startSaba-chan mc stop(apelido)Saba-chan palworld statusSaba-chan list: lista de servidores,Saba-chan help: ajuda
Todo servidor tem os comandos padrão start, stop e status; os demais comandos são definidos pelo módulo. Recursos extras, como música, são fornecidos pelo bot do lado do servidor de relay.
remote: daemon remoto
A porta remota à qual seus outros PCs se conectam e a lista de daemons remotos aos quais este PC se conecta. Altere no app em Configurações → Conexão → Daemon remoto ou com saba-chan-cli remote. Não entra na exportação de configurações. Uso: Daemon remoto. É uma chave de nível superior do config.json, separada de relay.
| Chave | Tipo | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | true | Abre a porta remota |
port | number | 57480 | Porta remota (TLS) |
address | string | nenhum | IP público ou nome de host que seus outros PCs alcançam. Vazio significa que eles só se conectam pelo relay |
transport | string | "direct" | Forma de conexão. Por enquanto só existe "direct"; deixe como está |
clients | array | [] | PCs pareados com este daemon (os tokens são guardados só como hash) |
daemons | array | [] | Daemons remotos aos quais este PC se conecta |
5. instances\: instâncias de servidor
Cada servidor que você cria na GUI é guardado em uma pasta própria instances\<id>\. <id> é um UUID.
instance.json: Nome, módulo, executável/pasta de trabalho, porta, informações de conexão REST, tarefas agendadas, dados de extensão (extension_data) etc.settings.json: Valores das configurações do jogo que o módulo declara (por exemplo, máximo de jogadores, dificuldade).order.json: Ordem da lista na GUI.
// instances\<id>\instance.json (trecho)
{
"id": "3f6c…",
"name": "My Minecraft Server",
"module_name": "minecraft",
"working_dir": null,
"port": 25565,
"extension_data": {}
}
- O RCON só é usado para um jogo cujo módulo declara
supported = ["rcon"](sem console e sem REST API); nesse caso o daemon define uma porta e uma senha aleatória por instância e conecta apenas por loopback (127.0.0.1). Os demais comandos de jogo são enviados ao console do servidor (stdin), e o Palworld usa a REST API dele. Chaves de RCON que sobraram em arquivos antigos são removidas ao serem carregadas. extension_dataé um espaço reservado para extensões. Por exemplo, para módulos instalados via SteamCMD, o método de instalação e as informações do app ficam aqui.- Ao salvar as configurações do servidor (configurações do servidor na GUI,
PATCH /api/instance/:id), chaves que não são campos comuns da instância nem configurações declaradas pelo módulo são rejeitadas com o errounknown_setting. - Excluir uma instância apaga a pasta
instances\<id>\inteira, incluindo os arquivos do servidor de jogo no local de instalação padrão (server\) ebackups\.
Só edite esses arquivos à mão enquanto o daemon não estiver rodando. Editá-los com ele rodando cria divergência com o estado em memória do daemon, e o próximo salvamento sobrescreve a sua edição.
6. Arquivos de token (.ipc_token / .node_token)
| Arquivo | Formato | Quando é criado | Usado por |
|---|---|---|---|
.ipc_token | UUID v4 (uma linha) | Regenerado a cada início do daemon | GUI / CLI / módulos e extensões (chamadas à API local) |
.node_token | sbn_<hostId>.<secret> | Salvo pelo daemon quando o pareamento com o Discord é concluído | A conexão do daemon com o relay |
Token IPC
A API do daemon escuta apenas em 127.0.0.1, e toda requisição, exceto /health, precisa do cabeçalho X-Saba-Token.
GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <contents of the .ipc_token file>
- O token muda sempre que o daemon reinicia. A GUI e a CLI releem o arquivo de token quando a autenticação falha, então você não precisa fazer nada.
- O local do arquivo de token pode ser alterado com
SABA_TOKEN_PATH.
Token de nó
O .node_token é o segredo que conecta este PC ao bot do Discord (relay em nuvem). O daemon o envia ao relay por HTTPS para se autenticar. Nunca o mostre a ninguém; se suspeitar que vazou, pareie de novo pela GUI. Parear de novo invalida o token antigo.
7. Configurações de extensões e de isolamento (extensions / sandbox)
extensions.enabled: Lista de IDs das extensões ativadas.extensions.settings: Valores de configuração por extensão{ "<id>": { "<key>": value } }. Alterados pela API do daemonPUT /api/extensions/:id/config.sandbox.unisolated: Consentimento para executar sem isolamento um componente cujo ambiente isolado não pôde ser preparado. Ele é guardado como uma impressão digital dos arquivos do componente e é pedido de novo se algum arquivo mudar. Você pode retirá-lo em Configurações → Segurança → "Executar sem isolamento" na GUI, ou comsaba-chan-cli sandbox revoke <component>.
8. Principais variáveis de ambiente
| Variável | Alvo | Descrição |
|---|---|---|
SABA_IPC_PORT | Daemon / CLI | Substitui gui.ipcPort |
SABA_DAEMON | CLI | Daemon remoto que recebe os comandos, igual a --daemon <nome> |
SABA_DATA_DIR | Daemon | Redireciona a própria raiz de dados (avançado) |
SABA_TOKEN_PATH | Daemon | Caminho do arquivo de token IPC |
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH | Daemon | Redirecionam as pastas de módulos, extensões e instâncias |
RUST_LOG | Daemon | Filtro de log (padrão info) |
SABA_IPC_URL | Subprocessos de módulos/extensões | Endereço da API do daemon. Injetado pelo daemon nos processos filhos |
SABA_LANG | Subprocessos de módulos/extensões | Idioma atual (gui.language) |
PYTHONPATH | Subprocessos de módulos/extensões | Caminhos de módulos e extensões combinados e injetados |
SABA_ENABLED_EXTENSIONS | Subprocessos de módulos/extensões | Lista de IDs das extensões ativas (separados por ,) |
PYTHONIOENCODING | Subprocessos de módulos/extensões | Sempre utf-8 |
PYTHONUNBUFFERED | Subprocessos de módulos/extensões | 1: descarrega o stdout imediatamente |
Se você suspeitar que quebrou algo, pare o daemon primeiro, depois apague o arquivo em questão e inicie de novo; a maioria dos arquivos é regenerada com os padrões. Apagar o config.json redefine todas as configurações, incluindo as da integração com o Discord, então tente primeiro restaurar o config.json.bak. Não apague a pasta instances\: sua lista de servidores e os arquivos de jogo instalados no local padrão vão junto.