Operaciones y resolución de problemas

Todo lo que necesitas después de que la instancia esté en marcha: mantenerla sana, escalarla, respaldarla, actualizarla, ejecutarla aislada y arreglar lo que no salió en verde. Si todavía la estás poniendo en marcha, empieza con la guía de despliegue.

Operaciones

Tareas programadas

El escaneo diario de vencimientos/puestos y la entrega de webhooks se ejecutan en temporizadores in-process. En hosts que inactivan los temporizadores en segundo plano (algunas plataformas serverless), gestiónalos desde un planificador externo en su lugar — establece KEYRIGHT_CRON_SECRET e invoca:

curl -X POST -H "X-Cron-Secret: $SECRET" $BASE/internal/notifications/run
curl -X POST -H "X-Cron-Secret: $SECRET" $BASE/internal/webhooks/deliver

Observabilidad

• Liveness: GET /health (200 estático — nunca saca un nodo del balanceo por un parpadeo transitorio de la BD). Readiness: GET /health/ready (también comprueba la conectividad de la BD — 503 cuando es inaccesible).
• Registros: JSON estructurado a stdout (controladores de Docker/K8s, o el Registro de eventos de Windows vía ANCM). Observa las líneas de arranque que confirman las migraciones aplicadas y el estado de la autolicencia.
• Monitoriza: /health de la aplicación, la disponibilidad/conexiones/disco de PostgreSQL y el vencimiento del certificado en el balanceador de carga.

Diagnósticos (2.2.0)

• GET /admin/self-diagnostics (token de administración) — una instantánea de salud en una sola llamada para el triaje: versión, accesibilidad de la base de datos + migraciones pendientes, fase de la autolicencia, características habilitadas, si SMTP/alertas están configurados, y tiempo activo. Como /admin/self-license, sigue accesible incluso cuando la instancia está restringida, así que puedes diagnosticar una parada de licenciamiento.

  {
    "version": "2.2.0", "uptimeSeconds": 3600,
    "database": { "reachable": true, "error": null, "pendingMigrations": 0 },
    "selfLicense": { "status": "valid", "phase": "active", "isTrial": false, "daysUntilExpiry": 320, "runtimeBlocked": false },
    "features": { "operatorMode": false, "sso": true, "whitelabel": true, "airgap": true },
    "smtpConfigured": true,
    "alerts": { "rulesEnabled": 3, "errorsAlerted24h": 0 }
  }

• Ids de correlación de errores — cada error de servidor no controlado (HTTP 500) se registra una vez con un id corto y devuelve ese id al llamante en la cabecera de respuesta X-Keyright-Error-Id (y un campo errorId en el cuerpo). Cuando un cliente reporta un error, ese id asocia su reporte a exactamente una línea de registro.

Alertas por correo (2.2.0)

Recibe un correo cuando ocurren cosas — se configura en el panel → Settings → Email alerts (o vía la API):

• SMTP — establece tu propio host/puerto/usuario/contraseña/remitente de SMTP en el panel (POST /admin/alerts/smtp); la contraseña se almacena cifrada con KEK y es de solo escritura (nunca se devuelve). Si no lo estableces, las alertas recaen en la configuración de entorno KEYRIGHT_SMTP_*.
• Reglas por evento — habilita exactamente los eventos que quieras y da a cada uno su propia lista de destinatarios (POST /admin/alerts/rules), de modo que distintos eventos se encaminen a distintas direcciones. Un botón de “enviar correo de prueba” verifica tu configuración.
• Los eventos incluyen los de cara al cliente (licencia por vencer/vencida, límite de puestos alcanzado, revocada) e, importante para el autoalojamiento, la licencia de tu propia instancia acercándose al vencimiento, entrando en gracia o restringiéndose — para que una instancia de fallo cerrado nunca se detenga inesperadamente — más eventos de sistema (error de servidor, error de base de datos, fallo de tarea programada). Las condiciones recurrentes se deduplican para que envíen un correo una vez por ventana, no en cada escaneo.

Endurecimiento de seguridad

