feat(infraestrutura): adiciona plugin infraestrutura (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:09:01 +00:00
parent de2d6f2fb5
commit e43fec3bd9
73 changed files with 8589 additions and 0 deletions
@@ -0,0 +1,205 @@
+---
+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.
+layer: wiki
+---
+
+# 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 <service-name> [--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 (namespace logs.*, NAO services.app.*)
+curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","tail":100}}' | jq -sRr @uri)" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 2. Fetch Logs (alternativa SSH)
+```bash
+docker logs <container> --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://<domain>/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-name>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 SERVICE STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Container: <name>
+Status: Running | Stopped | Restarting
+Uptime: <time>
+Restarts: <count> (last 10min)
+Memory: X / Y MB
+CPU: X%
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔴 ISSUES FOUND (X)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. 🔴 CRITICAL: <Issue Title>
+   Detected: <details>
+   Impact: <what breaks>
+
+   Fix:
+   <step-by-step solution>
+
+2. ⚠️  WARNING: <Issue Title>
+   ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 LOGS (Last 20 lines)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[timestamp] INFO: ...
+[timestamp] ❌ ERROR: ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🛠️  RECOMMENDED ACTIONS (Prioritized)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. <Action 1>
+2. <Action 2>
+3. Redeploy: git commit + push
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔗 HELPFUL RESOURCES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Research: /media/ealmeida/Dados/Dev/Docs/EasyPanel-Deploy-Research/
+- Checklist: CHECKLIST_EasyPanel_Deploy.md
+- Templates: TEMPLATE_Dockerfile_NodeJS_MultiStage
+```
+
+## API Endpoints Usados
+
+Ver skill `/easypanel-api` para documentação completa