Variáveis de ambiente

O Lerian SPB é a integração de mensageria nativa da Lerian para o STR (Sistema de Transferência de Reservas), o sistema de liquidação bruta em tempo real do BACEN, alcançado sobre a RSFN. Defina estas variáveis no momento do deploy. Uma alteração entra em vigor somente depois que você reinicia o serviço. A maioria das variáveis é específica deste rail. Para os parâmetros que se comportam da mesma forma em todos os serviços Go da Lerian — postura de deployment, datastores, multi-tenancy e telemetria — consulte a referência de configuração BYOC. Nas tabelas abaixo, Obrigatória marca uma variável que você deve definir — globalmente, ou sob a condição indicada. Um qualificador como Em produção ou Se habilitado restringe quando a exigência se aplica. — significa que não há padrão.

ENV_NAME arma os controles de segurança mais estritos. Defina-o como production ou staging e o serviço impõe TLS no Redis, no RabbitMQ e na conexão STR. Ele também exige um backend de custódia de assinatura baseado em hardware e rejeita as superfícies exclusivas de desenvolvimento. ENV_NAME não tem padrão. Defina-o explicitamente. O serviço se recusa a iniciar quando ENV_NAME está sem definição ou tem um valor não reconhecido.

Runtime e servidor

Variável	Descrição	Padrão	Obrigatória
`ENV_NAME`	Ambiente de runtime. Deve ser um de `production`, `staging` ou `develop`. Production e staging armam os controles de segurança descritos acima.	—	Sim
`SERVICE_NAME`	Identificador de serviço usado em logs e telemetria.	Padrão do serviço	Não
`LOG_LEVEL`	Verbosidade dos logs (`debug`, `info`, `warn`, `error`).	`info`	Não
`SERVER_PORT`	Porta de escuta HTTP. As superfícies de liveness, readiness e systemplane se vinculam a essa mesma porta.	`3000`	Não
`CORS_ALLOWED_ORIGINS`	Origens CORS permitidas, separadas por vírgula. Em produção/staging, apenas origens `https://` são aceitas e origens localhost são rejeitadas.	`http://localhost:3000`	Não
`TRUSTED_PROXIES`	IPs/CIDRs de proxy, separados por vírgula, confiáveis para definir o IP real do cliente.	—	Não

Autenticação

O Lerian SPB delega a autorização — incluindo a API de administração do systemplane — ao Access Manager. Consulte a referência de configuração BYOC.

Variável	Descrição	Padrão	Obrigatória
`PLUGIN_AUTH_ENABLED`	Exige autenticação via Access Manager em rotas protegidas.	`true`	Não
`PLUGIN_AUTH_ADDRESS`	Endereço do serviço Access Manager.	`http://localhost:4000`	Se habilitado

PostgreSQL

Variável	Descrição	Padrão	Obrigatória
`POSTGRES_HOST`	Host primário do PostgreSQL.	`localhost`	Sim
`POSTGRES_PORT`	Porta primária do PostgreSQL.	`5432`	Não
`POSTGRES_USER`	Usuário do banco de dados.	—	Sim
`POSTGRES_PASSWORD`	Senha do banco de dados. Sensível — injete no momento do deploy; nunca faça commit.	—	Em produção/staging
`POSTGRES_DB`	Nome do banco de dados.	—	Sim
`POSTGRES_SSLMODE`	Modo TLS do libpq. Deve ser `verify-full` em produção/staging.	`require`	Não
`POSTGRES_MAX_OPEN_CONNS`	Máximo de conexões abertas.	`25`	Não
`POSTGRES_MAX_IDLE_CONNS`	Máximo de conexões ociosas.	`10`	Não
`POSTGRES_CONN_MAX_LIFETIME`	Tempo máximo de vida da conexão (duração Go, ex: `5m`).	`5m`	Não
`POSTGRES_CONN_MAX_IDLE_TIME`	Tempo máximo ocioso da conexão (duração Go).	`2m`	Não

