O Matcher automatiza a reconciliação financeira entre múltiplas fontes de dados, eliminando o trabalho manual de conciliação e fornecendo uma trilha de auditoria completa para cada transação. Configurar o Matcher significa estabelecer a base para o gerenciamento de exceções, relatórios de conformidade e visibilidade operacional. Este guia apresenta o passo a passo para implantar o Matcher em ambientes de desenvolvimento e produção.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.
Docker Compose (desenvolvimento)
Docker Compose é a abordagem recomendada para desenvolvimento local e testes.
1. Clone o repositório
2. Configure o ambiente
O arquivodocker-compose.yml inclui valores padrão adequados para desenvolvimento local. Você pode sobrescrever qualquer valor definindo variáveis de ambiente no seu shell ou criando um arquivo .env na raiz do projeto.
Consulte Variáveis de ambiente para detalhes sobre as configurações disponíveis.
Uma variável obrigatória não possui valor padrão:
SYSTEMPLANE_SECRET_MASTER_KEY. Veja config/.config-map.example no repositório para instruções de geração.3. Inicie os serviços
Inicie os serviços de infraestrutura necessários:4. Verifique a instalação
Confirme que o Matcher está em execução listando os contextos de configuração (a chamada retorna um array vazio em uma instalação nova):Serviços do Docker Compose
Odocker-compose.yml padrão inclui:
| Serviço | Porta | Propósito |
|---|---|---|
postgres | 5432 | Banco de dados PostgreSQL primário |
postgres-replica | 5433 | Réplica de leitura PostgreSQL |
redis | 6379 | Cache Valkey (compatível com Redis) |
rabbitmq | 5672, 15672 | RabbitMQ (AMQP e UI de gerenciamento) |
seaweedfs | 8333, 9333 | Armazenamento de objetos compatível com S3 |
app | 4018 | API do Matcher |
Desenvolvimento com hot reload
Para desenvolvimento ativo, use:Kubernetes / Helm (produção)
Implantações em produção devem usar o chart Helm oficial.
Pré-requisitos
- Kubernetes 1.28+
- Helm 3.12+
kubectlconfigurado para o cluster de destino
1. Crie um namespace
2. Configure os valores
Crie um arquivovalues.yaml com sua configuração de implantação:
3. Crie os secrets
Crie secrets do Kubernetes para credenciais sensíveis:4. Instale o chart
5. Verifique a implantação
Atualizando
Para atualizar uma implantação existente:Variáveis de ambiente
O Matcher é configurado inteiramente através de variáveis de ambiente.
Aplicação
| Variável | Padrão | Descrição |
|---|---|---|
ENV_NAME | development | Nome do ambiente de runtime |
LOG_LEVEL | info | Verbosidade do log |
DEPLOYMENT_MODE | local | Modo de deploy (local, byoc, saas) |
SERVER_ADDRESS | :4018 | Endereço de bind do servidor HTTP |
HTTP_BODY_LIMIT_BYTES | 33554432 | Tamanho máximo do corpo da requisição (bytes) |
CORS
| Variável | Padrão | Descrição |
|---|---|---|
CORS_ALLOWED_ORIGINS | http://localhost:3000 | Origens permitidas |
CORS_ALLOWED_METHODS | GET,POST,PUT,PATCH,DELETE,OPTIONS | Métodos HTTP permitidos |
CORS_ALLOWED_HEADERS | Origin,Content-Type,Accept,Authorization,X-Request-ID | Headers de request permitidos |
Banco de dados (PostgreSQL)
| Variável | Padrão | Descrição |
|---|---|---|
POSTGRES_HOST | localhost | Host do banco primário |
POSTGRES_PORT | 5432 | Porta do banco primário |
POSTGRES_USER | matcher | Usuário |
POSTGRES_PASSWORD | matcher_dev_password | Senha |
POSTGRES_DB | matcher | Nome do banco de dados |
POSTGRES_SSLMODE | disable | Modo SSL |
POSTGRES_TLS_REQUIRED | false | Exigir TLS no bootstrap |
POSTGRES_MAX_OPEN_CONNS | 25 | Máximo de conexões abertas |
POSTGRES_MAX_IDLE_CONNS | 5 | Máximo de conexões ociosas |
POSTGRES_CONN_MAX_LIFETIME_MINS | 30 | Tempo máximo de vida da conexão (minutos) |
POSTGRES_CONN_MAX_IDLE_TIME_MINS | 5 | Tempo máximo ocioso da conexão (minutos) |
POSTGRES_CONNECT_TIMEOUT_SEC | 10 | Timeout de conexão (segundos) |
POSTGRES_QUERY_TIMEOUT_SEC | 30 | Timeout de query (segundos) |
MIGRATIONS_PATH | migrations | Caminho dos arquivos de migração |
Réplica do banco de dados (PostgreSQL)
| Variável | Padrão | Descrição |
|---|---|---|
POSTGRES_REPLICA_HOST | — | Host da réplica |
POSTGRES_REPLICA_PORT | — | Porta da réplica |
POSTGRES_REPLICA_USER | — | Usuário da réplica |
POSTGRES_REPLICA_PASSWORD | — | Senha da réplica |
POSTGRES_REPLICA_DB | — | Nome do banco da réplica |
POSTGRES_REPLICA_SSLMODE | — | Modo SSL da réplica |
POSTGRES_REPLICA_TLS_REQUIRED | false | Exigir TLS para a réplica |
Cache (Redis)
| Variável | Padrão | Descrição |
|---|---|---|
REDIS_HOST | localhost:6379 | Endereço do Redis (host:porta) |
REDIS_MASTER_NAME | — | Nome do master Sentinel |
REDIS_PASSWORD | — | Senha |
REDIS_DB | 0 | Índice do banco de dados |
REDIS_PROTOCOL | 3 | Versão do protocolo RESP |
REDIS_TLS | false | Habilitar TLS |
REDIS_TLS_REQUIRED | false | Exigir TLS no bootstrap |
REDIS_CA_CERT | — | Caminho do certificado CA |
REDIS_POOL_SIZE | 10 | Tamanho do pool de conexões |
REDIS_MIN_IDLE_CONNS | 2 | Mínimo de conexões ociosas |
REDIS_READ_TIMEOUT_MS | 3000 | Timeout de leitura (milissegundos) |
REDIS_WRITE_TIMEOUT_MS | 3000 | Timeout de escrita (milissegundos) |
REDIS_DIAL_TIMEOUT_MS | 5000 | Timeout de conexão (milissegundos) |
Mensageria (RabbitMQ)
| Variável | Padrão | Descrição |
|---|---|---|
RABBITMQ_URI | amqp | Esquema URI (amqp ou amqps) |
RABBITMQ_HOST | localhost | Host do broker |
RABBITMQ_PORT | 5672 | Porta do broker |
RABBITMQ_USER | matcher_admin | Usuário |
RABBITMQ_PASSWORD | matcher_dev_password | Senha |
RABBITMQ_VHOST | / | Virtual host |
RABBITMQ_HEALTH_URL | http://localhost:15672 | URL da API de gerenciamento para health checks |
RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK | false | Permitir health check HTTP (sem TLS) |
RABBITMQ_TLS_REQUIRED | false | Exigir TLS no bootstrap |
Autenticação
| Variável | Padrão | Descrição |
|---|---|---|
PLUGIN_AUTH_ENABLED | false | Habilitar autenticação |
PLUGIN_AUTH_ADDRESS | — | URL do serviço de auth |
AUTH_JWT_SECRET | — | Segredo de assinatura JWT |
Armazenamento de objetos (compatível com S3)
| Variável | Padrão | Descrição |
|---|---|---|
OBJECT_STORAGE_ENDPOINT | http://localhost:8333 | URL do endpoint S3 |
OBJECT_STORAGE_REGION | us-east-1 | Região S3 |
OBJECT_STORAGE_BUCKET | matcher-exports | Bucket para exportações |
OBJECT_STORAGE_ACCESS_KEY_ID | — | ID da chave de acesso |
OBJECT_STORAGE_SECRET_ACCESS_KEY | — | Chave de acesso secreta |
OBJECT_STORAGE_USE_PATH_STYLE | true | Usar endereçamento path-style |
OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT | false | Permitir endpoint HTTP (sem TLS) |
OBJECT_STORAGE_TLS_REQUIRED | false | Exigir TLS no bootstrap |
Observabilidade
| Variável | Padrão | Descrição |
|---|---|---|
ENABLE_TELEMETRY | false | Habilitar OpenTelemetry |
OTEL_RESOURCE_SERVICE_NAME | matcher | Nome do serviço para traces/métricas |
OTEL_LIBRARY_NAME | github.com/LerianStudio/matcher | Nome da biblioteca de instrumentação |
OTEL_RESOURCE_SERVICE_VERSION | 1.1.0 | Versão do serviço |
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT | development | Label do ambiente de deploy |
OTEL_EXPORTER_OTLP_ENDPOINT | localhost:4317 | Endpoint do coletor OTLP |
DB_METRICS_INTERVAL_SEC | 15 | Intervalo de coleta de métricas do DB |
TLS
| Variável | Padrão | Descrição |
|---|---|---|
SERVER_TLS_CERT_FILE | — | Caminho do certificado TLS |
SERVER_TLS_KEY_FILE | — | Caminho da chave privada TLS |
TLS_TERMINATED_UPSTREAM | false | Confiar na terminação TLS upstream (ex: load balancer) |
TRUSTED_PROXIES | — | Ranges CIDR de proxies confiáveis |
Limitação de taxa
| Variável | Padrão | Descrição |
|---|---|---|
RATE_LIMIT_ENABLED | true | Habilitar limitação de taxa global |
RATE_LIMIT_MAX | 100 | Máximo de requisições por janela |
RATE_LIMIT_EXPIRY_SEC | 60 | Janela de limitação de taxa (segundos) |
EXPORT_RATE_LIMIT_MAX | 10 | Máximo de requisições de exportação por janela |
EXPORT_RATE_LIMIT_EXPIRY_SEC | 60 | Janela de limitação de exportação (segundos) |
DISPATCH_RATE_LIMIT_MAX | 50 | Máximo de requisições de despacho por janela |
DISPATCH_RATE_LIMIT_EXPIRY_SEC | 60 | Janela de limitação de despacho (segundos) |
ADMIN_RATE_LIMIT_MAX | 30 | Máximo de requisições admin por janela |
ADMIN_RATE_LIMIT_EXPIRY_SEC | 60 | Janela de limitação admin (segundos) |
Swagger
| Variável | Padrão | Descrição |
|---|---|---|
SWAGGER_ENABLED | false | Habilitar Swagger UI |
SWAGGER_HOST | — | Sobrescrever host da spec Swagger |
SWAGGER_SCHEMES | https | Esquemas da spec Swagger (separados por vírgula) |
Idempotência
| Variável | Padrão | Descrição |
|---|---|---|
IDEMPOTENCY_RETRY_WINDOW_SEC | 300 | Janela para retentar requisições idempotentes com falha (segundos) |
IDEMPOTENCY_SUCCESS_TTL_HOURS | 168 | Tempo de cache de chaves de idempotência concluídas (horas) |
IDEMPOTENCY_HMAC_SECRET | — | Segredo HMAC para assinar chaves de idempotência (mín 32 bytes) |
Deduplicação
| Variável | Padrão | Descrição |
|---|---|---|
DEDUPE_TTL_SEC | 3600 | TTL das chaves de deduplicação (segundos) |
Outbox
| Variável | Padrão | Descrição |
|---|---|---|
OUTBOX_RETRY_WINDOW_SEC | 300 | Cooldown antes de retentar eventos com falha (segundos) |
OUTBOX_DISPATCH_INTERVAL_SEC | 2 | Intervalo de polling do dispatcher (segundos) |
Workers
| Variável | Padrão | Descrição |
|---|---|---|
EXPORT_WORKER_ENABLED | true | Habilitar worker de exportação |
EXPORT_WORKER_POLL_INTERVAL_SEC | 5 | Intervalo de polling do worker de exportação (segundos) |
EXPORT_WORKER_PAGE_SIZE | 1000 | Linhas por página de exportação |
EXPORT_PRESIGN_EXPIRY_SEC | 3600 | Validade da URL pré-assinada para exportações (segundos) |
CLEANUP_WORKER_ENABLED | true | Habilitar worker de limpeza |
CLEANUP_WORKER_INTERVAL_SEC | 3600 | Intervalo do worker de limpeza (segundos) |
CLEANUP_WORKER_BATCH_SIZE | 100 | Tamanho do lote de limpeza |
CLEANUP_WORKER_GRACE_PERIOD_SEC | 3600 | Período de graça antes da limpeza (segundos) |
WEBHOOK_TIMEOUT_SEC | 30 | Timeout de despacho de webhook (segundos) |
CALLBACK_RATE_LIMIT_PER_MIN | 60 | Máximo de callbacks por sistema externo por minuto |
Agendador
| Variável | Padrão | Descrição |
|---|---|---|
SCHEDULER_INTERVAL_SEC | 60 | Intervalo de polling do agendador cron (segundos) |
Arquivamento
| Variável | Padrão | Descrição |
|---|---|---|
ARCHIVAL_WORKER_ENABLED | false | Habilitar worker de arquivamento de logs de auditoria |
ARCHIVAL_WORKER_INTERVAL_HOURS | 24 | Intervalo de execução do arquivamento (horas) |
ARCHIVAL_HOT_RETENTION_DAYS | 90 | Dias para manter dados em armazenamento quente |
ARCHIVAL_WARM_RETENTION_MONTHS | 24 | Meses para manter dados em armazenamento morno |
ARCHIVAL_COLD_RETENTION_MONTHS | 84 | Meses para manter dados em armazenamento frio |
ARCHIVAL_BATCH_SIZE | 5000 | Linhas por lote de arquivamento |
ARCHIVAL_STORAGE_BUCKET | matcher-archives | Bucket S3 para arquivos |
ARCHIVAL_STORAGE_PREFIX | archives/audit-logs | Prefixo de chave S3 para arquivos |
ARCHIVAL_STORAGE_CLASS | GLACIER | Classe de armazenamento S3 para arquivos |
ARCHIVAL_PARTITION_LOOKAHEAD | 3 | Quantidade de partições antecipadas |
ARCHIVAL_PRESIGN_EXPIRY_SEC | 3600 | Validade da URL pré-assinada para arquivos (segundos) |
Fetcher / Discovery
| Variável | Padrão | Descrição |
|---|---|---|
FETCHER_ENABLED | false | Habilitar discovery via Fetcher |
FETCHER_URL | http://localhost:4006 | URL do serviço Fetcher |
FETCHER_ALLOW_PRIVATE_IPS | false | Permitir ranges de IP privados |
FETCHER_HEALTH_TIMEOUT_SEC | 5 | Timeout do health check do Fetcher (segundos) |
FETCHER_REQUEST_TIMEOUT_SEC | 30 | Timeout de requisição ao Fetcher (segundos) |
FETCHER_DISCOVERY_INTERVAL_SEC | 60 | Intervalo de polling de discovery (segundos) |
FETCHER_SCHEMA_CACHE_TTL_SEC | 300 | TTL do cache de schema (segundos) |
FETCHER_EXTRACTION_POLL_INTERVAL_SEC | 5 | Intervalo de polling de extração (segundos) |
FETCHER_EXTRACTION_TIMEOUT_SEC | 600 | Timeout de extração (segundos) |
FETCHER_MAX_EXTRACTION_BYTES | 2147483648 | Tamanho máximo do payload de extração (bytes, padrão 2 GiB) |
FETCHER_BRIDGE_INTERVAL_SEC | 30 | Intervalo de polling do bridge worker (segundos) |
FETCHER_BRIDGE_BATCH_SIZE | 50 | Extrações por tenant por ciclo de bridge |
FETCHER_BRIDGE_TENANT_CONCURRENCY | 4 | Tenants concorrentes no ciclo de bridge |
FETCHER_BRIDGE_STALE_THRESHOLD_SEC | 3600 | Limiar de extração obsoleta (segundos) |
FETCHER_BRIDGE_RETRY_MAX_ATTEMPTS | 5 | Máximo de tentativas por extração |
FETCHER_CUSTODY_RETENTION_SWEEP_INTERVAL_SEC | 900 | Intervalo de varredura de custódia (segundos) |
FETCHER_CUSTODY_RETENTION_GRACE_PERIOD_SEC | 3600 | Período de graça antes de deletar custódia (segundos) |
APP_ENC_KEY | — | Chave mestra codificada em Base64 compartilhada com o Fetcher |
Credenciais M2M
| Variável | Padrão | Descrição |
|---|---|---|
M2M_TARGET_SERVICE | fetcher | Nome do serviço alvo para busca de credenciais |
M2M_CREDENTIAL_CACHE_TTL_SEC | 300 | TTL do cache Redis para credenciais M2M (segundos) |
AWS_REGION | — | Região AWS para o Secrets Manager |
Infraestrutura
| Variável | Padrão | Descrição |
|---|---|---|
INFRA_CONNECT_TIMEOUT_SEC | 30 | Timeout de conexão de infraestrutura no startup (segundos) |
HEALTH_CHECK_TIMEOUT_SEC | 5 | Timeout legado por verificação (segundos) |
HEALTH_CHECK_TIMEOUT_MS | 800 | Timeout por verificação (milissegundos, preferido) |
Para configurações de implantação multi-tenant, veja Modo Multi-Tenant. Para gerenciamento de configuração em runtime, veja Configuração em Runtime (Systemplane).
Verificar a instalação
Valide que o Matcher está operando corretamente exercitando a API:
Solução de problemas
Problemas comuns
Conexão recusada ao PostgreSQL
Conexão recusada ao PostgreSQL
- Causa: PostgreSQL não está em execução ou inacessível.
- Resolução:
- Verifique se o PostgreSQL está em execução:
docker-compose ps postgres - Verifique os valores de conexão em
.env - Teste a conectividade:
nc -zv localhost 5432 - Revise os logs:
docker-compose logs postgres
Timeout de conexão Redis
Timeout de conexão Redis
- Causa: Redis não está em execução ou as credenciais estão incorretas.
- Resolução:
- Verifique se o Redis está em execução:
docker-compose ps redis - Confirme
REDIS_PASSWORD - Teste a conectividade:
redis-cli -h localhost ping
Filas do RabbitMQ não criadas
Filas do RabbitMQ não criadas
- Causa: RabbitMQ ainda está inicializando ou o virtual host está faltando.
- Resolução:
- Aguarde até que o RabbitMQ esteja saudável
- Acesse a UI de gerenciamento em http://localhost:15672
- Verifique
RABBITMQ_VHOST
Erros de autenticação
Erros de autenticação
- Causa: Serviço de auth está inacessível ou o token é inválido.
- Resolução:
- Verifique
PLUGIN_AUTH_ADDRESS - Desabilite auth para desenvolvimento:
PLUGIN_AUTH_ENABLED=false - Revise os logs do serviço de auth
Migration falhou
Migration falhou
- Causa: Migrations do banco de dados não puderam ser aplicadas.
- Resolução:
- Verifique o status das migrations:
make migrate-status - Revise os logs das migrations
- Aplique migrations manualmente:
make migrate-up - Inspecione a tabela
schema_migrationsse necessário
Erros de migração do banco de dados ao atualizar a partir da branch main
Erros de migração do banco de dados ao atualizar a partir da branch main
Ao atualizar a partir da branch main, as migrations 000020 e 000021 são executadas automaticamente. A migration 000020 renomeia as chaves de configuração do systemplane para padronização entre produtos. A migration 000021 converte a coluna
external_system de um tipo enum para VARCHAR(255), permitindo identificadores arbitrários de sistema externo. Se as migrations falharem, verifique a tabela schema_migrations e certifique-se de que não existem alterações manuais conflitantes.Visualizando logs
Modo debug
Habilite logging de debug para visibilidade adicional:Próximos passos
Início rápido
Execute sua primeira conciliação.
Configuração
Configure contextos, fontes e regras de match.

