> ## 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

> Referência das variáveis de ambiente que configuram o Streaming Hub, agrupadas como o código as agrupa, com cada padrão e as verificações que o hub aplica na inicialização.

Esta referência lista as variáveis de ambiente que configuram o **Streaming Hub**. A Lerian define esses valores quando instala ou atualiza o hub. Use esta página para saber o que cada configuração faz, qual é o seu padrão e o que o hub verifica na inicialização.

Quando uma variável obrigatória está ausente ou é inválida, o hub não inicia. `STREAMING_HUB_ENV` seleciona o ambiente. Os valores `staging` e `production` são ambientes **endurecidos**: eles recusam os atalhos locais que a coluna **Obrigatório** marca como "Endurecido". Um valor de duração usa a sintaxe do Go, como `30s`, `5m` ou `720h`. A unidade `d` não existe, então escreva `2160h` para 90 dias.

## Núcleo

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_ENV` | Ambiente: `local`, `staging` ou `production`. O hub recusa qualquer outro valor e recusa uma variável definida mas em branco. | `local` | Não |
| `STREAMING_HUB_ROLE` | Parte do hub que este processo executa: `all`, `ingest` ou `delivery`. Um valor desconhecido registra um aviso e executa `all`. | `all` | Não |
| `STREAMING_HUB_HTTP_LISTEN_ADDR` | Endereço de bind da API HTTP. | `:8080` | Não |
| `STREAMING_HUB_LOG_LEVEL` | Nível de log. | `info` | Não |
| `STREAMING_HUB_SHUTDOWN_TIMEOUT` | Tempo que o hub permite para o trabalho em andamento terminar quando ele para. Precisa ser menor que `35s`, ou a inicialização falha. | `30s` | Não |
| `STREAMING_HUB_PRE_STOP_DRAIN_TIMEOUT` | Tempo que o hub espera depois de se declarar não pronto e antes de parar. `0` desabilita a espera. | `5s` | Não |
| `STREAMING_HUB_SWAGGER_ENABLED` | Serve a especificação OpenAPI e a página de documentação dela. | `false` | Não |

## Banco de dados

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_POSTGRES_DSN` | String de conexão do PostgreSQL. Ambientes endurecidos exigem um DSN que verifique o servidor: `sslmode=verify-full`, ou `verify-ca` com `sslrootcert`. Um host de socket Unix é aceito. Sensível. | — | Sim |
| `STREAMING_HUB_ALLOW_INSECURE_DB_TLS` | Aceita um DSN que não verifica o servidor em um ambiente endurecido. | `false` | Não |
| `STREAMING_HUB_POSTGRES_MAX_OPEN_CONNS` | Máximo de conexões abertas. Precisa ser maior que `0`. Quando não definido, o padrão depende do papel. | `25` (`all`), `8` (`ingest`), `16` (`delivery`) | Não |
| `STREAMING_HUB_POSTGRES_MAX_IDLE_CONNS` | Conexões ociosas mantidas abertas. Precisa ser `0` ou mais. Quando não definido, o padrão depende do papel. | `12` (`all`), `4` (`ingest`), `10` (`delivery`) | Não |
| `STREAMING_HUB_POSTGRES_CONN_MAX_LIFETIME` | Tempo até o hub substituir uma conexão. | `30m` | Não |

## Dispatcher

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_DISPATCH_WORKERS` | Workers de entrega. O hub limita o valor às conexões abertas menos `4`, com um mínimo de `1`. | `8` | Não |
| `STREAMING_HUB_DISPATCH_IDLE_INTERVAL_MS` | Milissegundos que um worker espera depois de não encontrar nenhum job. | `250` | Não |
| `STREAMING_HUB_POISON_THRESHOLD` | Vezes que a varredura de recuperação pode retomar um job depois de uma queda do worker, sem resultado de entrega, antes de o hub enviar o job para dead-letter como poison. | `5` | Não |

## Rate limit

O hub mede as leituras por tenant em um armazenamento de contadores Redis.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_REDIS_ADDRESS` | Endereço do armazenamento de contadores. | — | Sim |
| `STREAMING_HUB_REDIS_PASSWORD` | Senha do armazenamento de contadores. Sensível. | — | Não |
| `STREAMING_HUB_REDIS_TLS` | Usa TLS no armazenamento de contadores. | `true` | Endurecido: `true` |
| `STREAMING_HUB_REDIS_CA_CERT` | Bundle de CA para essa conexão TLS, em PEM codificado em base64. | — | Não |
| `RATE_LIMIT_ENABLED` | Habilita o rate limit. O hub se recusa a iniciar sem `true`. | `false` | Sim: `true` |
| `ALLOW_RATELIMIT_FAIL_OPEN` | Comportamento quando o armazenamento de contadores está inacessível. Com `true`, as leituras continuam sem limite. Com `false`, as rotas limitadas respondem `503`. | `false` | Não |
| `ALLOW_INSECURE_TLS` | Desabilita a exigência de TLS em todos os clientes que a biblioteca compartilhada cria neste processo. Serve apenas para trabalho local. | — | Endurecido: diferente de `true` |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | Milissegundos que uma atualização de contador pode levar antes de a requisição parar de esperar o armazenamento. | `500` | Não |
| `STREAMING_HUB_PULL_RATE` | Leituras por segundo de cada tenant em `GET /v1/events`. | `100` | Não |
| `STREAMING_HUB_DASHBOARD_RATE` | Requisições por minuto de cada tenant nas duas leituras do dashboard. | `60` | Não |
| `STREAMING_HUB_READ_RATE` | Requisições por minuto de cada tenant nas leituras do Console: subscriptions, endpoint, health, artefatos de configuração e catálogo. | `60` | Não |

