Variables de entorno

Variables de entorno de despliegue para Lerian SPB: runtime, conectividad STR/RSFN, firma de mensajes y certificados, persistencia, eventos y seguridad.

Lerian SPB es la integración de mensajería nativa de Lerian para el STR (Sistema de Transferência de Reservas), el sistema de liquidación bruta en tiempo real de BACEN, alcanzado a través de la RSFN. Define estas variables en el momento del despliegue. Un cambio surte efecto solo después de que reinicies el servicio. La mayoría de las variables 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 y telemetría— consulta la referencia de configuración BYOC.

En las tablas siguientes, Requerida marca una variable que debes definir —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.

ENV_NAME arma los controles de seguridad más estrictos. Defínelo como production o staging y el servicio impone TLS en Redis, RabbitMQ y la conexión STR. También exige un backend de custodia de firma respaldado por hardware y rechaza las superficies exclusivas de desarrollo. ENV_NAME no tiene valor por defecto. Defínelo de forma explícita. El servicio se niega a arrancar cuando ENV_NAME 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. Debe ser verify-full en producción/staging.	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. Debe ser verify-full en producción/staging cuando se define una 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
SILOC_ISPB	El ISPB de 8 dígitos de la cámara SILOC, resuelto en el servidor para los mensajes de liquidación relacionados con SILOC — nunca lo proporciona el cliente. En producción/staging debe ser un ISPB de cámara explícito de 8 dígitos, no 00000000.	02992335	No
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.	app	No
STR_MQ_PASSWORD	Contraseña de la conexión MQ. Sensible.	—	En producción/staging
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

Lerian SPB firma cada mensaje STR. Elige el backend de custodia de claves con SPB_SIGNER_KIND. Producción y staging rechazan el backend file 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 se permite solo cuando ENV_NAME=develop; producción y staging lo rechazan. (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.	—	En producción/staging
KEY_PATH	Ruta a la clave privada de firma.	—	En producción/staging
PROCESS_CERT_PATH	Ruta al certificado de proceso/TLS.	—	En producción/staging
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 y para el cifrado SFN.	—	En producción/staging
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 usada en la vía de descifrado entrante.	—	No
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	Máximo de reintentos del publicador de RabbitMQ por cada llamada de publicación. El agotamiento de entrega de webhooks se rige por separado mediante EVENT_DELIVERY_MAX_ATTEMPTS.	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
LDL_ADVISORY_CONSUMER_ENABLED	Habilita el consumidor supervisado de hechos de avisos de liquidación OT de SILOC. Requiere STREAMING_BROKERS y persistencia durable cuando está habilitado, y se niega a arrancar sin ellos. El tópico y el grupo del consumidor son fijos en el servicio; ninguno se configura por el entorno. La conexión con los brokers proviene de la configuración compartida STREAMING_* (consulta Streaming y outbox). Deshabilitado, su comprobación de readiness informa skipped.	false	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. PostgreSQL respalda este plano, 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 y staging.	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	En producción/staging
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint del colector OTLP. Debe usar https:// en producción/staging.	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

Mantén estas variables sin definir fuera del desarrollo local. Amplían la superficie de ataque, y producción o staging las rechaza o las fuerza a desactivarse.

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 y staging.	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.