NSBatch

Qué es NSBatch

nsbatch (NSBatch) es un gestor de colas de procesos al estilo mainframe (JES): cataloga trabajos (comandos shell con cola, timeout y notificaciones), los encola como ejecuciones (un PID por ejecución, estados QUEUED|HOLD|RUNNING|OK|ERROR|CANCELLED), guarda el spool de logs en vivo, planifica repeticiones con reglas cron simples y controla el acceso por RBAC. Cada servicio vive en su propio directorio de entorno (config.yaml + db/ + spool/ + logs/), y varios entornos se gestionan por nombre de instancia (-i / NSBATCH_ENV).

Los nombres de trabajos, colas, hosts y emails de los ejemplos son ficticios.

Casos de uso

1. Puesta en marcha y primer trabajo nocturno

Crear el entorno, arrancarlo y dar de alta el trabajo CIERRE en la cola BATCH.

nsbatch init ./miscolas
nsbatch register prd ./miscolas
nsbatch start prd --port 8100
nsbatch queues list -i prd                       # SYSTEM, BATCH, RAPIDA, NOCTURNA iniciales
nsbatch jobs create --name CIERRE --command "/opt/bin/cierre.sh" --queue BATCH -i prd --timeout 7200
nsbatch submit CIERRE -i prd --params "--fecha 20260904"
nsbatch execs RUNNING -i prd

Flujo web: login (admin/admin123, cambiar tras el primer login) → pestaña Trabajos → crear → Encolar → pestaña Ejecuciones → ver spool en vivo.

2. Programar el cierre laborable a las 02:30

Regla cron hora + días de semana, con consulta de próximas ejecuciones e historial.

nsbatch jobs cron CIERRE add --time 02:30 --days 1,2,3,4,5 -i prd
nsbatch jobs cron CIERRE next -i prd
nsbatch jobs cron CIERRE history --limit 20 -i prd

Flujo web: botón 🕒 del trabajo → alta de regla → lista de reglas e historial por regla. Si a la hora programada hay ejecuciones activas, la regla se omite con aviso (contador skips, evento en schedules.log y auditoría) en lugar de solaparse.

3. Operar una incidencia: retener, mover y relanzar

Una ejecución problemática se retiene, se mueve a la cola rápida y un fallo se relanza.

nsbatch execs ERROR --job CIERRE --limit 10 -i prd
nsbatch exec show 42 -i prd
nsbatch exec log 42 -i prd --lines 50
nsbatch exec hold 42 -i prd
nsbatch exec move 42 --queue RAPIDA -i prd
nsbatch exec release 42 -i prd
nsbatch exec rerun 42 -i prd
nsbatch exec cancel 42 -i prd

4. Pausar una cola y avisar por email ante errores

Congelar la cola BATCH sin perder lo encolado y activar notificación de error.

nsbatch queues pause BATCH -i prd
nsbatch jobs update CIERRE --notify-error --to "ops@empresa.com" -i prd
nsbatch queues open BATCH -i prd

Estados de cola: OPEN (ejecuta y admite), PAUSED (no ejecuta, admite), CLOSED (ni ejecuta ni admite). El resultado del envío queda en el spool; si el correo falla, la ejecución no se ve afectada.

Interfaz

Colas

Ejecuciones

Referencia

Comandos CLI

