Configuração do Fetcher

O Fetcher se configura inteiramente pelo ambiente. Cada serviço lê o próprio conjunto. O Manager e o Worker compartilham a maior parte das variáveis, e cada um tem algumas próprias. Para trabalho local, make set-env copia o .env.example de cada componente para .env. Em produção, defina as variáveis pelo seu orquestrador.

Os dois serviços precisam do mesmo APP_ENC_KEY. O Worker o usa para descriptografar credenciais de fontes de dados e para conferir a assinatura de toda mensagem que o Manager envia. Uma chave ausente ou curta interrompe o processo na inicialização. O log traz master key too short: got 0 bytes, minimum 32 required, e o serviço nunca abre uma porta.

Os dois serviços

Aplicação

Variável	Descrição	Padrão	Obrigatória
`APP_ENC_KEY`	Chave-mestra de 32 bytes codificada em base64. Gere com `make generate-master-key`. O Fetcher deriva quatro chaves independentes a partir dela.	—	Sim
`APP_ENC_KEY_VERSION`	Versão da chave registrada em cada credencial que o Fetcher criptografa. Incremente quando trocar a chave-mestra.	`1`	Não
`ENV_NAME`	Rótulo do ambiente. Ele também seleciona o perfil do logger: `production`, `staging`, `uat`, `development` ou `local`. Um valor ausente ou desconhecido seleciona o perfil `local`. O exemplo distribuído define `development`.	—	Não
`LOG_LEVEL`	Verbosidade dos logs. Sem definição, ela segue o perfil do ambiente: `debug` para `local` e `development`, `info` para os demais.	—	Não
`VERSION`	String de versão reportada por `/version`. O exemplo distribuído define `v1.0.0`.	`0.0.0`	Não
`DEPLOYMENT_MODE`	`saas`, `byoc` ou `local`. Etiqueta a resposta de `/readyz` e comanda a exigência de TLS em SaaS. `local` também relaxa a aplicação de licença.	`local`	Não
`ALLOW_INSECURE_TLS`	Permite conexões em texto claro com MongoDB, Redis, PostgreSQL e RabbitMQ. Deixe sem definir em produção.	não definida	Não
`READYZ_DRAIN_DELAY_SEC`	Janela de drenagem após `SIGTERM`, em segundos. Mínimo `1`.	`12`	Não

MongoDB

O MongoDB guarda os metadados do próprio Fetcher: registros de conexão e registros de job.

Variável	Descrição	Padrão	Obrigatória
`MONGO_URI`	Esquema de conexão: `mongodb` ou `mongodb+srv`. O Fetcher monta a URI de conexão a partir dele. O exemplo distribuído define `mongodb`.	—	Sim
`MONGO_HOST`	Host do MongoDB.	—	Sim
`MONGO_PORT`	Porta do MongoDB.	—	Sim
`MONGO_NAME`	Nome do banco de dados MongoDB. O acesso de repositório resolve este nome em minúsculas.	—	Sim
`MONGO_USER`	Usuário do banco.	—	Sim
`MONGO_PASSWORD`	Senha do banco. O Fetcher aplica escape de URL nela.	—	Sim
`MONGO_PARAMETERS`	Parâmetros adicionais de query string para a URI.	—	Não
`MONGO_TLS_CA_CERT`	Certificado CA PEM codificado em base64 para TLS.	—	Não

RabbitMQ

