Variáveis de ambiente

O Lerian SILOC é a integração de mensageria nativa da Lerian para o SILOC, o sistema de liquidação diferida líquida que a Núclea opera para fluxos de boleto e cartão. Você define essas variáveis no momento do deploy. Uma alteração apenas entra em vigor depois que você reinicia o serviço. Para os parâmetros que se comportam da mesma forma em todo serviço Go da Lerian (postura de deployment, telemetria e convenções de datastore), consulte Fundamentos de configuração do BYOC. Nas tabelas abaixo, Obrigatório marca uma variável que você deve definir, de forma global ou sob a condição indicada. — significa que não há padrão.

Runtime e servidor

Variável	Descrição	Padrão	Obrigatório
`SERVICE_NAME`	Identificador do serviço usado em logs e telemetria.	Padrão do serviço	Não
`ENV_NAME`	Rótulo do ambiente de runtime. `production` ou `prod` ativa os controles mais rígidos de autenticação e TLS descritos abaixo.	`development`	Não
`DEPLOYMENT_MODE`	Postura de aplicação de TLS (`local`, `byoc`, `saas`). `saas` torna o TLS obrigatório, exige um `ENV_NAME` de produção e recusa iniciar sem eles. Consulte Modo de deploy e TLS.	—	Não
`LOG_LEVEL`	Verbosidade de log (`debug`, `info`, `warn`, `error`).	`info`	Não
`SERVER_PORT`	Porta de escuta HTTP. Os probes de liveness e readiness usam essa mesma porta.	`9820`	Não
`IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY`	Chave AES-256 que criptografa as respostas que o serviço guarda para replays de `X-Idempotency`: 32 bytes brutos, ou sua forma em base64. Sensível.	—	Sim

Autenticação

O Lerian SILOC autoriza rotas protegidas por meio do Access Manager. AUTH_ENABLED não tem padrão, então o serviço recusa iniciar até que você o defina.

Variável	Descrição	Padrão	Obrigatório
`AUTH_ENABLED`	Exige autorização do Access Manager nas rotas protegidas: `true` ou `false`. O serviço aceita `false` apenas quando você define `ENV_NAME` como `development`, `develop`, `dev`, `local` ou `test`, e nunca com `DEPLOYMENT_MODE=saas`. Com `false`, o serviço pula a chamada ao Access Manager, mas ainda exige um bearer token.	—	Sim
`AUTH_ADDRESS`	Endereço do serviço Access Manager. Deve ser uma URL `https://` válida em produção e no SaaS. Com a autorização ativa e sem endereço, as rotas protegidas respondem 503.	—	Em produção e no SaaS

PostgreSQL

A réplica volta a usar o host primário quando você deixa DB_REPLICA_HOST vazio (padrão de nó único).

Variável	Descrição	Padrão	Obrigatório
`DB_HOST`	Host do PostgreSQL.	—	Sim (em operação real)
`DB_PORT`	Porta do PostgreSQL.	`5432`	Não
`DB_USER`	Usuário do banco de dados.	—	Sim (em operação real)
`DB_PASSWORD`	Senha do banco de dados. Sensível. Injete-a no momento do deploy e nunca faça commit dela.	—	Sim (em operação real)
`DB_NAME`	Nome do banco de dados.	—	Sim (em operação real)
`DB_SSLMODE`	Modo de TLS do libpq. Um modo diferente de `require`, `verify-ca` ou `verify-full` exige `ALLOW_INSECURE_TLS=true`.	`disable`	Não
`DB_REPLICA_HOST`	Host opcional de réplica de leitura. Volta a usar `DB_HOST` quando não definido.	—	Não

Redis

