Variáveis de ambiente

Esta referência lista as variáveis de ambiente que configuram o Matcher, o motor de conciliação. A Lerian define esses valores quando instala ou atualiza o Matcher. Use esta página para saber o que cada configuração faz, qual é o seu padrão e o que o Matcher verifica na inicialização. Quando uma variável obrigatória está ausente ou é inválida, o Matcher não inicia. Com ENV_NAME=production, o Matcher aplica verificações extras. A coluna Obrigatório indica cada uma como “Produção”. Algumas variáveis definem apenas o valor inicial de um documento de runtime. A Lerian pode alterar esses documentos em um Matcher em execução por meio do Systemplane. A seção documentos de runtime lista esses documentos.

Aplicação

Variável	Descrição	Padrão	Obrigatório
`ENV_NAME`	Nome do ambiente. Com `production`, o Matcher desabilita o Swagger e recusa um endpoint inseguro de armazenamento de objetos. Ele também aplica as verificações marcadas como “Produção” nesta página.	`development`	Não
`LOG_LEVEL`	Nível de log: `debug`, `info`, `warn`, `error` ou `fatal`. Qualquer outro valor interrompe a inicialização.	`info`	Não
`DEPLOYMENT_MODE`	Modelo de deploy: `saas`, `byoc` ou `local`, em maiúsculas ou minúsculas. Com `saas` ou `byoc`, o Matcher exige `IDEMPOTENCY_HMAC_SECRET`, recusa um valor `http` em `PUBLIC_BASE_SCHEMES` e recusa um `PUBLIC_BASE_HOST` malformado. A resposta de `/readyz` também informa o valor.	—	Sim
`SHUTDOWN_GRACE_PERIOD_SEC`	Segundos que o Matcher espera o trabalho em andamento terminar quando ele para.	`12`	Não
`ALLOW_INSECURE_TLS`	Permite conexões sem TLS com PostgreSQL, Redis e RabbitMQ. Sem `true`, o Matcher recusa essas conexões. Os padrões desta página não usam TLS.	—	Não

Servidor HTTP

Variável	Descrição	Padrão	Obrigatório
`SERVER_ADDRESS`	Endereço de bind da API.	`:4018`	Não
`HTTP_READ_TIMEOUT`	Tempo máximo para ler uma requisição, como uma duração do tipo `15m`. Também cobre uploads de arquivo em streaming.	`15m`	Não
`HTTP_BODY_LIMIT_BYTES`	Tamanho máximo do corpo, em bytes, para as rotas que armazenam a requisição inteira em buffer.	`104857600`	Não
`CORS_ALLOWED_ORIGINS`	Origens CORS permitidas (CSV).	`http://localhost:3000`	Produção: pelo menos uma origem, e não `*`
`CORS_ALLOWED_METHODS`	Métodos CORS permitidos (CSV).	`GET,POST,PUT,PATCH,DELETE,OPTIONS`	Não
`CORS_ALLOWED_HEADERS`	Headers CORS permitidos (CSV).	`Origin,Content-Type,Accept,Authorization,X-Request-ID`	Não
`SERVER_TLS_CERT_FILE`	Caminho do certificado TLS. Defina junto com `SERVER_TLS_KEY_FILE`. Um certificado habilita o HSTS.	—	Não
`SERVER_TLS_KEY_FILE`	Caminho da chave privada TLS. Defina junto com `SERVER_TLS_CERT_FILE`.	—	Não
`TLS_TERMINATED_UPSTREAM`	Defina como `true` quando um load balancer termina o TLS na frente do Matcher. Habilita o HSTS.	`false`	Não
`TRUSTED_PROXIES`	CIDRs de proxies confiáveis (CSV) para resolver o IP do cliente. O Matcher recusa `*`, `0.0.0.0/0` e `::/0`.	—	Produção
`PUBLIC_BASE_HOST`	`host[:port]` público que o Matcher coloca nas URLs de webhook e de callback que emite. Use o host puro, sem esquema nem caminho. Quando vazio, o Matcher usa `SERVER_ADDRESS`.	—	Não
`PUBLIC_BASE_SCHEMES`	Esquema dessas URLs públicas.	`https`	Não
`SWAGGER_ENABLED`	Serve a interface do Swagger. `ENV_NAME=production` a desabilita.	`false`	Não

Autenticação

