Referência de configuração

Referência de configuração do serviço Ledger

O serviço Ledger usa configurações de banco de dados específicas por módulo:

ledger:
  enabled: true
  name: "ledger"
  replicaCount: 1

  image:
    repository: lerianstudio/midaz-ledger
    tag: ""  # Defaults to Chart.AppVersion
    pullPolicy: IfNotPresent

  configmap:
    # App Configuration
    ENV_NAME: "production"
    LOG_LEVEL: "debug"
    SERVER_PORT: "3002"
    SERVER_ADDRESS: ":3002"

    # Auth Configuration
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""

    # Accounting Configuration
    # Managed via Ledger Settings API — see PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
    # Request body: {"accounting": {"validateRoutes": true, "validateAccountType": true}}

    # PostgreSQL - Onboarding Module
    DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_SSLMODE: "disable"
    DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # PostgreSQL - Transaction Module
    DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_SSLMODE: "disable"
    DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # MongoDB - Onboarding Module
    MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"

    # MongoDB - Transaction Module
    MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"

    # Redis (shared)
    REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

    # RabbitMQ (shared)
    RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."
    # RABBITMQ_VHOST: "/"

    # Database Connection Pools
    # DB_ONBOARDING_MAX_OPEN_CONNS: ""
    # DB_ONBOARDING_MAX_IDLE_CONNS: ""
    # DB_TRANSACTION_MAX_OPEN_CONNS: ""
    # DB_TRANSACTION_MAX_IDLE_CONNS: ""

    # Balance Sync Worker
    BALANCE_SYNC_BATCH_SIZE: "100"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
    BALANCE_SYNC_POLL_INTERVAL_MS: "500"

    # Multi-Tenant
    MULTI_TENANT_ENABLED: "false"
    # MULTI_TENANT_URL: "http://tenant-manager:4003"
    # MULTI_TENANT_SERVICE_API_KEY: ""
    # MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC: ""
    # MULTI_TENANT_CACHE_TTL_SEC: "120"
    # MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD: "5"
    # MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC: "30"
    # MULTI_TENANT_REDIS_HOST: ""
    # MULTI_TENANT_REDIS_PORT: "6379"
    # MULTI_TENANT_REDIS_PASSWORD: ""
    # MULTI_TENANT_REDIS_TLS: "false"

    # Multi-Tenant (CRM only)
    # MULTI_TENANT_TIMEOUT: "30"
    # MULTI_TENANT_MAX_TENANT_POOLS: "100"
    # MULTI_TENANT_IDLE_TIMEOUT_SEC: "300"

    # RabbitMQ Circuit Breaker
    RABBITMQ_CIRCUIT_BREAKER_CONSECUTIVE_FAILURES: "15"
    RABBITMQ_CIRCUIT_BREAKER_FAILURE_RATIO: "50"
    RABBITMQ_CIRCUIT_BREAKER_INTERVAL: "120"
    RABBITMQ_CIRCUIT_BREAKER_MAX_REQUESTS: "3"
    RABBITMQ_CIRCUIT_BREAKER_MIN_REQUESTS: "10"
    RABBITMQ_CIRCUIT_BREAKER_TIMEOUT: "30"
    RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_INTERVAL: "30"
    RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_TIMEOUT: "10"

    # Audit Logging
    AUDIT_LOG_ENABLED: "false"
    RABBITMQ_AUDIT_EXCHANGE: "audit.append_log.exchange"
    RABBITMQ_AUDIT_KEY: "audit.append_log.key"

    # Transaction Events
    RABBITMQ_TRANSACTION_EVENTS_ENABLED: "false"
    RABBITMQ_TRANSACTION_EVENTS_EXCHANGE: "transaction.transaction_events.exchange"

    # Async Transaction Processing
    RABBITMQ_TRANSACTION_ASYNC: "false"
    # RABBITMQ_NUMBERS_OF_WORKERS: "5"
    # RABBITMQ_NUMBERS_OF_PREFETCH: "10"

    # Bulk Recorder (requires RABBITMQ_TRANSACTION_ASYNC=true and BULK_RECORDER_ENABLED=true)
    BULK_RECORDER_ENABLED: "true"
    # BULK_RECORDER_SIZE: "0"
    # BULK_RECORDER_FLUSH_TIMEOUT_MS: ""
    # BULK_RECORDER_MAX_ROWS_PER_INSERT: ""

    # Pagination
    MAX_PAGINATION_MONTH_DATE_RANGE: "3"
    # MAX_PAGINATION_LIMIT: "100"

  secrets:
    # Onboarding Module
    DB_ONBOARDING_PASSWORD: ""
    DB_ONBOARDING_REPLICA_PASSWORD: ""
    MONGO_ONBOARDING_PASSWORD: ""

    # Transaction Module
    DB_TRANSACTION_PASSWORD: ""
    DB_TRANSACTION_REPLICA_PASSWORD: ""
    MONGO_TRANSACTION_PASSWORD: ""

    # Shared
    REDIS_PASSWORD: ""
    RABBITMQ_DEFAULT_PASS: ""
    RABBITMQ_CONSUMER_PASS: ""

Suporte a secrets externos

ledger:
  useExistingSecret: true
  existingSecretName: <existing-secret-name>

Referência de flags de deployment