Variável	Descrição	Padrão	Obrigatória
`RABBITMQ_URI`	Esquema AMQP. O Fetcher monta a URL do broker a partir dele. O exemplo distribuído define `amqp`.	—	Sim
`RABBITMQ_HOST`	Host do broker.	—	Sim
`RABBITMQ_PORT_AMQP`	Porta AMQP.	—	Sim
`RABBITMQ_PORT_HOST`	Porta de gerenciamento.	—	Não
`RABBITMQ_DEFAULT_USER`	Usuário do broker.	—	Sim
`RABBITMQ_DEFAULT_PASS`	Senha do broker.	—	Sim
`RABBITMQ_HEALTH_CHECK_URL`	URL de gerenciamento que a sonda de prontidão chama. O exemplo distribuído a monta com `RABBITMQ_HOST` e `RABBITMQ_PORT_HOST`.	—	Não
`RABBITMQ_FETCHER_WORK_QUEUE`	Fila que leva os jobs de extração do Manager ao Worker. Os dois serviços precisam nomear a mesma fila. O exemplo distribuído usa `fetcher.extract-external-data.queue`.	—	Sim
`RABBITMQ_TLS`	Habilita TLS com o broker.	`false`	Não

Multi-tenancy

Variável	Descrição	Padrão	Obrigatória
`MULTI_TENANT_ENABLED`	Liga o isolamento com um banco por tenant. Também ativa a guarda de segurança sobre hosts de fonte de dados fornecidos pelo tenant.	`false`	Não
`MULTI_TENANT_URL`	URL do serviço Tenant Manager.	—	Com multi-tenancy
`MULTI_TENANT_SERVICE_API_KEY`	Chave de API padrão para consultas ao Tenant Manager.	—	Com multi-tenancy
`MULTI_TENANT_SERVICE_API_KEY_<SERVICE>`	Chave por serviço. O sufixo é o nome do serviço em maiúsculas, com hífens virando underscores (`plugin-crm` vira `PLUGIN_CRM`). Ela cai para a chave padrão.	—	Não
`MULTI_TENANT_REDIS_HOST`	Host do Redis para o Pub/Sub de tenants.	—	Com multi-tenancy
`MULTI_TENANT_REDIS_PORT`	Porta do Redis de Pub/Sub de tenants.	`6379`	Não
`MULTI_TENANT_REDIS_PASSWORD`	Senha do Redis de Pub/Sub de tenants.	—	Não
`MULTI_TENANT_REDIS_TLS`	TLS para o Redis de Pub/Sub de tenants. O cliente confia no repositório de certificados do runtime, então instale ali a sua CA privada.	`false`	Não
`MULTI_TENANT_MAX_TENANT_POOLS`	Teto de pools de conexão por tenant simultâneos.	`100`	Não
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Tempo ocioso antes de um pool de tenant ser liberado.	`300`	Não
`MULTI_TENANT_CACHE_TTL_SEC`	TTL da configuração de tenant em cache. O exemplo distribuído define `120`.	—	Não
`MULTI_TENANT_TIMEOUT`	Tempo limite das chamadas ao Tenant Manager, em segundos.	`30`	Não
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Falhas consecutivas antes de o circuit breaker de tenants abrir.	`5`	Não
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	Quanto tempo o breaker fica aberto antes de uma tentativa de reset.	`30`	Não
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	Permite HTTP em texto claro com o Tenant Manager.	`false`	Não

Paradas de inicialização em modo multi-tenant. MULTI_TENANT_ENABLED=true exige MULTI_TENANT_URL, MULTI_TENANT_SERVICE_API_KEY e MULTI_TENANT_REDIS_HOST. Um valor ausente aborta a inicialização nos dois serviços, e o erro nomeia a variável. Duas variáveis MULTI_TENANT_SERVICE_API_KEY_<SERVICE> que normalizam para o mesmo token também abortam a inicialização, e o erro nomeia o token. A credencial de um serviço nunca sobrescreve a de outro em silêncio.

Telemetria

