Solução de problemas

Problemas comuns ao operar o Saba-chan, com passos de solução baseados em como o código realmente se comporta.

Solução de problemas

Este documento se organiza pelos sintomas que os usuários realmente enfrentam e explica como o código do daemon se comporta, além dos passos para resolver. Os exemplos de comandos e caminhos são para o Windows. No Linux, a pasta de dados é ~/.config/saba-chan.


1. O daemon não inicia / a GUI não consegue se conectar

1.1 Conflito de porta / daemon já em execução

O daemon (saba-core) escuta na porta 57474 por padrão, apenas em 127.0.0.1.

  • Só um daemon roda por PC. Se já houver um daemon rodando, um recém-iniciado encerra na hora, e a GUI e a CLI se conectam ao que já está rodando.
  • Se outro programa estiver ocupando a porta, o daemon tenta de novo 10 vezes em intervalos de 2 segundos e depois encerra.
# Windows: veja quem está usando a porta
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • Você pode verificar se o daemon está vivo sem token em http://127.0.0.1:57474/health. saba-chan-cli daemon status mostra a mesma informação.
  • Se um daemon que não responde continuar por aí, pare-o com saba-chan-cli daemon stop. Se mesmo assim ele não sumir, execute Stop-Process -Name saba-core -Force.
  • Se precisar mudar a porta, edite gui.ipcPort no config.json e reinicie. Ou defina uma variável de ambiente como SABA_IPC_PORT=57480.

1.2 Token IPC não confere

O daemon cria um novo .ipc_token a cada vez que inicia. Quando a autenticação falha (401), a GUI e a CLI releem o arquivo de token e tentam de novo uma vez, então isso costuma se resolver sozinho.

Se "falha de autenticação" continuar se repetindo:

  • Confira se a GUI e o daemon olham para a mesma pasta de dados. Se você definiu SABA_DATA_DIR ou SABA_TOKEN_PATH para apenas um deles, os locais do arquivo de token são diferentes.
  • Feche a GUI por completo e abra-a de novo.

2. Início/parada do servidor se comporta de forma estranha

2.1 Cliquei em Parar e nada acontece por um tempo

Isso pode ser normal. O daemon trabalha nesta ordem:

  1. Para servidores com console, ele envia o stop_command do módulo ao console (stdin). Para jogos sem console, como o Palworld, o módulo pede ao servidor que salve e desligue via REST.
  2. Ele espera o servidor encerrar sozinho. O padrão é 30 segundos; um módulo pode mudar isso com [config] stop_timeout no module.toml, e você pode mudar por servidor em Tempo de espera de parada na aba Saba-chan da tela do servidor. Aumente se o mundo for grande e salvar demorar.
  3. Se ele ainda estiver vivo, é finalizado à força.
  4. Durante 30 segundos após a parada, a detecção de crash fica suspensa.

Se ele sempre acaba sendo finalizado à força, o servidor não está recebendo o comando de parada. Confira se o comando de parada aparece no console do servidor. Exemplos: stop no Minecraft, quit no Zomboid.

2.2 O servidor fica voltando

Quando um servidor encerra, o daemon classifica a causa como parado por você / parado no jogo / crash / desconhecido. Por padrão, o reinício automático acontece apenas em crashes; a espera começa em 5 segundos e dobra a cada vez, e ele para de reiniciar depois de mais de 3 reinícios em 10 minutos.

Solução:

  • Confira a classificação em "Saídas recentes" na tela do servidor.
  • Para impedir os reinícios, desligue "Reiniciar após um crash" em "Reinício automático" na aba Saba-chan da tela do servidor. Se você ligou "Reiniciar também em saídas desconhecidas", confira isso também.
  • Confira nos logs do console do servidor (instances\<id>\logs\) a causa do crash. Para um OOM do Java (OutOfMemoryError), aumente a configuração de memória.

2.3 Erro "conflito de porta" ao iniciar

A verificação anterior à inicialização descobriu que a porta do servidor está em uso por outra instância em execução ou por outro programa. Em geral, um processo anterior ainda está por aí, ou outro servidor de jogo usa a mesma porta.

  • Encontre o processo que usa essa porta e pare-o.
  • Se isso não for possível, mude a porta nas configurações da instância e inicie de novo.
  • Você pode desligar a própria verificação com "Detecção de conflito de porta" nas configurações da GUI (gui.portConflictCheck), mas isso não é recomendado.

2.4 "Concordância necessária" (EULA do Minecraft etc.)

Em jogos cujo módulo declara termos (por exemplo, a EULA do Minecraft), você precisa ler e aceitar os termos antes de o servidor poder iniciar. Até fazer isso, a inicialização fica bloqueada com agreement_required.

  • Ao iniciar o servidor na GUI, leia os termos na janela que aparece, marque a caixa e inicie.
  • Não é possível aceitar termos pelo Discord. Depois que você os aceita no Saba-chan do seu PC, também pode iniciar o servidor pelo Discord.

