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, acessado pela RSFN. Defina essas variáveis no momento do deploy. Uma mudança apenas tem efeito depois que você reinicia o serviço. A maioria das variáveis é específica deste trilho. Para os parâmetros que se comportam da mesma forma em todo serviço Go da Lerian (postura de deploy, armazenamento de dados, multi-tenancy e telemetria), veja Fundamentos de configuração do BYOC. Nas tabelas abaixo, Obrigatório marca uma variável que você deve definir, de forma global ou na 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 ativa os portões de segurança mais rígidos. Defina-o como production ou staging e o serviço passa a exigir 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 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 não está definido ou contém um valor não reconhecido.

Runtime e servidor

Variável	Descrição	Padrão	Obrigatório
`ENV_NAME`	Ambiente de runtime. Deve ser um dos seguintes: `production`, `staging` ou `develop`. Produção e staging ativam os portões de segurança descritos acima.	—	Sim
`SERVICE_NAME`	Identificador do serviço usado em logs e telemetria.	Padrão do serviço	Não
`LOG_LEVEL`	Verbosidade do log (`debug`, `info`, `warn`, `error`).	`info`	Não
`SERVER_PORT`	Porta de escuta HTTP. As superfícies de liveness, readiness e systemplane vinculam 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 administrativa do systemplane, ao Access Manager. Veja Fundamentos de configuração do BYOC.

Variável	Descrição	Padrão	Obrigatório
`PLUGIN_AUTH_ENABLED`	Exige autenticação do Access Manager nas 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ório
`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`	Número máximo de conexões abertas.	`25`	Não
`POSTGRES_MAX_IDLE_CONNS`	Número máximo de conexões ociosas.	`10`	Não
`POSTGRES_CONN_MAX_LIFETIME`	Tempo máximo de vida da conexão (duração Go, por exemplo `5m`).	`5m`	Não
`POSTGRES_CONN_MAX_IDLE_TIME`	Tempo máximo ocioso da conexão (duração Go).	`2m`	Não

Réplica do PostgreSQL

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

Variável	Descrição	Padrão	Obrigatório
`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 de dados 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ório
`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 do 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 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`	Número mínimo de conexões ociosas.	`5`	Não

Conectividade STR (RSFN)

O Lerian SPB troca mensagens STR com o BACEN pela 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ório
`STR_ISPB`	O ISPB de 8 dígitos do participante. Em produção/staging, deve ser um ISPB real explícito, e não `00000000`.	`00000000`	Em produção/staging
`SILOC_ISPB`	O ISPB de 8 dígitos da câmara SILOC, resolvido no lado do servidor nas mensagens de liquidação relacionadas ao SILOC — nunca fornecido pelo cliente. Em produção/staging, deve ser um ISPB de câmara de 8 dígitos explícito, e não `00000000`.	`02992335`	Não
`STR_MQ_HOST`	Host do queue manager.	—	Sim (STR ativo)
`STR_MQ_PORT`	Porta de escuta do queue manager.	`1414`	Não
`STR_MQ_CHANNEL`	Canal de conexão do servidor MQ.	`DEV.APP.SVRCONN`	Não
`STR_MQ_QUEUE_MGR`	Nome do queue manager.	`QM1`	Não
`STR_MQ_USER`	Usuário de conexão do MQ.	`app`	Não
`STR_MQ_PASSWORD`	Senha de conexão do 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 do 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ções 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 reinício da sequência de mensagens do canal MQ.	`99999999`	Não
`MQ_ADOPTNEWMCA`	Configuração `AdoptNewMCA` do canal MQ.	`ALL`	Não

Circuit breaker

Protege o transporte STR contra falhas no queue manager.

Variável	Descrição	Padrão	Obrigatório
`CB_MAX_REQUESTS`	Requisições permitidas enquanto o circuit breaker está semiaberto.	`3`	Não
`CB_INTERVAL`	Janela móvel na qual as falhas são contadas (duração Go).	`30s`	Não
`CB_TIMEOUT`	Tempo limite de recuperação do estado aberto (duração Go).	`10s`	Não
`CB_CONSECUTIVE_FAILURES`	Falhas consecutivas antes de o circuit breaker disparar.	`5`	Não
`CB_FAILURE_RATIO`	Proporção de falhas que dispara o circuit breaker (0–1).	`0.5`	Não
`CB_MIN_REQUESTS`	Número mínimo de requisições em uma janela antes de o circuit breaker poder disparar.	`10`	Não

Assinatura de mensagens e certificados

O Lerian SPB assina toda 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ório
`SPB_SIGNER_KIND`	Backend de custódia de assinatura: `file`, `pkcs11` ou `kmip`. `file` apenas é permitido quando `ENV_NAME=develop`; produção e staging o rejeitam. (`hsm` e `kms` estã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 recebidas e para a criptografia do SFN.	—	Em produção/staging
`CERT_READINESS_MIN_DAYS`	Número mínimo de dias até o vencimento antes de a verificação de prontidão do certificado reportar degradado.	`30`	Não

Custódia PKCS#11

Obrigatório quando SPB_SIGNER_KIND=pkcs11.

Variável	Descrição	Padrão	Obrigatório
`SPB_PKCS11_MODULE_PATH`	Caminho para a biblioteca do módulo PKCS#11.	—	Se `pkcs11`
`SPB_PKCS11_TOKEN_LABEL`	Rótulo 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`	Rótulo da chave de assinatura no token.	—	Se `pkcs11`

Custódia KMIP

Obrigatório quando SPB_SIGNER_KIND=kmip (KMIP sobre HTTP para um HSM de rede).