Variável	Descrição	Padrão	Obrigatória
`ENABLE_TELEMETRY`	Liga traces e métricas OpenTelemetry.	`false`	Não
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint do coletor OTLP.	—	Com telemetria
`OTEL_INSECURE_EXPORTER`	Permite conexão do exportador em texto claro.	`false`	Não
`OTEL_RESOURCE_SERVICE_NAME`	Nome do serviço na telemetria. Os exemplos distribuídos definem `fetcher` para o Manager e `fetcher-worker` para o Worker.	—	Não
`OTEL_LIBRARY_NAME`	Nome da biblioteca de instrumentação. O exemplo distribuído define `github.com/LerianStudio/fetcher/v2`.	—	Não
`OTEL_RESOURCE_SERVICE_VERSION`	Atributo de versão do serviço. O `/readyz` reporta este valor, e reporta `unknown` quando ele não está definido. O exemplo distribuído o aponta para `VERSION`.	—	Não
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Atributo de ambiente de implantação. O exemplo distribuído o aponta para `ENV_NAME`.	—	Não

Somente o Manager

Variável	Descrição	Padrão	Obrigatória
`SERVER_ADDRESS`	Endereço de escuta da API HTTP. O mesmo listener serve `/health`, `/readyz`, `/metrics` e `/version`. O exemplo distribuído o monta a partir de `SERVER_PORT`, que ele define como `4006`.	—	Sim
`SWAGGER_ENABLED`	Serve a referência da API em `/swagger/docs` e o contrato OpenAPI 3.1 em `/swagger/openapi.json` e `/swagger/openapi.yaml`.	`false`	Não
`PLUGIN_AUTH_ENABLED`	Liga a autenticação pelo Access Manager. O modo multi-tenant a exige.	`false`	Não
`PLUGIN_AUTH_ADDRESS`	Endereço do Access Manager.	—	Com autenticação
`SCHEMA_CACHE_TTL_SECONDS`	TTL de um esquema de fonte de dados em cache. Um valor vazio ou inválido cai para 5 minutos.	`300`	Não
`REDIS_HOST`	Host do Valkey ou Redis. Ele sustenta o cache de esquema e o limitador de taxa do teste de conexão.	—	Não
`REDIS_PORT`	Porta do Redis.	—	Não
`REDIS_PASSWORD`	Senha do Redis.	—	Não
`REDIS_DB`	Índice do banco no Redis.	`0`	Não
`REDIS_TLS`	Habilita TLS com o Redis.	`false`	Não
`REDIS_CA_CERT`	CA PEM em base64 usada quando `REDIS_TLS=true`.	—	Não
`MAX_PAGINATION_LIMIT`	Teto do parâmetro de consulta `limit` em toda operação de listagem.	`100`	Não
`MAX_PAGINATION_MONTH_DATE_RANGE`	Teto da janela de data de criação em toda operação de listagem, em meses.	`1`	Não

O roteador se recusa a subir em duas incompatibilidades de segurança. Ele reporta tenant middleware requires effective authentication quando o modo multi-tenant roda com a autenticação desligada. Ele reporta auth middleware is enabled but its address is empty quando PLUGIN_AUTH_ENABLED=true e PLUGIN_AUTH_ADDRESS está em branco. Nos dois casos o Manager não inicia.

Somente o Worker

Execução e eventos