Variável	Descrição	Padrão	Obrigatório
`PLUGIN_AUTH_ENABLED`	Habilita a autenticação do Access Manager. O Matcher também aceita o nome antigo `AUTH_ENABLED`. Quando os dois nomes têm valores diferentes, o Matcher se recusa a iniciar.	`false`	Não
`PLUGIN_AUTH_ADDRESS`	Endereço do Access Manager. O Matcher também aceita o nome antigo `AUTH_SERVICE_ADDRESS`, com a mesma regra de conflito.	—	Quando o provedor é `plugin-auth`
`AUTH_PROVIDER`	Provedor de autenticação: `plugin-auth` ou `disabled`. Quando não definido, `PLUGIN_AUTH_ENABLED` o seleciona. Um valor explícito prevalece. Qualquer outro valor interrompe a inicialização.	—	Não
`AUTH_REQUIRED`	Com `true` e a autenticação desabilitada, cada operação em `/v1` que precisa de uma permissão responde `503`.	`false`	Não
`AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED`	Com `true` e a autenticação desabilitada, cada operação em `/v1` que precisa de uma permissão ainda exige um bearer token e responde `401` sem ele. O Matcher não chama o Access Manager para essas requisições. Sem `AUTH_JWT_VERIFY_CERT` ou `AUTH_JWT_VERIFY_CERT_PATH`, o Matcher não verifica a assinatura do token.	`false`	Não
`AUTH_M2M_PRODUCT_FORWARD_ENABLED`	Com `true`, o Matcher também envia o nome do seu produto ao Access Manager quando verifica um token de aplicação.	`false`	Não
`AUTH_TIMEOUT`	Tempo limite da verificação no Access Manager de uma requisição, com as novas tentativas incluídas, como uma duração do tipo `5s`.	`30s`	Não
`AUTH_CACHE_TTL`	Tempo que o Matcher guarda cada decisão do Access Manager, como uma duração do tipo `60s`. Uma mudança de permissão pode levar esse tempo para valer. Quando não definida, o Matcher não guarda nenhuma decisão.	—	Não
`AUTH_BREAKER_ENABLED`	Habilita um circuit breaker nas chamadas ao Access Manager. Depois de 5 chamadas seguidas com falha, ele interrompe as chamadas por 30 segundos. Nesse intervalo, o Matcher recusa cada requisição que não tem uma aprovação em cache.	`false`	Não
`AUTH_RETRY_MAX`	Máximo de novas tentativas de uma chamada ao Access Manager que falha sem uma decisão. `0` desabilita as novas tentativas.	`0`	Não
`AUTH_JWT_VERIFY_CERT`	Uma ou mais chaves públicas RSA ou certificados X.509 em PEM, separados por quebras de linha. Com uma chave carregada, o Matcher verifica a assinatura RS256 e a expiração de cada bearer token, e responde `401` quando a verificação falha. Tem precedência sobre `AUTH_JWT_VERIFY_CERT_PATH`.	—	Não
`AUTH_JWT_VERIFY_CERT_PATH`	Caminho de um arquivo com o mesmo conteúdo. O Matcher o lê apenas quando `AUTH_JWT_VERIFY_CERT` está vazia.	—	Não
`AUTH_JWT_ISSUER`	Com uma chave carregada, o Matcher responde `401` a um token cuja claim `iss` difere deste valor.	—	Não

Tenancy

Variável	Descrição	Padrão	Obrigatório
`DEFAULT_TENANT_ID`	ID do tenant no modo single-tenant. Precisa ser um UUID.	`11111111-1111-1111-1111-111111111111`	Não
`DEFAULT_TENANT_SLUG`	Slug do tenant no modo single-tenant.	`default`	Não
`MULTI_TENANT_ENABLED`	Habilita o modo multi-tenant por meio do Tenant Manager. Exige o provedor `plugin-auth`, um ambiente `staging` ou `production`, `MULTI_TENANT_URL` e `MULTI_TENANT_SERVICE_API_KEY`.	`false`	Não
`ENVIRONMENT_NAME`	Nome do ambiente que o modo multi-tenant verifica. Quando não definido, o Matcher usa `ENV_NAME`.	—	Não
`MULTI_TENANT_URL`	Origem do Tenant Manager: `http` ou `https`, sem caminho e sem informação de usuário.	—	Modo multi-tenant. Produção: `https`
`MULTI_TENANT_SERVICE_API_KEY`	Chave de API que o Matcher envia ao Tenant Manager. Sensível.	—	Modo multi-tenant
`MULTI_TENANT_ENVIRONMENT`	Nome do ambiente multi-tenant. Quando não definido, o Matcher usa `ENV_NAME`. O modo multi-tenant precisa de um dos dois.	—	Não
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	Permite uma origem `http` para o Tenant Manager.	`false`	Não
`MULTI_TENANT_REDIS_HOST`	Host do Redis que transporta os eventos de ciclo de vida dos tenants.	—	Não
`MULTI_TENANT_REDIS_PORT`	Porta desse Redis.	`6379`	Não
`MULTI_TENANT_REDIS_PASSWORD`	Senha desse Redis. Sensível.	—	Não
`MULTI_TENANT_REDIS_TLS`	Usa TLS nesse Redis.	`false`	Não
`MULTI_TENANT_MAX_TENANT_POOLS`	Número máximo de pools de conexão de tenants que o Matcher mantém abertos.	`100`	Não
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Segundos até o Matcher fechar um pool de tenant ocioso.	`300`	Não
`MULTI_TENANT_TIMEOUT`	Timeout, em segundos, de uma chamada ao Tenant Manager.	`30`	Não
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Chamadas ao Tenant Manager com falha até o circuit breaker abrir.	`5`	Não
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	Segundos em que o circuit breaker fica aberto.	`30`	Não
`MULTI_TENANT_CACHE_TTL_SEC`	Segundos em que o Matcher mantém em cache a configuração de um tenant.	`120`	Não
`MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`	Segundos entre verificações das configurações de conexão dos tenants.	`30`	Não
`MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT`	Conexões abertas por banco de dados de tenant. O valor é ao mesmo tempo o padrão e o teto. `0` mantém os padrões da biblioteca.	`0`	Não
`MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT`	Conexões ociosas por banco de dados de tenant, com a mesma regra.	`0`	Não

