Variables de entorno

Lerian SPB es la integración de mensajería nativa de Lerian para el STR (Sistema de Transferência de Reservas), que alcanza el sistema de liquidación bruta en tiempo real de BACEN a través de la RSFN. Las variables siguientes se definen en el momento del despliegue y requieren reiniciar el servicio para surtir efecto. La mayoría son específicas de este rail; para los ajustes que se comportan igual en todos los servicios Go de Lerian —postura de despliegue, almacenes de datos, multi-tenancy, telemetría— consulta la referencia de configuración BYOC. En las tablas siguientes, Requerida marca una variable que debe definirse (de forma global o bajo la condición indicada). Un calificador como En producción o Si está habilitada precisa cuándo se aplica el requisito. — significa que no hay valor por defecto.

Lerian SPB activa sus controles de seguridad más estrictos a partir de ENV_NAME: cuando se define como production o staging, el TLS pasa a ser obligatorio en Redis, RabbitMQ y la conexión STR, la firma de mensajes debe usar un backend de custodia respaldado por hardware y las superficies exclusivas de desarrollo se rechazan. ENV_NAME no tiene valor por defecto: defínelo de forma explícita; el servicio se niega a arrancar si está sin definir o tiene un valor no reconocido.

Runtime y servidor

Variable	Descripción	Valor por defecto	Requerida
`ENV_NAME`	Entorno de runtime. Debe ser uno de `production`, `staging` o `develop`. `production` y `staging` activan los controles de seguridad descritos arriba.	—	Sí
`SERVICE_NAME`	Identificador del servicio usado en los logs y la telemetría.	Valor por defecto del servicio	No
`LOG_LEVEL`	Verbosidad de los logs (`debug`, `info`, `warn`, `error`).	`info`	No
`SERVER_PORT`	Puerto de escucha HTTP. Las superficies de liveness, readiness y systemplane se enlazan a este mismo puerto.	`3000`	No
`CORS_ALLOWED_ORIGINS`	Orígenes CORS permitidos, separados por comas. En producción/staging solo se aceptan orígenes `https://` y se rechazan los orígenes de localhost.	`http://localhost:3000`	No
`TRUSTED_PROXIES`	IPs/CIDR de proxy de confianza, separados por comas, autorizados a establecer la IP real del cliente.	—	No

Autenticación

Lerian SPB delega la autorización —incluida la API de administración de systemplane— en Access Manager. Consulta la referencia de configuración BYOC.

Variable	Descripción	Valor por defecto	Requerida
`PLUGIN_AUTH_ENABLED`	Exige autenticación de Access Manager en las rutas protegidas.	`true`	No
`PLUGIN_AUTH_ADDRESS`	Dirección del servicio Access Manager.	`http://localhost:4000`	Si está habilitada

PostgreSQL

Variable	Descripción	Valor por defecto	Requerida
`POSTGRES_HOST`	Host principal de PostgreSQL.	`localhost`	Sí
`POSTGRES_PORT`	Puerto principal de PostgreSQL.	`5432`	No
`POSTGRES_USER`	Usuario de la base de datos.	—	Sí
`POSTGRES_PASSWORD`	Contraseña de la base de datos. Sensible: inyéctala en el momento del despliegue; nunca la guardes en el repositorio.	—	En producción/staging
`POSTGRES_DB`	Nombre de la base de datos.	—	Sí
`POSTGRES_SSLMODE`	Modo TLS de libpq. Usa `require` o más estricto en producción.	`require`	No
`POSTGRES_MAX_OPEN_CONNS`	Máximo de conexiones abiertas.	`25`	No
`POSTGRES_MAX_IDLE_CONNS`	Máximo de conexiones inactivas.	`10`	No
`POSTGRES_CONN_MAX_LIFETIME`	Vida máxima de la conexión (duración de Go, p. ej. `5m`).	`5m`	No
`POSTGRES_CONN_MAX_IDLE_TIME`	Tiempo máximo de inactividad de la conexión (duración de Go).	`2m`	No

Réplica de PostgreSQL

Réplica de lectura opcional. Todos los campos recurren a la primaria cuando no se definen.

