SIAX-MONITOR/README.md

# SIAX Agent - Sistema de Monitoreo y Gestión de Procesos

Sistema completo de monitoreo y gestión de aplicaciones Node.js y Python con integración systemd, API REST y streaming de logs en tiempo real.

## Características

### ✅ Monitoreo en Tiempo Real
- Detección automática de procesos Node.js y Python
- Métricas de CPU y RAM
- Reconciliación con systemd para detectar estados inconsistentes
- Reporte automático a API central cloud

### 🔧 Gestión de Servicios
- Registro dinámico de aplicaciones
- Generación automática de archivos `.service` para systemd
- Control de ciclo de vida: start, stop, restart
- Soporte para Node.js y Python/FastAPI
- Rate limiting para prevenir spam de operaciones

### 📊 Interface Web Local
- Dashboard de procesos en ejecución
- Escaneo y detección automática
- Visualizador de logs del sistema
- Control de aplicaciones (solo VPN)

### 🔌 API REST
- Endpoints para gestión completa de aplicaciones
- WebSocket para streaming de logs en tiempo real
- Documentación OpenAPI/Swagger ready

### 🔒 Seguridad
- Interface web solo accesible vía VPN
- Validaciones de permisos sudo
- Sistema de rate limiting
- Detección de discrepancias de estado

---

## Arquitectura

```
┌─────────────────────────────────────┐
│  API Central Cloud                  │
│  https://api.siax-system.net        │
│  - Dashboard público analytics      │
│  - Recibe reportes de agents        │
└──────────────┬──────────────────────┘
               │ POST /apps_servcs/apps
               │ (reportes de estado)
               │
┌──────────────▼──────────────────────┐
│  SIAX Agent (local en servidor)     │
│  http://192.168.x.x:8080 (VPN only) │
│                                      │
│  Componentes:                        │
│  1. Monitor (background)             │
│  2. Interface Web (puerto 8080)      │
│  3. API REST (puerto 8081)           │
│  4. WebSocket Logs (puerto 8081)     │
└──────────────────────────────────────┘
```

---

## Instalación

### Requisitos Previos

- Linux con systemd
- Rust 1.70+ (instalación abajo)
- Acceso sudo para gestión de servicios

### Instalar Rust (si no está instalado)

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

### Instalación Automática

```bash
# Clonar repositorio
git clone <repo-url>
cd siax_monitor

# Ejecutar script de despliegue
sudo ./desplegar_agent.sh
```

El script automáticamente:
- ✅ Verifica dependencias
- ✅ Compila en modo release
- ✅ Crea usuario del sistema
- ✅ Instala binario en `/opt/siax-agent`
- ✅ Configura sudoers para systemctl
- ✅ Crea y habilita servicio systemd
- ✅ Inicia el agente
- ✅ Verifica instalación

### Instalación Manual

```bash
# Compilar
cargo build --release

# Copiar binario
sudo mkdir -p /opt/siax-agent
sudo cp target/release/siax_monitor /opt/siax-agent/siax-agent

# Crear usuario
sudo useradd --system --no-create-home siax-agent

# Configurar sudoers (ver sección Configuración)

# Crear servicio systemd (ver ejemplo abajo)
sudo nano /etc/systemd/system/siax-agent.service

# Habilitar e iniciar
sudo systemctl daemon-reload
sudo systemctl enable siax-agent
sudo systemctl start siax-agent
```

---

## Configuración

### Archivo de Configuración

`/opt/siax-agent/config/monitored_apps.json`

```json
{
  "apps": [
    {
      "name": "app_tareas",
      "port": 3000
    },
    {
      "name": "fidelizacion",
      "port": 3001
    }
  ]
}
```

### Configuración de Sudoers

`/etc/sudoers.d/siax-agent`

```bash
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl start *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl stop *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl restart *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl status *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl enable *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl disable *
siax-agent ALL=(ALL) NOPASSWD: /bin/systemctl daemon-reload
siax-agent ALL=(ALL) NOPASSWD: /bin/journalctl *
```

### Variables de Entorno (main.rs)

```rust
let server_name = "siax-intel";  // Nombre del servidor
let api_key = "ak_xxx...";       // API key para cloud
let cloud_url = "https://api.siax-system.net/api/apps_servcs/apps";
```

---

## Uso

### Comandos del Sistema

```bash
# Ver estado del agente
sudo systemctl status siax-agent

# Ver logs en tiempo real
sudo journalctl -u siax-agent -f

# Reiniciar agente
sudo systemctl restart siax-agent

# Detener agente
sudo systemctl stop siax-agent
```

### Interface Web

```
http://localhost:8080
```

**Páginas disponibles:**
- `/` - Inicio
- `/scan` - Escanear procesos Node.js
- `/select` - Seleccionar y agregar procesos
- `/logs` - Ver logs del sistema

### API REST

**Base URL:** `http://localhost:8081`

#### Listar Aplicaciones
```bash
GET /api/apps

Response:
{
  "success": true,
  "data": {
    "apps": ["app1", "app2"],
    "total": 2
  }
}
```

#### Registrar Nueva Aplicación
```bash
POST /api/apps
Content-Type: application/json

{
  "app_name": "mi-app",
  "script_path": "/opt/apps/mi-app/index.js",
  "working_directory": "/opt/apps/mi-app",
  "user": "nodejs",
  "environment": {
    "PORT": "3000",
    "NODE_ENV": "production"
  },
  "restart_policy": "always",
  "app_type": "nodejs",
  "description": "Mi aplicación"
}
```

#### Iniciar Aplicación
```bash
POST /api/apps/:name/start
```

#### Detener Aplicación
```bash
POST /api/apps/:name/stop
```

