--- name: easypanel-troubleshoot description: Diagnóstico automático de problemas de deploy no EasyPanel — análise de logs de containers, health endpoints, routing Traefik e recursos para identificar causas raiz. --- # EasyPanel Troubleshoot Diagnóstico automático e inteligente de problemas de deploy no EasyPanel. ## Quando Usar - Deploy falhou com erros 502/503 - Container em crash loop (restarts frequentes) - Health endpoint não responde - Problemas de routing Traefik - Investigar causa de deploy falhado - After deploy validation ## Quando NÃO Usar - Para deploys iniciais (usar `/easypanel-init`) - Para rollbacks de versão (usar `/easypanel-rollback`) - Para validação pós-deploy bem-sucedido (usar `/easypanel-validate`) - Quando o problema é conhecido e a solução já está identificada ## Sintaxe ```bash /easypanel-troubleshoot [--verbose] ``` ## Exemplos ```bash # Diagnóstico básico /easypanel-troubleshoot dashboard-api # Diagnóstico detalhado (logs completos) /easypanel-troubleshoot dashboard-api --verbose ``` ## Workflow Automático ### 1. Check Service Status via API ```bash # Obter token TOKEN=$(cat /etc/easypanel/.api-token) # Inspeccionar serviço (estado completo) curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' | jq -sRr @uri)" \ -H "Authorization: Bearer $TOKEN" | jq '.result.data.json' # Obter logs via API curl -s "http://localhost:3000/api/trpc/services.app.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","lines":100}}' | jq -sRr @uri)" \ -H "Authorization: Bearer $TOKEN" ``` ### 2. Fetch Logs (alternativa SSH) ```bash docker logs --tail 100 ``` Parse de erros comuns: - Port already in use (EADDRINUSE) - Cannot find module (dependencies) - Connection refused (database) - Out of memory (OOM) - Unhandled promise rejection - Listen errors ### 3. Check Health Endpoint ```bash curl https:///health ``` - Status code: 200, 404, 502, 503? - Response time - Response body validation ### 4. Check Traefik Routing - Traefik labels correctos? - router.rule com domain - service.loadbalancer.server.port - entrypoints=websecure - certresolver=letsencrypt - Domain DNS aponta para servidor? - SSL certificate válido? ### 5. Check Port Mismatch - Dockerfile EXPOSE vs app actual port - docker-compose ports vs Traefik port - App listening port (from logs) - Common mismatch: 3000 vs 8080 ### 6. Check Environment Variables - Required vars set? (compare .env.example) - Sensitive vars (DATABASE_URL, API_KEY) - Missing vars causing app crash? ### 7. Check Dependencies - Database reachable? (if applicable) - Redis reachable? (if applicable) - External APIs responding? ### 8. Check Resources - CPU throttling? - Memory limit reached (OOM)? - Disk space? ### 9. Generate Report - Issues found (prioritized: CRITICAL, WARNING, INFO) - Root cause (if detected) - Recommended fixes (step-by-step) - Commands to run ## Error Pattern Detection ### Port Mismatch ``` Pattern: "listening on port X" + Traefik port Y Fix: Update Dockerfile EXPOSE or Traefik label ``` ### Missing Environment Variable ``` Pattern: "is not defined" / "undefined" Fix: Add variable to EasyPanel environment ``` ### Crash Loop ``` Pattern: Restart count > 3 in 10min Fix: Check logs for root cause ``` ### Database Connection ``` Pattern: "ECONNREFUSED" / "Connection refused" Fix: Verify DATABASE_URL and network connectivity ``` ### Memory Issues ``` Pattern: "out of memory" / "OOM killed" Fix: Increase memory limit in docker-compose ``` ## Output Format ``` 🔍 EasyPanel Troubleshooting: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 SERVICE STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Container: Status: Running | Stopped | Restarting Uptime: