Primeiros passos

Guia de instalação, configuração e operação do Saba-chan, cobrindo a arquitetura de execução e o comportamento durante a operação.

Primeiros passos

Este documento cobre os procedimentos básicos de instalação, configuração e criação de servidores do Saba-chan. Para a integração remota e a resolução de problemas, consulte a documentação do Bot do Discord e de Solução de problemas.


1. Download e instalação

Requisitos: Windows 10 ou 11 (64 bits), o Microsoft Edge WebView2 Runtime (incluído no Windows 11 e nas versões recentes do Windows 10) e conexão com a internet. No Linux (x86_64), a instalação é feita com um comando de uma linha (veja 1.1 abaixo). No macOS (Apple silicon), baixe o .dmg na página inicial e arraste o app para Aplicativos. O app não é notarizado pela Apple: se o macOS bloquear na primeira abertura, permita abrir em Ajustes do Sistema > Privacidade e Segurança.

  1. Baixe o instalador saba-chan-installer.exe pelo botão de download do site ou pelo GitHub Releases.
  2. Execute o instalador, escolha o local de instalação, os módulos de jogo a instalar primeiro e as opções de atalho, e clique em Install.
    • O local de instalação padrão é C:\Program Files\Saba-chan. Se você escolher uma pasta que já contém outros arquivos, o instalador cria uma pasta Saba-chan dentro dela.
    • Também é possível adicionar módulos de jogo depois, pelo aplicativo.
  3. O instalador configura os componentes abaixo. Dependendo da sua conexão, isso pode levar alguns minutos.
    • Verifica a release assinada mais recente e então baixa e implanta o daemon, a GUI, a CLI, os arquivos de idioma e os demais componentes (o hash de cada arquivo é conferido). O instalador também fica na pasta de instalação, para aplicar atualizações e desinstalar o Saba-chan depois
    • Instala os módulos de jogo selecionados e as extensões de que eles precisam (por exemplo, SteamCMD)
    • Baixa um Python portátil e cria um ambiente venv (instalado em uma pasta do Saba-chan; o PATH do sistema não é alterado)
    • Registra as versões dos componentes instalados em installed-manifest.json
  4. Ao terminar a instalação, clique em Launch Saba-chan para abrir a GUI. Também é possível iniciá-la pelo atalho da área de trabalho ou do menu Iniciar.

Configurações, arquivos dos servidores de jogo, mundos e backups ficam em %APPDATA%\saba-chan. Apagar a pasta do programa não remove os dados dos seus servidores.

Reinstalação: se a instalação falhou no meio do caminho ou há arquivos danificados, execute o instalador de novo. Ele baixa novamente os arquivos do programa e apaga e baixa de novo um runtime Python danificado. Suas configurações e os dados dos servidores são mantidos. Um instalador mais antigo que a release atual é bloqueado, então sempre baixe o instalador mais recente.

1.1 Linux

No Linux (x86_64), a instalação é feita com um comando de uma linha. É preciso ter curl, unzip, sha256sum e python3.

curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
  • Num desktop com tela, instala também o app (GUI), coloca o Saba-chan no menu de aplicativos e abre o app. Como no Windows, o app inicia o daemon. A janela do app precisa do WebKitGTK; se faltar, o instalador mostra o comando de instalação (por exemplo, sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1).
  • Num servidor sem tela, instala só o daemon e a CLI e inicia o daemon como serviço de usuário do systemd. Você também pode escolher com --gui ou --no-gui.
  • O instalador baixa a versão estável mais recente, confere os arquivos com os hashes da versão e o manifesto assinado, instala e cria ~/.local/bin/saba-chan-cli. Num servidor sem tela, inicia o daemon como serviço de usuário do systemd (saba-chan.service). Escolha a pasta de instalação e os módulos com sh -s -- --dir <pasta> --modules <módulo…>.
  • Num servidor sem tela, para iniciar com o sistema sem fazer login, rode uma vez sudo loginctl enable-linger $USER.
  • A pasta de dados é ~/.config/saba-chan.
  • Um servidor Linux sem tela é gerenciado pelo app de outro PC como daemon remoto. A conexão com o Discord e a ativação das conexões remotas estão em Daemon remoto.

