Solução de problemas

Este guia reúne os problemas mais comuns em instalações self-hosted do BrutusForge no Windows e como resolvê-los. Cada seção segue o mesmo formato: sintomas, como diagnosticar e as causas mais frequentes com a solução correspondente.

O BrutusForge roda como um stack completo (Postgres + API + Web + Bot) registrado como Windows Services. A maioria dos diagnósticos abaixo usa o PowerShell e a pasta de instalação padrão C:\BrutusForge.

A API não sobe

Sintomas

• O serviço BrutusForge-API aparece como Stopped em services.msc.
• O Launcher na bandeja exibe o ícone vermelho.
• O navegador retorna ERR_CONNECTION_REFUSED em http://localhost:3001.

Diagnóstico

# Logs de erro da API
Get-Content "C:\BrutusForge\logs\api-stderr.log" -Tail 50
 
# Verificar se a porta 3001 está em uso por outro processo
netstat -ano | findstr :3001
 
# Confirmar que o Postgres está rodando
Get-Service "BrutusForge-Postgres"
 
# Testar a conexão com o banco diretamente
$env:PGPASSWORD = "senha_do_env"; psql -U brutus -d brutusforge -c "SELECT 1"

Causas comuns

• Postgres não subiu antes da API. O serviço do banco inicia de forma atrasada (Automatic - Delayed). Se a API iniciar antes, a conexão falha. Reinicie a API após cerca de 30 segundos.
• Porta 3001 ocupada. Outro processo (IIS, Node.js) está usando a porta. Identifique o PID pelo netstat e encerre ou reconfigure o processo conflitante.
• Chave de criptografia ausente ou inválida. A API recusa iniciar se a CONFIG_ENCRYPTION_KEY não tiver 32 bytes em hexadecimal. Verifique o arquivo .env na raiz da instalação.
• Banco desatualizado após update. Uma atualização aplicada sem migrar o schema deixa o banco fora de sincronia. Reinicie os serviços pelo Launcher para reaplicar as migrations.
• Permissão negada na pasta de logs. O serviço não consegue gravar os arquivos de log. Confira as permissões de C:\BrutusForge\logs\.

RCON dá timeout

Sintomas

• Comandos RCON enviados pelo painel admin não retornam resposta.
• O painel mostra timeout ou connection refused no histórico de comandos.
• Os servidores de jogo continuam funcionando normalmente.

Diagnóstico

# Testar RCON telnet manualmente (7 Days to Die)
telnet ip_do_servidor porta_rcon
# Após conectar, digite a senha RCON
 
# Testar Source RCON (ARK, Minecraft, Rust) com um cliente externo
rcon-cli -a ip:porta -p senha "status"

Causas comuns

• Senha RCON incorreta após rotação. O servidor de jogo foi reiniciado com uma nova senha, mas o BrutusForge ainda tem a antiga. Atualize em Admin → Servidores → Editar → Senha RCON.
• Firewall bloqueando a porta RCON. O Windows Firewall ou o roteador está bloqueando a porta (padrões: ARK 27020, 7 Days to Die 8081, Minecraft 25575). Adicione uma regra de entrada.
• O servidor de jogo travou. O processo do jogo parou, mas o sistema operacional ainda escuta a porta por alguns segundos. Verifique os logs do servidor de jogo.
• Senha RCON criptografada incompatível. Após uma troca da chave de criptografia, os valores cifrados no banco podem ficar ilegíveis. Reabra a edição do servidor no admin e salve a senha novamente para re-encriptar.

Filas travadas (jobs em background)

Sintomas

• O endpoint /api/health/queues mostra muitas falhas em alguma fila.
• Entregas da loja paradas, sem processar.
• A instalação de mods não progride.

Diagnóstico

Abra Admin → Sistema → Saúde para ver a contagem de jobs por fila. Para inspecionar diretamente no banco:

$env:PGPASSWORD = "senha_do_env"; psql -U brutus -d brutusforge

-- Listar jobs por fila e estado
SELECT name, state, COUNT(*) FROM pgboss.job GROUP BY name, state ORDER BY name;
 