Réplica PostgreSQL

Réplica de leitura opcional. Todos os campos usam o primário como fallback quando não definidos.

Variável	Descrição	Padrão	Obrigatória
`POSTGRES_REPLICA_HOST`	Host da réplica. Não definido = sem réplica.	—	Não
`POSTGRES_REPLICA_PORT`	Porta da réplica.	—	Não
`POSTGRES_REPLICA_USER`	Usuário da réplica.	—	Não
`POSTGRES_REPLICA_PASSWORD`	Senha da réplica. Sensível.	—	Não
`POSTGRES_REPLICA_DB`	Nome do banco da réplica.	—	Não
`POSTGRES_REPLICA_SSLMODE`	Modo TLS da réplica. Deve ser `verify-full` em produção/staging quando uma réplica está definida.	—	Não

Redis

Variável	Descrição	Padrão	Obrigatória
`REDIS_HOST`	Host do Redis. Deve ser explícito e não-local em produção/staging.	`localhost`	Em produção/staging
`REDIS_PORT`	Porta do Redis.	`6379`	Não
`REDIS_PASSWORD`	Senha do Redis. Sensível.	—	Em produção/staging
`REDIS_DB`	Número do banco de dados Redis.	`0`	Não
`REDIS_TLS_ENABLED`	Habilita TLS para o Redis. Deve ser `true` em produção/staging.	`false`	Em produção/staging
`REDIS_TLS_CA_CERT_BASE64`	Certificado CA codificado em base64 para o TLS do Redis. Obrigatório quando `REDIS_TLS_ENABLED=true` em produção/staging.	—	Se TLS habilitado
`REDIS_POOL_SIZE`	Tamanho do pool de conexões.	`20`	Não
`REDIS_MIN_IDLE_CONNS`	Mínimo de conexões ociosas.	`5`	Não

Conectividade STR (RSFN)

O Lerian SPB troca mensagens STR com o BACEN sobre a RSFN usando um transporte IBM MQ. Essas variáveis definem a identidade do participante, a conexão com o queue manager e as filas.

Variável	Descrição	Padrão	Obrigatória
`STR_ISPB`	O ISPB de 8 dígitos do participante. Em produção/staging deve ser um ISPB real explícito, não `00000000`.	`00000000`	Em produção/staging
`SILOC_ISPB`	O ISPB de 8 dígitos da câmara SILOC, resolvido no servidor para as mensagens de liquidação relacionadas ao SILOC — nunca fornecido pelo cliente. Em produção/staging deve ser um ISPB de câmara explícito de 8 dígitos, não `00000000`.	`02992335`	Não
`STR_MQ_HOST`	Host do queue manager.	—	Sim (STR real)
`STR_MQ_PORT`	Porta do listener do queue manager.	`1414`	Não
`STR_MQ_CHANNEL`	Canal de server-connection do MQ.	`DEV.APP.SVRCONN`	Não
`STR_MQ_QUEUE_MGR`	Nome do queue manager.	`QM1`	Não
`STR_MQ_USER`	Usuário da conexão MQ.	`app`	Não
`STR_MQ_PASSWORD`	Senha da conexão MQ. Sensível.	—	Em produção/staging
`STR_MQ_TLS_ENABLED`	Habilita TLS mútuo no canal MQ. Obrigatório para uma conexão STR real.	`false`	Em produção/staging
`MQSSLKEYR`	Caminho para o repositório de chaves GSKit que dá suporte ao TLS do MQ. A chave privada fica aqui, nunca em uma variável de ambiente.	—	Se TLS habilitado
`STR_MQ_SEND_QUEUE`	Fila de requisição de saída. Derivada de `STR_ISPB` quando não definida.	Derivado	Não
`STR_MQ_RESPONSE_QUEUE`	Fila de resposta. Derivada de `STR_ISPB` quando não definida.	Derivado	Não
`STR_MQ_RECEIVE_QUEUE`	Fila de recebimento de entrada. Derivada de `STR_ISPB` quando não definida.	Derivado	Não
`MQ_HEARTBEAT_INTERVAL`	Intervalo de heartbeat do MQ (duração Go).	`300s`	Não
`MQ_DISCONNECT_INTERVAL`	Intervalo de desconexão do MQ (duração Go).	`6000s`	Não
`MQ_SEQ_WRAP`	Teto de wrap da sequência de mensagens para o canal MQ.	`99999999`	Não
`MQ_ADOPTNEWMCA`	Configuração de canal `AdoptNewMCA` do MQ.	`ALL`	Não