## Licença

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `LICENSE_KEY` | Chave de licença da Lerian. O hub a verifica na inicialização em todos os ambientes. Sensível. | — | Sim |
| `ORGANIZATION_IDS` | Escopo da licença. O valor precisa ser `global`. | — | Sim |
| `IS_DEVELOPMENT` | Com `true`, o hub verifica a licença no servidor de licenças de desenvolvimento. | — | `production`: diferente de `true` |

## Tenancy

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_TENANT_ID` | Tenant de um hub single-tenant. Letras, dígitos, `-` e `_`, começando por uma letra ou um dígito. Precisa corresponder ao `ce-tenantid` que os produtores colocam nos eventos. O modo multi-tenant o ignora e registra um aviso. | — | Modo single-tenant |
| `STREAMING_HUB_DELEGATED_SCOPE_CLAIM` | Nome da claim do token que carrega o escopo delegado de um chamador. | `atua_por` | Não |
| `STREAMING_HUB_DELEGATED_KIND_CLAIM` | Nome da claim do token que carrega o tipo de credencial de um chamador com escopo. | `nature` | Não |

## Dashboard e health

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_DASHBOARD_CURSOR_HMAC_KEY` | Chave que assina os cursores de página do dashboard. Base64 padrão de exatamente 32 bytes. Uma nova chave invalida os cursores em uso. Ambientes endurecidos recusam a chave de desenvolvimento publicada. Sensível. | — | Sim |
| `STREAMING_HUB_HEALTH_WINDOW` | Período mais longo que a visão de health da subscription mede. | `720h` | Não |

## Segredos

O hub criptografa os segredos de assinatura de webhook que armazena com uma chave de criptografia de chaves (KEK).

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_KEK_SOURCE` | Origem da KEK: `env` ou `secretsmanager`. Com os dois valores, o hub lê a KEK da variável que `STREAMING_HUB_KEK_REF` indica. Com `secretsmanager`, a camada de deploy coloca o segredo gerenciado nessa variável. | `env` | Não |
| `STREAMING_HUB_KEK_REF` | Nome da variável que guarda a KEK. Essa variável não pode estar vazia, e a chave precisa ter pelo menos 32 bytes. Ambientes endurecidos recusam a chave de desenvolvimento publicada. | — | Sim |

## Kafka

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_KAFKA_BROKERS` | Brokers do Kafka (CSV). | — | Sim |
| `STREAMING_HUB_KAFKA_SCRAM_MECHANISM` | Mecanismo SCRAM: `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Exige TLS. | — | Não |
| `STREAMING_HUB_KAFKA_SCRAM_USERNAME` | Usuário SCRAM. | — | Com um mecanismo SCRAM |
| `STREAMING_HUB_KAFKA_SCRAM_PASSWORD` | Senha SCRAM. Sensível. | — | Com um mecanismo SCRAM |
| `STREAMING_HUB_KAFKA_TLS_ENABLED` | Usa TLS no Kafka. | `false` | Não |
| `STREAMING_HUB_KAFKA_CA_CERT` | Certificado da CA para o TLS do Kafka. | — | Não |
| `STREAMING_HUB_ALLOW_INSECURE_KAFKA` | Permite Kafka sem criptografia. Uma conexão sem TLS precisa dela. | `false` | Endurecido: `false` |
| `STREAMING_HUB_DLQ_RETENTION` | Tempo que o hub mantém uma observação de dead-letter. | `168h` | Não |
| `STREAMING_HUB_DLQ_PRUNE_INTERVAL` | Tempo entre remoções das observações de dead-letter expiradas. `0` ou menos desabilita a remoção. | `1h` | Não |

## Telemetria

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_METRICS_ENABLED` | Habilita o OpenTelemetry. | `true` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. Quando vazio, o hub não envia telemetria. | — | Não |
| `OTEL_INSECURE_EXPORTER` | Envia a telemetria sem TLS. | `false` | Não |
| `ALLOW_INSECURE_OTEL` | Permite um exportador sem criptografia quando `STREAMING_HUB_ENV` é `production`. Sem ela, esse caso interrompe a inicialização. | — | Não |

