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

%APPDATA%\saba-chan\
  • 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).

NamespaceConteúdoOnde é alterado
guiComportamento da GUI, tema, idioma, porta do daemonConfigurações da GUI
relayIntegração com o Discord (prefixo, apelidos, configurações por servidor do Discord)Página Discord da GUI
updatesIntervalo de verificação de atualizações, download automático, canal de atualizações (channel)Configurações da GUI
remoteDaemon remoto: porta remota e PCs pareadosConfigurações da GUI → Conexão → Daemon remoto
bootÚltimo modo de inicialização escolhido (GUI / CLI / só o daemon)Seletor de inicialização
extensionsLista de extensões ativadas enabled, configurações por extensão settingsConfigurações da GUI → Extensões
chatbotConfigurações da Saba-chan falante (chat com IA)Página Discord da GUI
sandboxConsentimento para executar componentes não verificados sem isolamentoO aviso de execução bloqueada, Configurações → Avançado
cli etc.Configurações próprias de cada clienteO 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.json estiver corrompido e não puder ser lido, o daemon o move para config.json.corrupt-<timestamp> e restaura a partir do .bak.
  • Chaves desconhecidas colocadas em gui ou relay sã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.

ChaveTipoPadrãoDescrição
ipcPortnumber57474Porta da API HTTP do daemon (sempre aberta apenas em 127.0.0.1)
autoRefreshbooleantrueAtualização automática do status na GUI
refreshIntervalnumber (ms)2000Intervalo de consulta do status na GUI. Baixá-lo demais aumenta o uso de CPU
consoleBufferSizenumber2000Número de linhas que o console da GUI mantém
portConflictCheckbooleantrueVerifica conflitos de porta antes de iniciar um servidor
languagestringinferido do SOIdioma (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Também usado nas respostas dos módulos e do Discord
themestringnenhum (a GUI usa auto)"dark" / "light" / "auto"
osNotificationsbooleantrueTambém envia crashes e inícios ou paradas inesperados como notificações do sistema
daemonViewstringnenhum (switch)Formato da lista de servidores quando há daemons remotos. "switch" só o daemon escolhido, "unified" todos os daemons combinados
mainDaemonstringnenhum (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.

ChaveTipoPadrãoDescrição
prefixesstring[]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
serverWordsobject{}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
newGuildInstancesstring"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
nodeSettingsobject{}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.)
cloudobjectrelayUrl, hostId. Preenchidos no pareamento

Os antigos apelidos globais (moduleAliases, commandAliases, instanceAliases) são movidos para serverWords e esvaziados quando o daemon inicia.

As configurações de permissão e do Discord dentro de nodeSettings só 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 start
  • Saba-chan mc stop (apelido)
  • Saba-chan palworld status
  • Saba-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.

ChaveTipoPadrãoDescrição
enabledbooleantrueAbre a porta remota
portnumber57480Porta remota (TLS)
addressstringnenhumIP público ou nome de host que seus outros PCs alcançam. Vazio significa que eles só se conectam pelo relay
transportstring"direct"Forma de conexão. Por enquanto só existe "direct"; deixe como está
clientsarray[]PCs pareados com este daemon (os tokens são guardados só como hash)
daemonsarray[]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 erro unknown_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\) e backups\.

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)

ArquivoFormatoQuando é criadoUsado por
.ipc_tokenUUID v4 (uma linha)Regenerado a cada início do daemonGUI / CLI / módulos e extensões (chamadas à API local)
.node_tokensbn_<hostId>.<secret>Salvo pelo daemon quando o pareamento com o Discord é concluídoA 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 daemon PUT /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 com saba-chan-cli sandbox revoke <component>.

8. Principais variáveis de ambiente

VariávelAlvoDescrição
SABA_IPC_PORTDaemon / CLISubstitui gui.ipcPort
SABA_DAEMONCLIDaemon remoto que recebe os comandos, igual a --daemon <nome>
SABA_DATA_DIRDaemonRedireciona a própria raiz de dados (avançado)
SABA_TOKEN_PATHDaemonCaminho do arquivo de token IPC
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATHDaemonRedirecionam as pastas de módulos, extensões e instâncias
RUST_LOGDaemonFiltro de log (padrão info)
SABA_IPC_URLSubprocessos de módulos/extensõesEndereço da API do daemon. Injetado pelo daemon nos processos filhos
SABA_LANGSubprocessos de módulos/extensõesIdioma atual (gui.language)
PYTHONPATHSubprocessos de módulos/extensõesCaminhos de módulos e extensões combinados e injetados
SABA_ENABLED_EXTENSIONSSubprocessos de módulos/extensõesLista de IDs das extensões ativas (separados por ,)
PYTHONIOENCODINGSubprocessos de módulos/extensõesSempre utf-8
PYTHONUNBUFFEREDSubprocessos de módulos/extensões1: 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.