Variável	Descrição	Padrão	Obrigatória
`HEALTH_PORT`	Porta do microsservidor de saúde do Worker. Ele serve `/health`, `/readyz`, `/readyz/tenant/:id` e `/metrics`. O Worker não tem outro servidor HTTP.	`4007`	Não
`RABBITMQ_NUMBERS_OF_WORKERS`	Quantos jobs o Worker processa em paralelo.	`5`	Não
`MONGO_MAX_POOL_SIZE`	Tamanho do pool do cliente Mongo para o repositório de metadados. O exemplo distribuído define `1000`.	`100`	Não
`STREAMING_ENABLED`	Deve ser `true`. Os eventos terminais de job são um contrato do produto, então o Worker se recusa a iniciar sem streaming.	`false`	Sim
`STREAMING_BROKERS`	Lista de brokers bootstrap da camada de streaming, como pares `host:porta` separados por vírgula. O exemplo distribuído define `localhost:9092`.	—	Sim
`STREAMING_CLOUDEVENTS_SOURCE`	Origem CloudEvents carimbada nos eventos emitidos pelo Worker. Deve ser exatamente `fetcher`.	—	Sim
`STREAMING_CLIENT_ID`	Identificador do cliente de streaming.	—	Não
`STREAMING_COMPRESSION`	Codec de compressão: `snappy`, `lz4`, `zstd`, `gzip` ou `none`.	`lz4`	Não
`STREAMING_REQUIRED_ACKS`	Nível de confirmação do produtor: `all`, `leader` ou `none`.	`all`	Não
`RABBITMQ_JOB_EVENTS_EXCHANGE`	Exchange que leva `job.completed` e `job.failed`. O exemplo distribuído usa `fetcher.job.events`.	—	Sim
`MULTI_TENANT_RECONCILE_INTERVAL_SEC`	Intervalo em que o Worker reconcilia os consumidores por tenant com os tenants ativos.	`60`	Não
`ENGINE_MAX_RESULT_BYTES`	Substitui o teto de resultado serializado do Engine, como contagem de bytes. Zero ou negativo mantém o padrão.	`268435456`	Não
`CRYPTO_ENCRYPT_SECRET_KEY_PLUGIN_CRM`	Chave de criptografia do caminho de extração de compatibilidade com o CRM.	—	Não
`CRYPTO_HASH_SECRET_KEY_PLUGIN_CRM`	Chave de hash do caminho de extração de compatibilidade com o CRM.	—	Não

O Worker falha de forma fechada na configuração de eventos. STREAMING_ENABLED não definida ou false aborta a inicialização com STREAMING_ENABLED=true is required for mandatory job event notifications. Um RABBITMQ_JOB_EVENTS_EXCHANGE em branco, um STREAMING_BROKERS vazio e um STREAMING_CLOUDEVENTS_SOURCE vazio abortam a inicialização do mesmo jeito, assim como um STREAMING_COMPRESSION ou um STREAMING_REQUIRED_ACKS fora do conjunto aceito. O Worker nunca cai para um emissor silencioso que não faz nada.

Armazenamento de objetos

O Worker grava todo resultado armazenado em armazenamento de objetos compatível com S3. O esquema do endpoint controla o TLS, então http:// o desliga.

Variável	Descrição	Padrão	Obrigatória
`OBJECT_STORAGE_ENDPOINT`	Endpoint compatível com S3, por exemplo `http://minio:9000`. Deixe sem definir para apontar para o AWS S3.	—	Não
`OBJECT_STORAGE_REGION`	Região S3.	`us-east-1`	Não
`OBJECT_STORAGE_BUCKET`	Bucket dos resultados armazenados. O Worker não inicia sem ele.	—	Sim
`OBJECT_STORAGE_KEY_PREFIX`	Prefixo de chave aplicado aos objetos armazenados.	—	Não
`OBJECT_STORAGE_ACCESS_KEY_ID`	ID de chave de acesso estática. Defina-o junto com `OBJECT_STORAGE_SECRET_KEY`, ou deixe os dois sem definir para usar a cadeia de credenciais da AWS do ambiente.	—	Não
`OBJECT_STORAGE_SECRET_KEY`	Chave de acesso secreta estática. Defina-a junto com `OBJECT_STORAGE_ACCESS_KEY_ID`. Definir apenas uma das duas aborta a inicialização.	—	Não
`OBJECT_STORAGE_USE_PATH_STYLE`	Endereçamento path-style. Defina como `true` para MinIO e SeaweedFS.	`false`	Não

Defina a expiração dos resultados com uma política de ciclo de vida no bucket. Veja Implantação.

Compatibilidade da assinatura de mensagens