PostgreSQL

Variável	Descrição	Padrão	Obrigatório
`POSTGRES_HOST`	Host do banco de dados primário.	`localhost`	Não
`POSTGRES_PORT`	Porta do banco de dados primário.	`5432`	Não
`POSTGRES_USER`	Usuário do banco de dados primário.	`matcher`	Não
`POSTGRES_PASSWORD`	Senha do banco de dados primário. Sensível. O padrão é um valor de desenvolvimento.	Valor de desenvolvimento	Produção: não vazia e diferente de um valor de desenvolvimento
`POSTGRES_DB`	Nome do banco de dados.	`matcher`	Não
`POSTGRES_SSLMODE`	`sslmode` do PostgreSQL.	`disable`	Não
`POSTGRES_TLS_REQUIRED`	Recusa a inicialização quando `POSTGRES_SSLMODE` é `disable`.	`false`	Não
`POSTGRES_REPLICA_HOST`	Host da réplica de leitura. Sem ele, o Matcher ignora as outras variáveis de réplica.	—	Não
`POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_DB`, `POSTGRES_REPLICA_SSLMODE`	Conexão da réplica de leitura. Cada uma usa o valor do primário quando não definida. A senha é sensível.	Valor do primário	Não
`POSTGRES_REPLICA_TLS_REQUIRED`	Mesma regra de `POSTGRES_TLS_REQUIRED`, para a réplica.	`false`	Não
`POSTGRES_MAX_OPEN_CONNS`	Máximo de conexões abertas.	`25`	Não
`POSTGRES_MAX_IDLE_CONNS`	Máximo de conexões ociosas.	`5`	Não
`POSTGRES_CONN_MAX_LIFETIME_MINS`	Minutos até o Matcher substituir uma conexão.	`30`	Não
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	Minutos até o Matcher fechar uma conexão ociosa.	`5`	Não
`POSTGRES_CONNECT_TIMEOUT_SEC`	Timeout de conexão, em segundos.	`10`	Não
`POSTGRES_QUERY_TIMEOUT_SEC`	Timeout de consulta, em segundos. `0` usa o padrão.	`30`	Não
`SYSTEMPLANE_POSTGRES_DSN`	String de conexão do armazenamento do Systemplane. Quando não definida, o Matcher a monta a partir da conexão primária. Sensível.	—	Não

Redis

Variável	Descrição	Padrão	Obrigatório
`REDIS_HOST`	Endereço do Redis. Um endereço seleciona o modo standalone. Uma lista CSV seleciona o modo Cluster. Com `REDIS_MASTER_NAME`, a lista indica nós Sentinel.	`localhost:6379`	Não
`REDIS_MASTER_NAME`	Nome do master no Sentinel.	—	Não
`REDIS_PASSWORD`	Senha do Redis. Sensível.	—	Produção
`REDIS_DB`	Número do banco de dados do Redis.	`0`	Não
`REDIS_TLS`	Usa TLS no Redis.	`false`	Não
`REDIS_TLS_REQUIRED`	Recusa a inicialização quando `REDIS_TLS` é `false`.	`false`	Não
`REDIS_CA_CERT`	Certificado da CA para o TLS do Redis.	—	Não
`REDIS_POOL_SIZE`	Tamanho do pool de conexões.	`10`	Não
`REDIS_MIN_IDLE_CONNS`	Mínimo de conexões ociosas.	`2`	Não
`REDIS_READ_TIMEOUT_MS`	Timeout de leitura, em milissegundos.	`3000`	Não
`REDIS_WRITE_TIMEOUT_MS`	Timeout de escrita, em milissegundos.	`3000`	Não
`REDIS_DIAL_TIMEOUT_MS`	Timeout de discagem, em milissegundos.	`5000`	Não

RabbitMQ

