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,139 @@
+---
+name: easypanel-api
+description: Referência completa da API tRPC oficial do EasyPanel — todos os endpoints para projectos, serviços, deploy e configurações.
+layer: wiki
+---
+
+# /easypanel-api - API Oficial EasyPanel
+
+Referência da API tRPC do EasyPanel. Baseado em engenharia reversa do SDK oficial.
+
+---
+
+## Autenticação
+
+```bash
+TOKEN=$(cat /etc/easypanel/.api-token)
+# Header obrigatório em todos os pedidos:
+-H "Authorization: Bearer $TOKEN"
+```
+
+**Base URL:** `http://localhost:3000/api/trpc/`
+
+Usar sempre via SSH localhost. Nunca expor externamente.
+
+---
+
+## Formato de Pedidos
+
+| Método | Quando usar | Formato |
+|--------|-------------|---------|
+| GET | Leitura (list, inspect, get) | `?input=URL_ENCODED_JSON` |
+| POST | Escrita (create, update, deploy, destroy) | `-d '{"json":{...}}'` com `Content-Type: application/json` |
+
+```bash
+# GET
+curl -s "http://localhost:3000/api/trpc/ENDPOINT?input=URL_ENCODED_JSON" \
+  -H "Authorization: Bearer $TOKEN"
+
+# POST
+curl -s -X POST "http://localhost:3000/api/trpc/ENDPOINT" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{...}}'
+```
+
+---
+
+## Projects API
+
+| Endpoint | Tipo | Descrição |
+|----------|------|-----------|
+| `projects.listProjects` | GET | Listar todos os projectos |
+| `projects.listProjectsAndServices` | GET | Projectos + todos os serviços |
+| `projects.createProject` | POST | Criar projecto (`name`) |
+| `projects.destroyProject` | POST | Destruir projecto (`projectName`) |
+| `projects.inspectProject` | GET | Inspecionar projecto (`projectName`) |
+
+```bash
+# Listar projectos (teste rápido de autenticação)
+curl -s "http://localhost:3000/api/trpc/projects.listProjects" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Criar projecto
+curl -s -X POST "http://localhost:3000/api/trpc/projects.createProject" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"json":{"name":"novo-projecto"}}'
+```
+
+---
+
+## Services API
+
+Endpoints completos com exemplos curl: ver [references/services-api.md](references/services-api.md)
+
+**Verificados 12-03-2026** (engenharia reversa do backend.js minificado):
+
+| Endpoint | Tipo | Descrição |
+|----------|------|-----------|
+| `services.app.createService` | POST | Criar serviço app |
+| `services.postgres.createService` | POST | Criar PostgreSQL |
+| `services.mysql.createService` | POST | Criar MySQL |
+| `services.redis.createService` | POST | Criar Redis |
+| `services.app.inspectService` | GET | Inspecionar serviço |
+| `services.app.deployService` | POST | Fazer deploy |
+| `services.app.stopService` | POST | Parar serviço |
+| `services.app.startService` | POST | Iniciar serviço |
+| `services.app.restartService` | POST | Reiniciar serviço |
+| `services.app.destroyService` | POST | Destruir serviço |
+
+**Endpoints que NAO existem** (removidos da versao anterior):
+`enableService`, `disableService` — usar `startService`/`stopService` em vez disso.
+
+**Parâmetros obrigatórios:** `projectName` + `serviceName` em todos os endpoints de serviços.
+
+**Regra Descomplicar:** `projectName:"descomplicar"` para serviços próprios.
+
+---
+
+## Service Configuration API
+
+Endpoints completos com exemplos curl: ver [references/service-config-api.md](references/service-config-api.md)
+
+**Verificados 12-03-2026:**
+
+| Endpoint | Descrição | Verificado |
+|----------|-----------|:----------:|
+| `services.app.updateSourceGithub` | Source GitHub (`owner`, `repo`, `ref`, `path`) | Sim |
+| `services.app.updateSourceGit` | Source Git custom (`repo`, `ref`, `path`) — params no nivel raiz, NAO dentro de `source` | Sim |
+| `services.app.updateSourceImage` | Source Docker image (`image`) | Sim |
+| `services.app.updateEnv` | Variáveis de ambiente (`env` como string multi-linha) | Sim |
+| `services.app.updateBuild` | Build config (`type`, `buildCommand`, `startCommand`) | Sim |
+| `services.app.updateResources` | CPU/RAM (`memoryLimit`, `cpuLimit`, etc.) | Sim |
+| `services.app.updateAdvanced` | Deploy avançado (`replicas`, `command`, `zeroDowntime`) | Sim |
+| `services.app.updateRedirects` | Redireccionamentos HTTP | Sim |
+| `services.app.updateBasicAuth` | Autenticacao basica | Sim |
+| `services.app.updateMaintenance` | Modo manutencao | Sim |
+
+**Endpoints que NAO existem na versao instalada:**
+- ~~`services.app.updateDomains`~~ — dominios so via UI do EasyPanel
+- ~~`services.app.updateMounts`~~ — nao encontrado
+- ~~`services.app.updatePorts`~~ — nao encontrado
+
+---
+
+## Domains API (Verificado 12-03-2026)
+
+Os dominios NAO sao geridos por `services.app.*` mas sim pelo namespace `domains.*`.
+
+| Endpoint | Tipo | Descricao |
+|----------|------|-----------|
+| `domains.listDomains` | GET | Listar dominios do projecto (`projectName`) |
+| `domains.createDomain` | POST | Criar dominio |
+| `domains.updateDomain` | POST | Actualizar dominio |
+| `domains.deleteDomain` | POST | Remover dominio |
+
+```bash
+# Listar dominios
+INPUT='{"json":{"projectName":"descomplicar"}}'
+ENCODED=$(python3 -c "import urllib.parse; print(urllib.par
@@ -0,0 +1,283 @@
+# EasyPanel API - Service Configuration
+
+**Verificado:** 12-03-2026 (engenharia reversa do backend.js)
+
+---
+
+## Actualizar Source (GitHub)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGithub" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "owner":"ealmeida",
+    "repo":"MeuRepo",
+    "ref":"main",
+    "path":"/"
+  }}'
+```
+
+## Actualizar Source (Git Custom)
+
+**IMPORTANTE:** Os parametros `repo`, `ref`, `path` devem estar no nivel RAIZ do JSON, NAO dentro de um objecto `source`.
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "repo":"https://ealmeida:TOKEN@git.descomplicar.pt/ealmeida/repo",
+    "ref":"main",
+    "path":"/"
+  }}'
+```
+
+**Errado (causa zodErrors):**
+```json
+{"json":{"projectName":"x","serviceName":"y","source":{"type":"git","repo":"...","ref":"main","path":"/"}}}
+```
+
+**Correcto:**
+```json
+{"json":{"projectName":"x","serviceName":"y","repo":"...","ref":"main","path":"/"}}
+```
+
+## Actualizar Source (Docker Image)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceImage" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "image":"node:22-alpine"
+  }}'
+```
+
+## Actualizar Environment Variables
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateEnv" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "env":"NODE_ENV=production\nPORT=3000\nDATABASE_URL=postgres://..."
+  }}'
+```
+
+## Actualizar Build Config
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateBuild" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "build":{
+      "type":"nixpacks",
+      "buildCommand":"npm run build",
+      "startCommand":"npm start"
+    }
+  }}'
+```
+
+## Actualizar Resources
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateResources" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "resources":{
+      "memoryLimit":"512m",
+      "memoryReservation":"256m",
+      "cpuLimit":1,
+      "cpuReservation":0.5
+    }
+  }}'
+```
+
+## Actualizar Deploy (Replicas, Command)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "deploy":{
+      "replicas":2,
+      "command":"node dist/index.js",
+      "zeroDowntime":true
+    }
+  }}'
+```
+
+## Actualizar Redirects
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateRedirects" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "redirects":[]
+  }}'
+```
+
+## Actualizar Basic Auth
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateBasicAuth" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "basicAuth":{"enabled":false}
+  }}'
+```
+
+## Actualizar Maintenance Mode
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateMaintenance" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "maintenance":{"enabled":false}
+  }}'
+```
+
+## Database Backup Config
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.updateBackup" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-db",
+    "backup":{
+      "enabled":true,
+      "schedule":"0 3 * * *",
+      "destination":{
+        "type":"s3",
+        "bucket":"backups",
+        "region":"eu-west-1",
+        "accessKey":"...",
+        "secretKey":"..."
+      }
+    }
+  }}'
+```
+
+---
+
+## Domains API (Namespace separado)
+
+**IMPORTANTE:** Os dominios NAO sao geridos por `services.app.*` mas sim pelo namespace `domains.*`.
+
+### Listar Dominios (GET)
+
+```bash
+INPUT='{"json":{"projectName":"descomplicar"}}'
+ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))")
+curl -s "http://localhost:3000/api/trpc/domains.listDomains?input=$ENCODED" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Criar Dominio (POST)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "id":"meu-dominio-id",
+    "https":true,
+    "host":"app.descomplicar.pt",
+    "path":"/",
+    "middlewares":[],
+    "certificateResolver":"letsencrypt",
+    "wildcard":false,
+    "destinationType":"service",
+    "serviceDestination":{
+      "protocol":"http",
+      "port":3000,
+      "path":"/",
+      "projectName":"descomplicar",
+      "serviceName":"meu-servico"
+    }
+  }}'
+```
+
+**Notas:**
+- O `id` pode ser qualquer string unica (cuid ou slug)
+- `certificateResolver`: `"letsencrypt"` para HTTPS, `""` para dominios internos
+- `destinationType`: `"service"` para servicos EasyPanel, `"custom"` para destinos externos
+
+### Actualizar Dominio (POST)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/domains.updateDomain" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{...mesmo schema de createDomain...}}'
+```
+
+### Remover Dominio (POST)
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/domains.deleteDomain" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"id":"meu-dominio-id"}}'
+```
+
+---
+
+## Resumo de Endpoints de Configuracao
+
+| Endpoint | Tipo | Descricao | Verificado |
+|----------|------|-----------|:----------:|
+| `services.app.updateSourceGithub` | POST | Source GitHub (`owner`,`repo`,`ref`,`path`) | Sim |
+| `services.app.updateSourceGit` | POST | Source Git custom (`repo`,`ref`,`path` RAIZ) | Sim |
+| `services.app.updateSourceImage` | POST | Source Docker image (`image`) | Sim |
+| `services.app.updateEnv` | POST | Variaveis de ambiente (`env` string) | Sim |
+| `services.app.updateBuild` | POST | Build config (`type`,`buildCommand`,`startCommand`) | Sim |
+| `services.app.updateResources` | POST | CPU/RAM limits | Sim |
+| `services.app.updateAdvanced` | POST | Deploy avancado (replicas, command, zeroDowntime) | Sim |
+| `services.app.updateRedirects` | POST | Redireccionamentos HTTP | Sim |
+| `services.app.updateBasicAuth` | POST | Autenticacao basica | Sim |
+| `services.app.updateMaintenance` | POST | Modo manutencao | Sim |
+| `domains.listDomains` | GET | Listar dominios (`projectName`) | Sim |
+| `domains.createDomain` | POST | Criar dominio | Sim |
+| `domains.updateDomain` | POST | Actualizar dominio | Sim |
+| `domains.deleteDomain` | POST | Remover dominio | Sim |
+
+**Endpoints que NAO existem na versao instalada:**
+- ~~`services.app.updateDomains`~~ — usar `domains.createDomain`
+- ~~`services.app.updateMounts`~~ — nao encontrado
+- ~~`services.app.updatePorts`~~ — nao encontrado
+- ~~`services.app.saveDomains`~~ — nao existe
+- ~~`services.app.saveGithubSource`~~ — usar `updateSourceGithub` ou `updateSourceGit`
+
+---
+
+*Actualizado: 12-03-2026*
@@ -0,0 +1,135 @@
+# EasyPanel API - Services
+
+**Verificado:** 12-03-2026 (engenharia reversa do backend.js)
+
+## Service Types
+
+| Type | Descricao |
+|------|-----------|
+| `app` | Aplicacao (Node.js, Python, Go, Rust, etc.) |
+| `mysql` | MySQL database |
+| `mariadb` | MariaDB database |
+| `postgres` | PostgreSQL database |
+| `mongo` | MongoDB database |
+| `redis` | Redis cache |
+
+## Criar Servico App
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.createService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+```
+
+## Criar Servico Database
+
+```bash
+# PostgreSQL
+curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.createService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-db"}}'
+
+# MySQL
+curl -s -X POST "http://localhost:3000/api/trpc/services.mysql.createService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"mysql-db"}}'
+
+# Redis
+curl -s -X POST "http://localhost:3000/api/trpc/services.redis.createService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"cache"}}'
+```
+
+## Inspeccionar Servico (GET)
+
+```bash
+INPUT='{"json":{"projectName":"descomplicar","serviceName":"dashboard_descomplicar"}}'
+ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))")
+curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Response parcial:
+```json
+{
+  "projectName": "descomplicar",
+  "name": "dashboard_descomplicar",
+  "type": "app",
+  "enabled": true,
+  "token": "deploy-webhook-token",
+  "source": {"type": "git", "repo": "https://...", "ref": "main"},
+  "build": {"type": "nixpacks", "buildCommand": "npm run build"},
+  "env": "VAR=value",
+  "mounts": [],
+  "ports": []
+}
+```
+
+## Deploy Servico
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+```
+
+## Stop / Start / Restart Servico
+
+```bash
+# Parar servico
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.stopService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+
+# Iniciar servico
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.startService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+
+# Reiniciar servico
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.restartService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+```
+
+**IMPORTANTE:** `enableService` e `disableService` NAO existem na versao instalada. Usar `startService`/`stopService`.
+
+## Destruir Servico
+
+```bash
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.destroyService" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
+```
+
+---
+
+## Resumo de Endpoints
+
+| Endpoint | Tipo | Descricao | Verificado |
+|----------|------|-----------|:----------:|
+| `services.app.createService` | POST | Criar servico app | Sim |
+| `services.postgres.createService` | POST | Criar PostgreSQL | Sim |
+| `services.mysql.createService` | POST | Criar MySQL | Sim |
+| `services.redis.createService` | POST | Criar Redis | Sim |
+| `services.app.inspectService` | GET | Inspeccionar servico | Sim |
+| `services.app.deployService` | POST | Fazer deploy | Sim |
+| `services.app.stopService` | POST | Parar servico | Sim |
+| `services.app.startService` | POST | Iniciar servico | Sim |
+| `services.app.restartService` | POST | Reiniciar servico | Sim |
+| `services.app.destroyService` | POST | Destruir servico | Sim |
+
+**Endpoints que NAO existem:** `enableService`, `disableService`, `redeployService`
+
+---
+
+*Actualizado: 12-03-2026*