Variable	Descripción	Valor por defecto	Requerida
`POSTGRES_REPLICA_HOST`	Host de la réplica. Sin definir = sin réplica.	—	No
`POSTGRES_REPLICA_PORT`	Puerto de la réplica.	—	No
`POSTGRES_REPLICA_USER`	Usuario de la réplica.	—	No
`POSTGRES_REPLICA_PASSWORD`	Contraseña de la réplica. Sensible.	—	No
`POSTGRES_REPLICA_DB`	Nombre de la base de datos de la réplica.	—	No
`POSTGRES_REPLICA_SSLMODE`	Modo TLS de la réplica.	—	No

Redis

Variable	Descripción	Valor por defecto	Requerida
`REDIS_HOST`	Host de Redis. Debe ser explícito y no local en producción/staging.	`localhost`	En producción/staging
`REDIS_PORT`	Puerto de Redis.	`6379`	No
`REDIS_PASSWORD`	Contraseña de Redis. Sensible.	—	En producción/staging
`REDIS_DB`	Número de base de datos de Redis.	`0`	No
`REDIS_TLS_ENABLED`	Habilita el TLS hacia Redis. Debe ser `true` en producción/staging.	`false`	En producción/staging
`REDIS_TLS_CA_CERT_BASE64`	Certificado CA codificado en Base64 para el TLS de Redis. Requerido cuando `REDIS_TLS_ENABLED=true` en producción/staging.	—	Si TLS está habilitado
`REDIS_POOL_SIZE`	Tamaño del pool de conexiones.	`20`	No
`REDIS_MIN_IDLE_CONNS`	Mínimo de conexiones inactivas.	`5`	No

Conectividad STR (RSFN)

Lerian SPB intercambia mensajes STR con BACEN a través de la RSFN mediante un transporte IBM MQ. Estas variables definen la identidad del participante, la conexión al gestor de colas y las colas.

Variable	Descripción	Valor por defecto	Requerida
`STR_ISPB`	El ISPB de 8 dígitos del participante. En producción/staging debe ser un ISPB real explícito, no `00000000`.	`00000000`	En producción/staging
`STR_MQ_HOST`	Host del gestor de colas.	—	Sí (STR en vivo)
`STR_MQ_PORT`	Puerto de escucha del gestor de colas.	`1414`	No
`STR_MQ_CHANNEL`	Canal de conexión de servidor de MQ.	`DEV.APP.SVRCONN`	No
`STR_MQ_QUEUE_MGR`	Nombre del gestor de colas.	`QM1`	No
`STR_MQ_USER`	Usuario de la conexión MQ.	—	No
`STR_MQ_PASSWORD`	Contraseña de la conexión MQ. Sensible.	—	No
`STR_MQ_TLS_ENABLED`	Habilita el TLS mutuo en el canal MQ. Requerido para una conexión STR real.	`false`	En producción/staging
`MQSSLKEYR`	Ruta al repositorio de claves GSKit que respalda el TLS de MQ. La clave privada reside aquí, nunca en una variable de entorno.	—	Si TLS está habilitado
`STR_MQ_SEND_QUEUE`	Cola de solicitudes salientes. Se deriva de `STR_ISPB` cuando no se define.	Derivada	No
`STR_MQ_RESPONSE_QUEUE`	Cola de respuestas. Se deriva de `STR_ISPB` cuando no se define.	Derivada	No
`STR_MQ_RECEIVE_QUEUE`	Cola de recepción entrante. Se deriva de `STR_ISPB` cuando no se define.	Derivada	No
`MQ_HEARTBEAT_INTERVAL`	Intervalo de heartbeat de MQ (duración de Go).	`300s`	No
`MQ_DISCONNECT_INTERVAL`	Intervalo de desconexión de MQ (duración de Go).	`6000s`	No
`MQ_SEQ_WRAP`	Techo de reinicio de la secuencia de mensajes para el canal MQ.	`99999999`	No
`MQ_ADOPTNEWMCA`	Ajuste `AdoptNewMCA` del canal MQ.	`ALL`	No

Circuit breaker

Protege el transporte STR frente a un gestor de colas que falla.

Variable	Descripción	Valor por defecto	Requerida
`CB_MAX_REQUESTS`	Peticiones permitidas mientras el breaker está en estado semiabierto.	`3`	No
`CB_INTERVAL`	Ventana móvil en la que se cuentan los fallos (duración de Go).	`30s`	No
`CB_TIMEOUT`	Tiempo de recuperación del estado abierto (duración de Go).	`10s`	No
`CB_CONSECUTIVE_FAILURES`	Fallos consecutivos antes de que el breaker se dispare.	`5`	No
`CB_FAILURE_RATIO`	Proporción de fallos que dispara el breaker (0–1).	`0.5`	No
`CB_MIN_REQUESTS`	Mínimo de peticiones en una ventana antes de que el breaker pueda dispararse.	`10`	No