Variável	Descrição	Padrão	Obrigatório
`RABBITMQ_URI`	Esquema de conexão: `amqp` ou `amqps`.	`amqp`	Não
`RABBITMQ_HOST`	Host do broker.	`localhost`	Não
`RABBITMQ_PORT`	Porta do broker.	`5672`	Não
`RABBITMQ_USER`	Usuário do broker.	`matcher_admin`	Produção: diferente de `guest`
`RABBITMQ_PASSWORD`	Senha do broker. Sensível. O padrão é um valor de desenvolvimento.	Valor de desenvolvimento	Produção: diferente de `guest` e de um valor de desenvolvimento
`RABBITMQ_VHOST`	Virtual host.	`/`	Não
`RABBITMQ_HEALTH_URL`	URL da API de gerenciamento para o health check.	`http://localhost:15672`	Não
`RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK`	Permite uma URL `http` de health check.	`false`	Produção: `false`
`RABBITMQ_TLS_REQUIRED`	Recusa a inicialização quando `RABBITMQ_URI` não é `amqps`.	`false`	Não

Armazenamento de objetos

O Matcher grava os arquivos de exportação neste armazenamento compatível com S3.

Variável	Descrição	Padrão	Obrigatório
`OBJECT_STORAGE_ENDPOINT`	URL do endpoint de armazenamento.	`http://localhost:8333`	Com o worker de exportação ou de limpeza habilitado. Produção: `https`
`OBJECT_STORAGE_REGION`	Região do armazenamento.	`us-east-1`	Não
`OBJECT_STORAGE_BUCKET`	Bucket dos arquivos de exportação.	`matcher-exports`	Com o worker de exportação ou de limpeza habilitado
`OBJECT_STORAGE_ACCESS_KEY_ID`	ID da chave de acesso estática. Sem as duas chaves estáticas, o Matcher usa a cadeia padrão de credenciais da AWS.	—	Não
`OBJECT_STORAGE_SECRET_ACCESS_KEY`	Chave secreta de acesso estática. Sensível.	—	Não
`OBJECT_STORAGE_USE_PATH_STYLE`	Usa endereços de bucket no estilo de caminho.	`true`	Não
`OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT`	Permite um endpoint `http`. O Matcher aceita `true` apenas quando `ENV_NAME` é `development`, `dev`, `local` ou `test`.	`false`	Não
`OBJECT_STORAGE_TLS_REQUIRED`	Recusa a inicialização quando o endpoint não é `https`.	`false`	Não

Timeouts de infraestrutura

Variável	Descrição	Padrão	Obrigatório
`INFRA_CONNECT_TIMEOUT_SEC`	Total de segundos que o Matcher permite para as conexões com as dependências na inicialização. O valor precisa ser pelo menos `1`, e o Matcher o limita a `300`.	`30`	Não
`HEALTH_CHECK_TIMEOUT_MS`	Timeout, em milissegundos, de cada verificação de readiness. Prevalece sobre `HEALTH_CHECK_TIMEOUT_SEC`.	`800`	Não
`HEALTH_CHECK_TIMEOUT_SEC`	Timeout, em segundos, de cada verificação de readiness. O Matcher o usa apenas quando `HEALTH_CHECK_TIMEOUT_MS` é `0`.	`5`	Não

Telemetria

Variável	Descrição	Padrão	Obrigatório
`ENABLE_TELEMETRY`	Habilita a exportação do OpenTelemetry.	`false`	Não
`OTEL_RESOURCE_SERVICE_NAME`	Nome do serviço na telemetria.	`matcher`	Não
`OTEL_LIBRARY_NAME`	Nome da biblioteca de instrumentação.	`github.com/LerianStudio/matcher`	Não
`OTEL_RESOURCE_SERVICE_VERSION`	Versão do serviço na telemetria.	`1.1.0`	Não
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Ambiente de deploy na telemetria. Com a telemetria habilitada, precisa ser `development`, `staging` ou `production`.	`development`	Não
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint do coletor OTLP.	`localhost:4317`	Não
`OTEL_TRACES_SAMPLER`	Sampler de traces, lido pelo SDK do OpenTelemetry.	`parentbased_always_on`	Não
`OTEL_TRACES_SAMPLER_ARG`	Argumento do sampler, como uma proporção.	—	Não
`ALLOW_INSECURE_OTEL`	Permite um endpoint de coletor sem criptografia quando o ambiente de deploy é `production`. Sem ela, o Matcher roda sem telemetria nesse caso.	—	Não
`DB_METRICS_INTERVAL_SEC`	Segundos entre amostras das métricas do pool do banco de dados.	`15`	Não

Rate limits

Cada limite é um número máximo de requisições por janela. Um máximo precisa estar entre 1 e 1000000. Uma janela precisa estar entre 1 e 86400 segundos.