Circuit breaker

Protege o transporte STR contra um queue manager com falhas.

Variável	Descrição	Padrão	Obrigatória
`CB_MAX_REQUESTS`	Requisições permitidas enquanto o breaker está half-open.	`3`	Não
`CB_INTERVAL`	Janela deslizante sobre a qual as falhas são contadas (duração Go).	`30s`	Não
`CB_TIMEOUT`	Timeout de recuperação do estado open (duração Go).	`10s`	Não
`CB_CONSECUTIVE_FAILURES`	Falhas consecutivas antes de o breaker disparar.	`5`	Não
`CB_FAILURE_RATIO`	Razão de falhas que dispara o breaker (0–1).	`0.5`	Não
`CB_MIN_REQUESTS`	Mínimo de requisições em uma janela antes de o breaker poder disparar.	`10`	Não

Assinatura de mensagens e certificados

O Lerian SPB assina cada mensagem STR. Escolha o backend de custódia de chaves com SPB_SIGNER_KIND. Produção e staging rejeitam o backend file e exigem uma chave baseada em hardware (pkcs11 ou kmip).

Variável	Descrição	Padrão	Obrigatória
`SPB_SIGNER_KIND`	Backend de custódia de assinatura: `file`, `pkcs11` ou `kmip`. `file` é permitido somente quando `ENV_NAME=develop`; produção e staging o rejeitam. (`hsm` e `kms` são declarados mas não implementados.)	`file`	Não
`CERT_BASE_PATH`	Diretório base para o material de certificados.	`/certs`	Não
`CERT_PATH`	Caminho para o certificado de assinatura.	—	Em produção/staging
`KEY_PATH`	Caminho para a chave privada de assinatura.	—	Em produção/staging
`PROCESS_CERT_PATH`	Caminho para o certificado de processo/TLS.	—	Em produção/staging
`PROCESS_PRIVATE_KEY_PATH`	Caminho para a chave privada de processo/TLS. Sensível.	—	Não
`BACEN_PUBLIC_CERT_PATH`	Caminho para o certificado público do BACEN, usado para verificar assinaturas de entrada e para a criptografia SFN.	—	Em produção/staging
`CERT_READINESS_MIN_DAYS`	Mínimo de dias até o vencimento antes de a verificação de readiness do certificado reportar estado degradado.	`30`	Não

Custódia PKCS#11

Obrigatória quando SPB_SIGNER_KIND=pkcs11.

Variável	Descrição	Padrão	Obrigatória
`SPB_PKCS11_MODULE_PATH`	Caminho para a biblioteca do módulo PKCS#11.	—	Se `pkcs11`
`SPB_PKCS11_TOKEN_LABEL`	Label do token PKCS#11.	—	Se `pkcs11`
`SPB_PKCS11_PIN_FILE`	Caminho para um arquivo que contém o PIN do token. Sensível.	—	Se `pkcs11`
`SPB_PKCS11_KEY_LABEL`	Label da chave de assinatura no token.	—	Se `pkcs11`

Custódia KMIP

Obrigatória quando SPB_SIGNER_KIND=kmip (KMIP-over-HTTP para um HSM de rede).

Variável	Descrição	Padrão	Obrigatória
`SPB_KMIP_BASE_URL`	URL base do serviço KMIP.	—	Se `kmip`
`SPB_KMIP_VHSM`	Identificador do HSM virtual.	—	Se `kmip`
`SPB_KMIP_CRYPTO_USER`	Usuário cripto do KMIP.	—	Se `kmip`
`SPB_KMIP_CRYPTO_USER_TOKEN`	Token do usuário cripto do KMIP. Sensível.	—	Se `kmip`
`SPB_KMIP_SIGN_PRIVATE_KEY_UID`	UID da chave privada de assinatura.	—	Se `kmip`
`SPB_KMIP_SIGN_PUBLIC_KEY_UID`	UID da chave pública de assinatura.	—	Se `kmip`
`SPB_KMIP_DECRYPT_KEY_UID`	UID da chave de descriptografia usada no caminho de descriptografia de entrada.	—	Não
`SPB_KMIP_DIGEST_INFO_PREFIX`	Prefixa o prefixo ASN.1 DigestInfo antes da chamada de assinatura KMIP.	`false`	Não

Eventos, outbox e RabbitMQ

O Lerian SPB registra cada mensagem antes do dispatch e publica eventos de ciclo de vida através de um outbox transacional no RabbitMQ.

Variável	Descrição	Padrão	Obrigatória
`EMISSION_REQUIRED`	Quando `true`, o bootstrap falha fechado a menos que a emissão de eventos esteja totalmente conectada.	`false`	Não
`RABBITMQ_HOST`	Host do RabbitMQ.	—	Sim (eventos)
`RABBITMQ_PORT`	Porta do RabbitMQ.	`5672`	Não
`RABBITMQ_USER`	Usuário do RabbitMQ. Não deve ser o padrão `guest` em produção/staging.	`guest`	Em produção/staging
`RABBITMQ_PASSWORD`	Senha do RabbitMQ. Sensível. Não deve ser vazia ou o padrão em produção/staging.	`guest`	Em produção/staging
`RABBITMQ_VHOST`	Virtual host do RabbitMQ.	`/`	Não
`RABBITMQ_STR_EXCHANGE`	Nome do exchange para eventos de ciclo de vida do STR.	`str.events`	Não
`RABBITMQ_TLS_ENABLED`	Habilita TLS para o RabbitMQ. Deve ser `true` em produção/staging quando um host está definido.	`false`	Em produção/staging
`OUTBOX_DISPATCH_INTERVAL`	Intervalo entre ciclos de dispatch do outbox (duração Go).	`2s`	Não
`OUTBOX_BATCH_SIZE`	Linhas drenadas por ciclo de dispatch.	`50`	Não
`OUTBOX_MAX_PUBLISH_ATTEMPTS`	Máximo de tentativas do publicador RabbitMQ para cada chamada de publicação. O esgotamento da entrega de webhooks é regido separadamente por `EVENT_DELIVERY_MAX_ATTEMPTS`.	`3`	Não
`OUTBOX_POSTGRES_MAX_OPEN_CONNS`	Máximo de conexões abertas para o pool do outbox.	`10`	Não
`OUTBOX_POSTGRES_MAX_IDLE_CONNS`	Máximo de conexões ociosas para o pool do outbox.	`5`	Não
`EVENT_DELIVERY_BATCH_SIZE`	Eventos entregues por ciclo.	`25`	Não
`EVENT_DELIVERY_MAX_ATTEMPTS`	Tentativas de entrega antes de um evento ser estacionado.	`3`	Não
`EVENT_DELIVERY_RETRY_BACKOFF`	Backoff base entre tentativas de entrega (duração Go).	`30s`	Não
`DISPATCH_MAX_AUTO_ATTEMPTS`	Tentativas automáticas de dispatch antes de intervenção manual.	`8`	Não
`DISPATCH_RETRY_BACKOFF_CEILING`	Backoff máximo entre tentativas de dispatch (duração Go).	`30m`	Não
`LDL_ADVISORY_CONSUMER_ENABLED`	Habilita o consumidor supervisionado de fatos de avisos de liquidação OT do SILOC. Ele requer `STREAMING_BROKERS` e persistência durável quando habilitado, e se recusa a iniciar sem eles. O tópico e o grupo do consumidor são fixos no serviço; nenhum deles é configurável pelo ambiente. A conexão com os brokers vem das configurações compartilhadas `STREAMING_*` (consulte Streaming e outbox). Desabilitado, seu check de prontidão reporta `skipped`.	`false`	Não