2. Entendendo a arquitetura do Saba-chan

O diagrama abaixo mostra como os componentes do Saba-chan se relacionam e se comunicam:

Seu PC
App GUIApp para desktop · opcional
CLIComandos e shell interativo · opcional
Daemon do Saba-chan (saba-core)Cuida sozinho dos servidores, das configurações e da conexão com o Discord
Servidores de jogoIniciados e vigiados pelo daemon
MódulosManuais por jogo · Python
ExtensõesRecursos extras · Python
Nuvem
Relay do DiscordBot do Saba-chan · liga o Discord ao seu PC
DiscordComandos pelo chat
Os servidores de jogo rodam no seu PC. Com o relay só trafegam comandos do Discord, seus resultados e um resumo como a lista e o estado dos servidores, e nenhuma porta é aberta para o controle remoto.
  • Daemon (saba-core.exe): O núcleo que executa todas as funções do Saba-chan. Ele executa e gerencia os processos dos servidores, coleta logs e expõe uma API HTTP apenas no endereço local 127.0.0.1:57474.
  • GUI: O aplicativo de desktop que chama a API do daemon.
  • CLI: A ferramenta de linha de comando que chama a API do daemon. Executada sem argumentos, ela abre um shell interativo.
  • Runner (saba-runner): Um pequeno processo vigia anexado a cada servidor. Ele mantém o console e os logs do servidor contínuos mesmo quando o daemon reinicia.
  • Servidor de relay: O serviço em nuvem onde o bot do Discord roda. Após o pareamento, o daemon se conecta para fora (long-polling) para receber os comandos de gerenciamento do Discord, e cada requisição é autenticada via HTTPS com o token de nó recebido no pareamento. O relay só transporta comandos do Discord, seus resultados e resumos dos servidores, nunca o tráfego do jogo, então o acesso de rede dos jogadores que entram no jogo precisa ser configurado separadamente.

Os servidores de jogo rodam no seu próprio PC. A GUI e a CLI apenas enviam requisições ao daemon; elas nunca editam arquivos nem iniciam processos por conta própria.

Fechar a janela com 'Fechar apenas interface' mantém o daemon e os servidores de jogo em execução em segundo plano. Ao reabrir a GUI, ela se reconecta ao daemon e recupera o estado atual dos servidores e os logs do console. Se o daemon reiniciar, ele se reconecta (re-attach) aos processos de servidor que continuam em execução para retomar o monitoramento (processos encerrados por queda de energia ou reinicialização do sistema não são restaurados). Para parar um servidor de jogo específico, clique em Parar na interface.


3. Criando seu primeiro servidor (pela GUI)

Na primeira vez que o Saba-chan é aberto, a lista de servidores está vazia e um cartão 'Próximo passo' orienta você a instalar um módulo de jogo e criar seu primeiro servidor. Se ainda não houver nenhum módulo de jogo instalado, instale um primeiro pela Saba Storage no aplicativo. Depois, siga estes passos para criar um servidor:

  1. Adicionar um servidor: Clique em Adicionar servidor e escolha Adicionar como novo servidor. Para vincular uma pasta de servidor que você já usa, escolha Migrar servidor existente.
  2. Escolher um jogo: Selecione um dos módulos de jogo instalados (módulos oficiais: Minecraft, Palworld, Project Zomboid e Terraria).
  3. Configurar o servidor: Informe um nome para o servidor e preencha as opções que o módulo pedir (por exemplo, o tipo de servidor do Minecraft) e a configuração recomendada. A porta (o número que um jogo usa para aceitar jogadores) é atribuída automaticamente para não colidir com outros servidores.
  4. Aceitar os termos: Em jogos que exigem a aceitação de termos (EULA), como o Minecraft, você precisa ler os termos e marcar a caixa você mesmo antes de o servidor poder ser criado. O Saba-chan nunca aceita termos automaticamente.
  5. Iniciar a instalação: Ao clicar em Adicionar Servidor, o daemon executa as tarefas de configuração na seguinte ordem:
    • Verifica as extensões exigidas pelo módulo (por exemplo, Palworld e Project Zomboid precisam do SteamCMD). Se uma extensão necessária estiver desativada, você será solicitado a ativá-la em Configurações → Extensões.
    • Salva os dados da instância na pasta %APPDATA%\saba-chan\instances\<ID da instância>\
    • Executa o hook server.post_create
    • Baixa a versão mais recente dos arquivos do servidor de jogo para o diretório server\ da pasta da instância (download oficial do servidor para o Minecraft e o Terraria, SteamCMD para Palworld e Project Zomboid). O andamento é mostrado na barra de progresso.
  6. Iniciar: Ao clicar em Iniciar, o daemon confere se os termos exigidos foram aceitos e executa as verificações anteriores à inicialização, executa o hook server.pre_start e então inicia o processo com o comando de inicialização do módulo (get_launch_command). A saída do console do servidor é exibida ao vivo no console da GUI.