Variável	Descrição	Padrão	Obrigatório
`REDIS_ADDRESS`	Host e porta do Redis/Valkey. O gate de `X-Idempotency` guarda suas chaves aqui, então as requisições que alteram estado e o readiness precisam dele.	—	Sim (em operação real)
`REDIS_PASSWORD`	Senha do Redis. Sensível.	—	Não
`REDIS_DB`	Número do banco de dados Redis. Um valor que não seja inteiro recusa iniciar.	`0`	Não
`REDIS_TLS`	Abre a conexão com o Redis sobre TLS. `DEPLOYMENT_MODE=saas` exige `true`.	`false`	Não
`REDIS_CA_CERT`	Autoridade certificadora PEM codificada em base64 que valida o servidor Redis quando `REDIS_TLS=true`. Quando ela está vazia, o serviço usa as autoridades confiáveis do sistema operacional.	—	Não
`ALLOW_INSECURE_TLS`	Defina true para o serviço abrir conexões com PostgreSQL e Redis sem TLS. O serviço registra um aviso enquanto essa exceção estiver ativa.	—	Não

Conectividade de liquidação do SILOC

O Lerian SILOC mantém uma única conexão IBM MQ com o gerenciador de filas de liquidação do SILOC na Núclea. Definir MQ_HOST, MQ_CHANNEL, MQ_QUEUE_MANAGER, MQ_SEND_QUEUE ou MQ_RECEIVE_QUEUE faz o serviço validar todo o descritor de conexão de forma fail-closed na inicialização. Sozinhas, as demais variáveis MQ_* não ativam essa validação.

Variável	Descrição	Padrão	Obrigatório
`LOCAL_FI_ISPB`	O ISPB de 8 dígitos desta instituição. Toda mensagem OT é autorizada contra ele. Com o MQ configurado, ele deve corresponder ao ISPB em `MQ_CHANNEL`.	—	Sim
`MQ_HOST`	Host do gerenciador de filas.	—	Sim (SILOC em operação real)
`MQ_PORT`	Porta de escuta do gerenciador de filas.	—	Sim (SILOC em operação real)
`MQ_QUEUE_MANAGER`	Nome do gerenciador de filas. Deve ser o gerenciador de filas de liquidação do SILOC na Núclea.	—	Sim (SILOC em operação real)
`MQ_CHANNEL`	Canal de conexão do servidor. Deve corresponder ao padrão de canal do SILOC na Núclea `C02992335.<ISPB>.1`, em que `<ISPB>` é o ISPB de 8 dígitos do participante.	—	Sim (SILOC em operação real)
`MQ_SEND_QUEUE`	Fila de envio de saída.	—	Sim (SILOC em operação real)
`MQ_RECEIVE_QUEUE`	Fila de recebimento de entrada.	—	Sim (SILOC em operação real)
`MQ_BACKOUT_THRESHOLD`	Quantas vezes o serviço pode recusar um frame de entrada antes de estacioná-lo em seu banco de dados e retirá-lo da fila de recebimento. Um inteiro de 1 a 1000.	—	Sim (SILOC em operação real)
`MQ_BACKOUT_DELAY`	Pausa antes de um frame recusado ser entregue novamente, como uma duração com unidade, de `100ms` a `1m` (por exemplo, `2s`).	—	Sim (SILOC em operação real)
`MQ_TLS_ENABLED`	Habilita o TLS mútuo no canal MQ. Deve ser `true` em produção e no SaaS.	`false`	Em produção e no SaaS
`MQ_SSL_KEY_REPOSITORY`	Caminho do repositório de chaves do GSKit (`MQSSLKEYR`) que sustenta o TLS do MQ. A chave privada fica aqui, nunca em uma variável de ambiente. Obrigatório quando `MQ_TLS_ENABLED=true`.	—	Se TLS habilitado
`MQ_CIPHER_SPEC`	Especificação de cifra TLS do canal MQ quando `MQ_TLS_ENABLED=true`. Deve corresponder à especificação de cifra do canal de conexão do servidor no gerenciador de filas.	`ECDHE_RSA_AES_256_CBC_SHA384`	Não
`MQ_CERT_LABEL`	Rótulo do certificado no repositório de chaves que o serviço apresenta no canal MQ quando `MQ_TLS_ENABLED=true`. Quando ele está vazio, o cliente MQ usa seu rótulo padrão.	—	Não
`CAMARA_PAG_ISPB`	O ISPB de 8 dígitos da câmara do SILOC. Toda mensagem de liquidação de entrada é autorizada contra esse remetente antes de ter qualquer efeito semântico. Ele corresponde ao prefixo do canal de liquidação, então apenas substitua esse valor para uma câmara de teste. Um valor que não tenha 8 dígitos recusa iniciar.	`02992335`	Não

Mensagens de saída

O serviço envia as requisições da instituição à Núclea apenas quando os dois identificadores de certificado e MQ_SEND_QUEUE estão definidos. Defina os dois identificadores ou nenhum: um sem o outro recusa iniciar.

Variável	Descrição	Padrão	Obrigatório
`SFN_OUTBOUND_SIGNER_CERT_ID`	O certificado que assina as mensagens de saída, no formato `<authority>:<64 hex>`. O provedor de custódia guarda sua chave.	—	Para enviar
`SFN_CAMARA_CERT_ID`	O certificado da câmara, do manifesto de confiança, para o qual as mensagens de saída são criptografadas, no mesmo formato.	—	Para enviar
`OT_OUTBOUND_DISPATCH_INTERVAL`	Com que frequência o dispatcher coloca as mensagens enviadas na fila de envio.	`5s`	Não
`UNANSWERED_REQUEST_DEADLINES`	Quanto tempo uma requisição despachada aguarda sua resposta antes de o serviço gerar `UNANSWERED_REQUEST`, no formato `default=<duration>,<COD_MSG>=<duration>`. Sem definição, consultas aguardam 2 minutos, confirmações 5 e comandos 15. O mínimo é 1 segundo.	—	Não
`UNANSWERED_REQUEST_SWEEP_INTERVAL`	Com que frequência o serviço verifica requisições sem resposta, de `1s` a `10m`.	`30s`	Não

Validação de mensagens

O serviço valida as mensagens de entrada que aplica e as mensagens de saída que envia contra os schemas XSD oficiais, por meio de um sidecar validador.

Variável	Descrição	Padrão	Obrigatório
`XSD_VALIDATOR_URL`	URL base do sidecar validador.	—	Sim (SILOC em operação real)
`XSD_VALIDATOR_TIMEOUT_SEC`	Timeout de uma requisição de validação, em segundos. Um valor que não seja inteiro recusa iniciar.	`10`	Não

O sidecar escuta em XSD_VALIDATOR_ADDR (padrão 127.0.0.1:9091), e o seu próprio AUTH_ENABLED não tem padrão. O serviço não envia bearer token ao sidecar, então execute o sidecar com AUTH_ENABLED=false em um endereço de loopback literal.

Certificados

Variável	Descrição	Padrão	Obrigatório
`CERT_READINESS_MIN_DAYS`	Limite de dias até o vencimento abaixo do qual um certificado atualmente válido registra um aviso e gera um alerta `CERTIFICATE_EXPIRY`. Não degrada o readiness apenas porque o certificado está perto do vencimento. Deve ser um inteiro maior que 0.	`30`	Não

Confiança e custódia

Variável	Descrição	Padrão	Obrigatório
`SFN_TRUST_MANIFEST_PATH`	Caminho do manifesto de confiança do SFN usado para validar o material de confiança de mensagens regulatórias. Sem ele, o serviço informa que não está pronto.	—	Sim (SILOC em operação real)
`SFN_CUSTODY_CONFIG_PATH`	Caminho da configuração do provedor de custódia. Sem ele, o serviço informa que não está pronto.	—	Sim (SILOC em operação real)
`SFN_CUSTODY_CACHE_ENTRIES`	Número máximo de entradas de custódia mantidas no cache em memória. Um valor que não seja inteiro recusa iniciar.	`16`	Não

Processamento em segundo plano

As cinco chaves *_ENABLED desta tabela não têm padrão. Defina cada uma como true ou false, porque um valor em branco recusa iniciar. Com false, o runtime fica desligado e sua verificação de readiness informa skipped. Com true, o serviço tenta de novo um runtime que falha ao iniciar até que ele rode, e sua verificação de readiness informa o motivo sem falhar.