Variável	Descrição	Padrão	Obrigatório
`RATE_LIMIT_ENABLED`	Habilita os limites desta seção. Quando ela não está definida ou é `false`, o Matcher não aplica nenhum deles, seja qual for o conteúdo do documento de runtime `rate_limit`.	`false`	Não
`ALLOW_RATELIMIT_FAIL_OPEN`	Comportamento quando o Matcher não consegue atualizar um contador de limite no Redis. Com `true`, a requisição continua sem limite. Com `false`, o Matcher responde `503`.	`false`	Não
`RATE_LIMIT_REDIS_TIMEOUT_MS`	Milissegundos que uma atualização de contador no Redis pode levar antes de a requisição parar de esperar por ela.	`500`	Não
`RATE_LIMIT_MAX`	Limite geral da API.	`100`	Não
`RATE_LIMIT_EXPIRY_SEC`	Janela geral da API, em segundos.	`60`	Não
`EXPORT_RATE_LIMIT_MAX`	Limite das requisições de exportação.	`10`	Não
`EXPORT_RATE_LIMIT_EXPIRY_SEC`	Janela de exportação, em segundos.	`60`	Não
`DISPATCH_RATE_LIMIT_MAX`	Limite das requisições de despacho de exceções.	`50`	Não
`DISPATCH_RATE_LIMIT_EXPIRY_SEC`	Janela de despacho, em segundos.	`60`	Não
`ADMIN_RATE_LIMIT_MAX`	Limite das rotas administrativas `/system`.	`30`	Não
`ADMIN_RATE_LIMIT_EXPIRY_SEC`	Janela administrativa, em segundos.	`60`	Não

Idempotência

Variável	Descrição	Padrão	Obrigatório
`IDEMPOTENCY_HMAC_SECRET`	Segredo usado como chave dos registros de idempotência. Precisa ter pelo menos 32 bytes em todos os modos. Um novo segredo torna indisponíveis os replays em cache anteriores. Sensível.	—	`saas`, `byoc`
`IDEMPOTENCY_RETIRED_HMAC_SECRET`	Segredo da versão anterior. Defina quando você trocar `IDEMPOTENCY_HMAC_SECRET` com a ponte de transição habilitada. Sensível.	—	Não
`IDEMPOTENCY_CUTOVER_BRIDGE`	Lê também os registros de idempotência da versão anterior, para que uma nova tentativa durante uma atualização não execute duas vezes.	`true`	Não
`IDEMPOTENCY_RETRY_WINDOW_SEC`	Segundos até uma requisição com falha poder executar de novo com a mesma chave.	`300`	Não
`IDEMPOTENCY_SUCCESS_TTL_HOURS`	Horas em que o Matcher guarda uma resposta de sucesso para replay.	`168`	Não

Outbox

Variável	Descrição	Padrão	Obrigatório
`OUTBOX_DISPATCH_INTERVAL_SEC`	Segundos entre execuções de despacho do outbox.	`2`	Não
`OUTBOX_RETRY_WINDOW_SEC`	Segundos até o Matcher tentar de novo um evento do outbox com falha.	`300`	Não

Ingestão

Variável	Descrição	Padrão	Obrigatório
`INGESTION_MAX_UPLOAD_BYTES`	Tamanho máximo de upload, em bytes. O limite vale para o corpo multipart inteiro.	`1073741824`	Não
`DEDUPE_TTL_SEC`	Segundos em que o Matcher mantém uma chave de detecção de duplicidade no Redis.	`3600`	Não

Correspondência

Variável	Descrição	Padrão	Obrigatório
`MATCH_RUN_WORKER_ENABLED`	Executa o worker que roda as execuções de correspondência.	`true`	Não
`MATCH_RUN_WORKER_POLL_INTERVAL_SEC`	Segundos entre consultas por novas execuções de correspondência.	`3`	Não
`MATCHING_CANDIDATE_BATCH_SIZE`	Candidatos por lote de correspondência. O Matcher o limita a `100000`.	`10000`	Não
`SCHEDULER_INTERVAL_SEC`	Segundos entre verificações de agendamentos vencidos.	`60`	Não
`BINDING_SCHEDULER_ENABLED`	Executa as coletas agendadas das fontes vinculadas.	`false`	Não
`BINDING_SCHEDULER_INTERVAL_SEC`	Segundos entre verificações de coletas vencidas.	`60`	Não

Exceções e webhooks

Variável	Descrição	Padrão	Obrigatório
`EXCEPTION_DISPUTE_LOCK_TIMEOUT_MS`	Milissegundos que o Matcher espera pelo lock de uma disputa.	`2000`	Não
`WEBHOOK_TIMEOUT_SEC`	Timeout padrão, em segundos, de uma chamada de webhook de saída. O Matcher o limita a `300`.	`30`	Não
`CALLBACK_RATE_LIMIT_PER_MIN`	Callbacks por minuto que o Matcher aceita de um sistema externo.	`60`	Não

Exportação e limpeza

