Emanuel Almeida
2cb3210962
Plugins: automacao, crm-ops, design-media, dev-tools, gestao, infraestrutura, marketing, negocio, perfex-dev, project-manager, wordpress + hello-plugin (existente). Totais: 83 skills, 44 agents, 12 datasets.json Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
293 lines
8.3 KiB
Markdown
293 lines
8.3 KiB
Markdown
---
|
|
name: easypanel-troubleshoot
|
|
description: >
|
|
Automated diagnostics for EasyPanel deployment issues via API oficial. Analyzes container logs,
|
|
health endpoints, Traefik routing, and resources to identify root causes.
|
|
Use when user mentions "easypanel troubleshoot", "deploy failed", "502 error",
|
|
"crash loop", "container problems", "debug deployment".
|
|
author: Descomplicar® Crescimento Digital
|
|
version: 2.0.0
|
|
quality_score: 70
|
|
user_invocable: true
|
|
desk_task: TBD
|
|
allowed-tools: Bash, Read
|
|
dependencies:
|
|
- easypanel-api
|
|
---
|
|
|
|
# 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
|
|
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 <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.
|
|
|
|
| Acção | Endpoint |
|
|
|-------|----------|
|
|
| Estado serviço | `GET services.app.inspectService` |
|
|
| Logs serviço | `GET services.app.getServiceLogs` |
|
|
| Listar projectos | `GET projects.listProjects` |
|
|
| Estatísticas monitor | `GET monitor.getStats` |
|
|
|
|
## MCPs Necessários
|
|
|
|
- ✅ `ssh-unified` - Acesso ao servidor para API e fallback
|
|
|
|
## Tools Necessários
|
|
|
|
```bash
|
|
# Via SSH
|
|
docker ps
|
|
docker logs <container> --tail 100
|
|
docker inspect <container>
|
|
curl https://<domain>/health
|
|
```
|
|
|
|
## Checklist Execução
|
|
|
|
- [ ] Conectar via SSH ao servidor EasyPanel
|
|
- [ ] Obter status do container (docker ps)
|
|
- [ ] Fetch logs (últimas 100 linhas)
|
|
- [ ] Parse errors automático (patterns conhecidos)
|
|
- [ ] Check health endpoint (curl)
|
|
- [ ] Verificar Traefik labels (docker inspect)
|
|
- [ ] Detectar port mismatch
|
|
- [ ] Verificar env vars (se possível)
|
|
- [ ] Gerar report estruturado
|
|
- [ ] Recomendar fixes priorizados
|
|
|
|
## Error Messages Database
|
|
|
|
### Common Patterns
|
|
|
|
| Pattern | Root Cause | Fix |
|
|
|---------|------------|-----|
|
|
| `EADDRINUSE :::PORT` | Port já em uso | Matar processo ou usar porta diferente |
|
|
| `Cannot find module 'X'` | Dependency missing | npm install no build |
|
|
| `ECONNREFUSED` | Database/service down | Verificar network/DATABASE_URL |
|
|
| `502 Bad Gateway` | App crash ou port mismatch | Check logs + ports |
|
|
| `MODULE_NOT_FOUND` | Build incorrecto | Verificar Dockerfile COPY |
|
|
| `OOM killed` | Memória insuficiente | Aumentar limite RAM |
|
|
|
|
## Security
|
|
|
|
- NUNCA expor credenciais nos logs
|
|
- Sanitizar env vars em output
|
|
- Limitar acesso SSH apenas ao necessário
|
|
|
|
## Performance
|
|
|
|
- Limitar logs a 100 linhas (evitar overflow)
|
|
- Cache de patterns conhecidos
|
|
- Timeout de 30s em curl health checks
|
|
|
|
---
|
|
|
|
**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04
|
|
|
|
## Metadata (Desk CRM Task #65)
|
|
|
|
```
|
|
Tarefa: SKL: /easypanel-troubleshoot - Automated Diagnostics
|
|
Milestone: 294 (Skills Claude Code)
|
|
Tags: skill(79), stackworkflow(75), claude-code(81), activo(116)
|
|
Responsáveis: Emanuel(1), AikTop(25)
|
|
Status: 4 (Em progresso) → 5 (Concluído)
|
|
```
|
|
|
|
---
|
|
|
|
**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ |