Pular para o conteúdo principal

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.

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.

Docker Compose (desenvolvimento)


Docker Compose é a abordagem recomendada para desenvolvimento local e testes.

1. Clone o repositório

git clone https://github.com/LerianStudio/matcher.git
cd matcher

2. Configure o ambiente

O arquivo docker-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:
docker-compose up -d postgres redis rabbitmq
Aguarde até que todos os serviços reportem status saudável:
docker-compose ps
Inicie a aplicação do Matcher:
docker-compose up -d app
Para iniciar todos os serviços de uma vez:
docker-compose up -d

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):
curl -H "Authorization: Bearer $TOKEN" http://localhost:4018/v1/contexts
Se a chamada for bem-sucedida, a API do Matcher e suas dependências (PostgreSQL, Redis, RabbitMQ, object storage) estão acessíveis.

Serviços do Docker Compose

O docker-compose.yml padrão inclui:
ServiçoPortaPropósito
postgres5432Banco de dados PostgreSQL primário
postgres-replica5433Réplica de leitura PostgreSQL
redis6379Cache Valkey (compatível com Redis)
rabbitmq5672, 15672RabbitMQ (AMQP e UI de gerenciamento)
seaweedfs8333, 9333Armazenamento de objetos compatível com S3
app4018API do Matcher

Desenvolvimento com hot reload

Para desenvolvimento ativo, use:
make dev
Isso inicia o Matcher com live reload habilitado usando Air.

Kubernetes / Helm (produção)


Implantações em produção devem usar o chart Helm oficial.

Pré-requisitos

  • Kubernetes 1.28+
  • Helm 3.12+
  • kubectl configurado para o cluster de destino

1. Crie um namespace

kubectl create namespace matcher

2. Configure os valores

Crie um arquivo values.yaml com sua configuração de implantação:
replicaCount: 2

image:
 repository: lerianstudio/matcher
 tag: "latest"
 pullPolicy: IfNotPresent

service:
 type: ClusterIP
 port: 4018

ingress:
 enabled: true
 className: nginx
 hosts:
 - host: matcher.example.com
 paths:
 - path: /
 pathType: Prefix
 tls:
 - secretName: matcher-tls
 hosts:
 - matcher.example.com

postgresql:
 external: true
 host: postgres.example.com
 port: 5432
 database: matcher
 username: matcher
 existingSecret: matcher-db-credentials
 existingSecretKey: password

redis:
 external: true
 host: redis.example.com
 port: 6379
 existingSecret: matcher-redis-credentials

rabbitmq:
 external: true
 host: rabbitmq.example.com
 port: 5672
 username: matcher
 existingSecret: matcher-rabbitmq-credentials

auth:
 enabled: true
 serviceAddress: https://auth.example.com

observability:
 enabled: true
 otelExporterEndpoint: http://otel-collector:4317

resources:
 requests:
 cpu: 500m
 memory: 512Mi
 limits:
 cpu: 2000m
 memory: 2Gi

3. Crie os secrets

Crie secrets do Kubernetes para credenciais sensíveis:
kubectl create secret generic matcher-db-credentials \
 --from-literal=password=your-db-password \
 -n matcher

kubectl create secret generic matcher-redis-credentials \
 --from-literal=password=your-redis-password \
 -n matcher

kubectl create secret generic matcher-rabbitmq-credentials \
 --from-literal=password=your-rabbitmq-password \
 -n matcher

4. Instale o chart

helm install matcher oci://registry-1.docker.io/lerianstudio/matcher-helm \
 --version 2.1.1 \
 --namespace matcher \
 --values values.yaml

5. Verifique a implantação

kubectl get pods -n matcher
kubectl get svc -n matcher
kubectl logs -f deployment/matcher -n matcher

Atualizando

Para atualizar uma implantação existente:
helm upgrade matcher oci://registry-1.docker.io/lerianstudio/matcher-helm \
 --version 2.1.1 \
 --namespace matcher \
 --values values.yaml

Variáveis de ambiente


O Matcher é configurado inteiramente através de variáveis de ambiente.

Aplicação

VariávelPadrãoDescrição
ENV_NAMEdevelopmentNome do ambiente de runtime
LOG_LEVELinfoVerbosidade do log
DEPLOYMENT_MODElocalModo de deploy (local, byoc, saas)
SERVER_ADDRESS:4018Endereço de bind do servidor HTTP
HTTP_BODY_LIMIT_BYTES33554432Tamanho máximo do corpo da requisição (bytes)

CORS

VariávelPadrãoDescrição
CORS_ALLOWED_ORIGINShttp://localhost:3000Origens permitidas
CORS_ALLOWED_METHODSGET,POST,PUT,PATCH,DELETE,OPTIONSMétodos HTTP permitidos
CORS_ALLOWED_HEADERSOrigin,Content-Type,Accept,Authorization,X-Request-IDHeaders de request permitidos

Banco de dados (PostgreSQL)

VariávelPadrãoDescrição
POSTGRES_HOSTlocalhostHost do banco primário
POSTGRES_PORT5432Porta do banco primário
POSTGRES_USERmatcherUsuário
POSTGRES_PASSWORDmatcher_dev_passwordSenha
POSTGRES_DBmatcherNome do banco de dados
POSTGRES_SSLMODEdisableModo SSL
POSTGRES_TLS_REQUIREDfalseExigir TLS no bootstrap
POSTGRES_MAX_OPEN_CONNS25Máximo de conexões abertas
POSTGRES_MAX_IDLE_CONNS5Máximo de conexões ociosas
POSTGRES_CONN_MAX_LIFETIME_MINS30Tempo máximo de vida da conexão (minutos)
POSTGRES_CONN_MAX_IDLE_TIME_MINS5Tempo máximo ocioso da conexão (minutos)
POSTGRES_CONNECT_TIMEOUT_SEC10Timeout de conexão (segundos)
POSTGRES_QUERY_TIMEOUT_SEC30Timeout de query (segundos)
MIGRATIONS_PATHmigrationsCaminho dos arquivos de migração

Réplica do banco de dados (PostgreSQL)

VariávelPadrãoDescrição
POSTGRES_REPLICA_HOSTHost da réplica
POSTGRES_REPLICA_PORTPorta da réplica
POSTGRES_REPLICA_USERUsuário da réplica
POSTGRES_REPLICA_PASSWORDSenha da réplica
POSTGRES_REPLICA_DBNome do banco da réplica
POSTGRES_REPLICA_SSLMODEModo SSL da réplica
POSTGRES_REPLICA_TLS_REQUIREDfalseExigir TLS para a réplica

Cache (Redis)

VariávelPadrãoDescrição
REDIS_HOSTlocalhost:6379Endereço do Redis (host:porta)
REDIS_MASTER_NAMENome do master Sentinel
REDIS_PASSWORDSenha
REDIS_DB0Índice do banco de dados
REDIS_PROTOCOL3Versão do protocolo RESP
REDIS_TLSfalseHabilitar TLS
REDIS_TLS_REQUIREDfalseExigir TLS no bootstrap
REDIS_CA_CERTCaminho do certificado CA
REDIS_POOL_SIZE10Tamanho do pool de conexões
REDIS_MIN_IDLE_CONNS2Mínimo de conexões ociosas
REDIS_READ_TIMEOUT_MS3000Timeout de leitura (milissegundos)
REDIS_WRITE_TIMEOUT_MS3000Timeout de escrita (milissegundos)
REDIS_DIAL_TIMEOUT_MS5000Timeout de conexão (milissegundos)

Mensageria (RabbitMQ)