Aprovação (maker-checker)

Aprovação opcional por faixa de valor que controla a emissão STR. Desligada por padrão — uma tabela de faixas vazia permite que cada emissão prossiga em etapa única.

Variável	Descrição	Padrão	Obrigatória
`APPROVAL_ALCADA_BANDS`	Faixas `maxExclusive:requiredSignatures` separadas por ponto e vírgula (ex: `10000.00:1;100000.00:2`). Vazio mantém a aprovação desligada.	—	Não
`APPROVAL_DEADLINE_WINDOW`	Por quanto tempo uma emissão estacionada pode aguardar (duração Go, limitada a 7 dias).	`24h`	Não
`APPROVAL_EXPIRY_ENABLED`	Executa a varredura em segundo plano que expira emissões estacionadas em atraso.	`true`	Não
`APPROVAL_EXPIRY_SWEEP_INTERVAL`	Intervalo da varredura (duração Go).	`1m`	Não

Rate limiting e idempotência

Variável	Descrição	Padrão	Obrigatória
`RATE_LIMIT_IP_MAX`	Máximo de requisições por IP por janela.	`300`	Não
`RATE_LIMIT_IP_WINDOW`	Janela de rate-limit por IP (duração Go).	`1m`	Não
`RATE_LIMIT_KEY_MAX`	Máximo de requisições por chave de API por janela.	`100`	Não
`RATE_LIMIT_KEY_WINDOW`	Janela de rate-limit por chave (duração Go).	`1m`	Não
`IDEMPOTENCY_ENABLED`	Habilita a deduplicação por chave de idempotência.	`true`	Não
`IDEMPOTENCY_DEFAULT_TTL_SEC`	Por quanto tempo (segundos) uma chave de idempotência é retida.	`300`	Não

Systemplane e configuração de runtime

O Lerian SPB monta a API de administração de configuração de runtime do systemplane em /v1/system na porta principal. O PostgreSQL apoia este plano, então operadores podem ler e alterar configurações recarregáveis a quente sem uma reinicialização. Consulte Systemplane para a API, os namespaces e as permissões.

Variável	Descrição	Padrão	Obrigatória
`SYSTEMPLANE_LISTEN_CHANNEL`	Canal `LISTEN`/`NOTIFY` do PostgreSQL ao qual o plano de configuração de runtime se inscreve para mudanças de configuração a quente.	Padrão do serviço	Não

Criptografia e segredos

Variável	Descrição	Padrão	Obrigatória
`STR_PAYLOAD_ENCRYPTION_KEY`	Chave AES-256 codificada em base64 para criptografia em repouso dos payloads STR armazenados. Sensível. Obrigatória em produção/staging.	—	Em produção/staging
`WEBHOOK_SECRET_KEY`	Chave usada para criptografar os segredos de webhook armazenados. Sensível. Obrigatória em produção/staging.	—	Em produção/staging
`INBOUND_ALLOW_CLEARTEXT_FALLBACK`	Permite que o caminho de entrada aceite payloads não criptografados. Mantenha `false` em produção e staging.	`false`	Não

Nunca faça commit nem registre em log os valores de qualquer variável marcada como Sensível (senhas, tokens, PINs e chaves AES). Injete-os no momento do deploy através do seu gerenciador de segredos.