-- Ver detalhes dos jobs com falha na fila de entrega
SELECT id, name, data, output, "retryCount", "startedOn", "completedOn"
FROM pgboss.job
WHERE name = 'delivery' AND state = 'failed'
ORDER BY "startedOn" DESC
LIMIT 10;

Causas comuns

• O processo de worker caiu. A API saiu inesperadamente durante o processamento e os jobs ficaram presos. Reinicie a API: os jobs órfãos são recuperados automaticamente.
• Loop de retry. Um job falha, volta para a fila e falha de novo. Veja a causa raiz no campo output do job. A contagem acumulada aparece em /api/health/queues.
• RCON do jogo inacessível. A fila de entrega tenta executar RCON, mas o servidor de jogo está offline e os jobs acumulam falhas. Resolva primeiro a seção de RCON acima.
• Payload inválido. Um produto com item inexistente no jogo gera erro permanente. Corrija o produto na loja e cancele os jobs travados:

UPDATE pgboss.job SET state = 'cancelled' WHERE name = 'delivery' AND state = 'failed';

PostgreSQL lento

Sintomas

• O painel admin demora mais de 5 segundos para carregar.
• O endpoint /api/health/database mostra latência alta.
• Os logs da API exibem queries com tempo de execução elevado.

Diagnóstico

-- Habilitar pg_stat_statements (rodar uma vez como superuser)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
 
-- Top 10 queries mais lentas
SELECT
  query,
  calls,
  mean_exec_time::numeric(10,2) AS mean_ms,
  total_exec_time::numeric(10,2) AS total_ms
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;
 
-- Tabelas que mais ocupam espaço
SELECT
  relname AS table_name,
  pg_size_pretty(pg_total_relation_size(relid)) AS total_size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC
LIMIT 10;

Causas comuns

• Log de auditoria cresceu demais. Cada ação no admin gera uma linha. A rotina de limpeza roda diariamente, mas o período de retenção pode estar alto demais. Ajuste AUDIT_LOG_RETENTION_DAYS no .env.
• Log de eventos sem purga. Ajuste EVENT_LOG_RETENTION_DAYS no .env (padrão 90 dias, faixa de 7 a 730).
• VACUUM pendente. Após muitos INSERTs e DELETEs, o Postgres precisa de manutenção. Rode VACUUM ANALYZE audit_logs; manualmente.
• Índices faltando. Verifique tabelas grandes que não usam índice.
• Conexões esgotadas. O pool de conexões pode estar saturado. Verifique o max_connections do Postgres e ajuste a DATABASE_URL com ?connection_limit=N.

Game Agent desconectado

Sintomas

• O endpoint /api/health/agents mostra o servidor como stale: true.
• O painel admin não exibe os jogadores online em tempo real.
• Comandos RCON via WebSocket não chegam ao plugin do jogo.

Diagnóstico

# Logs do plugin C++ no servidor de jogo (exemplo ARK SE)
Get-Content "C:\ArkServer\ShooterGame\Saved\Logs\BrutusForgeCore.log" -Tail 100
 
# Confirmar que o plugin está presente
ls "C:\ArkServer\ShooterGame\Binaries\Win64\Plugins\BrutusForgeCore.dll"
 
# Testar a conectividade da API com o Game Agent
curl http://localhost:3001/api/game-agent/status
 
# Conferir o config.json do plugin
Get-Content "C:\ArkServer\ShooterGame\Binaries\Win64\Plugins\BrutusForge\config.json"

Causas comuns

• URL da API incorreta no plugin. O campo apiUrl no config.json precisa apontar para um endereço acessível a partir do servidor de jogo. Em redes com NAT, use o IP interno.
• Fallback para HTTP polling ativo. O plugin cai para HTTP polling após 3 falhas consecutivas de WebSocket. Nesse modo o heartbeat é mais lento (60s contra 5s). É normal sob instabilidade de rede.
• Plugin configurado só para HTTP polling. Se useWebSocket estiver false no config.json, aumente a tolerância de stale no monitoramento.
• DLL do plugin bloqueada por antivírus. O Windows Defender pode colocar BrutusForgeCore.dll em quarentena. Adicione uma exclusão para a pasta do servidor.
• Chaves de autenticação desalinhadas. O plugin usa o segredo do Game Agent para autenticar. Confirme que o .env da API e o config.json do plugin compartilham o mesmo valor.