VariávelPadrãoDescrição
RABBITMQ_URIamqpEsquema URI (amqp ou amqps)
RABBITMQ_HOSTlocalhostHost do broker
RABBITMQ_PORT5672Porta do broker
RABBITMQ_USERmatcher_adminUsuário
RABBITMQ_PASSWORDmatcher_dev_passwordSenha
RABBITMQ_VHOST/Virtual host
RABBITMQ_HEALTH_URLhttp://localhost:15672URL da API de gerenciamento para health checks
RABBITMQ_ALLOW_INSECURE_HEALTH_CHECKfalsePermitir health check HTTP (sem TLS)
RABBITMQ_TLS_REQUIREDfalseExigir TLS no bootstrap

Autenticação

VariávelPadrãoDescrição
PLUGIN_AUTH_ENABLEDfalseHabilitar autenticação
PLUGIN_AUTH_ADDRESSURL do serviço de auth
AUTH_JWT_SECRETSegredo de assinatura JWT

Armazenamento de objetos (compatível com S3)

VariávelPadrãoDescrição
OBJECT_STORAGE_ENDPOINThttp://localhost:8333URL do endpoint S3
OBJECT_STORAGE_REGIONus-east-1Região S3
OBJECT_STORAGE_BUCKETmatcher-exportsBucket para exportações
OBJECT_STORAGE_ACCESS_KEY_IDID da chave de acesso
OBJECT_STORAGE_SECRET_ACCESS_KEYChave de acesso secreta
OBJECT_STORAGE_USE_PATH_STYLEtrueUsar endereçamento path-style
OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINTfalsePermitir endpoint HTTP (sem TLS)
OBJECT_STORAGE_TLS_REQUIREDfalseExigir TLS no bootstrap

Observabilidade

VariávelPadrãoDescrição
ENABLE_TELEMETRYfalseHabilitar OpenTelemetry
OTEL_RESOURCE_SERVICE_NAMEmatcherNome do serviço para traces/métricas
OTEL_LIBRARY_NAMEgithub.com/LerianStudio/matcherNome da biblioteca de instrumentação
OTEL_RESOURCE_SERVICE_VERSION1.1.0Versão do serviço
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENTdevelopmentLabel do ambiente de deploy
OTEL_EXPORTER_OTLP_ENDPOINTlocalhost:4317Endpoint do coletor OTLP
DB_METRICS_INTERVAL_SEC15Intervalo de coleta de métricas do DB

TLS

VariávelPadrãoDescrição
SERVER_TLS_CERT_FILECaminho do certificado TLS
SERVER_TLS_KEY_FILECaminho da chave privada TLS
TLS_TERMINATED_UPSTREAMfalseConfiar na terminação TLS upstream (ex: load balancer)
TRUSTED_PROXIESRanges CIDR de proxies confiáveis

Limitação de taxa

VariávelPadrãoDescrição
RATE_LIMIT_ENABLEDtrueHabilitar limitação de taxa global
RATE_LIMIT_MAX100Máximo de requisições por janela
RATE_LIMIT_EXPIRY_SEC60Janela de limitação de taxa (segundos)
EXPORT_RATE_LIMIT_MAX10Máximo de requisições de exportação por janela
EXPORT_RATE_LIMIT_EXPIRY_SEC60Janela de limitação de exportação (segundos)
DISPATCH_RATE_LIMIT_MAX50Máximo de requisições de despacho por janela
DISPATCH_RATE_LIMIT_EXPIRY_SEC60Janela de limitação de despacho (segundos)
ADMIN_RATE_LIMIT_MAX30Máximo de requisições admin por janela
ADMIN_RATE_LIMIT_EXPIRY_SEC60Janela de limitação admin (segundos)

Swagger

VariávelPadrãoDescrição
SWAGGER_ENABLEDfalseHabilitar Swagger UI
SWAGGER_HOSTSobrescrever host da spec Swagger
SWAGGER_SCHEMEShttpsEsquemas da spec Swagger (separados por vírgula)

Idempotência

VariávelPadrãoDescrição
IDEMPOTENCY_RETRY_WINDOW_SEC300Janela para retentar requisições idempotentes com falha (segundos)
IDEMPOTENCY_SUCCESS_TTL_HOURS168Tempo de cache de chaves de idempotência concluídas (horas)
IDEMPOTENCY_HMAC_SECRETSegredo HMAC para assinar chaves de idempotência (mín 32 bytes)