Variável	Descrição	Padrão	Obrigatório
`EXPORT_WORKER_ENABLED`	Executa o worker que grava os arquivos de exportação.	`true`	Não
`EXPORT_WORKER_POLL_INTERVAL_SEC`	Segundos entre consultas por novos jobs de exportação.	`5`	Não
`EXPORT_WORKER_PAGE_SIZE`	Linhas por página de exportação.	`1000`	Não
`EXPORT_PRESIGN_EXPIRY_SEC`	Segundos em que um link de download de exportação fica válido. O Matcher o limita a `604800`.	`3600`	Não
`CLEANUP_WORKER_ENABLED`	Executa o worker que remove os arquivos de exportação expirados.	`true`	Não
`CLEANUP_WORKER_INTERVAL_SEC`	Segundos entre execuções de limpeza.	`3600`	Não
`CLEANUP_WORKER_BATCH_SIZE`	Arquivos por lote de limpeza.	`100`	Não
`CLEANUP_WORKER_GRACE_PERIOD_SEC`	Segundos após a expiração até a limpeza remover um arquivo.	`3600`	Não

Arquivamento

Variável	Descrição	Padrão	Obrigatório
`ARCHIVAL_WORKER_ENABLED`	Executa o worker que arquiva as partições antigas do log de auditoria.	`false`	Não
`ARCHIVAL_WORKER_INTERVAL_HOURS`	Horas entre execuções de arquivamento.	`24`	Não
`ARCHIVAL_HOT_RETENTION_DAYS`	Retenção quente, em dias.	`90`	Não
`ARCHIVAL_WARM_RETENTION_MONTHS`	Meses até uma partição passar para o armazenamento frio de arquivos. Com o worker habilitado, precisa ser maior que a retenção quente dividida por 30.	`24`	Não
`ARCHIVAL_COLD_RETENTION_MONTHS`	Retenção fria, em meses. Com o worker habilitado, precisa ser pelo menos a retenção morna.	`84`	Não
`ARCHIVAL_BATCH_SIZE`	Linhas por lote de arquivamento.	`5000`	Não
`ARCHIVAL_STORAGE_BUCKET`	Bucket dos arquivos arquivados.	`matcher-archives`	Com o worker de arquivamento habilitado
`ARCHIVAL_STORAGE_CLASS`	Classe de armazenamento: `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER_IR`, `GLACIER` ou `DEEP_ARCHIVE`.	`GLACIER`	Não
`ARCHIVAL_PARTITION_LOOKAHEAD`	Partições mensais futuras que o Matcher cria com antecedência.	`3`	Não
`ARCHIVAL_PRESIGN_EXPIRY_SEC`	Segundos em que um link de download de um arquivo arquivado fica válido.	`3600`	Não

Com o worker de arquivamento habilitado, a retenção quente, o tamanho do lote e a antecedência precisam ser cada um pelo menos 1.

Governança

Variável	Descrição	Padrão	Obrigatório
`ACTOR_PII_ENCRYPTION_KEY`	Chave que criptografa os nomes e os endereços de e-mail dos atores. Base64 padrão de exatamente 32 bytes. Quando `ENV_NAME` não é `development`, `dev`, `local` nem `test`, os mapeamentos de atores precisam dela. Sensível.	—	Não

Motor de extração

Variável	Descrição	Padrão	Obrigatório
`APP_ENC_KEY`	Chave mestra que criptografa as credenciais de conexão armazenadas. Base64 padrão de pelo menos 32 bytes. Fora de produção, o Matcher usa uma chave temporária quando ela não está definida. Sensível.	—	Produção
`FETCHER_DISCOVERY_INTERVAL_SEC`	Segundos entre execuções de descoberta no motor de extração.	`60`	Não
`FETCHER_SCHEMA_CACHE_TTL_SEC`	Segundos em que o Matcher mantém em cache um schema descoberto.	`300`	Não
`FETCHER_EXTRACTION_TIMEOUT_SEC`	Segundos que o Matcher espera por uma extração.	`600`	Não
`FETCHER_MAX_EXTRACTION_BYTES`	Tamanho máximo, em bytes, do resultado de uma extração.	`2147483648`	Não

Conectores

Variável	Descrição	Padrão	Obrigatório
`PAGBANK_CONNECTOR_BASE_URL`	URL base da API do PagBank.	`https://api.pagseguro.com`	Não
`STRIPE_CONNECTOR_BASE_URL`	URL base da API do Stripe.	`https://api.stripe.com`	Não
`STRIPE_CONNECTOR_FILES_BASE_URL`	URL base da API de arquivos do Stripe.	`https://files.stripe.com`	Não
`PIX_CONNECTOR_BASE_URL`	URL base da API Pix. Sem ela, o conector Pix falha no primeiro uso.	—	Para o conector Pix
`PLUGGY_CONNECTOR_BASE_URL`	URL base da API do Pluggy.	`https://api.pluggy.ai`	Não
`PLUGGY_WEBHOOK_HMAC_SECRET`	Segredo que verifica os webhooks do Pluggy. Prevalece sobre a lista de IPs. Sensível.	—	Não
`PLUGGY_WEBHOOK_ALLOWED_IPS`	IPs de origem que o Matcher aceita para os webhooks do Pluggy (CSV).	—	Não
`BELVO_CONNECTOR_BASE_URL`	URL base da API do Belvo.	`https://api.belvo.com`	Não
`BELVO_WEBHOOK_HMAC_SECRET`	Segredo que verifica os webhooks do Belvo. Prevalece sobre a lista de IPs. Sensível.	—	Não
`BELVO_WEBHOOK_ALLOWED_IPS`	IPs de origem que o Matcher aceita para os webhooks do Belvo (CSV).	—	Não

