366 lines
15 KiB
Markdown
366 lines
15 KiB
Markdown
# Especificação Técnica: Arcadia Kernel
|
|
|
|
> **Versão:** 3.3
|
|
> **Status:** ✅ Produção
|
|
> **Última atualização:** 2026-04-08
|
|
|
|
---
|
|
|
|
## 1. Visão Geral
|
|
|
|
O **Arcadia Kernel** é o sistema operacional nativo da ArcadiaSuite - um orquestrador de serviços em Node.js que unifica discovery, health monitoring e gerenciamento de processos.
|
|
|
|
### 1.1 Objetivos
|
|
|
|
- **Discovery**: Descobrir automaticamente todos os serviços do ecossistema
|
|
- **Orquestração**: Iniciar, parar e reiniciar serviços (processos e containers)
|
|
- **Observabilidade**: Health checks, logs e métricas centralizados
|
|
- **Integração**: Unificar visão da Casa de Máquinas com dados reais
|
|
|
|
### 1.2 Arquitetura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ ARCADIA APPLICATION (5000) │
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|
│ │ ARCADIA KERNEL (5001) │ │
|
|
│ ├─────────────────────────────────────────────────────────────────┤ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
|
|
│ │ │ Dashboard │ │ Process │ │ LogAggregator │ │ │
|
|
│ │ │ (Web UI) │ │ Manager │ │ │ │ │
|
|
│ │ └──────┬──────┘ └──────┬──────┘ └─────────────────────────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └────────────────┴────────────────┐ │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌───────────┴───────────┐ │ │ │
|
|
│ │ │ Service Registry │◄──┼──┐ │ │
|
|
│ │ │ (Unified Discovery) │ │ │ │ │
|
|
│ │ └───────────┬───────────┘ │ │ │ │
|
|
│ │ │ │ │ │ │
|
|
│ │ ┌─────────────────────┼───────────────┘ │ │ │
|
|
│ │ │ │ │ │ │
|
|
│ │ ┌──┴──┐ ┌──────────┐ ┌┴─────────┐ ┌────┴─────┐ ┌────────┐ │ │
|
|
│ │ │Static│ │ Coolify │ │ XOS │ │ Docker │ │ ... │ │ │
|
|
│ │ │Disc. │ │ Disc. │ │ Disc. │ │ Disc. │ │ │ │ │
|
|
│ │ └──┬──┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ └──────────┴─────────────┴─────────────┴────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ┌──────────┴──────────┐ │ │
|
|
│ │ │ UnifiedRegistry │ │ │
|
|
│ │ │ (Agregação + Dedu) │ │ │
|
|
│ │ └──────────┬──────────┘ │ │
|
|
│ └─────────────────────────┼─────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────┴──────────────────┐ │
|
|
│ │ global.arcadiaKernelRegistry │ │
|
|
│ │ (Acesso direto - mesmo processo) │ │
|
|
│ └──────────────────┬──────────────────┘ │
|
|
│ │ │
|
|
│ ┌───────────────────────┴───────────────────────┐ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────┐ │
|
|
│ │ Casa de │ │ /api/engine-room/* │ │
|
|
│ │ Máquinas │ │ (API Express) │ │
|
|
│ │ (React UI) │ │ │ │
|
|
│ └─────────────────┘ └─────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Legenda:
|
|
───► HTTP/HTTPS ─ ─► Acesso direto (memória)
|
|
Porta 5000: App principal Porta 5001: Kernel Dashboard (interno)
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Componentes
|
|
|
|
### 2.1 Core (ProcessManager, HealthMonitor, LogAggregator)
|
|
|
|
**Status:** ✅ Estável
|
|
|
|
- **ProcessManager**: Gerencia processos Node.js/Python locais
|
|
- **HealthMonitor**: Health checks periódicos
|
|
- **LogAggregator**: Coleta e armazena logs
|
|
|
|
### 2.2 Service Registry
|
|
|
|
**Status:** ✅ Implementado
|
|
|
|
Catálogo central de serviços com:
|
|
- Registro manual ou automático
|
|
- Health status tracking
|
|
- Capabilities e metadados
|
|
- Eventos (service:registered, service:health_changed, etc)
|
|
|
|
### 2.3 Discovery Providers
|
|
|
|
| Provider | Status | Descrição |
|
|
|----------|--------|-----------|
|
|
| `StaticDiscovery` | ✅ | DNS interno (nomes fixos) |
|
|
| `CoolifyDiscovery` | ✅ | API Coolify (produção) |
|
|
| `DockerDiscovery` | ✅ | Docker labels (fallback) |
|
|
| `XOSDiscovery` | ✅ | Banco XOS (filas, integrações) |
|
|
| `UnifiedRegistry` | ⏳ | Agregador (Semana 5) |
|
|
|
|
---
|
|
|
|
## 3. Discovery Providers
|
|
|
|
### 3.1 StaticDiscovery
|
|
|
|
Descobre serviços via nomes DNS fixos na rede Docker.
|
|
|
|
```typescript
|
|
// Ex: http://contabil:8003, http://bi:8004
|
|
```
|
|
|
|
### 3.2 CoolifyDiscovery
|
|
|
|
Consulta API Coolify para descobrir serviços em produção.
|
|
|
|
**Endpoints:**
|
|
- `GET /api/v1/services` - Docker Compose services
|
|
- `GET /api/v1/applications` - Aplicações
|
|
|
|
**Filtro:** `arcadia.discovery.enabled=true`
|
|
|
|
### 3.3 DockerDiscovery
|
|
|
|
Lê labels de containers Docker na rede local.
|
|
|
|
**Labels:**
|
|
- `arcadia.discovery.enabled=true`
|
|
- `arcadia.name=MetaSet BI`
|
|
- `arcadia.type=python`
|
|
- `arcadia.port=8100`
|
|
- `arcadia.capabilities=dashboards,charts,sql_lab`
|
|
|
|
### 3.4 XOSDiscovery
|
|
|
|
Consulta banco de dados para descobrir serviços XOS.
|
|
|
|
**Descobre:**
|
|
- Filas de atendimento (`xos_queues`)
|
|
- Integrações WhatsApp (`whatsapp_sessions`)
|
|
- Automações ativas (`xos_automations`)
|
|
|
|
---
|
|
|
|
## 4. API do Kernel
|
|
|
|
### 4.1 Endpoints Core
|
|
|
|
| Endpoint | Método | Descrição |
|
|
|----------|--------|-----------|
|
|
| `/health` | GET | Health check do Kernel |
|
|
| `/api/kernel/services` | GET | Lista serviços do ProcessManager |
|
|
| `/api/kernel/services/:id/start` | POST | Inicia serviço |
|
|
| `/api/kernel/services/:id/stop` | POST | Para serviço |
|
|
| `/api/kernel/services/:id/restart` | POST | Reinicia serviço |
|
|
| `/api/kernel/services/:id/logs` | GET | Logs do serviço |
|
|
|
|
### 4.2 Endpoints Registry
|
|
|
|
| Endpoint | Método | Descrição |
|
|
|----------|--------|-----------|
|
|
| `/api/registry/services` | GET | Lista serviços descobertos |
|
|
| `/api/registry/services/:id` | GET | Detalhes de um serviço |
|
|
| `/api/registry/by-category/:cat` | GET | Serviços por categoria |
|
|
| `/api/registry/by-capability/:cap` | GET | Serviços por capability |
|
|
| `/api/registry/stats` | GET | Estatísticas do registry |
|
|
| `/api/registry/discover` | POST | Força discovery manual |
|
|
|
|
### 4.3 Endpoints Casa de Máquinas
|
|
|
|
| Endpoint | Método | Descrição |
|
|
|----------|--------|-----------|
|
|
| `/api/engine-room/status` | GET | Status unificado (Registry + Presets) |
|
|
| `/api/engine-room/engine/:name/health` | GET | Health de um motor |
|
|
| `/api/engine-room/engine/:name/start` | POST | Inicia motor |
|
|
| `/api/engine-room/engine/:name/stop` | POST | Para motor |
|
|
| `/api/engine-room/engine/:name/restart` | POST | Reinicia motor |
|
|
| `/api/engine-room/engine/:name/logs` | GET | Logs do motor |
|
|
|
|
---
|
|
|
|
## 5. Integração Casa de Máquinas
|
|
|
|
### 5.1 Fluxo de Dados
|
|
|
|
```
|
|
Casa de Máquinas (React)
|
|
│
|
|
▼
|
|
/api/engine-room/status
|
|
│
|
|
▼
|
|
┌─────────────────────────────┐
|
|
│ fetchRegistryServices() │
|
|
│ │
|
|
│ PRIORIDADE 1: Registry │
|
|
│ Global (mesmo processo) │
|
|
│ ───────────────────────── │
|
|
│ (global.arcadiaKernel │
|
|
│ .serviceRegistry) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────┐ │
|
|
│ │ Acesso │ │
|
|
│ │ direto │ │
|
|
│ │ (memória) │ │
|
|
│ └──────┬──────┘ │
|
|
│ │ │
|
|
│ Se falhar: │
|
|
│ ───────────────────────── │
|
|
│ PRIORIDADE 2: HTTP │
|
|
│ Fallback para porta 5001 │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────┐ │
|
|
│ │ http.get │ │
|
|
│ │ 127.0.0.1 │ │
|
|
│ │ localhost │ │
|
|
│ └──────┬──────┘ │
|
|
└─────────┼───────────────────┘
|
|
│
|
|
▼
|
|
Resposta JSON
|
|
│
|
|
▼
|
|
Frontend Render
|
|
```
|
|
|
|
### 5.2 Implementação Atual
|
|
|
|
```typescript
|
|
// server/engine-room/routes.ts
|
|
async function fetchRegistryServicesWithRetry(): Promise<any[] | null> {
|
|
// PRIORIDADE 1: Registry global (mesmo processo Node.js)
|
|
const globalRegistry = (global as any).arcadiaKernelRegistry;
|
|
if (globalRegistry) {
|
|
const services = globalRegistry.getServices();
|
|
console.log(`[Engine Room] Usando Registry global: ${services.length} serviços`);
|
|
return services;
|
|
}
|
|
|
|
// PRIORIDADE 2: HTTP request para porta 5001 (fallback)
|
|
console.log('[Engine Room] Registry global não disponível, tentando HTTP...');
|
|
// ... retry com 127.0.0.1 e localhost
|
|
}
|
|
```
|
|
|
|
#### Vantagens do Registry Global
|
|
|
|
| Aspecto | HTTP (antigo) | Registry Global (novo) |
|
|
|---------|---------------|------------------------|
|
|
| Latência | ~10-50ms | ~0.1ms |
|
|
| Confiabilidade | Problemas com loopback Docker | 100% (mesmo processo) |
|
|
| Complexidade | Retry, timeout, hostname | Acesso direto |
|
|
| Failover | Necessário | Não aplicável |
|
|
|
|
#### Inicialização no server/index.ts
|
|
|
|
```typescript
|
|
// Inicia Kernel ANTES do servidor HTTP
|
|
const kernel = new ArcadiaKernel({
|
|
dashboard: { enabled: true, port: 5001, host: '0.0.0.0' },
|
|
autoStart: process.env.KERNEL_AUTOSTART === 'true',
|
|
});
|
|
await kernel.start();
|
|
|
|
// Exporta Registry globalmente
|
|
if (kernel.serviceRegistry) {
|
|
(global as any).arcadiaKernelRegistry = kernel.serviceRegistry;
|
|
}
|
|
|
|
// DEPOIS inicia servidor HTTP (porta 5000)
|
|
httpServer.listen({ port: 5000, host: "0.0.0.0" }, ...);
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Configuração
|
|
|
|
### 6.1 Variáveis de Ambiente
|
|
|
|
```bash
|
|
# Kernel
|
|
KERNEL_ENABLED=true
|
|
KERNEL_AUTOSTART=true
|
|
|
|
# Coolify Discovery
|
|
COOLIFY_API_TOKEN=seu_token_aqui
|
|
|
|
# MetaSet
|
|
METASET_HOST=metaset
|
|
METASET_PORT=8100
|
|
|
|
# Modo Docker (desativa spawn de processos)
|
|
DOCKER_MODE=true
|
|
```
|
|
|
|
### 6.2 Docker Compose Labels
|
|
|
|
```yaml
|
|
services:
|
|
metaset:
|
|
labels:
|
|
- "arcadia.discovery.enabled=true"
|
|
- "arcadia.name=MetaSet BI"
|
|
- "arcadia.type=python"
|
|
- "arcadia.category=bi"
|
|
- "arcadia.port=8100"
|
|
- "arcadia.capabilities=dashboards,charts,sql_lab,rls,embedding"
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Roadmap
|
|
|
|
### Semana 4 ✅ CONCLUÍDO
|
|
- [x] Service Registry
|
|
- [x] StaticDiscovery
|
|
- [x] CoolifyDiscovery
|
|
- [x] DockerDiscovery
|
|
- [x] Integração com Casa de Máquinas
|
|
|
|
### Semana 5 ✅ CONCLUÍDO
|
|
- [x] XOSDiscovery
|
|
- [x] Registry Global (acesso direto)
|
|
- [x] Integração Casa de Máquinas via memória
|
|
- [ ] UnifiedRegistry (agregador) - Opcional
|
|
|
|
### Semana 6 PLANEJADO
|
|
- [ ] Maestro IA (Guardião de IAs)
|
|
- [ ] Policy Engine
|
|
- [ ] Audit Trail
|
|
|
|
### Semana 7 PLANEJADO
|
|
- [ ] Integração completa Maestro
|
|
- [ ] Documentação P2P
|
|
|
|
---
|
|
|
|
## 8. Histórico de Mudanças
|
|
|
|
| Data | Versão | Mudança |
|
|
|------|--------|---------|
|
|
| 2026-04-06 | 3.0 | Service Registry + Discovery |
|
|
| 2026-04-07 | 3.1 | Integração Casa de Máquinas |
|
|
| 2026-04-08 | 3.2 | Coolify Discovery, XOS Discovery, correção MetaSet |
|
|
| 2026-04-08 | 3.3 | **Registry Global** - Casa de Máquinas usa acesso direto (memória) em vez de HTTP |
|
|
| 2026-04-08 | 3.4 | **MetaSet Consolidado** - Migração Metabase → Apache Superset 4.1.0 |
|
|
|
|
---
|
|
|
|
## 9. Referências
|
|
|
|
- `/server/kernel/` - Código fonte do Kernel
|
|
- `/server/kernel/registry/` - Service Registry
|
|
- `/server/kernel/discovery/` - Discovery Providers
|
|
- `/server/engine-room/` - Casa de Máquinas (backend)
|
|
- `/client/src/pages/Admin.tsx` - Casa de Máquinas (frontend)
|
|
- `/home/ubuntu/.kimi/kernel e tenants.md` - Planejamento executivo
|