Variáveis de ambiente

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

Introdução

Access Manager

Console

Streaming Hub

Multi-tenancy

Observabilidade

Narya

Lifecycle Management

Licenciamento

Variáveis de ambiente

Núcleo

Banco de dados

Dispatcher

Rate limit

Licença

Tenancy

Dashboard e health

Segredos

Kafka

Telemetria

Catálogo

Verificador de tópicos

Partições e histórico

Idempotência

Desabilitação automática de endpoints

Autenticação

Modo multi-tenant

Artefatos de configuração da AWS

​Núcleo

​Banco de dados

​Dispatcher

​Rate limit

​Licença

​Tenancy

​Dashboard e health

​Segredos

​Kafka

​Telemetria

​Catálogo

​Verificador de tópicos

​Partições e histórico

​Idempotência

​Desabilitação automática de endpoints

​Autenticação

​Modo multi-tenant

​Artefatos de configuração da AWS

Núcleo

Banco de dados

Dispatcher

Rate limit

Licença

Tenancy

Dashboard e health

Segredos

Kafka

Telemetria

Catálogo

Verificador de tópicos

Partições e histórico

Idempotência

Desabilitação automática de endpoints

Autenticação

Modo multi-tenant

Artefatos de configuração da AWS