2.5 Salvar as configurações do servidor é rejeitado

  • unknown_setting: A chave não é um campo comum da instância nem uma configuração declarada pelo módulo. É um erro de digitação ou uma configuração de outro jogo.
  • validation_failed / invalid_format: O intervalo ou o formato do valor não corresponde à declaração do módulo. Corrija o campo indicado no erro.
  • "As configurações foram salvas, mas o arquivo de configuração do jogo não pôde ser atualizado": As configurações foram salvas, mas o módulo não conseguiu editar o arquivo de configuração do jogo. Confira se o arquivo do jogo não está bloqueado por outro programa e salve de novo.

2.6 Um componente não verificado não roda

Módulos e extensões que não foram instalados pelo catálogo oficial, ou cujos arquivos mudaram depois, são marcados como "Não verificado". O Saba-chan não os analisa com antivírus. No Windows eles rodam em um ambiente isolado (AppContainer) e no Linux em bubblewrap; onde não é possível isolar (Linux sem bubblewrap ou em que ele não funciona, e macOS), só rodam depois que você consentir com os arquivos atuais. Se a execução for bloqueada, um destes códigos é exibido.

CódigoSignificadoSolução
launch_outside_instanceO módulo tentou executar um programa fora da pasta do servidorConfira de onde o módulo veio
sandbox_unavailableO ambiente isolado não pôde ser preparado neste PCVeja abaixo

Em sandbox_unavailable, a GUI pergunta "Executar sem isolamento?". Permita apenas para componentes em que você confia. Se permitir, esse componente poderá acessar todos os arquivos e a rede com as permissões da sua conta. O consentimento só pode ser dado neste PC, e ele é pedido de novo se os arquivos do componente mudarem. Você pode retirar o consentimento em Configurações → Segurança → "Executar sem isolamento".

A solução mais garantida é reinstalar o módulo ou a extensão pelo catálogo oficial. Componentes verificados pulam essas verificações.


3. Problemas de instalação / atualização

3.1 A instalação falha no meio

  • Quando o instalador para, a tela de erro mostra um código de causa (fetch_failed, download_failed, extract_failed, elevation_failed, installer_outdated) e o caminho do log. O log é gravado em %TEMP%\saba-chan-installer.log.
  • installer_outdated significa que o instalador é mais antigo que a release mais recente. Baixe e execute o instalador mais recente.
  • Para problemas de rede, confira sua conexão e clique em Retry ou execute o instalador de novo.
  • Uma falha ao preparar o runtime Python não interrompe a instalação. O daemon o prepara de novo na primeira execução, e executar o instalador de novo apaga um runtime danificado e o baixa do zero.

3.2 O progresso da instalação do servidor não aparece ou fica travado (para desenvolvedores de módulos)

O progresso da instalação do servidor está disponível em GET /api/provision-progress/:name.

  • Verifique se o módulo/extensão imprime o progresso no stderr no formato PROGRESS:{json}.
  • Verifique se o JSON é válido (escape aspas duplas e quebras de linha dentro de message).
  • Um progresso bem-sucedido é removido 5 segundos após a conclusão, então uma consulta tardia demais já o encontra vazio. Um progresso com falha permanece até o usuário dispensá-lo e, se era um servidor recém-criado, dispensá-lo apaga essa instância.

3.3 Uma atualização não é aplicada

As atualizações são verificadas com base em informações de release assinadas fornecidas pelo relay do Saba-chan, e o hash de cada arquivo é conferido antes da aplicação. Se a assinatura ou um hash não conferir, nada é aplicado.

  • Se, após uma atualização, aparecer um aviso de que alguns itens não puderam ser atualizados, clique nele para ver quais itens falharam.
  • Verifique as atualizações de novo nas configurações da GUI e aplique-as.
  • Atualizações que substituem o daemon, a GUI ou o próprio instalador são aplicadas pelo instalador (saba-chan-installer) depois que o daemon encerra. Não reabra o Saba-chan enquanto ele estiver aplicando.
  • Se mesmo assim não resolver, feche o Saba-chan, esvazie a pasta updates\ e tente de novo.

4. Bot do Discord / pareamento em nuvem

4.1 O bot não responde

  • Escreva o prefixo (padrão Saba-chan), um espaço e então o nome do servidor e o comando. Exemplo: Saba-chan minecraft status.
  • O pareamento precisa estar concluído na GUI para que o .node_token esteja salvo.
  • O Saba-chan (o daemon) precisa estar rodando. O bot roda na nuvem, mas os comandos são executados pelo daemon neste PC.
  • Se o daemon não conseguir se conectar ao relay, confira os avisos recentes em Configurações → Solução de problemas → "Diagnóstico" na GUI. Se você vir "older than relay minimum", atualize o Saba-chan.
  • Confira se o bot oficial foi convidado para o seu servidor do Discord e não está dormindo. Se estiver, acorde-o com /saba wake.

