Variáveis de ambiente

Variáveis de ambiente de deploy do Lerian SPB: runtime, conectividade STR/RSFN, assinatura de mensagens e certificados, persistência, eventos e segurança.

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. Uma entrada que não é um endereço IP nem um intervalo CIDR impede o serviço de iniciar.	—	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 ou tem qualquer outro valor. 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

​

Declaração de permissões

O Lerian SPB pode publicar seu próprio conjunto de permissões no Access Manager na inicialização. IDP_DECLARATION_ENABLED=true ativa isso, e qualquer valor diferente de true ou false impede o serviço de iniciar. Com a publicação ativa, uma variável ausente abaixo recusa iniciar.

Variável	Descrição	Padrão	Obrigatório
IDP_DECLARATION_ENABLED	Publica o conjunto de permissões na inicialização.	false	Não
IDP_HOST	URL base do Access Manager para a qual o conjunto é publicado.	—	Com declaração
IDP_M2M_CLIENT_ID	Client ID da aplicação machine-to-machine do serviço, cujo nome deve ser br-spb.	—	Com declaração
IDP_M2M_CLIENT_SECRET	Client secret dessa aplicação. Sensível.	—	Com declaração

Com a declaração ativa, PLUGIN_AUTH_ENABLED deve ser true e PLUGIN_AUTH_ADDRESS deve estar definido, porque o serviço os usa para obter o token que a publicação usa.

​

Licença

O Lerian SPB precisa de uma licença em todo ambiente, inclusive no de desenvolvimento. Ele não inicia sem LICENSE_FILE_PATH ou LICENSE_KEY. A licença é global: o Lerian SPB não lê nenhum identificador de organização. Para o host que a verificação da chave consulta, veja License Manager.

Variável	Descrição	Padrão	Obrigatória
LICENSE_FILE_PATH	Caminho de um arquivo de licença. Quando ela está definida, o Lerian SPB usa o arquivo e ignora LICENSE_KEY, e um arquivo que o Lerian SPB recusa impede a inicialização. Deixe-a vazia e defina LICENSE_KEY.	—	Não
LICENSE_KEY	Chave de licença que a Lerian emite. Sensível.	—	Sim

A licença protege toda rota sob /v1/str. Uma licença recusada responde 403 com um código LCS-, como a lista de erros descreve.

​

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_CA_FILE	Caminho de um pacote PEM com a autoridade certificadora privada de um HSM. O serviço o adiciona às raízes do sistema e mantém a verificação TLS ligada. O serviço se recusa a iniciar quando o arquivo não existe ou não contém nenhum certificado PEM.	—	Não
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. Na inicialização, o serviço assina um digest de teste com ela, e, em produção e staging, uma chave que não consegue assinar impede o serviço de iniciar.	—	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. Em produção e staging, um valor que faz a assinatura de teste da inicialização falhar impede o serviço de iniciar.	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 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) o trilho guarda a resposta em cache de uma chave de idempotência.	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.

A resposta de /readyz inclui uma verificação license. Com LICENSE_KEY, a verificação não faz nenhuma chamada e aparece como no ar. Uma licença que deixa de ser válida após a inicialização não leva /readyz a 503.

As verificações certificates, bacen-public-certificate, ibm-mq e ldl-advisory-consumer reportam sem fazer /readyz falhar, então um serviço em execução continua em rotação. A verificação certificates aparece como fora do ar quando o certificado SFN está expirado ou ainda não é válido, ou quando a custódia não responde. A verificação bacen-public-certificate aparece como fora do ar quando o certificado público do BACEN tem um problema. Um signer ausente ainda faz /readyz falhar. Crie alertas sobre essas verificações, porque /readyz sozinho não sinaliza um certificado expirado.