Firma de mensajes y certificados

Los mensajes STR se firman digitalmente. Elige un backend de custodia con SPB_SIGNER_KIND; producción y staging rechazan el backend de archivo y requieren una clave respaldada por hardware (pkcs11 o kmip).

Variable	Descripción	Valor por defecto	Requerida
`SPB_SIGNER_KIND`	Backend de custodia de firma: `file`, `pkcs11` o `kmip`. `file` es solo para desarrollo/homologación: se rechaza en producción/staging. (`hsm` y `kms` están declarados pero no implementados.)	`file`	No
`CERT_BASE_PATH`	Directorio base para el material de certificados.	`/certs`	No
`CERT_PATH`	Ruta al certificado de firma.	—	No
`KEY_PATH`	Ruta a la clave privada de firma (solo backend de archivo).	—	Si `file`
`PROCESS_CERT_PATH`	Ruta al certificado de proceso/TLS.	—	No
`PROCESS_PRIVATE_KEY_PATH`	Ruta a la clave privada de proceso/TLS. Sensible.	—	No
`BACEN_PUBLIC_CERT_PATH`	Ruta al certificado público de BACEN, usado para verificar las firmas entrantes.	—	No
`CERT_READINESS_MIN_DAYS`	Días mínimos hasta la expiración antes de que la comprobación de readiness del certificado informe `degraded`.	`30`	No

Custodia PKCS#11

Requerido cuando SPB_SIGNER_KIND=pkcs11.

Variable	Descripción	Valor por defecto	Requerida
`SPB_PKCS11_MODULE_PATH`	Ruta a la biblioteca del módulo PKCS#11.	—	Si `pkcs11`
`SPB_PKCS11_TOKEN_LABEL`	Etiqueta del token PKCS#11.	—	Si `pkcs11`
`SPB_PKCS11_PIN_FILE`	Ruta a un archivo que contiene el PIN del token. Sensible.	—	Si `pkcs11`
`SPB_PKCS11_KEY_LABEL`	Etiqueta de la clave de firma en el token.	—	Si `pkcs11`

Custodia KMIP

Requerido cuando SPB_SIGNER_KIND=kmip (KMIP sobre HTTP hacia un HSM de red).

Variable	Descripción	Valor por defecto	Requerida
`SPB_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si `kmip`
`SPB_KMIP_VHSM`	Identificador del HSM virtual.	—	Si `kmip`
`SPB_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si `kmip`
`SPB_KMIP_CRYPTO_USER_TOKEN`	Token del usuario cripto de KMIP. Sensible.	—	Si `kmip`
`SPB_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si `kmip`
`SPB_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si `kmip`
`SPB_KMIP_DECRYPT_KEY_UID`	UID de la clave de descifrado.	—	Si `kmip`
`SPB_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP.	`false`	No

Eventos, outbox y RabbitMQ

Lerian SPB registra cada mensaje antes de despacharlo y publica eventos de ciclo de vida hacia RabbitMQ a través de un outbox transaccional.

Variable	Descripción	Valor por defecto	Requerida
`EMISSION_REQUIRED`	Cuando es `true`, el arranque falla de forma cerrada salvo que la emisión de eventos esté completamente cableada.	`false`	No
`RABBITMQ_HOST`	Host de RabbitMQ.	—	Sí (eventos)
`RABBITMQ_PORT`	Puerto de RabbitMQ.	`5672`	No
`RABBITMQ_USER`	Usuario de RabbitMQ. No debe ser el `guest` por defecto en producción/staging.	`guest`	En producción/staging
`RABBITMQ_PASSWORD`	Contraseña de RabbitMQ. Sensible. No debe estar vacía ni ser la de por defecto en producción/staging.	`guest`	En producción/staging
`RABBITMQ_VHOST`	Host virtual de RabbitMQ.	`/`	No
`RABBITMQ_STR_EXCHANGE`	Nombre del exchange para los eventos de ciclo de vida de STR.	`str.events`	No
`RABBITMQ_TLS_ENABLED`	Habilita el TLS hacia RabbitMQ. Debe ser `true` en producción/staging cuando se define un host.	`false`	En producción/staging
`OUTBOX_DISPATCH_INTERVAL`	Intervalo entre ciclos de despacho del outbox (duración de Go).	`2s`	No
`OUTBOX_BATCH_SIZE`	Filas drenadas por ciclo de despacho.	`50`	No
`OUTBOX_MAX_PUBLISH_ATTEMPTS`	Intentos de publicación antes de aparcar un evento.	`3`	No
`OUTBOX_POSTGRES_MAX_OPEN_CONNS`	Máximo de conexiones abiertas para el pool del outbox.	`10`	No
`OUTBOX_POSTGRES_MAX_IDLE_CONNS`	Máximo de conexiones inactivas para el pool del outbox.	`5`	No
`EVENT_DELIVERY_BATCH_SIZE`	Eventos entregados por ciclo.	`25`	No
`EVENT_DELIVERY_MAX_ATTEMPTS`	Intentos de entrega antes de aparcar un evento.	`3`	No
`EVENT_DELIVERY_RETRY_BACKOFF`	Backoff base entre reintentos de entrega (duración de Go).	`30s`	No
`DISPATCH_MAX_AUTO_ATTEMPTS`	Intentos de despacho automático antes de la intervención manual.	`8`	No
`DISPATCH_RETRY_BACKOFF_CEILING`	Backoff máximo entre reintentos de despacho (duración de Go).	`30m`	No

Aprobación (maker-checker)

Aprobación opcional por bandas de valor que controla la emisión STR. Desactivada por defecto: una tabla de bandas vacía permite que cada emisión avance en un solo paso.

Variable	Descripción	Valor por defecto	Requerida
`APPROVAL_ALCADA_BANDS`	Bandas `maxExclusive:requiredSignatures` separadas por punto y coma (p. ej. `10000.00:1;100000.00:2`). Vacío mantiene la aprobación desactivada.	—	No
`APPROVAL_DEADLINE_WINDOW`	Cuánto tiempo puede esperar una emisión aparcada (duración de Go, con un tope de 7 días).	`24h`	No
`APPROVAL_EXPIRY_ENABLED`	Ejecuta el barrido en segundo plano que expira las emisiones aparcadas vencidas.	`true`	No
`APPROVAL_EXPIRY_SWEEP_INTERVAL`	Intervalo del barrido (duración de Go).	`1m`	No

Limitación de tasa e idempotencia

Variable	Descripción	Valor por defecto	Requerida
`RATE_LIMIT_IP_MAX`	Máximo de peticiones por IP por ventana.	`300`	No
`RATE_LIMIT_IP_WINDOW`	Ventana de limitación de tasa por IP (duración de Go).	`1m`	No
`RATE_LIMIT_KEY_MAX`	Máximo de peticiones por clave de API por ventana.	`100`	No
`RATE_LIMIT_KEY_WINDOW`	Ventana de limitación de tasa por clave (duración de Go).	`1m`	No
`IDEMPOTENCY_ENABLED`	Habilita la deduplicación por clave de idempotencia.	`true`	No
`IDEMPOTENCY_DEFAULT_TTL_SEC`	Cuánto tiempo (segundos) se conserva una clave de idempotencia.	`300`	No

Systemplane y configuración en tiempo de ejecución

Lerian SPB monta la API de administración de configuración en tiempo de ejecución de systemplane en /v1/system en el puerto principal; está respaldada por PostgreSQL, de modo que los operadores pueden leer y cambiar los ajustes recargables en caliente sin reiniciar. Consulta Systemplane para la API, los espacios de nombres y los permisos.

Variable	Descripción	Valor por defecto	Requerida
`SYSTEMPLANE_LISTEN_CHANNEL`	Canal `LISTEN`/`NOTIFY` de PostgreSQL al que el plano de configuración en tiempo de ejecución se suscribe para los cambios de configuración en caliente.	Valor por defecto del servicio	No

Cifrado y secretos

Variable	Descripción	Valor por defecto	Requerida
`STR_PAYLOAD_ENCRYPTION_KEY`	Clave AES-256 codificada en Base64 para el cifrado en reposo de los payloads STR almacenados. Sensible. Requerida en producción/staging.	—	En producción/staging
`WEBHOOK_SECRET_KEY`	Clave usada para cifrar los secretos de webhook almacenados. Sensible. Requerida en producción/staging.	—	En producción/staging
`INBOUND_ALLOW_CLEARTEXT_FALLBACK`	Permite que la vía entrante acepte payloads sin cifrar. Déjala en `false` en producción.	`false`	No

Nunca guardes en el repositorio ni registres en logs los valores de ninguna variable marcada como Sensible (contraseñas, tokens, PIN y claves AES). Inyéctalos en el momento del despliegue mediante tu gestor de secretos.

Observabilidad

Variable	Descripción	Valor por defecto	Requerida
`ENABLE_TELEMETRY`	Habilita el tracing y las métricas de OpenTelemetry.	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del colector OTLP.	`http://localhost:4318`	Si la telemetría está habilitada
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio adjuntado a la telemetría exportada.	Valor por defecto del servicio	No
`METRICS_PROMETHEUS_ENABLED`	Expone un endpoint de scrape de Prometheus dedicado.	`false`	No
`METRICS_PROMETHEUS_ADDRESS`	Dirección de escucha del endpoint de Prometheus. Se enlaza a loopback por defecto.	`127.0.0.1:9090`	No

