Troubleshooting

Ferramenta principal: bridgeDiagnostics

Todo response de GET /v1/dashboard/server-health inclui o objeto bridgeDiagnostics com o motivo exato de cada falha do bridge Lua. O painel mostra ele expandido no Overview quando o Lua está offline. Os campos chave:

• phase — tenant_missing | no_base_url | no_token | timeout | network | http_error | invalid_json | ok
• requestUrl — URL exata que o Nest tentou (confira o host/porta/path).
• httpStatus — quando > 0, o Lua respondeu mas com erro (401, 400, 500…).
• responseSnippet — corpo da resposta (primeiros 200 chars).

Erros frequentes

401 Unauthorized do Lua

Sintoma: phase: "http_error", httpStatus: 401.

Causas:

• Config.ServerLinkToken no Lua difere do serverLinkToken do tenant no painel. Compare ambos com cuidado (espaços, quebras).
• O FXServer ainda está com o resource antigo em memória — restart elite_saas_api.

400 "tenant slug mismatch"

O header x-tenant-id da request não bate com Config.TenantSlug. Verifique no painel Configurações → Conta qual é o slug corrente — especialmente após editar Branding.

404 "path not under base"

O Config.BasePath não casa com o path da request. Se o Lua usa /elite-saas, o backend deve montar a URL como http://ip:30120/elite-saas/.... Confira tanto luaApiBaseUrl no painel quanto FIVEM_LUA_HTTP_BASE_PATHno .env do backend.

Phase "timeout"

O Lua não respondeu em 5s. Causas comuns:

• oxmysql congestionado (verifique queries lentas em outros resources).
• FXServer travado em playerConnecting / spawn.
• Firewall bloqueando a porta 30120 vinda do IP do backend.

Phase "network"

Backend não conseguiu sequer abrir conexão. Confira:

• O IP em luaApiBaseUrl é acessível do servidor onde o backend roda.
• Não tem https:// apontando para uma porta HTTP simples.
• O FXServer aceita HTTP externo (não só localhost). Verifique endpoint_add_tcp no server.cfg.

Diagnóstico passo a passo

1. Curl manual do Lua

curl -i http://IP-DO-FX:30120/elite-saas/health \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "x-tenant-id: seu-slug"

Espera-se 200 com JSON. Se não, o problema está entre você e o FXServer; o painel não está envolvido.

2. Ative o debug do Lua

Config.DebugHttp = true

Restart o resource. No console do FX vai aparecer cada request com path recebido, decisão de auth e routing:

[elite_saas_api][debug] request GET rawPath=/elite-saas/metrics fullPath=/elite-saas/metrics
[elite_saas_api][debug] resolved rel=/metrics
[elite_saas_api][debug] auth OK (Bearer matches Config.ServerLinkToken)
[elite_saas_api][debug] tenant OK slug="elite-city"
[elite_saas_api][debug] → 200 /metrics

3. Endpoint dedicado de bridge

O backend expõe um endpoint para depurar sem subir o frontend:

curl -i https://seu-painel.com/v1/dashboard/bridge-debug \
  -H "Authorization: Bearer JWT_DO_PAINEL" \
  -H "x-tenant-id: SEU_TENANT_ID"

Devolve diagnósticos de várias rotas (/health, /system, /metrics) em paralelo.

Logs do backend

No console do Nest, procure os prefixos:

• [LuaBridge] — chamadas ao Lua + status
• [ServerHealth] — agregador de saúde
• [Dashboard] — endpoint do painel
• [EventsService] — feed de eventos (lua + auditoria)

Problemas no painel (frontend)

"Sem sessão. Faça login"

Token JWT expirou e refresh falhou. Confira no DevTools localStorage:

• elite_access_token — JWT (15 min de vida)
• elite_refresh_token — refresh token (14 dias)
• elite_tenant_id — slug

Se faltar elite_refresh_token, você fez login em uma versão antiga do painel — basta logar de novo.

Player aparece em Online mas perfil retorna 404

O userId que vem do Lua não bate com a tabela vrp_users.id. Causas: o adapter de search não está implementado para o seu schema, ou o player não tem identidade registrada ainda. Veja adapter player_search.