## Catálogo

Um hub single-tenant lê o catálogo de eventos dos produtores em `STREAMING_HUB_MANIFEST_SOURCES`. Um hub multi-tenant encontra os seus produtores a partir das credenciais de cada tenant.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_MANIFEST_SOURCES` | URLs base dos produtores (CSV), como `scheme://host[:port]` sem caminho. O modo multi-tenant a recusa. Uma entrada inválida interrompe a inicialização. | — | Não |
| `STREAMING_HUB_MANIFEST_CLIENT_ID` | Client ID que o hub usa para ler manifestos protegidos. Defina junto com o segredo, ou não defina nenhum dos dois. | — | Não |
| `STREAMING_HUB_MANIFEST_CLIENT_SECRET` | Client secret dessas leituras. Sensível. | — | Não |
| `STREAMING_HUB_MANIFEST_REFRESH_INTERVAL` | Segundos entre atualizações do catálogo. | `300` | Não |

## Verificador de tópicos

O verificador compara tópicos, subscriptions e o catálogo, e informa as diferenças em métricas e logs. Ele não altera nada.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_RECONCILER_ENABLED` | Executa o verificador. | `true` | Não |
| `STREAMING_HUB_RECONCILER_INTERVAL` | Segundos entre passagens do verificador. | `300` | Não |

## Partições e histórico

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_PARTITION_CRON_INTERVAL` | Tempo entre as execuções que criam partições futuras. | `6h` | Não |
| `STREAMING_HUB_PARTITION_FUTURE_BUFFER_WEEKS` | Partições semanais que o hub mantém prontas com antecedência. Precisa ser pelo menos `1`. | `4` | Não |
| `STREAMING_HUB_PARTITION_RETENTION_ENABLED` | Remove as partições expiradas. Com `false`, o hub não remove nenhuma. | `false` | Não |
| `STREAMING_HUB_PARTITION_RETENTION_HORIZON` | Idade em que uma partição expira. Com a retenção habilitada, precisa ser pelo menos as semanas de antecedência vezes sete dias, e um valor inválido interrompe a inicialização. | `2160h` | Não |
| `STREAMING_HUB_ARCHIVE_BUCKET` | Nome do bucket S3 para o histórico de entregas arquivado. Use o nome puro. Quando vazio, o arquivamento fica desabilitado. Depois que uma réplica inicia com um bucket, a retenção remove apenas o histórico que chegou ao arquivo. Limpar a variável depois não remove essa regra. | — | Não |
| `STREAMING_HUB_HISTORY_RETENTION_ENABLED` | Mantém um histórico curto de entregas: o hub remove os dados quentes depois de arquivá-los. Exige a retenção de partições e o bucket de arquivo. Depois que o hub registra esse modo, o modo é permanente. | `false` | Não |

## Idempotência

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_IDEMPOTENCY_TTL` | Tempo em que uma resposta confirmada fica disponível para replay com a mesma chave `X-Idempotency`. | `24h` | Não |
| `STREAMING_HUB_IDEMPOTENCY_REAP_INTERVAL` | Tempo entre remoções dos registros de idempotência expirados. `0` ou menos desabilita a remoção. | `5m` | Não |

## Desabilitação automática de endpoints

O hub desabilita uma subscription quando as suas entregas falham por um período longo e espaçado. Uma entrega com sucesso zera a contagem.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_AUTODISABLE_ENABLED` | Habilita a desabilitação automática. | `true` | Não |
| `STREAMING_HUB_AUTODISABLE_FAILURE_WINDOW` | Tempo mínimo desde a primeira falha. | `120h` | Não |
| `STREAMING_HUB_AUTODISABLE_FAILURE_SPREAD` | Tempo mínimo entre a primeira e a última falha. | `12h` | Não |

