feat: adiciona 12 plugins Descomplicar ao marketplace
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>
This commit is contained in:
293
infraestrutura/skills/easypanel-troubleshoot/SKILL.md
Normal file
293
infraestrutura/skills/easypanel-troubleshoot/SKILL.md
Normal file
@@ -0,0 +1,293 @@
|
||||
---
|
||||
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 **/
|
||||
Reference in New Issue
Block a user