Variável	Descrição	Padrão	Obrigatório
`OT_REPLAY_ENABLED`	Aplica as mensagens de entrada estacionadas, exceto `PAG0101`: mensagens de ciclo OT, avisos da câmara e respostas às requisições da instituição.	—	Sim
`OT_REPLAY_INTERVAL`	Com que frequência o replay de OT roda.	`10s`	Não
`STATUS_REPLAY_ENABLED`	Aplica as mensagens de status de participante `PAG0101` estacionadas.	—	Sim
`STATUS_REPLAY_INTERVAL`	Com que frequência o replay de status roda.	`10s`	Não
`RECONCILE_ENABLED`	Concilia os ciclos OT com o resultado multilateral `GEN0015` da câmara e liquida um ciclo cujo resultado corresponde à sua obrigação.	—	Sim
`RECONCILE_INTERVAL`	Com que frequência a conciliação roda.	`10s`	Não
`LDL_FACT_CONSUMER_ENABLED`	Consome os fatos de liquidação LDL do SPB. Cada fato registra o resultado da instrução que ele nomeia.	—	Sim
`CARD_COMMAND_CONSUMER_ENABLED`	Consome comandos de cartão do Lerian SLC e os envia à Núclea.	—	Sim

Declaração de permissões

O serviço pode publicar seu próprio conjunto de permissões no Access Manager na inicialização. Apenas IDP_DECLARATION_ENABLED=true ativa isso. 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. Deve ser `https://` fora de ambientes locais e de desenvolvimento.	—	Com declaração
`IDP_M2M_CLIENT_ID`	Client ID da aplicação máquina a máquina do serviço, cujo nome deve ser `siloc`.	—	Com declaração
`IDP_M2M_CLIENT_SECRET`	Client secret dessa aplicação. Sensível.	—	Com declaração
`PLUGIN_AUTH_ENABLED`	Deve ser `true` para que o serviço obtenha o token que a publicação usa. Não controla a autorização de rotas, que é o papel de `AUTH_ENABLED`.	—	Com declaração
`PLUGIN_AUTH_HOST`	Endereço do Access Manager para esse token.	—	Com declaração

Observabilidade

Variável	Descrição	Padrão	Obrigatório
`ENABLE_TELEMETRY`	Habilita a instrumentação do OpenTelemetry.	`false`	Não
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint do coletor OTLP.	—	Se telemetria habilitada
`STREAMING_BROKERS`	Endereços dos brokers para o dispatcher obrigatório de fatos do SILOC. O streaming não tem modo desabilitado: uma configuração de broker ausente ou inválida impede a inicialização, em vez de deixar os fatos como `PENDING`. Configure as opções compartilhadas `STREAMING_*` conforme descrito em Streaming e outbox.	—	Sim
`STREAMING_CLOUDEVENTS_SOURCE`	Identidade de origem do CloudEvents. Deve ser exatamente `br-siloc`. Um valor diferente, incluindo espaços em branco no início ou no fim, impede a inicialização; o serviço usa essa identidade para derivar os tópicos de broker e o escopo de controle de acesso.	—	Sim

Se STREAMING_EVENT_POLICIES define enabled=false para um evento de comando de cartão (siloc_command.accepted, siloc_command.answered, siloc_command.refused ou siloc_command.failed), o consumidor de comandos de cartão não inicia. Se define enabled=false para siloc.relay.inbound, o processamento de mensagens de entrada não inicia. Nos dois casos, o erro nomeia o evento.

Health e readiness

O Lerian SILOC expõe GET /health (liveness), GET /readyz (readiness) e GET /version na porta HTTP principal. O serviço recusa iniciar quando o PostgreSQL não responde em até 10 segundos. Ele inicia antes que o Redis e a conexão de liquidação estejam acessíveis. /readyz informa a saúde de cada dependência. Enquanto o queue manager do SILOC da Núclea não está acessível, siloc-mq informa down e não faz o /readyz passar a 503. siloc-mq reprova o readiness quando o queue manager recusa a configuração deste deploy, e nomeia o ajuste a corrigir. Consulte Health e readiness para o contrato de probe.

​Runtime e servidor

​Autenticação

​PostgreSQL

​Redis

​Conectividade de liquidação do SILOC

​Mensagens de saída

​Validação de mensagens

​Certificados

​Confiança e custódia

​Processamento em segundo plano

​Declaração de permissões

​Observabilidade

​Health e readiness