Variável	Descrição	Padrão	Obrigatória
`RABBITMQ_ALLOW_LEGACY_BODY_SIGNATURE_FALLBACK`	Flag de compatibilidade para uma atualização gradual. Ela também aceita assinaturas somente de corpo nas mensagens consumidas. Uma assinatura somente de corpo não vincula a mensagem ao tenant, ao job, ao exchange nem à routing key dela. Ela vem desligada. Ligue-a apenas enquanto você atualiza uma frota, e depois desligue-a.	`false`	Não

Fontes de dados internas

Fontes de dados internas são os bancos de outros produtos Lerian. O Fetcher as resolve sem uma conexão registrada pela API. Você declara cada uma com um grupo DATASOURCE_{NAME}_*, onde {NAME} é um prefixo que você escolhe. Os valores aceitos de _CONFIG_NAME formam um registro fixo: midaz_onboarding, midaz_transaction e plugin_crm. O Fetcher pula qualquer outro nome e registra um aviso que nomeia tanto o valor rejeitado quanto o conjunto aceito. Para os seus próprios bancos, registre uma conexão pela API.

Variável	Descrição	Exemplo
`DATASOURCE_{NAME}_CONFIG_NAME`	Nome da fonte de dados no registro. Obrigatório.	`midaz_onboarding`
`DATASOURCE_{NAME}_TYPE`	Tipo da fonte de dados, comparado sem diferenciar maiúsculas de minúsculas. Obrigatório.	`POSTGRESQL`
`DATASOURCE_{NAME}_HOST`	Host. Obrigatório.	`db.internal.example.com`
`DATASOURCE_{NAME}_PORT`	Porta. Obrigatório.	`5432`
`DATASOURCE_{NAME}_DATABASE`	Nome do banco. Obrigatório.	`onboarding`
`DATASOURCE_{NAME}_USER`	Usuário.	`fetcher_ro`
`DATASOURCE_{NAME}_PASSWORD`	Senha. Forneça-a a partir do seu gerenciador de segredos.	—
`DATASOURCE_{NAME}_SSLMODE`	Modo de TLS. Este é o controle de TLS neste caminho.	`require`
`DATASOURCE_{NAME}_OPTIONS`	Opções de query string. Apenas MongoDB.	`authSource=admin`

Um valor ruim pula a fonte de dados, em alto e bom som. Um _TYPE inválido, um _SSLMODE inválido ou um _HOST ou _DATABASE ausente faz o Fetcher pular essa fonte de dados e registrar um aviso que nomeia o config name e o valor problemático. O Fetcher nunca rebaixa uma configuração de TLS para alcançar um banco de dados.

Próximos passos

Implantação

Dependências, filas, armazenamento, escala e checagens de inicialização.

Segurança

Chave-mestra, chaves derivadas, assinatura e validação de host.

Observabilidade

Sondas, comportamento de drenagem, métricas e tracing.

Primeiros passos

Uma primeira extração, com ou sem infraestrutura.

Visão geral

Primeiros passos

Conceitos

Motor

Integração

Operações

Configuração do Fetcher

Os dois serviços

Aplicação

MongoDB

RabbitMQ

Multi-tenancy

Telemetria

Somente o Manager

Somente o Worker

Execução e eventos

Armazenamento de objetos

Compatibilidade da assinatura de mensagens

Fontes de dados internas

Próximos passos

Implantação

Segurança

Observabilidade

Primeiros passos

​Os dois serviços

​Aplicação

​MongoDB

​RabbitMQ

​Multi-tenancy

​Telemetria

​Somente o Manager

​Somente o Worker

​Execução e eventos

​Armazenamento de objetos

​Compatibilidade da assinatura de mensagens

​Fontes de dados internas

​Próximos passos

Implantação

Segurança

Observabilidade

Primeiros passos

Os dois serviços

Aplicação

MongoDB

RabbitMQ

Multi-tenancy

Telemetria

Somente o Manager

Somente o Worker

Execução e eventos

Armazenamento de objetos

Compatibilidade da assinatura de mensagens

Fontes de dados internas

Próximos passos