> ## 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 BC Correios: postura de runtime, armazenamentos de dados, a conexão com o BC Correio, chaves de criptografia, IA e configurações de auditoria. O Lerian BC Correios lê sua configuração a partir do ambiente do processo na inicialização. Você define essas variáveis no momento do deploy. Um restart do serviço as torna efetivas. A [referência de configuração do BYOC](/pt/reference/byoc-configuration) documenta a base que todo serviço Go da Lerian compartilha. Para instalar ou atualizar o Lerian BC Correios, consulte o [README do chart do Lerian BC Correios](https://github.com/LerianStudio/helm/tree/main/charts/plugin-bc-correios). 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 fora de desenvolvimento**. "Fora de desenvolvimento" significa um `ENV_NAME` diferente de `development`. `—` 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 | | - | - | - | | `ENV_NAME` | `development` | Ambiente de deploy. Qualquer valor diferente de `development` ativa as verificações de inicialização mais rígidas desta página. Com `production`, o serviço recusa `LOG_LEVEL=debug`. | | `DEPLOYMENT_MODE` | `local` | Postura operacional: `local`, `byoc` ou `saas`. Em `saas`, cada dependência configurada deve usar TLS. Outro valor interrompe o boot. | | `APP_NAME` | `br-correios` | Nome da aplicação. | | `LOG_LEVEL` | `info` | Nível de log: `debug`, `info`, `warn` ou `error`. | | `SERVER_PORT` | `8080` | Porta HTTP de escuta, de 1 a 65535. | | `SERVER_READ_TIMEOUT_SEC` | `30` | Timeout de leitura HTTP, em segundos. | | `SERVER_WRITE_TIMEOUT_SEC` | `30` | Timeout de escrita HTTP, em segundos. | | `SERVER_SHUTDOWN_TIMEOUT_SEC` | `30` | Tempo que o serviço aguarda as requisições abertas no desligamento, em segundos. | | `DEFAULT_TENANT_ID` | `00000000-0000-0000-0000-000000000001` | Tenant de um token sem claim de tenant, no modo single-tenant. Aceita um UUID. | | `STREAMING_CLOUDEVENTS_SOURCE` | `—` | Deixe sem definir ou defina exatamente como `br-correios`. Outro valor interrompe o boot. | ## Licença | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `LICENSE_KEY` | **Obrigatório** | Credencial de licença emitida pela Lerian. Todo ambiente precisa dela. `Sensitive.` | | `ORGANIZATION_IDS` | `global` | Escopo de organização que a licença cobre. | | `READYZ_LICENSE_TIMEOUT_SECONDS` | `5` | Tempo máximo da verificação de licença no `/readyz`, em segundos. | ## CORS e proxies | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `ALLOWED_ORIGINS` | `*` em desenvolvimento. **Obrigatório fora de desenvolvimento** | Lista separada por vírgulas das origens de navegador permitidas. Fora de desenvolvimento, o serviço recusa `*`. | | `TRUSTED_PROXIES` | `127.0.0.1,::1` | Lista separada por vírgulas dos endereços de proxy cujo header `X-Forwarded-For` o serviço aceita como confiável. | ## PostgreSQL | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `POSTGRES_HOST` | `localhost` | Host do banco de dados. | | `POSTGRES_PORT` | `5432` | Porta do banco de dados. | | `POSTGRES_USER` | **Obrigatório fora de desenvolvimento** | Usuário do banco de dados. | | `POSTGRES_PASSWORD` | `—` | Senha do banco de dados. `Sensitive.` | | `POSTGRES_NAME` | **Obrigatório fora de desenvolvimento** | Nome do banco de dados. | | `POSTGRES_SSLMODE` | `disable` | Modo TLS do banco de dados. Fora de desenvolvimento, o serviço recusa `disable`. | | `POSTGRES_MAX_CONNS` | `50` | Máximo de conexões no pool. | | `POSTGRES_MIN_CONNS` | `5` | Mínimo de conexões no pool. | ## Cache (Valkey) O cache guarda as chaves de idempotência, os contadores de rate limit, a cota compartilhada de requisições ao BACEN e a cota de download de anexos. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `CACHE_ADDR` | `localhost:6379` | Endereço do cache como `host:port`. | | `CACHE_PASSWORD` | `—` | Senha do cache. `Sensitive.` | | `CACHE_DB` | `0` | Número do banco de dados lógico do cache. | | `CACHE_TLS` | `false` | Usa TLS na conexão com o cache. | | `CACHE_CA_CERT` | `—` | Certificado de CA personalizado para a conexão TLS com o cache, em PEM ou PEM codificado em base64. Sem ele, o serviço usa o repositório de confiança do sistema. | | `CACHE_TTL_SEC` | `60` | Tempo que o serviço mantém as configurações do tenant no cache, em segundos. | | `CACHE_POOL_SIZE` | `10` | Tamanho do pool de conexões do cache. | | `CACHE_MAX_ACTIVE_CONNS` | `20` | Máximo de conexões ativas com o cache. | ## RabbitMQ (pipeline de auditoria) | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `RABBITMQ_URL` | `amqp://guest:guest@localhost:5672/` | URL do broker. Fora de desenvolvimento, o serviço recusa as credenciais `guest:guest`, e uma falha de conexão interrompe o boot. `Sensitive.` | ## Criptografia e idempotência | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `ENCRYPTION_KEY` | **Obrigatório fora de desenvolvimento** | Chave AES-256-GCM das credenciais do BC Correio armazenadas, das chaves de API de IA e das respostas de idempotência. Exatamente 32 bytes. `Sensitive.` | | `AMQP_SIGNING_KEY` | Derivada de `ENCRYPTION_KEY` | Chave que assina as mensagens de auditoria no RabbitMQ. Quando definida, tem exatamente 32 bytes e é diferente de `ENCRYPTION_KEY`. `Sensitive.` | | `IDEMPOTENCY_TTL_SEC` | `86400` | Tempo que o serviço guarda uma chave `X-Idempotency`, em segundos, de 90 a 86400. | ## Conexão com o BC Correio | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `BC_CORREIO_ENVIRONMENT` | `—` | Ambiente do BACEN: `homologation` ou `production`. Ele seleciona o host do BC Correio. | | `BC_CORREIO_ENDPOINT_URL` | A partir de `BC_CORREIO_ENVIRONMENT` | URL completa do endpoint do BC Correio. Quando definida, tem precedência sobre `BC_CORREIO_ENVIRONMENT`. | | `BC_CORREIO_TLS_MIN_VERSION` | `TLSv1.2` | Versão mínima de TLS para o BC Correio. | | `BC_CORREIO_CONNECT_TIMEOUT_SEC` | `30` | Timeout de uma chamada ao BC Correio, em segundos, de 1 a 300. | | `BC_CORREIO_RATE_LIMIT_PER_MINUTE` | `50` | Máximo de chamadas ao BC Correio por minuto para cada credencial Sisbacen, de 1 a 60. | | `BC_CORREIO_RATE_LIMIT_PER_HOUR` | `2700` | Máximo de chamadas ao BC Correio por hora para cada credencial Sisbacen, de 1 a 3000. | | `BC_CORREIO_RATE_LIMIT_MAX_WAIT_SEC` | `90` | Espera máxima de uma chamada por uma vaga livre na cota, em segundos, de 1 a 300. | ## Armazenamento de objetos | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `OBJECT_STORAGE_PROVIDER` | `s3` | Armazenamento de anexos: `s3` para armazenamento de objetos compatível com S3, ou `local` para o sistema de arquivos local. | | `OBJECT_STORAGE_ENDPOINT` | `—` | URL do endpoint compatível com S3. | | `OBJECT_STORAGE_REGION` | `us-east-1` | Região do armazenamento. | | `OBJECT_STORAGE_BUCKET` | `bc-correios-attachments` | Bucket dos anexos. | | `OBJECT_STORAGE_ACCESS_KEY` | `—` | Chave de acesso do armazenamento. `Sensitive.` | | `OBJECT_STORAGE_SECRET_KEY` | `—` | Chave secreta do armazenamento. `Sensitive.` | | `OBJECT_STORAGE_PATH_STYLE` | `false` | Usa endereços S3 path-style. | | `OBJECT_STORAGE_LOCAL_PATH` | `/data/bc-correios/storage` | Diretório base do provedor `local`. | ## Multi-tenancy | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `MULTI_TENANT_ENABLED` | `false` | Ativa o modo multi-tenant. Exige `PLUGIN_AUTH_ENABLED=true` e um `ENV_NAME` igual a `staging` ou `production`. | | `MULTI_TENANT_URL` | **Obrigatório no modo multi-tenant** | URL do Tenant Manager. Deve usar `https://`, a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` seja `true`. | | `MULTI_TENANT_SERVICE_API_KEY` | **Obrigatório no modo multi-tenant** | Chave de API do Tenant Manager. `Sensitive.` | | `MULTI_TENANT_REDIS_HOST` | **Obrigatório no modo multi-tenant** | Host do Redis que transporta os eventos de tenant. | | `MULTI_TENANT_REDIS_PORT` | `6379` | Porta do Redis de eventos de tenant. | | `MULTI_TENANT_REDIS_PASSWORD` | `—` | Senha do Redis de eventos de tenant. `Sensitive.` | | `MULTI_TENANT_REDIS_TLS` | `false` | Usa TLS no Redis de eventos de tenant. | | `MULTI_TENANT_REDIS_CA_CERT` | `—` | Certificado de CA personalizado para o Redis de eventos de tenant, em PEM ou PEM codificado em base64. | | `MULTI_TENANT_EVENT_CHANNEL` | **Obrigatório no modo multi-tenant** | Canal Redis dos eventos de tenant. | | `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Falhas antes que o circuit breaker do Tenant Manager abra. | | `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Tempo até o circuit breaker do Tenant Manager tentar de novo, em segundos. | | `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Número máximo de pools de banco de dados de tenant. | | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Tempo ocioso até o serviço fechar um pool de tenant, em segundos. | | `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo entre as verificações de conexões ociosas de tenant, em segundos. | | `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | `0` | Máximo de conexões abertas em cada pool de tenant. `0` mantém o padrão da biblioteca. | | `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | `0` | Máximo de conexões ociosas em cada pool de tenant. `0` mantém o padrão da biblioteca. | | `MULTI_TENANT_ALLOW_INSECURE_HTTP` | `false` | Permite endereços `http://` para o Tenant Manager e o Access Manager no modo multi-tenant. | | `STREAMING_OUTBOX_MULTI_TENANT_ENABLED` | `false` | Deve ser `true` quando `MULTI_TENANT_ENABLED` é `true`, ou o serviço não inicia. | ## IA | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `FEATURE_AI_INSIGHTS_ENABLED` | `true` | Ativa ou desativa a análise de correspondências por IA. | | `AI_DEFAULT_MODEL_OPENAI` | `gpt-4o-mini` | Modelo de um tenant que usa `openai` e não define modelo. | | `AI_DEFAULT_MODEL_ANTHROPIC` | `claude-sonnet-4-20250514` | Modelo de um tenant que usa `anthropic` e não define modelo. | | `AI_DEFAULT_MODEL_GEMINI` | `gemini-2.0-flash` | Modelo de um tenant que usa `gemini` e não define modelo. | | `AI_DEFAULT_SYSTEM_PROMPT` | Prompt embutido | System prompt padrão da análise por IA. | | `AI_TENANT_RATE_LIMIT_PER_MIN` | `50` | Máximo de chamadas de IA por minuto para cada tenant. | | `AI_CIRCUIT_BREAKER_THRESHOLD` | `5` | Falhas seguidas antes que o circuit breaker de IA de um tenant e provedor abra. | | `AI_CIRCUIT_BREAKER_HALF_OPEN_SEC` | `30` | Tempo até um circuit breaker de IA aberto tentar uma chamada de novo, em segundos. | | `AI_TENANT_MAX_CONCURRENT` | `3` | Máximo de chamadas de IA simultâneas para cada tenant. | | `AI_GLOBAL_MAX_CONCURRENT` | `15` | Máximo de chamadas de IA simultâneas para a instância inteira. | | `AI_ACQUIRE_TIMEOUT_SEC` | `30` | Espera máxima de uma chamada de IA em segundo plano por uma vaga livre, em segundos. | | `AI_HTTP_ACQUIRE_TIMEOUT_SEC` | `5` | Espera máxima de uma requisição de reanálise por uma vaga livre, em segundos. Depois dela, a requisição responde `202`. | | `AI_INLINE_PROVIDER_TIMEOUT_SEC` | `15` | Timeout de uma chamada de IA durante o ciclo de polling, em segundos. | | `AI_BODY_INLINE_THRESHOLD` | `200` | Tamanho mínimo do corpo, em caracteres, para uma análise durante o ciclo de polling. | ## Transmissão | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `TRANSMISSION_PENDING_GRACE_SEC` | `30` | Janela de tolerância de um envio `PENDING`, em segundos, de 5 a 300. Quando uma repetição encontra um envio `PENDING` mais antigo que ela, o envio passa a `AMBIGUOUS`. | | `TRANSMISSION_RETRY_MAX_ATTEMPTS` | `3` | Tentativas de registrar um envio que o BC Correio aceitou, de 1 a 10. | | `TRANSMISSION_METRICS_QUERY_TIMEOUT_SEC` | `2` | Tempo máximo da consulta ao banco de dados por trás da métrica de envios pendentes, em segundos, de 1 a 8. | ## Auditoria | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `FEATURE_AUDIT_ENABLED` | `true` | Ativa ou desativa o pipeline de auditoria. Fora de desenvolvimento, o serviço recusa `false`. | | `AUDIT_OUTBOX_POLL_INTERVAL_SEC` | `2` | Intervalo entre as leituras do outbox de auditoria, em segundos, de 1 a 300. | | `AUDIT_OUTBOX_BATCH_LIMIT` | `50` | Máximo de eventos de auditoria em uma leitura para cada tenant, de 1 a 1000. | | `AUDIT_OUTBOX_MAX_ATTEMPTS` | `50` | Tentativas de publicar um evento de auditoria, de 1 a 1000. | | `AUDIT_OUTBOX_RETENTION_DAYS` | `7` | Dias até o serviço excluir uma linha publicada do outbox, de 1 a 90. | ## Autenticação | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `PLUGIN_AUTH_ENABLED` | **Obrigatório** | `true` ou `false`. Um valor em branco interrompe o boot. `false` exige um `ENV_NAME` igual a `development`, `develop`, `dev`, `local` ou `test`, e nunca funciona com `DEPLOYMENT_MODE=saas`. Com `false`, as requisições ainda precisam de um bearer token. | | `PLUGIN_AUTH_ADDRESS` | **Obrigatório quando `PLUGIN_AUTH_ENABLED` é `true`** | Endereço do Lerian Access Manager. No modo multi-tenant, deve usar `https://`, a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` seja `true`. | ## Telemetria e métricas | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `TRACING_ENABLED` | `false` | Exporta traces por OTLP. | | `METRICS_ENABLED` | `false` | Exporta métricas por OTLP. | | `OTEL_EXPORTER_OTLP_ENDPOINT` | `—` | Endpoint do coletor OTLP. | | `OTEL_SERVICE_NAME` | `br-correios` | Nome do serviço na telemetria. | | `OTEL_LIBRARY_NAME` | `br-correios` | Nome da biblioteca de instrumentação na telemetria. | | `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Valor de `ENV_NAME` | Ambiente de deploy na telemetria. | | `METRICS_PROMETHEUS_ENABLED` | `false` | Abre um listener separado para o scrape do Prometheus. | | `METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9076` | Endereço do listener do Prometheus. | ## Rate limits | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `RATE_LIMIT_ENABLED` | `false` | Ativa as cotas de requisições por tenant e operação. | | `RATE_LIMIT_REDIS_TIMEOUT_MS` | `500` | Timeout de uma chamada de contador de rate limit ao cache, em milissegundos. | | `ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN` | `500` | Cota de download de anexos por tenant, em megabytes por minuto, de 1 a 102400. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.