Variável	Descrição	Padrão	Obrigatório
`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 de criptografia do KMIP.	—	Se `kmip`
`SPB_KMIP_CRYPTO_USER_TOKEN`	Token de usuário de criptografia 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`	Adiciona o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP.	`false`	Não

Eventos, outbox e RabbitMQ

O Lerian SPB registra toda mensagem antes do envio e publica eventos de ciclo de vida para o RabbitMQ por meio de um outbox transacional.

Variável	Descrição	Padrão	Obrigatório
`EMISSION_REQUIRED`	Quando `true`, o bootstrap falha de forma fechada a menos que a emissão de eventos esteja totalmente configurada.	`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 estar vazia nem ser o padrão em produção/staging.	`guest`	Em produção/staging
`RABBITMQ_VHOST`	Host virtual 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 envio do outbox (duração Go).	`2s`	Não
`OUTBOX_BATCH_SIZE`	Linhas processadas por ciclo de envio.	`50`	Não
`OUTBOX_MAX_PUBLISH_ATTEMPTS`	Número máximo de novas tentativas do publisher do RabbitMQ para cada chamada de publicação. O esgotamento da entrega de webhook é controlado separadamente por `EVENT_DELIVERY_MAX_ATTEMPTS`.	`3`	Não
`OUTBOX_POSTGRES_MAX_OPEN_CONNS`	Número máximo de conexões abertas para o pool do outbox.	`10`	Não
`OUTBOX_POSTGRES_MAX_IDLE_CONNS`	Número 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 novas tentativas de entrega (duração Go).	`30s`	Não
`DISPATCH_MAX_AUTO_ATTEMPTS`	Tentativas automáticas de envio antes da intervenção manual.	`8`	Não
`DISPATCH_RETRY_BACKOFF_CEILING`	Backoff máximo entre novas tentativas de envio (duração Go).	`30m`	Não
`LDL_ADVISORY_CONSUMER_ENABLED`	Habilita o consumidor supervisionado dos fatos consultivos de liquidação OT do SILOC. Quando habilitado, exige `STREAMING_BROKERS` e persistência durável, e se recusa a iniciar sem eles. O tópico e o grupo do consumidor são fixos no serviço; nenhum dos dois é configurável pelo ambiente. A conexão com o broker vem das configurações compartilhadas `STREAMING_*` (veja Streaming e outbox). Quando desabilitado, sua verificação 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. Desativada por padrão. Uma tabela de faixas vazia permite que toda emissão prossiga em uma única etapa.

Variável	Descrição	Padrão	Obrigatório
`APPROVAL_ALCADA_BANDS`	Faixas `maxExclusive:requiredSignatures` separadas por ponto e vírgula (por exemplo, `10000.00:1;100000.00:2`). Vazio mantém a aprovação desativada.	—	Não
`APPROVAL_DEADLINE_WINDOW`	Por quanto tempo uma emissão estacionada pode esperar (duração Go, com teto de 7 dias).	`24h`	Não
`APPROVAL_EXPIRY_ENABLED`	Executa a varredura em segundo plano que expira emissões estacionadas vencidas.	`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ório
`RATE_LIMIT_IP_MAX`	Número 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`	Número 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 (em segundos) uma chave de idempotência é retida.	`300`	Não

Systemplane e configuração de runtime

O Lerian SPB monta a API administrativa de configuração de runtime do systemplane em /v1/system na porta principal. O PostgreSQL dá suporte a esse plano, para que os operadores possam ler e alterar configurações com hot reload sem reiniciar o serviço. Veja Systemplane para a API, os namespaces e as permissões.

Variável	Descrição	Padrão	Obrigatório
`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 em hot reload.	Padrão do serviço	Não

Criptografia e segredos

Variável	Descrição	Padrão	Obrigatório
`STR_PAYLOAD_ENCRYPTION_KEY`	Chave AES-256 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 nenhuma variável marcada como Sensível (senhas, tokens, PINs e chaves AES). Injete-os no momento do deploy por meio do seu gerenciador de segredos.

Observabilidade

Variável	Descrição	Padrão	Obrigatório
`ENABLE_TELEMETRY`	Habilita tracing e métricas do 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 do Prometheus. Vincula ao loopback por padrão.	`127.0.0.1:9090`	Não

Apenas desenvolvimento

Mantenha essas 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 desativar.

Variável	Descrição	Padrão	Obrigatório
`ENABLE_DEV_DEBUG_ROUTES`	Expõe rotas de depuração. Proibido em produção/staging.	`false`	Não
`DEV_DEBUG_TOKEN`	Token que protege as rotas de depuração. Sensível. Obrigatório quando as rotas de depuração estão habilitadas.	—	Se debug habilitado
`SWAGGER_ENABLED`	Serve a especificação OpenAPI e a interface de documentação da API. Forçado a desativado 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 do mock STR. Obrigatório quando `STR_MQ_MOCK=true`.	`http://localhost:8080`	Se mock habilitado
`STR_MQ_MOCK_ALLOWED_HOSTS`	Allowlist de hosts que o transporte mock pode acessar.	—	Não
`ALLOW_MOCK_TRANSPORT`	Permite que o transporte mock seja selecionado.	`false`	Não

Health e readiness

O Lerian SPB expõe GET /health (liveness) e GET /readyz (readiness) na porta HTTP principal. Veja Health and readiness para o contrato de probes.

​Runtime e servidor

​Autenticação

​PostgreSQL

​Réplica do 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 desenvolvimento

​Health e readiness

Runtime e servidor

Autenticação

PostgreSQL

Réplica do 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 desenvolvimento

Health e readiness