Recursos de IA

Cada recurso tem um controle de habilitação, uma chave de API e um modelo. A extração de documentos e as sugestões de regras também precisam do consentimento no documento de runtime ai_gates. Por padrão, esse consentimento fica desabilitado.

Variável	Descrição	Padrão	Obrigatório
`ADVISOR_ENABLED`	Habilita o assistente de mapeamento.	`false`	Não
`ADVISOR_ANTHROPIC_API_KEY`	Chave de API do provedor de modelo de linguagem do assistente de mapeamento. Sensível.	—	Com o assistente habilitado
`ADVISOR_MODEL`	Modelo do assistente de mapeamento.	`claude-sonnet-4-6`	Não
`DOC_EXTRACTION_ENABLED`	Habilita a extração de documentos.	`false`	Não
`DOC_EXTRACTION_ANTHROPIC_API_KEY`	Chave de API da extração de documentos. Sensível.	—	Com a extração de documentos habilitada
`DOC_EXTRACTION_MODEL`	Modelo da extração de documentos.	`claude-sonnet-4-6`	Não
`RULE_ADVISOR_ENABLED`	Habilita as sugestões de regras.	`false`	Não
`RULE_ADVISOR_ANTHROPIC_API_KEY`	Chave de API das sugestões de regras. Sensível.	—	Com as sugestões de regras habilitadas
`RULE_ADVISOR_MODEL`	Modelo das sugestões de regras.	`claude-sonnet-4-6`	Não

Streaming de eventos

