Sonda de servicios internos desde OPS (servicios-check)

Descripción

servicios-check es una sonda de monitoreo que vigila servicios internos solo-NetBird — aquellos que no son alcanzables desde internet y, por tanto, que UptimeRobot y el widget de Servidores del workspace no pueden vigilar. El widget de Servidores solo sabe si la máquina está encendida (API Hetzner); esta sonda mide si el servicio responde.

Qué cubre

Targets alcanzables únicamente por NetBird/localhost (o, en el caso de los runners, solo dentro de la propia máquina OPS) — lista canónica y códigos esperados: el array TARGETS del propio script — esta tabla se quedó en 4 durante s263→s284):

Por qué /backend-health desde el 25-09-2026 (mega-auditoría B-45)

Desde esa fecha los puertos 8428 (VictoriaMetrics) y 9093 (Alertmanager) de NetBird pasan por vmauth ([[decision—20260925—vmauth-auth-netbird-b45]]), que pide usuario y contraseña. vmauth contesta / y /health con 200/401 aunque el servicio real esté caído — la sonda se habría quedado ciega justo cuando más falta hace. /backend-health sí llega al servicio de detrás (502 si cae). Commit f90cb92.

Lógica de detección

• Fallo: timeout/error de conexión O HTTP ≥500. Un 3xx/4xx cuenta como VIVO (STAGE responde 302 al login por diseño; un muro de auth 401/403 significa que el servicio está ahí).
• Targets tcp://host:puerto (s284, 23-08-2026): prueba de conexión TCP en vez de HTTP, para máquinas sin endpoint HTTP alcanzable por NetBird — la estación solo expone SSH (el health del Agente escucha en 127.0.0.1:5050). Conexión aceptada = vivo (código tcp-ok); rechazo/timeout = fallo.
• Targets unit://unidad-systemd (01-09-2026, commit 3aa6436b): systemctl is-active <unidad> para un servicio systemd de la propia máquina OPS (sin red de por medio). Nace de un punto ciego real: el runner crearack-ops-1 murió por OOM el 28-08 y estuvo 4 días caído sin que nadie se enterara — el CI seguía en verde porque el otro runner absorbía todo el trabajo, a mitad de velocidad. Ni UptimeRobot (no ve dentro de la máquina) ni esta sonda (solo HTTP/TCP hasta entonces) lo veían. active = vivo; cualquier otro estado = caído, mismo camino de aviso que el resto (2 ticks → correo a infra@ + LED). Simulacro de caída verificado en el servidor real el 01-09.
• Caído: 2 ticks consecutivos fallando (~10 minutos, ventana anti-falsas-alarmas).
• Antispam: aviso por email a infra@ solo en transiciones (nuevo caído o recuperación), patrón idéntico al cron-heartbeat. Cero spam.
• Widget: la estación tiene mini-card propia en el widget Servidores (ServerGrid.tsx, fila Estación 24/7 alimentada por server='estacion') y su grupo en el modal de servicios; los demás targets encienden el LED “Servicios ON/OFF” de la tarjeta de su servidor.

Integración

Cron: /etc/cron.d/servicios-check ejecuta cada 5 minutos.

Vigilancia: el cron-heartbeat incluye una entrada servicios-check que monitorea el log de la sonda y genera alertas si la propia sonda falla (ventana 1 hora). El heartbeat es el meta-monitor de los automatismos.

Alertas: usa send_maintenance_email (tool MCP del workspace → infra@esfericlabs.com) con contexto completo:

• Qué servicio(s) cayó(eron)
• URL y código HTTP
• Ticks consecutivos fallando
• Inventario (link a AUTOMATISMOS.md)

Ubicación en ops

• Script: /opt/servicios-check/servicios-check.sh (bash)
• Fuente: scripts/ops/servicios-check/servicios-check.sh (repo workspace)
• Log: /opt/servicios-check/servicios-check.log
• Estado: /opt/servicios-check/state.down (último estado de DOWN/vivo) + /opt/servicios-check/state/<nombre>.fails (contador de fallos por target)

Instalación y prueba

# Copiar script a OPS
scp servicios-check.sh root@crearack-ops.netbird.cloud:/opt/servicios-check/
chmod +x /opt/servicios-check/servicios-check.sh

# Dry-run (imprime estado, no sella ni envía)
/opt/servicios-check/servicios-check.sh --dry-run

# Prueba de alerta (envía email de PRUEBA a infra@)
/opt/servicios-check/servicios-check.sh --test-alert

Probada E2E el 11-08: 4 de 4 servicios respondiendo + email de prueba verificado en infra@ y archivado por el filtro en la carpeta Infra de Edu.

Historicidad

• Nace de: task #215 (Integrar Zoho Mail en el Claude Method) — cierra su fleco 3 tras pausar el monitor público de STAGE (s222).
• Motivación: STAGE web no es alcanzable desde internet (puerto cerrado por diseño); UptimeRobot no puede vigilarla. Esto deja un agujero que la sonda ahora cubre.
• Sesión: s263 (11-08-2026), autor @Esquembri.
• Extensión unit:// (01-09-2026, commit 3aa6436b): tras el incidente de los 4 días de crearack-ops-1 caído sin detección, se añade el sondeo de servicios systemd locales y los dos runners de GitHub Actions como targets. Historia completa en [[entity—scripts—bash—servicios-check]].
• Paso por vmauth (25-09-2026, B-45, commit f90cb92): prod-vm y prod-alertmanager pasan a /backend-health para no quedar ciegos tras el portero vmauth, se corrige la medición cruzada PROD/STAGE de Alertmanager y se añade stage-alertmanager. Decisión completa en [[decision—20260925—vmauth-auth-netbird-b45]].

Relación con AUTOMATISMOS.md

La sonda entra en la tabla de Automatismos ejecutados periódicamente por cron en public/supercontext/AUTOMATISMOS.md como:

| servicios-check | /opt/servicios-check/servicios-check.sh | cada 5 min | sonda de servicios INTERNOS solo-NetBird...

Es un automatismo de clase B (vigilancia + alertas, sin cambios de estado en BD).

Véase también

• [[concept—infra—netbird-solo]]
• [[concept—infra—cron-heartbeat]]
• [[runbook—infra—alertas-ops]]
• [[entity—infra—mcp—send-maintenance-email]]
• [[feature—core—correo-trabajo-zoho-mail]]
• [[decision—20260925—vmauth-auth-netbird-b45]]