#### Reiniciar Aplicación
```bash
POST /api/apps/:name/restart
```

#### Obtener Estado
```bash
GET /api/apps/:name/status

Response:
{
  "success": true,
  "data": {
    "name": "mi-app",
    "status": "running",
    "pid": 12345,
    "cpu_usage": 2.5,
    "memory_usage": "128.50 MB",
    "systemd_status": "active",
    "last_updated": "2026-01-12 10:30:00"
  }
}
```

#### Eliminar Aplicación
```bash
DELETE /api/apps/:name
```

### WebSocket para Logs

```javascript
// Conectar a logs en tiempo real
const ws = new WebSocket('ws://localhost:8081/ws/logs/mi-app');

ws.onmessage = (event) => {
  console.log('Log:', event.data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};
```

**Ejemplo con wscat:**
```bash
wscat -c ws://localhost:8081/ws/logs/mi-app
```

---

## Ejemplos de Uso

### Registrar una app Node.js

```bash
curl -X POST http://localhost:8081/api/apps \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "api-backend",
    "script_path": "/home/nodejs/api-backend/server.js",
    "working_directory": "/home/nodejs/api-backend",
    "user": "nodejs",
    "environment": {
      "PORT": "3000",
      "NODE_ENV": "production"
    },
    "restart_policy": "always",
    "app_type": "nodejs",
    "description": "API Backend Principal"
  }'
```

### Registrar una app Python (FastAPI)

```bash
curl -X POST http://localhost:8081/api/apps \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "ml-service",
    "script_path": "/home/python/ml-service/main.py",
    "working_directory": "/home/python/ml-service",
    "user": "python",
    "environment": {
      "PORT": "8000",
      "WORKERS": "4"
    },
    "restart_policy": "on-failure",
    "app_type": "python"
  }'
```

### Reiniciar una aplicación

```bash
curl -X POST http://localhost:8081/api/apps/api-backend/restart
```

### Ver estado de todas las apps

```bash
curl http://localhost:8081/api/apps | jq
```

---

## Estructura del Proyecto

```
siax_monitor/
├── src/
│   ├── main.rs                 # Entry point
│   ├── lib.rs                  # Módulo raíz
│   ├── monitor.rs              # Monitor de procesos + reconciliación systemd
│   ├── interface.rs            # Interface web
│   ├── logger.rs               # Sistema de logs
│   ├── config.rs               # Gestión de configuración
│   ├── models/                 # Modelos de datos
│   │   ├── mod.rs
│   │   ├── app.rs             # ManagedApp, AppStatus, ServiceStatus
│   │   └── service_config.rs  # ServiceConfig, AppType, RestartPolicy
│   ├── systemd/               # Integración con systemd
│   │   ├── mod.rs
│   │   ├── systemctl.rs       # Wrapper de systemctl
│   │   ├── service_generator.rs # Generador de .service
│   │   └── parser.rs          # Parser de salida systemd
│   ├── orchestrator/          # Lógica de ciclo de vida
│   │   ├── mod.rs
│   │   ├── app_manager.rs     # CRUD de apps
│   │   └── lifecycle.rs       # Start/Stop/Restart + rate limiting
│   └── api/                   # API REST + WebSocket
│       ├── mod.rs
│       ├── handlers.rs        # Handlers HTTP
│       ├── dto.rs             # DTOs de request/response
│       └── websocket.rs       # LogStreamer con journalctl
├── web/                       # Templates HTML
├── config/                    # Configuración
│   └── monitored_apps.json
├── logs/                      # Logs del sistema
│   └── errors.log
├── Cargo.toml                 # Dependencias
├── desplegar_agent.sh         # Script de deployment
├── tareas.txt                 # Plan de desarrollo
└── README.md                  # Esta documentación
```

---

## Estados de Aplicaciones

El sistema reconcilia estados entre detección de procesos y systemd:

| Proceso | Systemd | Estado Final | Descripción |
|---------|---------|--------------|-------------|
| ✅ | Active | `running` | Funcionamiento normal |
| ❌ | Active | `crashed` | ⚠️ Systemd dice activo pero proceso no existe |
| ❌ | Failed | `failed` | Servicio falló y systemd lo detectó |
| ✅ | Inactive | `zombie` | ⚠️ Proceso existe pero systemd dice inactivo |
| ❌ | Inactive | `stopped` | Aplicación detenida normalmente |

Las **discrepancias** (crashed/zombie) se reportan automáticamente en logs y a la API central.

---

## Troubleshooting

### El agente no inicia

```bash
# Ver logs detallados
sudo journalctl -u siax-agent -n 100 --no-pager

# Verificar permisos
ls -la /opt/siax-agent
```

### Error de permisos sudo

```bash
# Verificar configuración sudoers
sudo cat /etc/sudoers.d/siax-agent

# Probar manualmente
sudo -u siax-agent sudo systemctl status siax-agent
```

### No puede registrar apps

**Error:** `Permission denied writing to /etc/systemd/system`

**Solución:** Asegúrate de que el servicio tiene permisos de escritura o ajusta `ProtectSystem` en el servicio systemd.

### WebSocket no conecta

```bash
# Verificar que el puerto 8081 esté abierto
sudo netstat -tlnp | grep 8081

# Probar conexión
curl http://localhost:8081/api/apps
```

---

## Desarrollo

### Compilar en modo desarrollo

```bash
cargo build
cargo run
```

### Ejecutar tests

```bash
cargo test
```

### Linter

```bash
cargo clippy
```

### Formateo

```bash
cargo fmt
```

---

## Licencia

[Especificar licencia]

---

## Contacto

[Información de contacto del proyecto]