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 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 e na conexão STR, e verify-full no PostgreSQL. Ele também exige custódia baseada em hardware para a chave privada SFN, 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
`DEPLOYMENT_MODE`	Variante de deploy: `local`, `byoc` ou `saas`. Produção e staging se recusam a iniciar sem ela. `saas` também exige `ENV_NAME` `production` ou `staging`, TLS nos armazenamentos de dados, nos upstreams e no broker, e SASL no broker.	`local`	Em produção/staging
`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. Defina-a como `true` ou `false`; o serviço se recusa a iniciar quando ela não está definida. `false` apenas é aceito com `ENV_NAME=develop` e com um `DEPLOYMENT_MODE` diferente de `saas`.	—	Sim
`PLUGIN_AUTH_ADDRESS`	Endereço do serviço Access Manager. Deve ser uma URL `https://` em produção/staging.	`http://localhost:4000`	Em produção/staging

PostgreSQL

Variável	Descrição	Padrão	Obrigatório
`POSTGRES_HOST`	Host primário do PostgreSQL. Não deve ser `localhost` em produção/staging.	`localhost`	Em produção/staging
`POSTGRES_PORT`	Porta primária do PostgreSQL.	`5432`	Não
`POSTGRES_USER`	Usuário do banco de dados.	`postgres`	Não
`POSTGRES_PASSWORD`	Senha do banco de dados. Sensível. Injete-a no momento do deploy e nunca faça commit dela. Não deve ser `postgres` em produção/staging.	`postgres`	Em produção/staging
`POSTGRES_DB`	Nome do banco de dados.	Padrão do serviço	Não
`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.	—	Em produção/staging
`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. Os três nomes de fila derivam de STR_ISPB. Produção e staging recusam um nome de fila diferente do nome derivado. O serviço inicia quando não consegue alcançar o queue manager e se conecta quando o queue manager volta. Qualquer outra falha de conexão impede a inicialização. Um exemplo é um queue manager que recusa o nome do queue manager, o canal, as credenciais, as configurações de TLS ou os nomes das 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 diferente de `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, sem a extensão do arquivo, do 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.	—	Em produção/staging
`STR_MQ_CIPHER_SPEC`	CipherSpec TLS que o serviço define no canal MQ quando `STR_MQ_TLS_ENABLED` está habilitado. Defina-a como a CipherSpec do canal `STR_MQ_CHANNEL` no seu queue manager. Um canal que usa uma CipherSpec `TLS_RSA_*` também precisa dessa CipherSpec em `AMQ_ALLOWED_CIPHERS`.	`ECDHE_RSA_AES_256_CBC_SHA384`	Não
`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 que o serviço define no canal (duração Go).	`300s`	Não
`MQ_DISCONNECT_INTERVAL`	Intervalo de desconexão esperado no queue manager (duração Go). O serviço o registra em log na conexão e não o define.	`6000s`	Não
`MQ_SEQ_WRAP`	Teto de reinício da sequência de mensagens esperado no canal do queue manager. O serviço o registra em log e não o define.	`99999999`	Não
`MQ_ADOPTNEWMCA`	Configuração `AdoptNewMCA` esperada no queue manager. O serviço a registra em log e não a define.	`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 a proporção de falhas poder disparar o circuit breaker.	`10`	Não

Assinatura de mensagens e certificados

O certificado SFN em PROCESS_CERT_PATH é a identidade do Lerian SPB na RSFN. A chave privada dele assina toda mensagem STR de saída e descriptografa as mensagens de entrada que o BACEN criptografa para esse certificado. Em um HSM, permita assinatura e descriptografia nessa chave. SPB_SIGNER_KIND define onde a chave fica. Produção e staging rejeitam a custódia file e exigem pkcs11 ou kmip.

Variável	Descrição	Padrão	Obrigatório
`SPB_SIGNER_KIND`	Custódia da chave privada SFN: `file`, `pkcs11` ou `kmip`. `file` apenas é permitido quando `ENV_NAME=develop`; produção e staging o rejeitam. O serviço recusa `hsm` e `kms`.	`file`	Não
`CERT_BASE_PATH`	Diretório de onde uma rotação de certificado lê os arquivos de certificado e de chave.	`/certs`	Não
`PROCESS_CERT_PATH`	Caminho para o certificado SFN. A chave pública dele precisa corresponder à chave privada em custódia.	—	Em produção/staging
`PROCESS_PRIVATE_KEY_PATH`	Caminho para a chave privada SFN quando `SPB_SIGNER_KIND=file`. Sensível.	—	Não
`BACEN_PUBLIC_CERT_PATH`	Caminho para o certificado público inicial do BACEN, usado para verificar assinaturas recebidas e para a criptografia do SFN. O serviço acompanha cada novo certificado do BACEN que um GEN0018 anuncia, sem mudança neste arquivo.	—	Em produção/staging
`CERT_READINESS_MIN_DAYS`	Número mínimo de dias até o vencimento. Um certificado que vence antes disso mantém o `/readyz` pronto: a verificação informa os dias restantes, e o serviço registra um aviso no log.	`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 SFN 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 SFN.	—	Se `kmip`
`SPB_KMIP_SIGN_PUBLIC_KEY_UID`	UID da chave pública SFN.	—	Se `kmip`
`SPB_KMIP_DECRYPT_KEY_UID`	UID da chave de descriptografia usada no caminho de descriptografia de entrada. Quando não definido, o serviço usa `SPB_KMIP_SIGN_PRIVATE_KEY_UID`.	—	Não
`SPB_KMIP_DIGEST_INFO_PREFIX`	Adiciona o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP.	`false`	Não

