> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/es/reference/byoc-configuration).
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](/es/reference/byoc-configuration#autenticación-de-plugins).
| 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](/es/reference/byoc-configuration#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](/es/reference/systemplane/overview) 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](/es/reference/health-and-readiness) para el contrato de las sondas.