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)

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

Instalación Automática

# 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

# 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

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

Configuración de Sudoers

/etc/sudoers.d/siax-agent

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)

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

# 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

GET /api/apps

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

Registrar Nueva Aplicación

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

POST /api/apps/:name/start

Detener Aplicación

POST /api/apps/:name/stop

Reiniciar Aplicación

POST /api/apps/:name/restart

Obtener Estado

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

DELETE /api/apps/:name

WebSocket para Logs

// 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:

wscat -c ws://localhost:8081/ws/logs/mi-app

---

Ejemplos de Uso

Registrar una app Node.js

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)

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

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

Ver estado de todas las apps

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

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

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

Error de permisos sudo

# 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

# 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

cargo build
cargo run

Ejecutar tests

cargo test

Linter

cargo clippy

Formateo

cargo fmt

---

Licencia

[Especificar licencia]

---

Contacto

[Información de contacto del proyecto]