Variables de entorno

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, al que se llega a través de la RSFN. Configura estas variables en el momento del despliegue. Un cambio surte efecto solo después de reiniciar el servicio. La mayoría de las variables son específicas de este riel. Para los parámetros que se comportan igual en todos los servicios Go de Lerian (postura de despliegue, almacenes de datos, multi-tenancy y telemetría), consulta Fundamentos de configuración de BYOC. En las tablas siguientes, Obligatorio marca una variable que debes configurar, de forma global o bajo la condición indicada. Un calificador como En production o Si está habilitado acota cuándo se aplica el requisito. — significa que no hay un valor predeterminado.

ENV_NAME activa las barreras de seguridad más estrictas. Configúralo como production o staging y el servicio exige TLS en Redis, RabbitMQ y la conexión STR. También requiere un backend de custodia de firma respaldado por hardware y rechaza las superficies exclusivas de desarrollo. ENV_NAME no tiene un valor predeterminado. Configúralo explícitamente. El servicio se niega a empezar cuando ENV_NAME no está configurado o contiene un valor no reconocido.

Runtime y servidor

Variable	Descripción	Predeterminado	Obligatorio
`ENV_NAME`	Entorno de runtime. Debe ser uno de `production`, `staging` o `develop`. Production y staging activan las barreras de seguridad descritas antes.	—	Sí
`SERVICE_NAME`	Identificador del servicio usado en logs y telemetría.	Predeterminado del servicio	No
`LOG_LEVEL`	Nivel de detalle del log (`debug`, `info`, `warn`, `error`).	`info`	No
`SERVER_PORT`	Puerto de escucha HTTP. Las superficies de liveness, readiness y systemplane se vinculan a este mismo puerto.	`3000`	No
`CORS_ALLOWED_ORIGINS`	Orígenes CORS permitidos, separados por comas. En production/staging, solo se aceptan orígenes `https://` y se rechazan los orígenes localhost.	`http://localhost:3000`	No
`TRUSTED_PROXIES`	IPs/CIDRs de proxy, separados por comas, autorizados para 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 Fundamentos de configuración de BYOC.

Variable	Descripción	Predeterminado	Obligatorio
`PLUGIN_AUTH_ENABLED`	Requiere autenticación de Access Manager en las rutas protegidas.	`true`	No
`PLUGIN_AUTH_ADDRESS`	Dirección del servicio de Access Manager.	`http://localhost:4000`	Si está habilitado

PostgreSQL

Variable	Descripción	Predeterminado	Obligatorio
`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 incluyas en un commit.	—	En production/staging
`POSTGRES_DB`	Nombre de la base de datos.	—	Sí
`POSTGRES_SSLMODE`	Modo TLS de libpq. Debe ser `verify-full` en production/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, por ejemplo `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 al primario cuando no están configurados.

Variable	Descripción	Predeterminado	Obligatorio
`POSTGRES_REPLICA_HOST`	Host de la réplica. Sin configurar = 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 production/staging cuando se configura una réplica.	—	No

Redis

Variable	Descripción	Predeterminado	Obligatorio
`REDIS_HOST`	Host de Redis. Debe ser explícito y no local en production/staging.	`localhost`	En production/staging
`REDIS_PORT`	Puerto de Redis.	`6379`	No
`REDIS_PASSWORD`	Contraseña de Redis. Sensible.	—	En production/staging
`REDIS_DB`	Número de base de datos de Redis.	`0`	No
`REDIS_TLS_ENABLED`	Habilita TLS hacia Redis. Debe ser `true` en production/staging.	`false`	En production/staging
`REDIS_TLS_CA_CERT_BASE64`	Certificado de CA codificado en Base64 para TLS de Redis. Obligatorio cuando `REDIS_TLS_ENABLED=true` en production/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 usando un transporte IBM MQ. Estas variables definen la identidad del participante, la conexión al gestor de colas y las colas.

Variable	Descripción	Predeterminado	Obligatorio
`STR_ISPB`	El ISPB de 8 dígitos del participante. En production/staging debe ser un ISPB real explícito, no `00000000`.	`00000000`	En production/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 proporcionado por el cliente. En production/staging debe ser un ISPB de câmara de 8 dígitos explícito, 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 conexión de MQ.	`app`	No
`STR_MQ_PASSWORD`	Contraseña de conexión de MQ. Sensible.	—	En production/staging
`STR_MQ_TLS_ENABLED`	Habilita TLS mutuo en el canal de MQ. Obligatorio para una conexión STR real.	`false`	En production/staging
`MQSSLKEYR`	Ruta al repositorio de claves de GSKit que respalda TLS de MQ. La clave privada vive 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 está configurada.	Derivado	No
`STR_MQ_RESPONSE_QUEUE`	Cola de respuestas. Se deriva de `STR_ISPB` cuando no está configurada.	Derivado	No
`STR_MQ_RECEIVE_QUEUE`	Cola de recepción entrante. Se deriva de `STR_ISPB` cuando no está configurada.	Derivado	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 secuencia de mensajes para el canal de MQ.	`99999999`	No
`MQ_ADOPTNEWMCA`	Configuración `AdoptNewMCA` del canal de MQ.	`ALL`	No

Circuit breaker

Protege el transporte STR frente a un gestor de colas con fallas.

Variable	Descripción	Predeterminado	Obligatorio
`CB_MAX_REQUESTS`	Solicitudes permitidas mientras el breaker está en half-open.	`3`	No
`CB_INTERVAL`	Ventana móvil sobre la que se cuentan las fallas (duración de Go).	`30s`	No
`CB_TIMEOUT`	Tiempo de espera de recuperación del estado open (duración de Go).	`10s`	No
`CB_CONSECUTIVE_FAILURES`	Fallas consecutivas antes de que el breaker se dispare.	`5`	No
`CB_FAILURE_RATIO`	Proporción de fallas que dispara el breaker (0-1).	`0.5`	No
`CB_MIN_REQUESTS`	Mínimo de solicitudes 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. Production y staging rechazan el backend file y requieren una clave respaldada por hardware (pkcs11 o kmip).

Variable	Descripción	Predeterminado	Obligatorio
`SPB_SIGNER_KIND`	Backend de custodia de firma: `file`, `pkcs11` o `kmip`. `file` solo se permite cuando `ENV_NAME=develop`; production 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 production/staging
`KEY_PATH`	Ruta a la clave privada de firma.	—	En production/staging
`PROCESS_CERT_PATH`	Ruta al certificado de proceso/TLS.	—	En production/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 de SFN.	—	En production/staging
`CERT_READINESS_MIN_DAYS`	Días mínimos hasta el vencimiento antes de que la verificación de readiness del certificado reporte degradado.	`30`	No

Custodia PKCS#11

Obligatorio cuando SPB_SIGNER_KIND=pkcs11.

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

Custodia KMIP

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

Variable	Descripción	Predeterminado	Obligatorio
`SPB_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si es `kmip`
`SPB_KMIP_VHSM`	Identificador del HSM virtual.	—	Si es `kmip`
`SPB_KMIP_CRYPTO_USER`	Usuario criptográfico de KMIP.	—	Si es `kmip`
`SPB_KMIP_CRYPTO_USER_TOKEN`	Token de usuario criptográfico de KMIP. Sensible.	—	Si es `kmip`
`SPB_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si es `kmip`
`SPB_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si es `kmip`
`SPB_KMIP_DECRYPT_KEY_UID`	UID de la clave de descifrado usada en la ruta de descifrado entrante.	—	No
`SPB_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP.	`false`	No

Eventos, outbox y RabbitMQ

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

Variable	Descripción	Predeterminado	Obligatorio
`EMISSION_REQUIRED`	Cuando es `true`, el arranque falla de forma cerrada a menos que la emisión de eventos esté completamente configurada.	`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` predeterminado en production/staging.	`guest`	En production/staging
`RABBITMQ_PASSWORD`	Contraseña de RabbitMQ. Sensible. No debe estar vacía ni ser la predeterminada en production/staging.	`guest`	En production/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 TLS hacia RabbitMQ. Debe ser `true` en production/staging cuando se configura un host.	`false`	En production/staging
`OUTBOX_DISPATCH_INTERVAL`	Intervalo entre ciclos de envío del outbox (duración de Go).	`2s`	No
`OUTBOX_BATCH_SIZE`	Filas drenadas por ciclo de envío.	`50`	No
`OUTBOX_MAX_PUBLISH_ATTEMPTS`	Máximo de intentos de reintento del publicador de RabbitMQ para cada llamada de publicación. El agotamiento de la 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 que un evento quede retenido.	`3`	No
`EVENT_DELIVERY_RETRY_BACKOFF`	Backoff base entre reintentos de entrega (duración de Go).	`30s`	No
`DISPATCH_MAX_AUTO_ATTEMPTS`	Intentos de envío automático antes de la intervención manual.	`8`	No
`DISPATCH_RETRY_BACKOFF_CEILING`	Backoff máximo entre reintentos de envío (duración de Go).	`30m`	No
`LDL_ADVISORY_CONSUMER_ENABLED`	Habilita el consumidor supervisado de los datos informativos de liquidación OT de SILOC. Requiere `STREAMING_BROKERS` y persistencia duradera cuando está habilitado, y se niega a empezar sin ellos. El tema y el grupo del consumidor están fijos en el servicio; ninguno de los dos es configurable a través del entorno. La conexión al broker proviene de la configuración compartida `STREAMING_*` (consulta Streaming y outbox). Deshabilitado, su verificación de readiness reporta `skipped`.	`false`	No

Aprobación (maker-checker)

Aprobación opcional por banda de valor que condiciona la emisión de STR. Deshabilitada de forma predeterminada. Una tabla de bandas vacía deja que toda emisión avance en un solo paso.