4.2 O código de pareamento está "expirado"

Um código de pareamento vale só por 5 minutos. Gere um novo código pela GUI.

4.3 Conexão com o relay rejeitada com 401

ErroCausaSolução
TOKEN_REPLACEDEm outro lugar, um pareamento escolheu este PC com Reconectar, substituindo o token deste PCPareie de novo se quiser continuar usando este PC
INVALID_TOKEN / NODE_NOT_FOUNDO .node_token está errado ou foi removido no servidorPareie de novo (invalida o token existente)
MISSING_TOKEN / INVALID_TOKEN_FORMATO arquivo de token está ausente ou malformadoPareie de novo

4.4 Os comandos de música não funcionam

  • Na página Discord da GUI, confira se a música está ativada nas configurações daquele servidor do Discord.
  • Quem envia o comando precisa já estar em um canal de voz do Discord. Se o bot não conseguir entrar no canal de voz, confira as permissões de canal do bot.
  • A reprodução é feita pelo servidor de música oficial, então você não precisa de ffmpeg nem yt-dlp no seu PC.

4.5 Não consigo conectar a um daemon remoto

MensagemO que fazer
Esse PC não está aberto a conexões remotasNo PC servidor, Permitir conexões remotas está desligado em Configurações → Conexão → Daemon remoto. Ative e salve
Não foi possível alcançar o daemon remotoVerifique se o PC servidor e o Saba-chan dele estão ligados e com internet. Se não der para alcançar direto, a conexão passa pela nuvem do Saba-chan, então não é preciso abrir portas
Este PC não está conectado ao DiscordPareie os dois PCs com a mesma conta do Discord
O daemon remoto não aceita mais este PCO PC servidor desconectou este PC. Clique em Conectar de novo no seu PC
A porta já está em usoOutro programa usa a mesma porta. Mude a porta
Isso só pode ser feito naquele PCCoisas como atualizações e o início ao entrar não podem ser feitas remotamente
  • Um link abre uma única vez, em até 5 minutos. Peça outro com /saba web.
  • Se aparecer Não foi possível acessar seu PC, verifique se o Saba-chan está rodando no PC e na versão mais recente.
  • Em um link aberto sem PC, os menus de servidores, módulos e PCs ficam bloqueados. Instale o app, conecte com /saba connect e peça um novo link.
  • Fechar a aba ou recarregar encerra a sessão. Isso é normal.

5. Recuperação de dados / configurações

5.1 O config.json está corrompido

  • O daemon move um config.json corrompido para config.json.corrupt-<timestamp> e restaura automaticamente a partir do config.json.bak (a última cópia válida).
  • Se o .bak também estiver ausente ou corrompido, ele inicia com os padrões. Todas as configurações, incluindo as da integração com o Discord, são redefinidas, então reinsira na GUI os valores de que precisar usando o arquivo .corrupt- movido como referência.
  • A lista de servidores (instances\) e o .node_token são separados do config.json, então são mantidos.

5.2 Redefinição completa

1. Feche a GUI, a CLI e o daemon do Saba-chan
2. Faça backup e apague a pasta %APPDATA%\saba-chan inteira
3. Abra o Saba-chan → ele se reconstrói com os padrões

Atenção: se você instalou servidores no local padrão, os arquivos dos servidores de jogo e os backups estão dentro de %APPDATA%\saba-chan\instances\ e são apagados junto. Os arquivos de jogo só sobrevivem se você escolheu uma pasta de servidor fora desta pasta.


6. Onde encontro os logs?

LocalConteúdo
%APPDATA%\saba-chan\logs\saba-chan-*.logLog da GUI. Também contém a saída de um daemon iniciado pela GUI
Janela do console do daemon na GUILog do daemon (buffer em memória, últimas 10.000 linhas)
Configurações da GUI → Solução de problemas → DiagnósticoStatus do daemon e avisos/erros recentes. Não contém senhas nem tokens
%APPDATA%\saba-chan\instances\<id>\logs\Logs do console do servidor (console.log, sessions\)
Aba Console da GUISaída do servidor de jogo por instância
%APPDATA%\saba-chan\audit.logRegistro de início/parada/comandos dos servidores (com origem, segredos mascarados)
%TEMP%\saba-chan-installer.logLog do instalador

Você pode mudar o nível de log do daemon com a variável de ambiente RUST_LOG ao executar o daemon diretamente (padrão info).


7. Checklist para relatar um problema

Antes de abrir uma nova issue, confira e anexe o seguinte.

  1. Versão do Saba-chan (saba-chan-cli version ou o Diagnóstico da GUI).
  2. Passos para reproduzir.
  3. Logs relevantes (trechos recortados pelo horário). A saída de "Copiar" no Diagnóstico da GUI também ajuda.
  4. SO / build (por exemplo, Windows 10 x64 21H2).
  5. Nunca anexe os arquivos de token (.ipc_token, .node_token) nem o conteúdo deles.

Repositórios: