> ## 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 CCS: postura de runtime, armazenamentos de dados, os upstreams STA e Reporter, chaves de criptografia e configurações regulatórias. O Lerian CCS lê sua configuração a partir do ambiente do processo na inicialização. Você define essas variáveis no momento do deploy. Um reinício do serviço as torna efetivas. Um pequeno conjunto de parâmetros operacionais também aceita mudanças em tempo de execução pelo [Systemplane](/pt/reference/platform/systemplane/overview). A [referência de configuração do BYOC](/pt/reference/byoc-configuration) documenta a base que todo serviço Go da Lerian compartilha. Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor que o serviço aplica quando você deixa a variável sem definir. Um qualificador em negrito marca uma variável que você deve definir, como **Obrigatório** ou **Obrigatório em produção**. `—` significa que o serviço não aplica nenhum padrão. Uma variável marcada com `Sensitive.` carrega material de credencial ou de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor. Quando um valor no arquivo de exemplo publicado difere do valor que o código aplica, esta página publica o valor do código. ## Serviço e runtime | Variável | Padrão / Obrigatório | Descrição | | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `APPLICATION_NAME` | Nome do serviço | Nome do processo da aplicação que aparece nos logs e na telemetria. | | `VERSION` | `1.0.0` | String de versão publicada do serviço. | | `ENV_NAME` | `—` | Rótulo do ambiente de deploy, convertido para minúsculas. O valor `production` ativa todos os gates de produção desta página. | | `LOG_LEVEL` | `info` | Nível do logger estruturado: `debug`, `info`, `warn` ou `error`. | | `DEPLOYMENT_MODE` | `local` | Postura operacional: `local`, `byoc`, `saas` ou `onprem`. O valor `saas` impõe TLS em cada dependência. | | `CCS_RUN_MODE` | `all` | Seleciona os subsistemas que este processo executa: `manager` apenas para a API HTTP, `worker` apenas para os workers em segundo plano, ou `all` para ambos. Um valor inválido interrompe o boot. | | `SERVER_ADDRESS` | `—` | Endereço HTTP principal de escuta. Um valor não definido faz o servidor se vincular a uma porta atribuída pelo sistema operacional, então os deploys o definem. | | `SERVER_PORT` | `4030` | Porta que o binário de health check dentro do container chama. Mantenha-a alinhada com a porta em `SERVER_ADDRESS`. | | `GRPC_PORT` | `7001` | Porta de escuta gRPC. | | `HTTP_BODY_LIMIT_BYTES` | `104857600` | Tamanho máximo do corpo da requisição de entrada, em bytes. | | `SYSTEMPLANE_ENABLED` | `false` | Monta a API administrativa de configuração em tempo de execução do Systemplane sob `/system`. Desativada por padrão, o que mantém o serviço no modo apenas variável de ambiente. | | `DEFAULT_TENANT_ID` | `—` | Identificador de tenant de fallback para caminhos sem contexto de tenant por requisição. | | `MIGRATIONS_PATH` | `—` | Caminho no sistema de arquivos para os arquivos de migração SQL. Os binários de migração o leem diretamente. O serviço nunca aplica as migrações por conta própria. | | `INFRA_CONNECT_TIMEOUT_SEC` | `30` | Orçamento geral de dial de infraestrutura, em segundos. O serviço limita um valor igual ou menor que zero a 30 segundos. | ## Licença | Variável | Padrão / Obrigatório | Descrição | | ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LICENSE_KEY` | **Obrigatório em produção** | Credencial de licença emitida pela Lerian. `Sensitive.` Deixe em branco no desenvolvimento, o que desativa a aplicação da licença. | | `ORGANIZATION_IDS` | **Obrigatório em produção** | Escopo de organização que a licença cobre. O Lerian CCS executa a biblioteca de licenças em modo global, então o valor é o literal `global`. | | `LICENSE_SERVICE_ADDRESS` | `—` | URL base opcional do gerenciador de licenças. Em produção, o valor deve usar `https` e não pode apontar para um host loopback, privado, link-local ou de metadados. | ## CORS, TLS e proxies | Variável | Padrão / Obrigatório | Descrição | | ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CORS_ALLOWED_ORIGINS` | **Obrigatório em produção** | Lista separada por vírgulas das origens de navegador permitidas. Um boot em produção recusa uma lista vazia e recusa um curinga. | | `CORS_ALLOWED_METHODS` | `—` | Lista separada por vírgulas dos métodos HTTP permitidos. | | `CORS_ALLOWED_HEADERS` | `—` | Lista separada por vírgulas dos headers de requisição permitidos. | | `CORS_EXPOSE_HEADERS` | `—` | Lista separada por vírgulas dos headers de resposta que o navegador pode ler. | | `CORS_ALLOW_CREDENTIALS` | `false` | Permite requisições cross-origin com credenciais. | | `SERVER_TLS_CERT_FILE` | `—` | Caminho para o certificado TLS quando o serviço encerra o TLS por conta própria. Defina-o junto com o arquivo de chave. | | `SERVER_TLS_KEY_FILE` | `—` | Caminho para a chave privada TLS. Defina-o junto com o arquivo de certificado. | | `TLS_TERMINATED_UPSTREAM` | `false` | Marca o caminho da requisição como tendo o TLS encerrado por um proxy na frente do serviço. | | `TRUSTED_PROXIES` | **Obrigatório em produção** | Faixas CIDR separadas por vírgulas dos proxies de camada 7 cujo header `X-Forwarded-For` o serviço respeita. Um boot em produção recusa uma lista vazia e recusa uma faixa curinga. | ## Multi-tenancy | Variável | Padrão / Obrigatório | Descrição | | --------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MULTI_TENANT_ENABLED` | `false` | Ativa o perfil multi-tenant e o cliente do tenant-manager. | | `MULTI_TENANT_URL` | `—` | URL HTTP base do tenant-manager. | | `MULTI_TENANT_SERVICE_API_KEY` | `—` | Chave de API estática para o cliente do tenant-manager. `Sensitive.` | | `MULTI_TENANT_REDIS_HOST` | `—` | Host da instância Redis que carrega o pub/sub de tenant. | | `MULTI_TENANT_REDIS_PORT` | `6379` | Porta da instância Redis de pub/sub de tenant. | | `MULTI_TENANT_REDIS_PASSWORD` | `—` | Senha da instância Redis de pub/sub de tenant. `Sensitive.` | | `MULTI_TENANT_REDIS_TLS` | `false` — **Obrigatório em produção** quando um host Redis de tenant está definido | Ativa o TLS para o cliente Redis de pub/sub de tenant. | | `MULTI_TENANT_REDIS_CA_CERT` | `—` | Pacote de autoridade certificadora PEM codificado em base64 para o handshake do Redis de tenant. Defina-o apenas quando o cluster gerenciado usa uma autoridade certificadora fora do trust store do sistema. | | `MULTI_TENANT_MAX_TENANT_POOLS` | `0` | Limita o número de pools de conexão por tenant. Um valor `0` significa ilimitado e desativa a remoção de pools. | | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Timeout de ociosidade de conexão por tenant, em segundos. | | `MULTI_TENANT_TIMEOUT` | `30` | Timeout do cliente do tenant-manager, em segundos. | | `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `0` | Limite de falhas consecutivas para acionar o circuit breaker do tenant-manager. Um valor `0` desativa o breaker. | | `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Tempo de resfriamento no estado aberto, em segundos, para o circuit breaker do tenant-manager. | | `MULTI_TENANT_CACHE_TTL_SEC` | `120` | Tempo de vida do cache por tenant, em segundos. | | `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo em segundos entre as varreduras de conexões ociosas de tenant. | | `MULTI_TENANT_CONSUMER_PREFETCH_COUNT` | `10` | Contagem de prefetch de mensagens por canal de broker de tenant. | ## PostgreSQL | Variável | Padrão / Obrigatório | Descrição | | ---------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POSTGRES_HOST` | `—` | Host do banco de dados principal. A identidade de conexão não carrega padrões, então um bloco incompleto falha o dial no boot. | | `POSTGRES_PORT` | `—` | Porta do banco de dados principal. | | `POSTGRES_USER` | `—` | Usuário do banco de dados principal. Um valor vazio faz o driver recorrer ao usuário do sistema operacional do processo. | | `POSTGRES_PASSWORD` | `—` | Senha do banco de dados principal. `Sensitive.` | | `POSTGRES_NAME` | `—` | Nome do banco de dados principal. | | `POSTGRES_SSLMODE` | **Obrigatório em produção** | Modo TLS do banco de dados principal. Um boot em produção recusa o valor `disable`. | | `POSTGRES_REPLICA_HOST` | `—` | Host da réplica de leitura para escalar consultas. | | `POSTGRES_REPLICA_PORT` | `—` | Porta da réplica de leitura. | | `POSTGRES_REPLICA_USER` | `—` | Usuário da réplica de leitura. | | `POSTGRES_REPLICA_PASSWORD` | `—` | Senha da réplica de leitura. `Sensitive.` | | `POSTGRES_REPLICA_NAME` | `—` | Nome do banco de dados da réplica de leitura. | | `POSTGRES_REPLICA_SSLMODE` | `—` | Modo TLS da réplica de leitura. Um boot em produção recusa o valor `disable`. | | `POSTGRES_MAX_OPEN_CONNS` | `25` | Máximo de conexões abertas por pool. | | `POSTGRES_MAX_IDLE_CONNS` | `—` | Máximo de conexões ociosas por pool. O valor efetivo difere entre os caminhos single-tenant e multi-tenant, então o serviço não aplica nenhum padrão aqui. | | `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Tempo de vida máximo da conexão, em minutos. | | `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tempo máximo de ociosidade da conexão, em minutos. | | `POSTGRES_CONNECT_TIMEOUT_SEC` | `—` | Timeout de dial, em segundos. Um valor não definido deixa o dial limitado apenas pelo timeout do sistema operacional. | | `POSTGRES_POOL_FANOUT_ACK` | `—` | Consentimento do operador para exceder o fan-out seguro de conexões entre o pool do control plane e os pools por tenant. Aceita `true`, `1`, `yes` ou `on`. Sem ele, o boot recusa um fan-out excessivo. | ## Redis | Variável | Padrão / Obrigatório | Descrição | | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `REDIS_HOST` | `—` | Endereço do Redis como `host:port`. Um valor não vazio também ativa o gate de postura TLS no modo `saas`. | | `REDIS_MASTER_NAME` | `—` | Nome do master do Sentinel quando o deployment usa Redis Sentinel. | | `REDIS_PASSWORD` | `—` | Senha do Redis. `Sensitive.` | | `REDIS_DB` | `0` | Número do banco de dados lógico do Redis. | | `REDIS_PROTOCOL` | `3` | Versão do protocolo de rede do Redis. | | `REDIS_TLS` | `false` — **Obrigatório em produção** quando multi-tenancy está ativado | Ativa o TLS para o cliente Redis. | | `REDIS_CA_CERT` | `—` | Caminho para uma autoridade certificadora extra para o handshake do Redis. | | `REDIS_POOL_SIZE` | `10` | Tamanho máximo do pool do Redis. O cliente limita um valor acima de 1000. | | `REDIS_MIN_IDLE_CONNS` | `—` | Mínimo de conexões ociosas do Redis mantidas aquecidas. O cliente não pré-aquece nenhuma por padrão. | | `REDIS_READ_TIMEOUT` | `3` | Timeout de leitura do Redis, em segundos. | | `REDIS_WRITE_TIMEOUT` | `3` | Timeout de escrita do Redis, em segundos. | | `REDIS_DIAL_TIMEOUT` | `5` | Timeout de dial do Redis, em segundos. | | `REDIS_POOL_TIMEOUT` | `2` | Timeout de checkout do pool do Redis, em segundos. | | `REDIS_MAX_RETRIES` | `3` | Orçamento de novas tentativas de comando do Redis. | | `REDIS_MIN_RETRY_BACKOFF` | `8` | Backoff mínimo de nova tentativa do Redis, em milissegundos. | | `REDIS_MAX_RETRY_BACKOFF` | `1` | Backoff máximo de nova tentativa do Redis, em segundos. | ## Mensageria e circuit breaker | Variável | Padrão / Obrigatório | Descrição | | ---------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CIRCUIT_BREAKER_ENABLED` | `false` — **Obrigatório** como `true` | Conecta o gerenciador de circuit breaker. A integração com o Reporter e os adaptadores de armazenamento de objetos precisam dele, então o boot recusa um valor `false`. | | `RABBITMQ_ENABLED` | `false` | Ativa a conexão com o message broker. | | `RABBITMQ_URL` | `—` | URL completa de conexão com o broker. `Sensitive.` Defina esta variável ou o host, porque o boot recusa ambos vazios quando o broker está ativado. | | `RABBITMQ_HOST` | `—` | Host do broker. | | `RABBITMQ_PORT_AMQP` | `—` | Porta de mensagens do broker. | | `RABBITMQ_PORT_HOST` | `—` | Porta de gerenciamento do broker. | | `RABBITMQ_DEFAULT_USER` | `—` | Nome de usuário do broker. | | `RABBITMQ_DEFAULT_PASS` | `—` | Senha do broker. `Sensitive.` | | `RABBITMQ_VHOST` | `—` | Host virtual do broker. | | `RABBITMQ_QUEUE` | `—` | Nome da fila padrão. | | `RABBITMQ_EXCHANGE` | `—` | Nome do exchange padrão. Um valor vazio publica pelo exchange padrão do broker, que lê a chave de roteamento como um nome de fila. | | `RABBITMQ_HEALTH_CHECK_URL` | `—` | Endpoint HTTP que a probe de readiness chama para verificar o broker. | | `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS` | `—` | Lista de permissão separada por vírgulas dos hosts que a probe de health pode ter como alvo. | | `RABBITMQ_REQUIRE_HEALTH_ALLOWED_HOSTS` | `false` | Força a lista de permissão da probe de health a ser não vazia. | | `RABBITMQ_PUBLISHER_CONFIRM_TIMEOUT_MS` | `5000` | Timeout de confirmação do publisher, em milissegundos. | | `RABBITMQ_PUBLISHER_RECOVERY_INITIAL_MS` | `1000` | Primeiro backoff de recuperação do publisher, em milissegundos. | | `RABBITMQ_PUBLISHER_RECOVERY_MAX_MS` | `30000` | Backoff máximo de recuperação do publisher, em milissegundos. | | `RABBITMQ_PUBLISHER_MAX_RECOVERIES` | `10` | Máximo de tentativas de recuperação do publisher antes que ele desista. | | `CCS_CONSUMER_MAX_REDELIVERIES` | `5` | Máximo de ciclos de nova tentativa que uma mensagem com falha transitória pode ter antes que o consumidor a mova para a dead-letter queue terminal. | ## Outbox O Lerian CCS grava cada mensagem de saída em um outbox transacional, na mesma transação de banco de dados da mudança de estado. A família `OUTBOX_` abaixo configura o dispatcher que a biblioteca de plataforma compartilhada executa. | Variável | Padrão / Obrigatório | Descrição | | ------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- | | `OUTBOX_ENABLED` | `false` | Ativa o worker do outbox. | | `OUTBOX_TABLE_NAME` | `—` | Nome da tabela do outbox. O boot recusa um valor vazio quando o outbox está ativado. | | `OUTBOX_DISPATCH_INTERVAL_SEC` | `2` | Intervalo em segundos entre os ciclos de dispatch. | | `OUTBOX_BATCH_SIZE` | `50` | Máximo de eventos drenados por ciclo de dispatch. | | `OUTBOX_PUBLISH_MAX_ATTEMPTS` | `3` | Máximo de tentativas de publicação por evento dentro de um ciclo. | | `OUTBOX_PUBLISH_BACKOFF_MS` | `200` | Backoff de nova tentativa de publicação, em milissegundos. | | `OUTBOX_RETRY_WINDOW_SEC` | `300` | Janela de nova tentativa em segundos para um evento com falha. | | `OUTBOX_MAX_DISPATCH_ATTEMPTS` | `10` | Máximo de tentativas de dispatch por evento antes que o dispatcher pare de tentar novamente. | | `OUTBOX_PROCESSING_TIMEOUT_SEC` | `600` | Timeout em segundos após o qual o dispatcher recupera um evento travado. | | `OUTBOX_MAX_FAILED_PER_BATCH` | `25` | Máximo de eventos com falha em um lote antes que o dispatcher interrompa esse lote. | | `OUTBOX_INCLUDE_TENANT_METRICS` | `false` | Adiciona labels por tenant às métricas do outbox. | | `OUTBOX_PRIORITY_EVENT_TYPES` | `—` | Tipos de evento separados por vírgulas que o dispatcher envia primeiro. | | `OUTBOX_ALLOW_EMPTY_TENANT` | `false` | Aceita um evento que não carrega contexto de tenant. | ## Overrides de outbox do CCS | Variável | Padrão / Obrigatório | Descrição | | --------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `CCS_OUTBOX_OVERRIDES_ENABLED` | `false` | Ativa os quatro overrides abaixo. Enquanto for `false`, o serviço os carrega e nunca os aplica. | | `CCS_OUTBOX_DISPATCH_INTERVAL_MS` | `1000` | Intervalo de dispatch em milissegundos. Ele tem precedência sobre o intervalo baseado em segundos, o que preserva a precisão de sub-segundo. | | `CCS_OUTBOX_BATCH_SIZE` | `50` | Máximo de eventos que os handlers registrados processam por ciclo. | | `CCS_OUTBOX_MAX_ATTEMPTS` | `10` | Máximo de tentativas de dispatch antes que o dispatcher marque um evento como permanentemente não entregável. | | `CCS_OUTBOX_DLQ_ROUTING_KEY` | `ccs.outbox.dlq` | Chave de roteamento que o publisher de dead-letter carimba em um evento permanentemente não entregável. | ## Streaming A biblioteca de streaming da Lerian lê a família `STREAMING_`, não a configuração do serviço. O [Lerian Streaming Hub](/pt/platform/streaming-hub/what-is-streaming-hub) entrega os eventos publicados. | Variável | Padrão / Obrigatório | Descrição | | -------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STREAMING_ENABLED` | `false` | Chave mestra para a emissão de eventos de negócio. Enquanto estiver desativada, o serviço conecta um emissor no-operation e não publica nada. | | `STREAMING_BROKERS` | **Obrigatório** quando o streaming está ativado | Lista de bootstrap de brokers separada por vírgulas. Uma configuração ativada com uma lista vazia recusa o boot. | | `STREAMING_CLOUDEVENTS_SOURCE` | Fixo | A fonte CloudEvents deste serviço. Ela define o namespace do tópico e o prefixo do tipo de evento. Deixe-a sem definir. Qualquer valor diferente da fonte embutida recusa o boot, mesmo quando o streaming está desativado. | | `STREAMING_CLIENT_ID` | Nome do host | Identificador de cliente do broker usado para diagnósticos do lado do broker. | | `STREAMING_CB_FAILURE_RATIO` | `0.5` | Proporção de falhas que abre o circuit breaker do produtor. | | `STREAMING_CB_MIN_REQUESTS` | `10` | Mínimo de requisições antes que o circuit breaker do produtor avalie a proporção de falhas. | | `STREAMING_CB_TIMEOUT_S` | `30` | Tempo de resfriamento no estado aberto, em segundos, para o circuit breaker do produtor. | | `STREAMING_CLOSE_TIMEOUT_S` | `30` | Janela máxima de drenagem e flush, em segundos, quando o produtor encerra. | | `STREAMING_TLS_ENABLED` | `false` — **Obrigatório** como `true` em `saas` | Ativa o TLS para o dial do broker. A versão mínima é TLS 1.2. No modo `saas`, um dial de broker em texto claro recusa o boot. | | `STREAMING_TLS_CA_CERT` | `—` | Autoridade certificadora PEM codificada em base64 para um broker privado ou on-premises. Um valor vazio usa o trust store do host. Um valor malformado recusa o boot. | | `STREAMING_SASL_MECHANISM` | `—` | Mecanismo de autenticação do broker: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um valor vazio desativa a autenticação do broker. Um mecanismo sem suas credenciais recusa o boot. | | `STREAMING_SASL_USERNAME` | `—` | Nome de usuário de autenticação do broker. | | `STREAMING_SASL_PASSWORD` | `—` | Senha de autenticação do broker. `Sensitive.` | | `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Permite a autenticação do broker por uma conexão em texto claro, o que envia as credenciais sem criptografia. O serviço recusa essa combinação a menos que você defina essa flag. | ## Integração com o STA O Lerian CCS envia todo arquivo de saída ao BACEN por meio do [Lerian STA](/pt/rails/sta/what-is-lerian-sta) e recebe as respostas de volta por ele. | Variável | Padrão / Obrigatório | Descrição | | ----------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STA_ENABLED` | `false` | Conecta o cliente STA, o handler de submissão e a probe de readiness do STA. | | `STA_BASE_URL` | **Obrigatório** quando o STA está ativado | URL base do serviço STA. Um valor vazio recusa o boot. | | `STA_HTTP_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos, no cliente STA. O serviço recorre a 30 segundos para um valor igual ou menor que zero. | | `STA_SD_SERVICE_NAME` | `sta` | Nome no catálogo de serviços que o cliente de discovery resolve para o upstream do STA. | | `STA_FILE_HASH_VERIFY_ENABLED` | `false` | Verifica o digest SHA-256 de um arquivo de entrada baixado em relação ao digest no evento do arquivo. | | `STA_EVENT_HMAC_VERIFY_ENABLED` | `false` | Autentica os eventos de negócio de entrada do STA em relação ao esquema de assinatura compartilhado. Um boot com a verificação ativada e um catálogo de chaves incompleto falha de forma explícita. | | `STA_EVENT_HMAC_MASTER_KEYS` | `—` | Catálogo de chaves mestras `version:hex` compartilhadas com o serviço STA. `Sensitive.` | | `STA_EVENT_HMAC_MASTER_KEY_VERSION` | `—` | Versão do catálogo que o verificador trata como ativa. | | `STA_EVENT_HMAC_TOLERANCE_SECONDS` | `300` | Janela de atualidade, em segundos, para o timestamp assinado. O serviço limita um valor igual ou menor que zero a 300. | ## Integração com o Reporter O Lerian Reporter renderiza o arquivo ACCS001 diário, então é um upstream obrigatório. A probe de readiness o trata como uma dependência rígida. Inicie o Lerian Reporter antes de esperar que o Lerian CCS fique pronto. | Variável | Padrão / Obrigatório | Descrição | | -------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REPORTER_URL` | **Obrigatório** | URL base do serviço Reporter. Um valor vazio recusa o boot. | | `REPORTER_HTTP_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos, no cliente Reporter. O serviço recorre a 30 segundos para um valor igual ou menor que zero. | | `REPORTER_TEMPLATE_ID_ACCS001` | `—` | Identificador do template do Reporter que a renderização do ACCS001 tem como alvo. O Reporter gera esse identificador por ambiente quando você registra o template. Um valor vazio recusa a aprovação do lote com o erro `MYS-0008` e HTTP 503. | | `REPORTER_TEMPLATE_NAME_ACCS001` | `—` | Descrição do template ACCS001 no Reporter. O serviço resolve o template por essa descrição quando você deixa o identificador sem definir. | | `REPORTER_SD_SERVICE_NAME` | `reporter` | Nome no catálogo de serviços que o cliente de discovery resolve para o upstream do Reporter. | | `DETAIL_RENDER_MODE` | `inline` | Caminho de renderização para uma resposta de detalhamento. Apenas `inline` inicia o serviço. Qualquer outro valor recusa o boot. | | `CCS_REPORTER_POLL_INITIAL_DELAY_MS` | `2000` | Primeiro atraso de backoff, em milissegundos, no loop de poll de renderização. | | `CCS_REPORTER_POLL_MAX_DELAY_MS` | `30000` | Atraso máximo de backoff, em milissegundos, no loop de poll de renderização. | | `CCS_REPORTER_POLL_TOTAL_TIMEOUT_SEC` | `1800` | Orçamento total de poll, em segundos. Uma renderização mais antiga que esse orçamento termina como timeout. | | `CCS_REPORTER_POLL_BACKOFF_MULTIPLIER` | `2.0` | Multiplicador aplicado ao atraso após cada poll. O boot recusa um valor abaixo de `1.0`. | ## Descoberta de serviços A biblioteca de descoberta de serviços da Lerian lê a família `SD_`, não a configuração do serviço. O Lerian CCS resolve outros serviços e não se registra, então não precisa de um endereço anunciado. | Variável | Padrão / Obrigatório | Descrição | | ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `SD_ENABLED` | `false` | Ativa a resolução de upstreams pelo servidor de discovery. Enquanto estiver desativada, o serviço usa as URLs de upstream estáticas. | | `SD_ADDRESS` | `—` | Endereço do servidor de discovery como `host:port`. | | `SD_TLS` | `false` | Usa HTTPS para alcançar o servidor de discovery. | | `SD_TLS_SKIP_VERIFY` | `false` | Ignora a verificação de certificado na conexão com o servidor de discovery. | | `SD_TOKEN` | `—` | Token de controle de acesso para o servidor de discovery. `Sensitive.` | | `SD_DIAL_TIMEOUT` | `5s` | Timeout de dial para o cliente de discovery. | | `SD_TLS_HANDSHAKE_TIMEOUT` | `5s` | Timeout de handshake TLS para o cliente de discovery. | | `SD_RESPONSE_HEADER_TIMEOUT` | `10s` | Timeout de header de resposta para o cliente de discovery. | | `SD_SEED_TIMEOUT` | `3s` | Timeout para a primeira leitura do catálogo na inicialização. | | `SD_ALLOW_STALE` | `true` | Permite leituras desatualizadas do catálogo, o que mantém a resolução disponível durante uma troca de líder. | | `SD_EXTERNAL_ADDRESS` | `—` | Endereço externo anunciado para autorregistro. | | `SD_EXTERNAL_PORT` | `0` | Porta externa anunciada para autorregistro. | | `SD_INTERNAL_ADDRESS` | `—` | Endereço interno anunciado para autorregistro. | | `SD_INTERNAL_PORT` | `0` | Porta interna anunciada para autorregistro. | | `SD_INTERNAL_SCHEME` | `—` | Esquema, `http` ou `https`, para a visão interna de um registro. | | `SD_PREFER_VIEW` | `external` | Visão que o cliente prefere quando um serviço registra um endereço externo e um interno. | ## Autenticação | Variável | Padrão / Obrigatório | Descrição | | --------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `PLUGIN_AUTH_ENABLED` | `false` — **Obrigatório** como `true` em `saas` multi-tenant | Ativa a autenticação por bearer token em cada rota `/v1`. Também conduz a emissão de tokens de saída. | | `PLUGIN_AUTH_HOST` | **Obrigatório** quando a autenticação está ativada | URL base do [Lerian Access Manager](/pt/platform/access-manager). | ## Credenciais machine-to-machine O Lerian CCS emite um token de saída por upstream por meio do Lerian Access Manager. Cada upstream carrega seu próprio par de credenciais. Nenhum upstream compartilha uma credencial, e o serviço não tem fallback. | Variável | Padrão / Obrigatório | Descrição | | ------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REPORTER_CLIENT_ID` | **Obrigatório** quando a autenticação está ativada | Identificador de cliente para o upstream do Reporter. | | `REPORTER_CLIENT_SECRET` | **Obrigatório** quando a autenticação está ativada | Segredo de cliente para o upstream do Reporter. `Sensitive.` | | `STA_CLIENT_ID` | **Obrigatório** quando a autenticação está ativada | Identificador de cliente para o upstream do STA. | | `STA_CLIENT_SECRET` | **Obrigatório** quando a autenticação está ativada | Segredo de cliente para o upstream do STA. `Sensitive.` | | `REPORTER_M2M_TARGET_SERVICE` | `—` | Label de métricas para o upstream do Reporter. Um valor vazio recorre ao nome canônico do upstream. | | `STA_M2M_TARGET_SERVICE` | `—` | Label de métricas para o upstream do STA. Um valor vazio recorre ao nome canônico do upstream. | | `M2M_CREDENTIAL_CACHE_TTL_SEC` | `300` | Tempo de vida, em segundos, de uma credencial de saída em cache. | | `AWS_REGION` | `—` | Região para o cliente do AWS Secrets Manager que resolve credenciais por tenant no modo `saas`. Um valor vazio deixa a resolução de região a cargo do SDK de nuvem. | ## Criptografia e idempotência | Variável | Padrão / Obrigatório | Descrição | | ------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CCS_CRYPTO_MASTER_KEY` | **Obrigatório** | Chave mestra AES-256 de 32 bytes codificada em hexadecimal que protege os dados pessoais em repouso. `Sensitive.` O boot falha quando o valor está ausente, é mais curto ou mais longo que 64 caracteres hexadecimais, ou não é hexadecimal. | | `IDEMPOTENCY_KEY_PREFIX` | `idempotency:` | Prefixo base em cada chave de cache de idempotência. | | `IDEMPOTENCY_KEY_TTL_HRS` | `168` | Janela de retenção, em horas, para uma resposta em cache. | | `IDEMPOTENCY_RETRY_WINDOW_SEC` | `—` | Orçamento de nova tentativa legado, em segundos, mantido por compatibilidade. | ## Documentação da API | Variável | Padrão / Obrigatório | Descrição | | --------------------- | -------------------- | ------------------------------------------------------------------ | | `SWAGGER_ENABLED` | `false` | Monta a rota interativa de documentação da API. | | `SWAGGER_TITLE` | Nome do serviço | Título renderizado na especificação da API. | | `SWAGGER_DESCRIPTION` | `—` | Descrição renderizada na especificação da API. | | `SWAGGER_VERSION` | `1.0.0` | Rótulo de versão da API renderizado na especificação. | | `SWAGGER_HOST` | `—` | Substituição de host para a especificação da API. | | `SWAGGER_SCHEMES` | `https` | Esquemas de URL separados por vírgulas que a especificação aceita. | ## Telemetria e métricas | Variável | Padrão / Obrigatório | Descrição | | -------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | `ENABLE_TELEMETRY` | `false` | Conecta o exportador OpenTelemetry. Veja [Observabilidade](/pt/platform/observability) para a visão de plataforma. | | `OTEL_LIBRARY_NAME` | `—` | Nome da biblioteca de instrumentação. | | `OTEL_RESOURCE_SERVICE_NAME` | `—` | Atributo de recurso de nome do serviço. | | `OTEL_RESOURCE_SERVICE_VERSION` | `—` | Atributo de recurso de versão do serviço. Também alimenta a cadeia de versão de readiness. | | `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | `—` | Atributo de recurso de ambiente de deployment. | | `OTEL_EXPORTER_OTLP_ENDPOINT` | `—` | Endereço do coletor para o exportador OpenTelemetry. | ## Rate limits O Lerian CCS aplica cinco níveis de rate limit às rotas `/v1`. O nível de exportação cobre leituras pesadas, como consultas de auditoria e de conciliação. O nível de dispatch cobre escritas pesadas que chamam um upstream. | Variável | Padrão / Obrigatório | Descrição | | ---------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | | `RATE_LIMIT_ENABLED` | `false` — **Obrigatório em produção** como `true` | Ativa o subsistema de rate limit. Um boot em produção recusa o valor `false`. | | `RATE_LIMIT_MAX` | `500` | Teto de requisições do nível padrão por janela. | | `RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível padrão, em segundos. | | `AGGRESSIVE_RATE_LIMIT_MAX` | `100` | Teto de requisições do nível agressivo por janela. | | `AGGRESSIVE_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível agressivo, em segundos. | | `RELAXED_RATE_LIMIT_MAX` | `1000` | Teto de requisições do nível relaxado por janela. | | `RELAXED_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível relaxado, em segundos. | | `EXPORT_RATE_LIMIT_MAX` | `60` | Teto de requisições do nível de exportação por janela. | | `EXPORT_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível de exportação, em segundos. | | `DISPATCH_RATE_LIMIT_MAX` | `30` | Teto de requisições do nível de dispatch por janela. | | `DISPATCH_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível de dispatch, em segundos. | ## Readiness e encerramento | Variável | Padrão / Obrigatório | Descrição | | ------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | `READYZ_PROBE_TIMEOUT_SEC` | `5` | Timeout em segundos para cada probe de dependência. | | `READYZ_DEP_SLOW_THRESHOLD_MS` | `500` | Limite em milissegundos acima do qual uma probe reporta uma dependência como lenta sem falhar a readiness. | | `STARTUP_SELF_PROBE_MAX_DURATION_SEC` | `120` | Janela máxima em segundos para a self-probe de inicialização. | | `STARTUP_SELF_PROBE_INITIAL_DELAY_MS` | `1000` | Primeiro backoff da self-probe, em milissegundos. | | `STARTUP_SELF_PROBE_MAX_DELAY_MS` | `30000` | Backoff máximo da self-probe, em milissegundos. | | `SHUTDOWN_DRAIN_GRACE_PERIOD_SEC` | `15` | Janela em segundos após um sinal de encerramento durante a qual o serviço responde 503 antes de fechar o listener. | | `SHUTDOWN_TOTAL_TIMEOUT_SEC` | `30` | Prazo geral de encerramento, em segundos. | O Lerian CCS expõe `GET /health` para liveness e `GET /readyz` para readiness na porta principal, além de `GET /version` e `GET /metrics`. Com multi-tenancy ativado, ele também expõe `GET /readyz/tenant/{id}`. Veja [Health e readiness](/pt/reference/health-and-readiness) para o contrato da probe e [Operando o Lerian CCS](/pt/rails/ccs/ccs-operations) para a lista de probes. ## Armazenamento de objetos O Lerian CCS lê arquivos de entrada de um bucket e grava arquivos de saída em outro. Ambos aceitam qualquer armazenamento compatível com S3. Um nome de bucket vazio marca a verificação de readiness correspondente como ignorada. | Variável | Padrão / Obrigatório | Descrição | | ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `OBJECT_STORAGE_STA_ENDPOINT` | `—` | Endpoint do bucket de entrada. Um valor vazio seleciona o endpoint de nuvem padrão. | | `OBJECT_STORAGE_STA_REGION` | `us-east-1` | Região do bucket de entrada. | | `OBJECT_STORAGE_STA_BUCKET` | `—` | Nome do bucket de entrada somente leitura. | | `OBJECT_STORAGE_STA_ACCESS_KEY` | `—` | Chave de acesso para o bucket de entrada. `Sensitive.` Deixe sem definir quando uma role de nuvem anexada fornece as credenciais. | | `OBJECT_STORAGE_STA_SECRET_KEY` | `—` | Chave secreta para o bucket de entrada. `Sensitive.` | | `OBJECT_STORAGE_STA_USE_PATH_STYLE` | `false` | Usa endereçamento path-style no bucket de entrada. | | `OBJECT_STORAGE_STA_DISABLE_SSL` | `false` | Desativa o TLS na conexão com o bucket de entrada. | | `OBJECT_STORAGE_STA_MAX_OBJECT_BYTES` | `536870912` | Tamanho máximo de um objeto de entrada, em bytes. | | `OBJECT_STORAGE_CCS_ENDPOINT` | `—` | Endpoint do bucket de saída. Um valor vazio seleciona o endpoint de nuvem padrão. | | `OBJECT_STORAGE_CCS_REGION` | `us-east-1` | Região do bucket de saída. | | `OBJECT_STORAGE_CCS_BUCKET` | `—` | Nome do bucket de saída que guarda os arquivos regulatórios renderizados. | | `OBJECT_STORAGE_CCS_ACCESS_KEY` | `—` | Chave de acesso para o bucket de saída. `Sensitive.` Deixe sem definir quando uma role de nuvem anexada fornece as credenciais. | | `OBJECT_STORAGE_CCS_SECRET_KEY` | `—` | Chave secreta para o bucket de saída. `Sensitive.` | | `OBJECT_STORAGE_CCS_USE_PATH_STYLE` | `false` | Usa endereçamento path-style no bucket de saída. | | `OBJECT_STORAGE_CCS_DISABLE_SSL` | `false` | Desativa o TLS na conexão com o bucket de saída. | | `OBJECT_STORAGE_CCS_MAX_OBJECT_BYTES` | `536870912` | Tamanho máximo de um objeto de saída, em bytes. | ## Retenção e configurações regulatórias | Variável | Padrão / Obrigatório | Descrição | | -------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `CCS_OUTBOUND_RETENTION_DAYS` | `30` | Tempo de vida em dias de um arquivo de saída enviado ao bucket. O serviço aplica 30 dias para um valor igual ou menor que zero. | | `CCS_ACCS009_RETENTION_DAYS` | `30` | Tempo de vida em dias de um relatório de penalidade ACCS009 armazenado. | | `CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC` | `3600` | Intervalo em segundos entre as varreduras de não envio. O boot recusa um valor igual ou menor que zero e um valor acima de 86400. | | `CCS_BACEN_DESTINATARIO_CNPJ_BASE` | `00000000` | Destinatário BACEN de oito dígitos carimbado no envelope do arquivo. Defina o valor real antes de entrar em produção. | | `CCS_ACCS010_DTFIM_MODE` | `transfer_date` | Regra que resolve a data de término obrigatória em uma transferência de relacionamento. | [Integrando com o Lerian CCS](/pt/rails/ccs/ccs-integration) cobre a superfície da API, os códigos de erro e os eventos publicados.