## Autenticação

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Habilita a autenticação do Access Manager. | `true` | Endurecido: `true` |
| `PLUGIN_AUTH_ADDRESS` | Endereço do Access Manager. | `http://localhost:4000` | Não |
| `AUTH_REQUIRED` | Com `true`, as rotas protegidas respondem `503` quando a autenticação está desabilitada ou o endereço do Access Manager está vazio. | `false` | Não |
| `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED` | Com `true` e a autenticação desabilitada, as rotas protegidas ainda exigem um bearer token e respondem `401` sem ele. Elas não chamam o Access Manager. Sem `AUTH_JWT_VERIFY_CERT` ou `AUTH_JWT_VERIFY_CERT_PATH`, o hub não verifica a assinatura do token. | `false` | Não |
| `AUTH_M2M_INVERSION_ENABLED` | Com `true`, cada token de aplicação é autorizado com as próprias permissões. O hub então responde `401` a um token cuja claim `type` não é `normal-user` nem `application`. Sem `true`, todo token que não é de usuário é autorizado sob um único papel compartilhado. | `false` | Não |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Com `true` e `AUTH_M2M_INVERSION_ENABLED=true`, o hub 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. | `30s` | Não |
| `AUTH_CACHE_TTL` | Tempo que o hub guarda cada decisão do Access Manager. Uma mudança de permissão pode levar esse tempo para valer. Quando não definida, o hub 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 hub 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 hub 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 hub o lê apenas quando `AUTH_JWT_VERIFY_CERT` está vazia. | — | Não |
| `AUTH_JWT_ISSUER` | Com uma chave carregada, o hub responde `401` a um token cuja claim `iss` difere deste valor. | — | Não |
| `TRUSTED_PROXIES` | Faixas CIDR, separadas por vírgula, dos proxies que se conectam direto ao hub. O hub resolve o endereço de quem chama por meio deles e o envia ao Access Manager para a [lista de IPs permitidos](https://docs.lerian.studio/pt/platform/access-manager/features/ip-allowlist/deployment.md). Quando não definida, o hub não envia o endereço de quem chama. | — | Não |
| `IDP_DECLARATION_ENABLED` | Publica a declaração de permissões do hub no serviço de identidade na inicialização. Apenas `true` a habilita. A publicação também precisa de `PLUGIN_AUTH_ENABLED=true` definida no ambiente. Ela também precisa do endereço do Access Manager definido no ambiente como `PLUGIN_AUTH_HOST`, ou como `PLUGIN_AUTH_ADDRESS` quando `PLUGIN_AUTH_HOST` está vazia. Quando ela falha, o hub registra um aviso e continua atendendo. | — | Não |
| `IDP_HOST` | URL base do serviço de identidade para a declaração. | — | Com a declaração habilitada |
| `IDP_M2M_CLIENT_ID` | Client ID da declaração. | — | Com a declaração habilitada |
| `IDP_M2M_CLIENT_SECRET` | Client secret da declaração. Sensível. | — | Com a declaração habilitada |

## Modo multi-tenant

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `MULTI_TENANT_ENABLED` | Habilita o modo multi-tenant por meio do Tenant Manager. | `false` | Não |
| `ENV_NAME` | Nome do ambiente para o Tenant Manager. O modo multi-tenant recusa um valor vazio e `local`. | — | Modo multi-tenant |
| `MULTI_TENANT_URL` | URL do Tenant Manager. | — | Modo multi-tenant |
| `MULTI_TENANT_SERVICE_API_KEY` | Chave de API que o hub envia ao Tenant Manager. Sensível. | — | Modo multi-tenant |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite uma URL `http` para o Tenant Manager. | `false` | Não |
| `MULTI_TENANT_TIMEOUT` | Timeout, em segundos, de uma chamada ao Tenant Manager. `0` usa o padrão da biblioteca. | `0` | Não |
| `MULTI_TENANT_CACHE_TTL_SEC` | Segundos em que o hub mantém em cache a configuração de um tenant. `0` usa o padrão da biblioteca. | `0` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Chamadas ao Tenant Manager com falha até o circuit breaker abrir. `0` desabilita o breaker. | `0` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Segundos em que o circuit breaker fica aberto. `0` usa o padrão da biblioteca. | `0` | Não |
| `MULTI_TENANT_REDIS_HOST` | Host do Redis que transporta os eventos de ciclo de vida dos tenants. Quando vazio, o hub roda sem esse listener. | — | 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_REDIS_CA_CERT` | Certificado da CA para essa conexão TLS. | — | Não |
| `AWS_REGION` | Região da AWS, lida pelo SDK da AWS. | — | Não |

## Artefatos de configuração da AWS

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_HUB_AWS_HUB_PRINCIPAL_ARN` | ARN do papel AWS do hub. O seu papel de concessão delegada confia nele, e os artefatos de configuração o colocam na política de confiança. Quando vazio, o hub não gera artefatos de configuração da AWS. | — | Não |
| `STREAMING_HUB_AWS_SETUP_TEMPLATE_URL` | URL pública do template do CloudFormation que cria o papel de concessão delegada. Quando vazia, o hub não gera artefatos de configuração da AWS. | — | Não |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.