Solo para desarrollo

Estas variables amplían la superficie de ataque y se rechazan o se fuerzan a desactivarse en producción/staging. Mantenlas sin definir fuera del desarrollo local.

Variable	Descripción	Valor por defecto	Requerida
`ENABLE_DEV_DEBUG_ROUTES`	Expone rutas de depuración. Prohibido en producción/staging.	`false`	No
`DEV_DEBUG_TOKEN`	Token que protege las rutas de depuración. Sensible. Requerido cuando las rutas de depuración están habilitadas.	—	Si el debug está habilitado
`SWAGGER_ENABLED`	Sirve la especificación OpenAPI y la interfaz de documentación de la API. Se fuerza a desactivarse en producción.	`false`	No
`STR_MQ_MOCK`	Enruta el transporte STR a un mock en lugar de a un gestor de colas en vivo.	`false`	No
`STR_MQ_MOCK_HOST`	Host del mock de STR. Requerido cuando `STR_MQ_MOCK=true`.	`http://localhost:8080`	Si el mock está habilitado
`STR_MQ_MOCK_ALLOWED_HOSTS`	Lista de permitidos de hosts que el transporte mock puede alcanzar.	—	No
`ALLOW_MOCK_TRANSPORT`	Permite que el transporte mock pueda seleccionarse siquiera.	`false`	No

Salud y readiness

Lerian SPB expone GET /health (liveness) y GET /readyz (readiness) en el puerto HTTP principal. Consulta Salud y readiness para el contrato de las sondas.

Resumen

Lerian SPB

Lerian SPI

Lerian SILOC

Lerian SLC

Lerian STA

Lerian SISBAJUD

Lerian Consignado — Dataprev

Variables de entorno

Runtime y servidor

Autenticación

PostgreSQL

Réplica de PostgreSQL

Redis

Conectividad STR (RSFN)

Circuit breaker

Firma de mensajes y certificados

Custodia PKCS#11

Custodia KMIP

Eventos, outbox y RabbitMQ

Aprobación (maker-checker)

Limitación de tasa e idempotencia

Systemplane y configuración en tiempo de ejecución

Cifrado y secretos

Observabilidad

Solo para desarrollo

Salud y readiness

​Runtime y servidor

​Autenticación

​PostgreSQL

​Réplica de PostgreSQL

​Redis

​Conectividad STR (RSFN)

​Circuit breaker

​Firma de mensajes y certificados

​Custodia PKCS#11

​Custodia KMIP

​Eventos, outbox y RabbitMQ

​Aprobación (maker-checker)

​Limitación de tasa e idempotencia

​Systemplane y configuración en tiempo de ejecución

​Cifrado y secretos

​Observabilidad

​Solo para desarrollo

​Salud y readiness

Runtime y servidor

Autenticación

PostgreSQL

Réplica de PostgreSQL

Redis

Conectividad STR (RSFN)

Circuit breaker

Firma de mensajes y certificados

Custodia PKCS#11

Custodia KMIP

Eventos, outbox y RabbitMQ

Aprobación (maker-checker)

Limitación de tasa e idempotencia

Systemplane y configuración en tiempo de ejecución

Cifrado y secretos

Observabilidad

Solo para desarrollo

Salud y readiness