Deduplicação

VariávelPadrãoDescrição
DEDUPE_TTL_SEC3600TTL das chaves de deduplicação (segundos)

Outbox

VariávelPadrãoDescrição
OUTBOX_RETRY_WINDOW_SEC300Cooldown antes de retentar eventos com falha (segundos)
OUTBOX_DISPATCH_INTERVAL_SEC2Intervalo de polling do dispatcher (segundos)

Workers

VariávelPadrãoDescrição
EXPORT_WORKER_ENABLEDtrueHabilitar worker de exportação
EXPORT_WORKER_POLL_INTERVAL_SEC5Intervalo de polling do worker de exportação (segundos)
EXPORT_WORKER_PAGE_SIZE1000Linhas por página de exportação
EXPORT_PRESIGN_EXPIRY_SEC3600Validade da URL pré-assinada para exportações (segundos)
CLEANUP_WORKER_ENABLEDtrueHabilitar worker de limpeza
CLEANUP_WORKER_INTERVAL_SEC3600Intervalo do worker de limpeza (segundos)
CLEANUP_WORKER_BATCH_SIZE100Tamanho do lote de limpeza
CLEANUP_WORKER_GRACE_PERIOD_SEC3600Período de graça antes da limpeza (segundos)
WEBHOOK_TIMEOUT_SEC30Timeout de despacho de webhook (segundos)
CALLBACK_RATE_LIMIT_PER_MIN60Máximo de callbacks por sistema externo por minuto

Agendador

VariávelPadrãoDescrição
SCHEDULER_INTERVAL_SEC60Intervalo de polling do agendador cron (segundos)

Arquivamento

VariávelPadrãoDescrição
ARCHIVAL_WORKER_ENABLEDfalseHabilitar worker de arquivamento de logs de auditoria
ARCHIVAL_WORKER_INTERVAL_HOURS24Intervalo de execução do arquivamento (horas)
ARCHIVAL_HOT_RETENTION_DAYS90Dias para manter dados em armazenamento quente
ARCHIVAL_WARM_RETENTION_MONTHS24Meses para manter dados em armazenamento morno
ARCHIVAL_COLD_RETENTION_MONTHS84Meses para manter dados em armazenamento frio
ARCHIVAL_BATCH_SIZE5000Linhas por lote de arquivamento
ARCHIVAL_STORAGE_BUCKETmatcher-archivesBucket S3 para arquivos
ARCHIVAL_STORAGE_PREFIXarchives/audit-logsPrefixo de chave S3 para arquivos
ARCHIVAL_STORAGE_CLASSGLACIERClasse de armazenamento S3 para arquivos
ARCHIVAL_PARTITION_LOOKAHEAD3Quantidade de partições antecipadas
ARCHIVAL_PRESIGN_EXPIRY_SEC3600Validade da URL pré-assinada para arquivos (segundos)

Fetcher / Discovery