Comando	Descripción
`init [dir] [--force]`	Crea el entorno (`config.yaml` + `db/` + `spool/` + `logs/`, `admin`/`admin123`, colas `SYSTEM, BATCH, RAPIDA, NOCTURNA`)
`start [dir\|nombre] [--port N]`	Arranca el daemon (log en `<dir>/logs/nsbatch.log`)
`stop [dir\|nombre]`	Para el servidor
`status [dir\|nombre]`	Si corre, PID, dirección, config
`license [dir\|nombre]`	Estado de licencia/trial, cliente, fingerprint
`submit <job\|id> [dir\|nombre] [--params ...] [--queue <cola\|id>] [--as usuario]`	Encola sin pasar por la web; queda `QUEUED` si el servidor está parado
`queues list\|create\|open\|close\|pause\|delete`	Gestión de colas. `create`: `--name` (req.), `--desc`, `--max` (def. 2), `--prio 0-100` (def. 50), `--color #rrggbb`
`jobs list\|create\|update\|delete\|cron`	Catálogo. `create`: `--name`, `--command`, `--queue` (req.), `--desc`, `--timeout` (def. 3600), `--to`, `--notify-start/--notify-end/--notify-error`, `--no-notify-start/--no-notify-end/--no-notify-error`
`jobs cron <job> list\|add\|enable\|disable\|delete\|next\|history`	Reglas: `add --time HH:MM` (req.) `[--days 0-6] [--month-days 1-31] [--params ...] [--queue <cola>] [--catch-up] [--off]`; `history [--rule ID] [--limit N]`
`execs [ESTADO] [--queue X] [--job Y] [--limit N]`	Lista (`QUEUED\|HOLD\|RUNNING\|OK\|ERROR\|CANCELLED\|all`, def. 30)
`exec show\|cancel\|rerun\|move\|hold\|release\|log <id>`	`move --queue <cola>`; `log [--lines N] [-f\|--follow]`
`users [create]`	`create --username X --password Y` (mín. 6; alias `--user/--name`, `--pass`), `--fullname`, `--email`
`groups [create]`	`create --name X [--desc D]`
`roles`	Lista roles y permisos (`admin`, `queue:manage`, `job:manage`, `job:submit`, `exec:cancel`, `exec:rerun`, `exec:move`, `spool:view`, `users:manage`)
`audit [--limit N]`	Últimas entradas de auditoría
`dashboard`	KPIs: en ejecución, encolados, OK/errores de hoy, estado de colas, últimas 5 ejecuciones
`schedlog log [--limit N] [--type queue\|job]` / `pending` / `history [--limit N]`	Log de `schedules.log`, one-shots pendientes e historial
`purge [--days N] [--dry-run]`	Purga one-shots terminales antiguos (def.: `history.retention_days`, 90); no toca reglas cron ni ejecuciones
`config show\|set <clave> <valor>\|smtp-test\|telegram-test\|webhook-test`	Ver/modificar `config.yaml` y probar notificaciones (`email`, `telegram`, `webhook`)
`register <nombre> <ruta>` / `deregister` / `instances`	Registro de instancias en `~/.nsbatch/instances.yaml`

Flags globales: -i, --instance, --config <dir>, --port <n>, --version. Variable NSBATCH_ENV (alias obsoleto NSQUEUE_ENV). Los jobs reciben NSQ_JOB, NSQ_EXEC, NSQ_ATTEMPT.

Configuración principal (`config.yaml`)

Clave	Descripción
`server.host` / `server.port`	Escucha (def. `0.0.0.0:8100`)
`database.path`	SQLite (`./db/nsbatch.db`)
`auth.cookieName` / `jwtSecret` / `jwtExpiryMin`	Sesión (def. 480 min)
`license.trial_days`	Trial (30)
`spool.dir` / `max_mb` / `retention_days`	Spool (`./spool`, 50 MB, 30 días)
`history.retention_days`	Retención para `purge` (90)
`smtp.` / `notify.methods` / `telegram.` / `webhook.*`	Notificaciones `email,telegram,webhook`
`i18n.default`	Idioma (`es`)

Áreas de la web

Colas (estado, RUN/MAX, encolados, abrir/cerrar/pausar) · trabajos (catálogo, crear/editar, notificaciones 🔔) · ejecuciones (filtro por estado, detalle con tiempos/CPU/memoria, spool en vivo) · planificación (botón 🕒 por trabajo: reglas + alta + historial) · usuarios, grupos y roles · auditoría · configuración.

Ejemplos comentados

# Cierre laborable 02:30 + mensual el día 1 a las 08:00 con catch-up
nsbatch jobs cron CIERRE add --time 02:30 --days 1,2,3,4,5 -i prd
nsbatch jobs cron CIERRE add --time 08:00 --month-days 1 \
  --params "--modo mensual" --catch-up -i prd
nsbatch jobs cron CIERRE list -i prd
nsbatch jobs cron CIERRE next -i prd

# Trazabilidad: ejecuciones de una regla y purga en seco
nsbatch jobs cron CIERRE history --rule 2 --limit 20 -i prd
nsbatch schedlog log --limit 50 -i prd
nsbatch purge --dry-run -i prd
nsbatch purge --days 30 -i prd

# Trabajo con avisos de inicio/fin/error
nsbatch jobs create --name AVISO --command "echo hola" --queue RAPIDA -i prd \
  --notify-start --notify-end --notify-error --to "ops@empresa.com,turno@empresa.com"

Preguntas frecuentes

¿Qué pasa si envío un trabajo con el servidor parado? Avisa y la ejecución queda QUEUED hasta el start (con --catch-up, las reglas cron disparan una vez al arrancar si la hora de hoy ya pasó).

¿Las reglas cron se solapan? No: si hay ejecuciones activas a la hora programada, el disparo se omite con aviso (skips + schedules.log + auditoría).

¿El purge borra mis planificaciones? No: solo purga one-shots terminales antiguos; reglas cron y ejecuciones no se tocan (el spool lo cubre su propio janitor).

¿Cómo migro desde nsqueue? nsbatch migra solo el layout (db/nsqueue.db → db/nsbatch.db, logs) y el esquema; hay que re-emitir la licencia (nslm issue --app nsbatch ...). NSQ_* no cambian.