Licença revogada ou expirada

Sintomas

• Banner vermelho de "Licença inválida" no painel admin.
• Todas as requisições retornam HTTP 403.
• Os logs da API indicam falha na verificação da licença.

Diagnóstico

# Ver o status atual da licença
curl http://localhost:3001/api/internal/license/status
 
# Logs de verificação periódica (phone-home)
Get-Content "C:\BrutusForge\logs\api-stdout.log" | Select-String "LicenseService"

Causas comuns

• O HWID mudou após troca de hardware. A licença está vinculada à impressão digital da máquina. Solicite a transferência de HWID na sua área de cliente → License → Transferir HWID (1 vez grátis a cada 30 dias). Cole o HWID atual exatamente como exibido.
• A verificação periódica falhou por mais de 24h. A API revalida a licença a cada 24 horas. Se o servidor de licenças ficar inacessível, a licença entra em período de graça (LICENSE_GRACE_PERIOD_DAYS, padrão 7) e depois é rejeitada. Verifique a conectividade de saída para o portal.
• Licença revogada pelo suporte. Entre em contato pelo Discord informando o ID da licença.
• Chave pública incorreta no .env. O LICENSE_SERVER_PUBLIC_KEY precisa corresponder exatamente ao ambiente da sua licença. Confira o e-mail de ativação.
• Data e hora do servidor incorretas. A verificação valida as datas de emissão e expiração do token. Sincronize o relógio do Windows com w32tm /resync.

Bot do Discord offline

Sintomas

• O bot aparece como offline no servidor Discord.
• Os comandos slash não respondem.
• Os logs de eventos não chegam aos canais configurados.

Diagnóstico

# Status do serviço do bot
Get-Service "BrutusForge-Bot"
 
# Logs de erro do bot
Get-Content "C:\BrutusForge\logs\bot-stderr.log" -Tail 50

Causas comuns

• Token inválido ou rotacionado. No Discord Developer Portal, o token do bot é invalidado ao clicar em "Reset Token". Gere um novo token, atualize o .env e reinicie o serviço do bot.
• Intents não habilitados. O bot precisa dos privileged intents GUILD_MEMBERS e MESSAGE_CONTENT, habilitados no Developer Portal em Bot → Privileged Gateway Intents.
• Bot expulso do servidor. Se o bot foi removido do servidor Discord, reconvide-o com o link OAuth2 gerado no Developer Portal. Mantenha o CLIENT_ID e o GUILD_ID corretos no .env.
• Rate limit do Discord. Muitos requests em pouco tempo causam throttle temporário. O bot tem backoff automático; aguarde cerca de 60 segundos.
• API inacessível pelo bot. O bot consome a API interna (API_URL no .env). Se a API estiver fora do ar, o bot inicia mas não carrega as configurações. Resolva primeiro a seção da API.

Rotação da chave de criptografia

A CONFIG_ENCRYPTION_KEY (AES-256-GCM) protege segredos guardados no banco, como chaves de API de serviços externos. Para trocá-la com segurança:

# 1. Gerar uma nova chave (32 bytes em hex)
$newKey = -join ((0..31) | ForEach-Object { "{0:x2}" -f (Get-Random -Maximum 256) })
Write-Host "Nova chave: $newKey"
 
# 2. Fazer backup do banco antes de qualquer mudança
pg_dump -U brutus brutusforge > "backup_pre_rotation_$(Get-Date -Format 'yyyyMMdd_HHmmss').sql"
 
# 3. Parar a API
Stop-Service "BrutusForge-API"
 
# 4. Atualizar a chave no .env:
#    CONFIG_ENCRYPTION_KEY=<nova_chave>
 
# 5. Subir a API novamente
Start-Service "BrutusForge-API"
 
# 6. Verificar a saúde do stack
curl http://localhost:3001/api/health

Depois de subir a API, abra Admin → Plugins e salve novamente as seções que contêm campos sensíveis. Isso re-encripta os valores com a nova chave.