Observabilidade

Variável	Descrição	Padrão	Obrigatória
`ENABLE_TELEMETRY`	Habilita tracing e métricas OpenTelemetry.	`false`	Em produção/staging
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint do coletor OTLP. Deve usar `https://` em produção/staging.	`http://localhost:4318`	Se telemetria habilitada
`OTEL_RESOURCE_SERVICE_NAME`	Nome do serviço anexado à telemetria exportada.	Padrão do serviço	Não
`METRICS_PROMETHEUS_ENABLED`	Expõe um endpoint dedicado de scrape do Prometheus.	`false`	Não
`METRICS_PROMETHEUS_ADDRESS`	Endereço de escuta do endpoint Prometheus. Vincula-se ao loopback por padrão.	`127.0.0.1:9090`	Não

Apenas para desenvolvimento

Mantenha estas variáveis não definidas fora do desenvolvimento local. Elas ampliam a superfície de ataque, e produção ou staging as rejeita ou as força a desligado.

Variável	Descrição	Padrão	Obrigatória
`ENABLE_DEV_DEBUG_ROUTES`	Expõe rotas de debug. Proibido em produção/staging.	`false`	Não
`DEV_DEBUG_TOKEN`	Token que protege as rotas de debug. Sensível. Obrigatório quando as rotas de debug estão habilitadas.	—	Se debug habilitado
`SWAGGER_ENABLED`	Serve a spec OpenAPI e a UI de docs da API. Forçado a desligado em produção e staging.	`false`	Não
`STR_MQ_MOCK`	Roteia o transporte STR para um mock em vez de um queue manager real.	`false`	Não
`STR_MQ_MOCK_HOST`	Host STR do mock. Obrigatório quando `STR_MQ_MOCK=true`.	`http://localhost:8080`	Se mock habilitado
`STR_MQ_MOCK_ALLOWED_HOSTS`	Allow-list de hosts que o transporte mock pode alcançar.	—	Não
`ALLOW_MOCK_TRANSPORT`	Permite que o transporte mock seja selecionado.	`false`	Não

Saúde e prontidão

O Lerian SPB expõe GET /health (liveness) e GET /readyz (readiness) na porta HTTP principal. Consulte Saúde e prontidão para o contrato das probes.

Visão geral

Lerian SPB — mensageria nativa

JD — interface

BTG — interface

Console

Variáveis de ambiente

Runtime e servidor

Autenticação

PostgreSQL

Réplica PostgreSQL

Redis

Conectividade STR (RSFN)

Circuit breaker

Assinatura de mensagens e certificados

Custódia PKCS#11

Custódia KMIP

Eventos, outbox e RabbitMQ

Aprovação (maker-checker)

Rate limiting e idempotência

Systemplane e configuração de runtime

Criptografia e segredos

Observabilidade

Apenas para desenvolvimento

Saúde e prontidão

​Runtime e servidor

​Autenticação

​PostgreSQL

​Réplica PostgreSQL

​Redis

​Conectividade STR (RSFN)

​Circuit breaker

​Assinatura de mensagens e certificados

​Custódia PKCS#11

​Custódia KMIP

​Eventos, outbox e RabbitMQ

​Aprovação (maker-checker)

​Rate limiting e idempotência

​Systemplane e configuração de runtime

​Criptografia e segredos

​Observabilidade

​Apenas para desenvolvimento

​Saúde e prontidão

Runtime e servidor

Autenticação

PostgreSQL

Réplica PostgreSQL

Redis

Conectividade STR (RSFN)

Circuit breaker

Assinatura de mensagens e certificados

Custódia PKCS#11

Custódia KMIP

Eventos, outbox e RabbitMQ

Aprovação (maker-checker)

Rate limiting e idempotência

Systemplane e configuração de runtime

Criptografia e segredos

Observabilidade

Apenas para desenvolvimento

Saúde e prontidão