VariávelPadrãoDescrição
FETCHER_ENABLEDfalseHabilitar discovery via Fetcher
FETCHER_URLhttp://localhost:4006URL do serviço Fetcher
FETCHER_ALLOW_PRIVATE_IPSfalsePermitir ranges de IP privados
FETCHER_HEALTH_TIMEOUT_SEC5Timeout do health check do Fetcher (segundos)
FETCHER_REQUEST_TIMEOUT_SEC30Timeout de requisição ao Fetcher (segundos)
FETCHER_DISCOVERY_INTERVAL_SEC60Intervalo de polling de discovery (segundos)
FETCHER_SCHEMA_CACHE_TTL_SEC300TTL do cache de schema (segundos)
FETCHER_EXTRACTION_POLL_INTERVAL_SEC5Intervalo de polling de extração (segundos)
FETCHER_EXTRACTION_TIMEOUT_SEC600Timeout de extração (segundos)
FETCHER_MAX_EXTRACTION_BYTES2147483648Tamanho máximo do payload de extração (bytes, padrão 2 GiB)
FETCHER_BRIDGE_INTERVAL_SEC30Intervalo de polling do bridge worker (segundos)
FETCHER_BRIDGE_BATCH_SIZE50Extrações por tenant por ciclo de bridge
FETCHER_BRIDGE_TENANT_CONCURRENCY4Tenants concorrentes no ciclo de bridge
FETCHER_BRIDGE_STALE_THRESHOLD_SEC3600Limiar de extração obsoleta (segundos)
FETCHER_BRIDGE_RETRY_MAX_ATTEMPTS5Máximo de tentativas por extração
FETCHER_CUSTODY_RETENTION_SWEEP_INTERVAL_SEC900Intervalo de varredura de custódia (segundos)
FETCHER_CUSTODY_RETENTION_GRACE_PERIOD_SEC3600Período de graça antes de deletar custódia (segundos)
APP_ENC_KEYChave mestra codificada em Base64 compartilhada com o Fetcher

Credenciais M2M

VariávelPadrãoDescrição
M2M_TARGET_SERVICEfetcherNome do serviço alvo para busca de credenciais
M2M_CREDENTIAL_CACHE_TTL_SEC300TTL do cache Redis para credenciais M2M (segundos)
AWS_REGIONRegião AWS para o Secrets Manager

Infraestrutura

VariávelPadrãoDescrição
INFRA_CONNECT_TIMEOUT_SEC30Timeout de conexão de infraestrutura no startup (segundos)
HEALTH_CHECK_TIMEOUT_SEC5Timeout legado por verificação (segundos)
HEALTH_CHECK_TIMEOUT_MS800Timeout 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:
curl -X POST http://localhost:4018/v1/contexts \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Contexto de Teste",
   "type": "1:1"
 }'
Uma resposta bem-sucedida confirma que a API e suas dependências (banco de dados, cache, message broker, object storage) estão acessíveis. Os probes de liveness e readiness do Kubernetes são configurados no nível do cluster pela orquestração; você não precisa chamá-los diretamente.

Solução de problemas


Problemas comuns

  • Causa: PostgreSQL não está em execução ou inacessível.
  • Resolução:
  1. Verifique se o PostgreSQL está em execução: docker-compose ps postgres
  2. Verifique os valores de conexão em .env
  3. Teste a conectividade: nc -zv localhost 5432
  4. Revise os logs: docker-compose logs postgres
  • Causa: Redis não está em execução ou as credenciais estão incorretas.
  • Resolução:
  1. Verifique se o Redis está em execução: docker-compose ps redis
  2. Confirme REDIS_PASSWORD
  3. Teste a conectividade: redis-cli -h localhost ping
  • Causa: RabbitMQ ainda está inicializando ou o virtual host está faltando.
  • Resolução:
  1. Aguarde até que o RabbitMQ esteja saudável
  2. Acesse a UI de gerenciamento em http://localhost:15672
  3. Verifique RABBITMQ_VHOST
  • Causa: Serviço de auth está inacessível ou o token é inválido.
  • Resolução:
  1. Verifique PLUGIN_AUTH_ADDRESS
  2. Desabilite auth para desenvolvimento: PLUGIN_AUTH_ENABLED=false
  3. Revise os logs do serviço de auth
  • Causa: Migrations do banco de dados não puderam ser aplicadas.
  • Resolução:
  1. Verifique o status das migrations: make migrate-status
  2. Revise os logs das migrations
  3. Aplique migrations manualmente: make migrate-up
  4. Inspecione a tabela schema_migrations se necessário
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

docker-compose logs -f app
kubectl logs -f deployment/matcher -n matcher

Modo debug

Habilite logging de debug para visibilidade adicional:
LOG_LEVEL=debug docker-compose up app

Próximos passos


Início rápido

Execute sua primeira conciliação.

Configuração

Configure contextos, fontes e regras de match.