Todo comando de jogo passa pelo daemon, na ordem stdin (console do servidor) → REST → RCON. Jogos com console ou REST API (como o Palworld) rodam com o RCON desligado. Só um jogo que suporta apenas RCON o usa, com porta e senha aleatória por instância definidas pelo daemon, e apenas por loopback (127.0.0.1).


4. Comportamentos a conhecer durante a operação

4.1 Tempo limite de parada

Para processos gerenciados diretamente pelo daemon, quando o usuário clica em Parar, o daemon tenta o encerramento na seguinte ordem. Os valores de configuração são definidos em src/supervisor/mod.rs.

  1. Parada graciosa: envia o stop_command do módulo (por exemplo, stop no Minecraft, quit no Zomboid) ao console do servidor (stdin). Para um jogo sem entrada de console (Palworld), o módulo pede ao servidor que salve e desligue pela REST API. Em seguida, o daemon aguarda o tempo de espera de parada (o valor definido na aba Saba-chan do servidor; se não houver, [config].stop_timeout no module.toml; se também não houver, 30 segundos). Se o tempo limite for excedido, o daemon encerra o processo à força e aguarda mais 2 segundos.
  2. Encerramento forçado: no encerramento forçado, a árvore de processos é finalizada imediatamente, seguida de uma espera de até 5 segundos.
  3. Intervalo após a parada: durante 30 segundos após uma parada, a detecção automática de crash fica em pausa. Isso evita que um encerramento normal seja registrado como crash.

4.2 Tratamento de crashes

Quando um servidor encerra, o daemon classifica a causa como Parado por você, Parado no jogo, Crash ou Desconhecido, e a registra na lista 'Saídas recentes' do servidor. Uma saída só é classificada como crash quando há evidências, como um código de saída anormal ou um arquivo de crash declarado pelo módulo; sem evidências, ela não é tratada como crash.

  • Reinício automático: ative ou desative em 'Reinício automático' na aba Saba-chan da tela do servidor. Reiniciar após um crash vem ligado por padrão, e Reiniciar também em saídas desconhecidas vem desligado por padrão. Servidores que você mesmo parou ou que foram parados de dentro do jogo nunca são reiniciados.
  • Intervalo de reinício: o primeiro reinício acontece após 5 segundos, e a espera dobra a cada reinício. Depois de mais de 3 reinícios em 10 minutos, o Saba-chan para de reiniciar. Verifique os logs e inicie o servidor manualmente.

4.3 Local dos logs

  • Logs da GUI: %APPDATA%\saba-chan\logs\ (a saída de um daemon iniciado pela GUI também é gravada aqui). Também é possível ver os logs do daemon com saba-chan-cli daemon logs.
  • Logs do console do servidor: %APPDATA%\saba-chan\instances\<ID da instância>\logs\. Servidores executados pelo runner criam um arquivo em sessions\ a cada execução e mantêm 20 por padrão.
  • Visualização do console: o daemon mantém em memória as 10.000 linhas mais recentes de cada instância. A GUI consulta o endpoint GET /api/instance/:id/console?since=… com um cursor, até o seu limite de exibição consoleBufferSize (padrão de 2000 linhas).

5. Próximos passos