Variável	Descrição	Padrão	Obrigatório
`STREAMING_ENABLED`	Publica os eventos do Matcher no Kafka.	`false`	Não
`STREAMING_BROKERS`	Brokers do Kafka (CSV).	—	Com o streaming habilitado
`STREAMING_CLIENT_ID`	Client ID do Kafka.	`primary`	Não
`STREAMING_CLOUDEVENTS_SOURCE`	Nome da origem em cada evento. Também dá nome ao tópico `lerian.streaming.<source>`. Um único segmento em minúsculas que corresponda a `^[a-z0-9][a-z0-9_-]*$`. O Matcher verifica o formato mesmo com o streaming desabilitado.	—	Com o streaming habilitado
`STREAMING_TLS_ENABLED`	Usa TLS no Kafka.	`false`	Produção, com o streaming habilitado
`STREAMING_TLS_CA_CERT`	Certificado da CA para o TLS do Kafka.	—	Não
`STREAMING_SASL_MECHANISM`	Mecanismo SASL: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`.	—	Não
`STREAMING_SASL_USERNAME`	Usuário SASL.	—	Com um mecanismo SASL
`STREAMING_SASL_PASSWORD`	Senha SASL. Sensível.	—	Com um mecanismo SASL
`STREAMING_SASL_ALLOW_PLAINTEXT`	Permite SASL sem TLS.	`false`	Não
`STREAMING_CB_FAILURE_RATIO`	Proporção de falhas que abre o circuit breaker de publicação.	`0.5`	Não
`STREAMING_CB_MIN_REQUESTS`	Requisições de que o breaker precisa antes de poder abrir.	`10`	Não
`STREAMING_CB_TIMEOUT_S`	Segundos em que o breaker fica aberto.	`30`	Não
`STREAMING_CLOSE_TIMEOUT_S`	Segundos que o Matcher espera para enviar os eventos pendentes quando para.	`30`	Não
`STREAMING_TOPIC_AUTO_PROVISION`	Cria o tópico na inicialização quando ele não existe.	`true`	Não
`STREAMING_TOPIC_PARTITIONS`	Partições de um tópico criado. `-1` usa o padrão do broker.	`-1`	Não
`STREAMING_TOPIC_REPLICATION_FACTOR`	Fator de replicação de um tópico criado. `-1` usa o padrão do broker.	`-1`	Não

Documentos de runtime

O Matcher mantém onze documentos de runtime no namespace matcher do Systemplane, em /system. As variáveis abaixo definem o valor inicial de cada documento. Depois que a Lerian grava um documento por meio do Systemplane, o documento armazenado prevalece sobre as suas variáveis. O documento rate_limit não pode habilitar os limites enquanto RATE_LIMIT_ENABLED não está definida ou é false.

Documento	Variáveis
`http`	`HTTP_BODY_LIMIT_BYTES`, `CORS_ALLOWED_ORIGINS`, `CORS_ALLOWED_METHODS`, `CORS_ALLOWED_HEADERS`, `POSTGRES_QUERY_TIMEOUT_SEC`, `HEALTH_CHECK_TIMEOUT_SEC`, `HEALTH_CHECK_TIMEOUT_MS`
`rate_limit`	`RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_EXPIRY_SEC`, `EXPORT_RATE_LIMIT_MAX`, `EXPORT_RATE_LIMIT_EXPIRY_SEC`, `DISPATCH_RATE_LIMIT_MAX`, `DISPATCH_RATE_LIMIT_EXPIRY_SEC`, `ADMIN_RATE_LIMIT_MAX`, `ADMIN_RATE_LIMIT_EXPIRY_SEC`
`ingestion`	`IDEMPOTENCY_RETRY_WINDOW_SEC`, `IDEMPOTENCY_SUCCESS_TTL_HOURS`, `INGESTION_MAX_UPLOAD_BYTES`, `DEDUPE_TTL_SEC`
`fetcher`	`FETCHER_DISCOVERY_INTERVAL_SEC`, `FETCHER_SCHEMA_CACHE_TTL_SEC`, `FETCHER_EXTRACTION_TIMEOUT_SEC`, `FETCHER_MAX_EXTRACTION_BYTES`
`exception`	`EXCEPTION_DISPUTE_LOCK_TIMEOUT_MS`, `WEBHOOK_TIMEOUT_SEC`, `CALLBACK_RATE_LIMIT_PER_MIN`
`matching`	`MATCH_RUN_WORKER_ENABLED`, `MATCH_RUN_WORKER_POLL_INTERVAL_SEC`, `SCHEDULER_INTERVAL_SEC`
`reporting`	`EXPORT_WORKER_ENABLED`, `EXPORT_WORKER_POLL_INTERVAL_SEC`, `EXPORT_WORKER_PAGE_SIZE`, `EXPORT_PRESIGN_EXPIRY_SEC`, `CLEANUP_WORKER_ENABLED`, `CLEANUP_WORKER_INTERVAL_SEC`, `CLEANUP_WORKER_BATCH_SIZE`, `CLEANUP_WORKER_GRACE_PERIOD_SEC`
`archival`	`ARCHIVAL_WORKER_ENABLED`, `ARCHIVAL_WORKER_INTERVAL_HOURS`, `ARCHIVAL_HOT_RETENTION_DAYS`, `ARCHIVAL_WARM_RETENTION_MONTHS`, `ARCHIVAL_COLD_RETENTION_MONTHS`, `ARCHIVAL_BATCH_SIZE`, `ARCHIVAL_STORAGE_BUCKET`, `ARCHIVAL_STORAGE_CLASS`, `ARCHIVAL_PARTITION_LOOKAHEAD`, `ARCHIVAL_PRESIGN_EXPIRY_SEC`
`object_storage`	`OBJECT_STORAGE_ENDPOINT`, `OBJECT_STORAGE_REGION`, `OBJECT_STORAGE_BUCKET`, `OBJECT_STORAGE_USE_PATH_STYLE`, `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT`
`tenancy`	`MULTI_TENANT_URL`, `MULTI_TENANT_MAX_TENANT_POOLS`, `MULTI_TENANT_IDLE_TIMEOUT_SEC`, `MULTI_TENANT_TIMEOUT`, `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`, `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`, `MULTI_TENANT_CACHE_TTL_SEC`, `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`
`ai_gates`	Nenhuma variável. O documento guarda os consentimentos de IA, negados por padrão.

Visão geral

Guias

Console

Servidor MCP

Operações

Variáveis de ambiente

Aplicação

Servidor HTTP

Autenticação

Tenancy

PostgreSQL

Redis

RabbitMQ

Armazenamento de objetos

Timeouts de infraestrutura

Telemetria

Rate limits

Idempotência

Outbox

Ingestão

Correspondência

Exceções e webhooks

Exportação e limpeza

Arquivamento

Governança

Motor de extração

Conectores

Recursos de IA

Streaming de eventos

Documentos de runtime

​Aplicação

​Servidor HTTP

​Autenticação

​Tenancy

​PostgreSQL

​Redis

​RabbitMQ

​Armazenamento de objetos

​Timeouts de infraestrutura

​Telemetria

​Rate limits

​Idempotência

​Outbox

​Ingestão

​Correspondência

​Exceções e webhooks

​Exportação e limpeza

​Arquivamento

​Governança

​Motor de extração

​Conectores

​Recursos de IA

​Streaming de eventos

​Documentos de runtime

Aplicação

Servidor HTTP

Autenticação

Tenancy

PostgreSQL

Redis

RabbitMQ

Armazenamento de objetos

Timeouts de infraestrutura

Telemetria

Rate limits

Idempotência

Outbox

Ingestão

Correspondência

Exceções e webhooks

Exportação e limpeza

Arquivamento

Governança

Motor de extração

Conectores

Recursos de IA

Streaming de eventos

Documentos de runtime