Conector de DBReportes

Enlace local que permite a DBReportes consultar una base de datos privada —localhost, un contenedor, la red interna de la empresa— sin exponerla a internet y sin abrir ningún puerto.

Cómo funciona

El conector abre una conexión saliente hacia el servidor de DBReportes (WebSocket sobre 443) y queda a la espera. Cuando alguien ejecuta un reporte, el servidor pide por ese enlace que se abra un socket contra la base, y los bytes viajan multiplexados por la misma conexión.

Hacia fuera se comporta como cualquier programa que habla con un servicio web: no escucha en ningún puerto, no publica la base y no necesita que se toque el cortafuegos.

tu red                                     DBReportes
┌──────────────┐                          ┌──────────────┐
│  base        │◀── socket local ──┐      │              │
│  conector    │───── WSS 443 ─────┼─────▶│  servidor    │
└──────────────┘   (saliente)      └      └──────────────┘

Uso

El token se genera desde la página, en Conectores → Nuevo conector. Se muestra una sola vez: no queda guardado en claro y no hay forma de volver a verlo.

npx dbreportes-conector --servidor https://reportes.tuempresa.com --token dbrk_...

Con variables de entorno, que es lo cómodo en una máquina virtual o un contenedor:

DBREPORTES_SERVIDOR=https://reportes.tuempresa.com \
DBREPORTES_TOKEN=dbrk_... \
npx dbreportes-conector

Mientras el conector esté en marcha, en el formulario de conexión de DBReportes se elige este conector y se escribe el host tal como lo ve esta máquina: localhost, el nombre de un contenedor o una dirección de la red interna.

El enlace es de la empresa, no de quien lo levantó: se enciende una vez y todos sus empleados trabajan contra esa base desde la página.

Opciones

| Opción | Variable | Qué hace | |---|---|---| | --servidor <url> | DBREPORTES_SERVIDOR | Dirección de DBReportes | | --token <token> | DBREPORTES_TOKEN | Token emitido al dar de alta el conector | | --ca <ruta> | DBREPORTES_CA | Certificado de una autoridad propia | | --sin-verificar | DBREPORTES_VERIFICAR_TLS=off | No verificar el certificado de la base | | --json | DBREPORTES_JSON=on | Una línea de JSON por suceso | | --version | | Mostrar la versión | | --help | | Mostrar la ayuda |

Códigos de salida: 0 cierre ordenado · 2 faltan datos o son inválidos · 3 no se pudo leer el certificado.

Cifrado

Dos capas, y ninguna la puede leer el servidor:

1. WSS cifra el tramo entre el conector y DBReportes.
2. Si la conexión usa require, verify-ca o verify-full, el cifrado contra la base lo termina el conector, con el nombre real del host. El servidor solo reenvía bytes ya cifrados.

Por eso --sin-verificar es una mala idea salvo en una red de confianza con un certificado autofirmado. Lo correcto en ese caso es pasar la autoridad con --ca.

La conexión a la base es solo de lectura: el servidor pone la sesión en default_transaction_read_only y rechaza cualquier escritura.

Para automatizar

No hay ningún paso interactivo: nunca pregunta nada ni espera una tecla. Con --json cada suceso sale como una línea de JSON, con hora, nivel, evento y mensaje, lista para que otro programa la lea:

{"hora":"2026-09-01T20:14:03.221Z","nivel":"info","mensaje":"enlazado con wss://…","evento":"enlazado"}

Eventos: arranque, enlazado, listo, stream, desenlazado, reintento, aviso, cierre.

SIGINT y SIGTERM cierran el enlace de forma ordenada, así que funciona igual como servicio de systemd o como contenedor.

Ejemplo de unidad de systemd:

[Unit]
Description=Conector de DBReportes
After=network-online.target

[Service]
Environment=DBREPORTES_SERVIDOR=https://reportes.tuempresa.com
Environment=DBREPORTES_TOKEN=dbrk_...
Environment=DBREPORTES_JSON=on
ExecStart=/usr/bin/npx dbreportes-conector
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Si el enlace se cae, el conector reconecta solo con espera creciente (de 1 s hasta 30 s), así que no hace falta vigilarlo.

Requisitos

Node.js 20 o superior. Nada más.