• Mantén KEYRIGHT_ADMIN_TOKEN, KEYRIGHT_KEK y KEYRIGHT_SIGNING_KEY en un gestor de secretos — nunca en una imagen ni en el control de código fuente.
• Expón públicamente solo :443 (vía el balanceador de carga). /admin/* y /internal/* deberían ser accesibles solo por ti/tu red; la ruta de cliente /v1/* es la única que tus clientes necesitan.
• Restringe el acceso de red a la base de datos a los nodos de aplicación, y exige TLS hacia la base de datos.

Escalado y balanceo de carga

La aplicación es ligera en CPU y sin estado; la escala tiene que ver con la redundancia y la capacidad de base de datos, no con el rendimiento de la aplicación.

Escala	Licencias activas	Nodos de aplicación	PostgreSQL	Balanceador de carga
Evaluación	cualquiera	1 (0.5 vCPU / 512 MB)	incluido	ninguno
Pequeña	hasta ~50k	1 (1 vCPU / 1 GB)	2 vCPU / 2 GB gestionado	proxy TLS opcional
HA estándar	hasta ~500k	2–3 (1 vCPU / 1 GB)	HA (primario+standby)	sí
Grande	1M+	3–5+ autoescalado	4–8 vCPU / 16 GB+ HA + PgBouncer	sí

Ejecuta 2+ nodos de aplicación detrás de cualquier balanceador de carga HTTP. Como la aplicación es sin estado y los clientes verifican offline, no se necesita afinidad de sesión — envía cualquier solicitud a cualquier nodo. Termina TLS en el balanceador y reenvía X-Forwarded-For (IP real del cliente) y X-Forwarded-Proto (para que el panel/portal generen URLs https); la aplicación respeta ambos. La concurrencia es segura entre nodos — los créditos y los puestos usan comprobación-y-descuento serializable, así que no hay dos nodos que puedan gastar dos veces un saldo o un puesto.

Copia de seguridad y restauración

Todo está en PostgreSQL — pg_dump / pg_restore estándar. Haz copia de seguridad también de KEYRIGHT_KEK y KEYRIGHT_SIGNING_KEY por separado y de forma segura: sin la KEK, las claves de firma cifradas en la base de datos no pueden recuperarse.

Actualizaciones

1. Haz copia de seguridad de la base de datos (y confirma que tienes la KEK/clave de firma).
2. Descarga la nueva versión (docker compose pull / sube el image.tag de Helm / coloca el nuevo bundle de Windows).
3. Reinicia. Las migraciones se aplican automáticamente al arrancar — un solo paso, sin SQL manual.
4. curl /health (comprueba version) y confirma que /admin/self-license sigue informando de tu licencia.

Las actualizaciones son compatibles hacia atrás dentro de una línea menor; con 2+ nodos puedes actualizar de uno en uno para cero tiempo de inactividad. Las degradaciones después de que se haya ejecutado una migración no están soportadas — por eso importa el paso 1.

Operación aislada

Nada de esto necesita internet en tiempo de ejecución. Tu licencia y las licencias de tus clientes se verifican offline contra claves públicas integradas; los créditos para equipos desconectados usan bloques de crédito aislados firmados (una característica Enterprise): emite un bloque firmado, canjéalo offline, reconcilia al reconectar. Dos cosas para una ejecución aislada limpia:

• Desactiva GeoIP: establece KEYRIGHT_GEOIP_URL= (vacío) para que la búsqueda de ubicación de equipo del panel no intente nada saliente.
• Mueve las imágenes adentro: en un host conectado, docker save ghcr.io/delta1-labs/keyright:2.2.2 (y postgres:16 si usas la BD incluida) a un tarball, luego docker load dentro de la red aislada.

Resolución de problemas y preguntas frecuentes

El contenedor se cierra al arrancar quejándose de que la KEK debe estar establecida. Establece KEYRIGHT_KEK a un valor de 32 bytes en base64 (openssl rand -base64 32). Ten en cuenta que la aplicación se conecta a la base de datos y ejecuta migraciones primero, así que un error de conexión a la BD aparece antes que este.

Error de arranque al conectar con la base de datos / “relation does not exist”. Comprueba KEYRIGHT_DB (host, puerto, base de datos, credenciales, SSL Mode). El rol debe poder crear tablas (Configuración → Base de datos); confirma que la base de datos está vacía en el primer arranque y que el rol es su propietario (o tiene CREATE ON SCHEMA public en PG15+).

El pod está en CrashLoopBackOff / el contenedor se reinicia constantemente, los registros muestran Name or service not known / connection refused / un timeout de Npgsql. La aplicación ejecuta sus migraciones al arrancar, así que se cierra (y reinicia) si no puede alcanzar la base de datos cuando arranca — no obtendrás un pod en marcha-pero-no-listo. En una instalación de evaluación nueva con Postgres incluido unos cuantos reinicios son esperados mientras Postgres pasa a Ready, y se resuelven solos. De lo contrario es casi siempre un problema de conectividad, no un error: (1) el host de la BD no se resuelve o no es accesible desde el nodo de aplicación (comprueba DNS/egreso, y cualquier regla de NSG/firewall o “permitir servicios de Azure” en una BD gestionada); (2) desajuste de TLS — la mayoría de los Postgres gestionados necesitan SSL Mode=Require (añade ;Trust Server Certificate=true si no validas la CA); (3) credenciales/nombre de base de datos incorrectos. Comprobación previa antes de desplegar: desde un pod en la misma red, confirma que la aplicación puede resolver y alcanzar el host y el puerto de la BD. Una vez que la BD es accesible, el pod pasa a Ready por sí solo.

Cada solicitud devuelve 402. Tu instancia está restringida — sin clave de licencia/prueba válida (Licenciamiento). Comprueba /admin/self-license; instala una clave vía KEYRIGHT_SELF_LICENSE y reinicia.

/admin/* devuelve 401. Envía X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN. La ruta de cliente /v1/* nunca la necesita.

¿La imagen incluye una base de datos? No — es solo-aplicación. Ejecuta PostgreSQL junto a ella (consulta la visión general de la arquitectura y Configuración → Base de datos).

Las aplicaciones de mis clientes no pueden activar. Confirma que la URL de servicio del SDK apunta a tu instancia (Conecta tu producto) y que el slug del producto + la clave pública integrada coinciden con el producto para el que emites claves.

Mi licencia venció — ¿qué pasa? Una licencia de pago obtiene una gracia de solo lectura de 15 días (el runtime + las lecturas siguen funcionando); una prueba se detiene de inmediato. Tras la gracia, la instancia se detiene por completo hasta que instales una clave renovada (Licenciamiento).

¿Necesito un balanceador de carga? Solo para 2+ nodos de aplicación (Escalado). Un solo nodo no (puede que aun así quieras un proxy que termine TLS por delante).

---

¿Listo para ejecutar Keyright en tu propio entorno? Habla con ventas para una prueba o una licencia Standard/Enterprise, o consulta los precios.