Instalando o Matcher

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.

O Matcher está disponível para clientes licenciados; seu repositório é mantido internamente. As instruções a seguir presumem que você já tem acesso aos arquivos do projeto Matcher necessários.

Docker Compose (desenvolvimento)

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

1. Acesse o projeto Matcher

A partir do diretório do projeto Matcher:

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.

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. Em uma instalação nova, a resposta paginada por cursor tem o array items vazio:

curl -H "Authorization: Bearer $TOKEN" http://localhost:4018/v1/contexts

Em seguida, verifique as dependências obrigatórias pelo endpoint público de prontidão:

curl http://localhost:4018/readyz

O endpoint retorna 200 quando todas as dependências obrigatórias estão prontas. Ele retorna 503 com detalhes de cada verificação quando alguma dependência obrigatória está indisponível.

Serviços do Docker Compose

O docker-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 recarga automática

Para desenvolvimento ativo, use:

make dev

Isso inicia o Matcher com recarga automática habilitada usando o 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 4.1.0 \
 --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 4.1.0 \
 --namespace matcher \
 --values values.yaml

Variáveis de ambiente

As variáveis de ambiente fornecem a configuração de inicialização do Matcher. O Systemplane pode sobrescrever configurações modificáveis em tempo de execução após a inicialização.

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`	`104857600`	Tamanho máximo do corpo da requisição em buffer (bytes, padrão 100 MiB)

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)

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_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 (a validação do token é delegada aqui; o Matcher não guarda nenhum segredo JWT local)

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

Essas configurações controlam o Discovery, que lê bancos de dados externos através de um motor de extração em processo embarcado no Matcher — não um serviço em rede separado. Veja Discovery para entender como funciona.

Variável	Padrão	Descrição
`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_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)
`APP_ENC_KEY`	—	Chave mestra codificada em Base64 para o protetor de credenciais do motor embarcado

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 se o Matcher e suas dependências obrigatórias estão prontos:

curl http://localhost:4018/readyz

O endpoint retorna 200 quando todas as dependências obrigatórias estão prontas. Ele retorna 503 com detalhes de cada verificação quando alguma dependência obrigatória está indisponível. Configure as sondas de prontidão do Kubernetes para usar esse endpoint.

Solução de problemas

Problemas comuns

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

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

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

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

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_migrations se necessário

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

​Docker Compose (desenvolvimento)

​1. Acesse o projeto Matcher

​2. Configure o ambiente

​3. Inicie os serviços

​4. Verifique a instalação

​Serviços do Docker Compose

​Desenvolvimento com recarga automática

​Kubernetes / Helm (produção)

​Pré-requisitos

​1. Crie um namespace

​2. Configure os valores

​3. Crie os secrets

​4. Instale o chart

​5. Verifique a implantação

​Atualizando

​Variáveis de ambiente

​Aplicação

​CORS

​Banco de dados (PostgreSQL)

​Réplica do banco de dados (PostgreSQL)

​Cache (Redis)

​Mensageria (RabbitMQ)

​Autenticação

​Armazenamento de objetos (compatível com S3)

​Observabilidade

​TLS

​Limitação de taxa

​Swagger

​Idempotência

​Deduplicação

​Outbox

​Workers

​Agendador

​Arquivamento

​Fetcher / Discovery

​Infraestrutura

​Verificar a instalação

​Solução de problemas

​Problemas comuns

​Visualizando logs

​Modo debug

​Próximos passos

Início rápido

Configuração

Docker Compose (desenvolvimento)

1. Acesse o projeto Matcher

2. Configure o ambiente

3. Inicie os serviços

4. Verifique a instalação

Serviços do Docker Compose

Desenvolvimento com recarga automática

Kubernetes / Helm (produção)

Pré-requisitos

1. Crie um namespace

2. Configure os valores

3. Crie os secrets

4. Instale o chart

5. Verifique a implantação

Atualizando

Variáveis de ambiente

Aplicação

CORS

Banco de dados (PostgreSQL)

Réplica do banco de dados (PostgreSQL)

Cache (Redis)

Mensageria (RabbitMQ)

Autenticação

Armazenamento de objetos (compatível com S3)

Observabilidade

TLS

Limitação de taxa

Swagger

Idempotência

Deduplicação

Outbox

Workers

Agendador

Arquivamento

Fetcher / Discovery

Infraestrutura

Verificar a instalação

Solução de problemas

Problemas comuns

Visualizando logs

Modo debug

Próximos passos