Version inicial monitor RPi

2026-06-02 17:31:57 +02:00
commit 8a0e1e83ed
9 changed files with 3124 additions and 0 deletions
@@ -0,0 +1,257 @@
+# Monitor RPi Rack
+
+Aplicacion web local para monitorizar un rack de Raspberry Pi mediante SSH. Corre en un contenedor Docker dedicado y expone un dashboard accesible por navegador.
+
+## Arquitectura
+
+```text
+Navegador
+  dashboard.html / config.html
+        |
+        | HTTP API
+        v
+Contenedor monitor-rpi
+        |
+        | SSH con usuario/password
+        v
+Raspberry Pi activas
+```
+
+El backend mantiene el ultimo estado en memoria. El dashboard consulta ese estado, pero no abre conexiones SSH directamente.
+
+## Rutas Principales
+
+- Dashboard: `http://192.168.0.53:8787/dashboard.html`
+- Configuracion: `http://192.168.0.53:8787/config.html`
+- API estado: `http://192.168.0.53:8787/api/status`
+
+Credenciales HTTP actuales:
+
+```text
+usuario: admin
+password: monitor-rpi-2026
+```
+
+## Configuracion Persistente
+
+La configuracion vive en:
+
+```text
+/home/yamaray/docker/monitorRPi/data/config.json
+```
+
+Dentro del contenedor se lee como:
+
+```text
+/data/config.json
+```
+
+## Parametros Generales
+
+### `mockMode`
+
+Si es `true`, el sistema genera datos simulados. Si es `false`, consulta las Raspberry reales por SSH.
+
+### `refreshIntervalSeconds`
+
+Intervalo activo de escaneo cuando hay al menos un dashboard visible. Por defecto: `30`.
+
+### `idleScanIntervalSeconds`
+
+Intervalo lento de escaneo cuando no hay dashboards visibles. Por defecto: `300`.
+
+### `sshTimeoutSeconds`
+
+Tiempo maximo permitido para completar cada consulta SSH. Por defecto: `8`.
+
+### `temperatureThresholdsC`
+
+Umbrales de color para temperaturas:
+
+```json
+{
+  "warning": 60,
+  "hot": 70,
+  "critical": 80
+}
+```
+
+### `metricThresholdsPercent`
+
+Umbrales por metrica para barras de CPU, RAM y disco.
+
+Valores actuales recomendados:
+
+```json
+{
+  "cpu": { "warning": 60, "hot": 75, "critical": 90 },
+  "memory": { "warning": 70, "hot": 85, "critical": 95 },
+  "disk": { "warning": 70, "hot": 85, "critical": 95 }
+}
+```
+
+## Parametros Por Dispositivo
+
+### `active`
+
+Si es `true`, el backend consulta ese dispositivo. Si es `false`, aparece como inactivo y no se abre SSH.
+
+### `id`
+
+Identificador interno unico del dispositivo. Se usa para tracking interno y calculos como tasas de red.
+
+### `name`
+
+Nombre visible en el dashboard.
+
+### `host`
+
+IP o nombre DNS usado para conectar por SSH.
+
+### `port`
+
+Puerto SSH. Normalmente `22`; en Home Assistant puede ser `2222` si se usa un add-on SSH.
+
+### `username`
+
+Usuario SSH.
+
+### `password`
+
+Password SSH. Se guarda en `config.json`, por lo que el archivo debe permanecer protegido.
+
+### `model`
+
+Modelo visible: `RPi 3`, `RPi 4`, `RPi 5`.
+
+### `role`
+
+Funcion del dispositivo: Docker, Home Assistant, MQTT, Nginx, Gitea, etc.
+
+### `location`
+
+Ubicacion fisica o logica. Actualmente se muestra en la tarjeta.
+
+## Metricas Recogidas
+
+Por SSH se leen datos de solo lectura:
+
+- Temperatura CPU
+- Uso CPU
+- Uso RAM
+- Uso disco raiz `/`
+- Load average
+- Uptime
+- Docker instalado
+- Contenedores Docker activos
+- Contenedores Docker detenidos
+- Contenedores Docker unhealthy
+- Interfaz de red principal
+- Tipo de conexion: Cable/WiFi
+- Velocidad nominal si existe
+- Trafico RX/TX calculado entre scans
+
+## Clientes Activos
+
+El dashboard envia heartbeat al backend cuando esta visible.
+
+Comportamiento:
+
+```text
+0 clientes visibles -> escaneo lento idleScanIntervalSeconds
+1+ clientes visibles -> escaneo activo refreshIntervalSeconds
+```
+
+El navegador integrado de Codex se ignora para no alterar el conteo de clientes reales.
+
+## API
+
+Todas las llamadas requieren autenticacion HTTP Basic.
+
+### `GET /api/status`
+
+Devuelve ultimo estado conocido.
+
+Incluye:
+
+- `mockMode`
+- `refreshIntervalSeconds`
+- `idleScanIntervalSeconds`
+- `activeClients`
+- `currentScanIntervalSeconds`
+- `temperatureThresholdsC`
+- `metricThresholdsPercent`
+- `summary`
+- `devices`
+- `clients`
+
+Ejemplo PowerShell:
+
+```powershell
+$pair = 'admin:monitor-rpi-2026'
+$token = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
+Invoke-RestMethod http://192.168.0.53:8787/api/status -Headers @{Authorization="Basic $token"}
+```
+
+### `GET /api/config`
+
+Devuelve la configuracion actual.
+
+Nota: actualmente devuelve tambien passwords porque `config.html` permite editarlas.
+
+### `POST /api/config`
+
+Guarda la configuracion completa y reinicia el ciclo de escaneo.
+
+### `POST /api/reload`
+
+Recarga `config.json` desde disco.
+
+### `POST /api/scan-now`
+
+Fuerza un scan inmediato de todos los dispositivos activos.
+
+### `POST /api/client-heartbeat`
+
+Usado por el dashboard para avisar que hay un cliente visible.
+
+Body:
+
+```json
+{
+  "clientId": "client-id"
+}
+```
+
+### `POST /api/clients/clear`
+
+Limpia la lista de clientes activos en memoria.
+
+## Docker
+
+Ruta en la RPi:
+
+```text
+/home/yamaray/docker/monitorRPi/
+```
+
+Stack:
+
+```text
+/home/yamaray/docker/monitorRPi/docker-compose.yml
+```
+
+Reiniciar:
+
+```bash
+cd /home/yamaray/docker/monitorRPi
+docker compose restart monitor-rpi
+```
+
+Reconstruir:
+
+```bash
+cd /home/yamaray/docker/monitorRPi
+docker compose up -d --build
+```
+