Variable	Descripción	Predeterminado	Obligatorio
`APPROVAL_ALCADA_BANDS`	Bandas `maxExclusive:requiredSignatures` separadas por punto y coma (por ejemplo, `10000.00:1;100000.00:2`). Vacío mantiene la aprobación deshabilitada.	—	No
`APPROVAL_DEADLINE_WINDOW`	Cuánto tiempo puede esperar una emisión retenida (duración de Go, con un límite de 7 días).	`24h`	No
`APPROVAL_EXPIRY_ENABLED`	Ejecuta el barrido en segundo plano que vence las emisiones retenidas vencidas.	`true`	No
`APPROVAL_EXPIRY_SWEEP_INTERVAL`	Intervalo del barrido (duración de Go).	`1m`	No

Rate limiting e idempotencia

Variable	Descripción	Predeterminado	Obligatorio
`RATE_LIMIT_IP_MAX`	Máximo de solicitudes por IP y por ventana.	`300`	No
`RATE_LIMIT_IP_WINDOW`	Ventana de rate limit por IP (duración de Go).	`1m`	No
`RATE_LIMIT_KEY_MAX`	Máximo de solicitudes por clave de API y por ventana.	`100`	No
`RATE_LIMIT_KEY_WINDOW`	Ventana de rate limit 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 (en segundos) se conserva una clave de idempotencia.	`300`	No

Systemplane y configuración en runtime

Lerian SPB monta la API de administración de configuración en runtime de systemplane en /v1/system en el puerto principal. PostgreSQL respalda este plano, de modo que los operadores pueden leer y cambiar la configuración recargable en caliente sin un reinicio. Consulta Systemplane para conocer la API, los namespaces y los permisos.

Variable	Descripción	Predeterminado	Obligatorio
`SYSTEMPLANE_LISTEN_CHANNEL`	Canal `LISTEN`/`NOTIFY` de PostgreSQL al que se suscribe el plano de configuración en runtime para los cambios de configuración en caliente.	Predeterminado del servicio	No

Cifrado y secretos

Variable	Descripción	Predeterminado	Obligatorio
`STR_PAYLOAD_ENCRYPTION_KEY`	Clave AES-256 codificada en Base64 para el cifrado en reposo de los payloads STR almacenados. Sensible. Obligatoria en production/staging.	—	En production/staging
`WEBHOOK_SECRET_KEY`	Clave usada para cifrar los secretos de webhook almacenados. Sensible. Obligatoria en production/staging.	—	En production/staging
`INBOUND_ALLOW_CLEARTEXT_FALLBACK`	Permite que la ruta entrante acepte payloads sin cifrar. Deja `false` en production y staging.	`false`	No

Nunca subas a un commit ni registres en logs los valores de ninguna variable marcada como Sensible (contraseñas, tokens, PINs y claves AES). Inyéctalas en el momento del despliegue a través de tu gestor de secretos.

Observabilidad

Variable	Descripción	Predeterminado	Obligatorio
`ENABLE_TELEMETRY`	Habilita el trazado y las métricas de OpenTelemetry.	`false`	En production/staging
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del colector OTLP. Debe usar `https://` en production/staging.	`http://localhost:4318`	Si la telemetría está habilitada
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio adjunto a la telemetría exportada.	Predeterminado del servicio	No
`METRICS_PROMETHEUS_ENABLED`	Expone un endpoint de scraping de Prometheus dedicado.	`false`	No
`METRICS_PROMETHEUS_ADDRESS`	Dirección de escucha para el endpoint de Prometheus. Se vincula a loopback de forma predeterminada.	`127.0.0.1:9090`	No

Solo para desarrollo

Mantén estas variables sin configurar fuera del desarrollo local. Amplían la superficie de ataque, y production o staging las rechaza o las fuerza a estar deshabilitadas.

Variable	Descripción	Predeterminado	Obligatorio
`ENABLE_DEV_DEBUG_ROUTES`	Expone las rutas de depuración. Prohibido en production/staging.	`false`	No
`DEV_DEBUG_TOKEN`	Token que protege las rutas de depuración. Sensible. Obligatorio cuando las rutas de depuración están habilitadas.	—	Si la depuración está habilitada
`SWAGGER_ENABLED`	Sirve la especificación OpenAPI y la interfaz de documentación de la API. Forzado a deshabilitado en production y staging.	`false`	No
`STR_MQ_MOCK`	Enruta el transporte STR hacia un mock en lugar de un gestor de colas en vivo.	`false`	No
`STR_MQ_MOCK_HOST`	Host del mock de STR. Obligatorio cuando `STR_MQ_MOCK=true`.	`http://localhost:8080`	Si el mock está habilitado
`STR_MQ_MOCK_ALLOWED_HOSTS`	Lista de hosts permitidos que el transporte mock puede alcanzar.	—	No
`ALLOW_MOCK_TRANSPORT`	Permite que el transporte mock se pueda seleccionar.	`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 conocer el contrato de las sondas.

​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)

​Rate limiting e idempotencia

​Systemplane y configuración en runtime

​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)

Rate limiting e idempotencia

Systemplane y configuración en runtime

Cifrado y secretos

Observabilidad

Solo para desarrollo

Salud y readiness