Variáveis de ambiente

Variáveis de ambiente definidas no deploy do Lerian SILOC: runtime, conectividade com a fila de liquidação do SILOC, persistência, autenticação e certificados.

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

​

Licença

O Lerian SILOC recusa iniciar sem uma licença da Lerian, em todos os ambientes. Nenhum ajuste desliga a verificação.

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

​

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. Qualquer outro valor impede o serviço de iniciar. 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. Um valor que não é interpretado impede o serviço de iniciar. Uma nova requisição de saída é recusada com 503 SILOC-0024 enquanto esse certificado não está registrado, está revogado ou fora da validade, ou não corresponde à chave da custódia.	—	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. Um valor que não é interpretado impede o serviço de iniciar. Uma nova requisição de saída é recusada com 503 SILOC-0024 enquanto esse certificado está ausente do repositório de confiança, revogado ou fora da validade.	—	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. Quando o serviço abre um provedor kmip, ele assina um digest de teste, e um provedor cuja chave de assinatura não consegue assiná-lo também 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. Com true, a conexão MQ do SILOC (MQ_HOST e o restante de MQ_*) deve estar configurada, ou o serviço se recusa a iniciar e nomeia as duas configurações.	—	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. 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. 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. Qualquer valor diferente de true ou false impede o serviço de iniciar. 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 qualquer evento de fato do SILOC, o serviço recusa iniciar. Se 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.

/readyz também reporta 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 certificate e sfn-trust-store reportam sem fazer /readyz falhar, então um serviço em execução continua em rotação. A verificação certificate aparece como down quando não resta nenhum certificado local válido no momento, ou quando a custódia não responde. A verificação sfn-trust-store aparece como degraded quando não resta nenhum certificado de remetente confiável utilizável. Uma falha de composição da custódia ou do manifesto de confiança ainda faz /readyz falhar. Crie alertas sobre essas verificações, porque /readyz sozinho não sinaliza um certificado expirado.

Consulte Health e readiness para o contrato de probe.