> ## 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.
# 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, multi-tenancy e telemetria), veja [Fundamentos de configuração do BYOC](/pt/reference/byoc-configuration).
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](/pt/reference/byoc-configuration#plugin-authentication).
| 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](/pt/reference/byoc-configuration#streaming-and-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](/pt/reference/platform/systemplane/overview) 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](/pt/reference/health-and-readiness) para o contrato de probes.