Eventos e outbox

O Lerian SPB registra toda mensagem antes do envio e publica eventos de ciclo de vida para o broker de streaming por meio de um outbox transacional. O streaming não tem modo desabilitado. Defina as configurações compartilhadas STREAMING_* conforme descrito em Streaming e outbox. O serviço se recusa a iniciar quando STREAMING_EVENT_POLICIES desliga um evento do SPB que não seja str.message.submitted, str.approval.signed, str.approval.quorumReached, str.reconciliation.opened, str.reconciliation.resolved, str.certificate.rotated, str.certificate.activationRequested ou str.certificate.expiring.

Variável	Descrição	Padrão	Obrigatório
`STREAMING_BROKERS`	Endereços do broker para a publicação de eventos. O serviço se recusa a iniciar quando o valor está ausente ou é inválido.	—	Sim
`STREAMING_CLOUDEVENTS_SOURCE`	Identidade de origem do CloudEvents. Deve ser exatamente `br-spb`. Um valor diferente impede a inicialização; o serviço deriva os tópicos do broker a partir dele.	—	Sim
`EMISSION_REQUIRED`	Quando `true`, o bootstrap falha de forma fechada a menos que a emissão de eventos esteja totalmente configurada.	`false`	Não
`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
`DISPATCH_RETRY_BACKOFF_CEILING`	Backoff máximo entre novas tentativas de envio (duração Go).	`30m`	Não
`LDL_ADVISORY_CONSUMER_ENABLED`	Consome os avisos de liquidação OT do SILOC. Defina-a como `true` ou `false`; o serviço se recusa a iniciar quando ela não está definida. 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`.	—	Sim

Aprovação (maker-checker)

Aprovação opcional por faixa de valor que controla a emissão STR. Desativada por padrão. As faixas e as regras por tipo que um operador armazena pela API de governança têm precedência sobre APPROVAL_ALCADA_BANDS.

Variável	Descrição	Padrão	Obrigatório
`APPROVAL_ALCADA_BANDS`	Tabela de faixas inicial: faixas `maxExclusive:requiredSignatures` separadas por ponto e vírgula (por exemplo, `10000.00:1;100000.00:2`). Vazio mantém a aprovação desativada até que um operador defina faixas ou regras por tipo pela API de governança.	—	Não
`APPROVAL_DEADLINE_WINDOW`	Por quanto tempo uma emissão estacionada pode esperar (duração Go). A espera termina no máximo à próxima meia-noite de Brasília.	—	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. Produção e staging recusam `false`.	`true`	Não
`IDEMPOTENCY_DEFAULT_TTL_SEC`	Por quanto tempo (em segundos) uma chave de idempotência é retida.	`86400`	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. As origens CORS, os quatro valores de rate limit e os dois valores de envio do outbox aceitam hot reload. Para essas configurações, a variável define o valor inicial, e um valor armazenado no Systemplane tem precedência.

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

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
`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 serviço inicie em `develop` sem o certificado público do BACEN e sem a chave SFN. Recusado fora de `develop` e com um `STR_MQ_HOST` real.	`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 e outbox

​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 e outbox

Aprovação (maker-checker)

Rate limiting e idempotência

Systemplane e configuração de runtime

Criptografia e segredos

Observabilidade

Apenas desenvolvimento

Health e readiness