Flag	Padrão	Descrição
ledger.enabled	true	Habilita o serviço Ledger unificado
onboarding.enabled	—	Serviço dividido legado — removido das versões atuais do chart (apenas migração)
transaction.enabled	—	Serviço dividido legado — removido das versões atuais do chart (apenas migração)
migration.allowAllServices	false	Flag oculta para permitir todos os serviços simultaneamente

Referência de variáveis de ambiente

Descrições detalhadas para as variáveis que não são autoexplicativas a partir do bloco YAML acima.

Pools de conexão de banco de dados

Variável	Descrição	Padrão
`DB_ONBOARDING_MAX_OPEN_CONNS`	Máximo de conexões abertas com o banco PostgreSQL de Onboarding.	Valor padrão do Go (ilimitado)
`DB_ONBOARDING_MAX_IDLE_CONNS`	Máximo de conexões ociosas mantidas vivas para o banco de Onboarding.	Valor padrão do Go (2)
`DB_TRANSACTION_MAX_OPEN_CONNS`	Máximo de conexões abertas com o banco PostgreSQL de Transaction.	Valor padrão do Go (ilimitado)
`DB_TRANSACTION_MAX_IDLE_CONNS`	Máximo de conexões ociosas mantidas vivas para o banco de Transaction.	Valor padrão do Go (2)

Para cargas de trabalho em produção, defina limites explícitos de pool para evitar o esgotamento de conexões. Um ponto de partida comum: MAX_OPEN_CONNS=25, MAX_IDLE_CONNS=10 por módulo de banco. Ajuste com base na sua configuração max_connections do PostgreSQL e no número de réplicas do Midaz.

RabbitMQ

Variável	Descrição	Padrão
`RABBITMQ_VHOST`	Virtual host do RabbitMQ. Útil para isolar o tráfego do Midaz em clusters RabbitMQ compartilhados.	`/`

Audit logging

Quando habilitado, o Midaz publica logs de auditoria detalhados em nível de operação em um exchange do RabbitMQ após cada transação. O payload de auditoria inclui os dados completos da operação (valores, contas, saldos antes/depois) serializados como JSON. Você consome esses eventos vinculando sua própria fila ao exchange de auditoria.

Variável	Descrição	Padrão
`AUDIT_LOG_ENABLED`	Habilita o audit logging de transações.	`false`
`RABBITMQ_AUDIT_EXCHANGE`	Nome do exchange do RabbitMQ para as mensagens de auditoria.	`audit.append_log.exchange`
`RABBITMQ_AUDIT_KEY`	Routing key para as mensagens de auditoria.	`audit.append_log.key`

Eventos de transação

Variável	Descrição	Padrão
`RABBITMQ_TRANSACTION_EVENTS_ENABLED`	Habilita a publicação de eventos de transação em tempo real. Veja Event publisher para mais detalhes.	`false`
`RABBITMQ_TRANSACTION_EVENTS_EXCHANGE`	Nome do exchange do RabbitMQ para os eventos de transação.	`transaction.transaction_events.exchange`

Processamento assíncrono de transações

Quando RABBITMQ_TRANSACTION_ASYNC está habilitado, o Midaz processa transações de forma assíncrona via consumidores RabbitMQ, em vez de inline durante a requisição à API. O bulk recorder ainda agrupa gravações no banco de dados para maior throughput.

As variáveis BULK_RECORDER_* só têm efeito quando ambas RABBITMQ_TRANSACTION_ASYNC=true e BULK_RECORDER_ENABLED=true estão ativas.

Variável	Descrição	Padrão
`RABBITMQ_TRANSACTION_ASYNC`	Habilita o processamento assíncrono de transações via consumidores RabbitMQ.	`false`
`RABBITMQ_NUMBERS_OF_WORKERS`	Número de goroutines de workers consumidores assíncronos.	`5`
`RABBITMQ_NUMBERS_OF_PREFETCH`	Contagem de prefetch do RabbitMQ por worker — controla quantas mensagens cada worker armazena em buffer de uma vez.	`10`
`BULK_RECORDER_ENABLED`	Habilita o modo de inserção em lote para gravações de operações quando o processamento assíncrono está ativo.	`true`
`BULK_RECORDER_SIZE`	Tamanho do lote para inserções em bulk. Defina como `0` para dimensionamento automático baseado na carga.	`0` (auto)
`BULK_RECORDER_FLUSH_TIMEOUT_MS`	Tempo máximo (em milissegundos) para aguardar antes de fazer flush de um lote incompleto.	—
`BULK_RECORDER_MAX_ROWS_PER_INSERT`	Número máximo de linhas por instrução INSERT durante gravações em bulk.	—

Paginação

Variável	Descrição	Padrão
`MAX_PAGINATION_MONTH_DATE_RANGE`	Range máximo de datas (em meses) permitido para as consultas paginadas. Limita o quão para trás os endpoints de listagem podem consultar. Use `0` para range ilimitado.	`3`
`MAX_PAGINATION_LIMIT`	Número máximo de itens retornados por página nas respostas paginadas da API.	`100`

O limite do range de datas da paginação evita full table scans custosos em grandes volumes de dados. Se seu caso de uso precisa consultar dados históricos além de 3 meses, aumente esse valor ou defina como 0 — mas monitore o desempenho das consultas.