Instalação do Matcher

O Matcher automatiza a conciliação financeira entre várias fontes de dados, elimina o trabalho manual de correspondência e entrega uma trilha de auditoria completa de cada transação. Este guia percorre o deploy do Matcher em ambientes de desenvolvimento e de produção.

O Matcher está disponível para clientes licenciados. A Lerian mantém o repositório dele internamente. As instruções abaixo supõem que você já tem acesso aos arquivos necessários do projeto Matcher.

Docker compose (desenvolvimento)

O Docker Compose é a abordagem recomendada para desenvolvimento e testes locais.

1. Acesse o projeto Matcher

No diretório do projeto Matcher:

cd matcher

2. Configure o ambiente

O arquivo docker-compose.yml inclui padrões sensatos 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. Veja Variáveis de ambiente para detalhes sobre as configurações disponíveis.

3. Suba os serviços

Suba os serviços de infraestrutura necessários:

docker-compose up -d postgres redis rabbitmq

Espere até todos os serviços reportarem status saudável:

docker-compose ps

Suba a aplicação Matcher:

docker-compose up -d app

Para subir todos os serviços de uma vez:

docker-compose up -d

4. Verifique a instalação

Liste os contextos de configuração para confirmar que o Matcher está no ar. Em uma instalação nova, a resposta paginada por cursor traz um array items vazio:

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

Depois verifique as dependências obrigatórias pelo endpoint público de readiness:

curl http://localhost:4018/readyz

O endpoint retorna 200 quando cada dependência obrigatória está pronta. Ele retorna 503 com os detalhes por verificação quando uma dependência obrigatória está indisponível.

Serviços do Docker compose

O docker-compose.yml padrão inclui:

Serviço	Porta	Função
`postgres`	5432	Banco de dados primário PostgreSQL
`postgres-replica`	5433	Réplica de leitura do 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:

make dev

Isso sobe o Matcher com live reload habilitado usando o Air.

Kubernetes / helm (produção)

Recomenda-se que os deploys de produção usem o Helm chart 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 values

Crie um arquivo values.yaml com a configuração do seu deploy:

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 as 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 o deploy

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

Upgrade

Para fazer o upgrade de um deploy 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 bootstrap do Matcher. O Systemplane pode sobrescrever as configurações mutáveis em tempo de execução depois da inicialização.

Aplicação

Variável	Padrão	Descrição
`ENV_NAME`	`development`	Nome do ambiente de execução
`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 com 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 requisição permitidos

Banco de dados (PostgreSQL)

Variável	Padrão	Descrição
`POSTGRES_HOST`	`localhost`	Host do banco de dados primário
`POSTGRES_PORT`	`5432`	Porta do banco de dados 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`	Exige 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 de vida máximo da conexão (minutos)
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	`5`	Tempo máximo de ociosidade 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 de dados da réplica
`POSTGRES_REPLICA_SSLMODE`	—	Modo SSL da réplica
`POSTGRES_REPLICA_TLS_REQUIRED`	`false`	Exige TLS na réplica

Cache (Redis)

Variável	Padrão	Descrição
`REDIS_HOST`	`localhost:6379`	Endereço do Redis (host:port)
`REDIS_MASTER_NAME`	—	Nome do master do Sentinel
`REDIS_PASSWORD`	—	Senha
`REDIS_DB`	`0`	Índice do banco de dados
`REDIS_TLS`	`false`	Habilita o TLS
`REDIS_TLS_REQUIRED`	`false`	Exige TLS no bootstrap
`REDIS_CA_CERT`	—	Caminho do certificado da 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 estabelecimento da conexão (milissegundos)

Mensageria (RabbitMQ)

Variável	Padrão	Descrição
`RABBITMQ_URI`	`amqp`	Esquema da 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 os health checks
`RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK`	`false`	Permite health check por HTTP (sem TLS)
`RABBITMQ_TLS_REQUIRED`	`false`	Exige TLS no bootstrap

Autenticação

Variável	Padrão	Descrição
`PLUGIN_AUTH_ENABLED`	`false`	Habilita a autenticação
`PLUGIN_AUTH_ADDRESS`	—	URL do serviço de Auth (a validação de token é delegada a ele; 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 do S3
`OBJECT_STORAGE_BUCKET`	`matcher-exports`	Bucket para exportações
`OBJECT_STORAGE_ACCESS_KEY_ID`	—	ID da access key
`OBJECT_STORAGE_SECRET_ACCESS_KEY`	—	Secret access key
`OBJECT_STORAGE_USE_PATH_STYLE`	`true`	Usa endereçamento path-style
`OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT`	`false`	Permite endpoint por HTTP (sem TLS)
`OBJECT_STORAGE_TLS_REQUIRED`	`false`	Exige TLS no bootstrap

Observabilidade

Variável	Padrão	Descrição
`ENABLE_TELEMETRY`	`false`	Habilita o OpenTelemetry
`OTEL_RESOURCE_SERVICE_NAME`	`matcher`	Nome do serviço nos 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`	Rótulo do ambiente de deploy
`OTEL_EXPORTER_OTLP_ENDPOINT`	`localhost:4317`	Endpoint do coletor OTLP
`DB_METRICS_INTERVAL_SEC`	`15`	Intervalo de coleta das métricas do banco

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`	Confia na terminação TLS upstream (por exemplo, um load balancer)
`TRUSTED_PROXIES`	—	Faixas CIDR de proxies confiáveis

Rate limiting

Variável	Padrão	Descrição
`RATE_LIMIT_ENABLED`	`true`	Habilita o rate limit global
`RATE_LIMIT_MAX`	`100`	Máximo de requisições por janela
`RATE_LIMIT_EXPIRY_SEC`	`60`	Janela do rate limit (segundos)
`EXPORT_RATE_LIMIT_MAX`	`10`	Máximo de requisições de exportação por janela
`EXPORT_RATE_LIMIT_EXPIRY_SEC`	`60`	Janela do rate limit 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 do rate limit de despacho (segundos)
`ADMIN_RATE_LIMIT_MAX`	`30`	Máximo de requisições de admin por janela
`ADMIN_RATE_LIMIT_EXPIRY_SEC`	`60`	Janela do rate limit de admin (segundos)

Swagger

Variável	Padrão	Descrição
`SWAGGER_ENABLED`	`false`	Habilita a UI do Swagger
`SWAGGER_HOST`	—	Sobrescreve o host da especificação Swagger
`SWAGGER_SCHEMES`	`https`	Esquemas da especificação Swagger (separados por vírgula)

Idempotência

Variável	Padrão	Descrição
`IDEMPOTENCY_RETRY_WINDOW_SEC`	`300`	Janela para repetir requisições idempotentes que falharam (segundos)
`IDEMPOTENCY_SUCCESS_TTL_HOURS`	`168`	Por quanto tempo as chaves de idempotência concluídas ficam em cache (horas)
`IDEMPOTENCY_HMAC_SECRET`	—	Segredo HMAC para assinar as chaves de idempotência (mínimo 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`	Espera antes de repetir eventos que falharam (segundos)
`OUTBOX_DISPATCH_INTERVAL_SEC`	`2`	Intervalo de polling do dispatcher (segundos)

Workers

Variável	Padrão	Descrição
`EXPORT_WORKER_ENABLED`	`true`	Habilita o 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`	Expiração da URL pré-assinada das exportações (segundos)
`CLEANUP_WORKER_ENABLED`	`true`	Habilita o 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 carência antes da limpeza (segundos)
`WEBHOOK_TIMEOUT_SEC`	`30`	Timeout do 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 baseado em cron (segundos)

Arquivamento

Variável	Padrão	Descrição
`ARCHIVAL_WORKER_ENABLED`	`false`	Habilita o worker de arquivamento do log de auditoria
`ARCHIVAL_WORKER_INTERVAL_HOURS`	`24`	Intervalo entre execuções de arquivamento (horas)
`ARCHIVAL_HOT_RETENTION_DAYS`	`90`	Dias para manter os dados no armazenamento hot
`ARCHIVAL_WARM_RETENTION_MONTHS`	`24`	Meses para manter os dados no armazenamento warm
`ARCHIVAL_COLD_RETENTION_MONTHS`	`84`	Meses para manter os dados no armazenamento cold
`ARCHIVAL_BATCH_SIZE`	`5000`	Linhas por lote de arquivamento
`ARCHIVAL_STORAGE_BUCKET`	`matcher-archives`	Bucket S3 dos arquivamentos
`ARCHIVAL_STORAGE_CLASS`	`GLACIER`	Classe de armazenamento S3 dos arquivamentos
`ARCHIVAL_PARTITION_LOOKAHEAD`	`3`	Número de partições antecipadas
`ARCHIVAL_PRESIGN_EXPIRY_SEC`	`3600`	Expiração da URL pré-assinada dos arquivamentos (segundos)

Discovery

Estas configurações controlam o Discovery, que lê bancos de dados externos por um motor de extração embutido no Matcher, no mesmo processo, e não por um serviço de rede separado. Veja Discovery para entender como ele funciona.

Variável	Padrão	Descrição
`FETCHER_DISCOVERY_INTERVAL_SEC`	`60`	Intervalo de polling do 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 do protetor de credenciais do motor embutido

Infraestrutura

Variável	Padrão	Descrição
`INFRA_CONNECT_TIMEOUT_SEC`	`30`	Timeout de conexão na inicialização da infraestrutura (segundos)
`HEALTH_CHECK_TIMEOUT_SEC`	`5`	Timeout legado do probe por verificação (segundos)
`HEALTH_CHECK_TIMEOUT_MS`	`800`	Timeout do probe por verificação (milissegundos, preferido)

Para as configurações de deploy multi-tenant, veja Modo multi-tenant. Para o gerenciamento da configuração em tempo de execução, veja Configuração em tempo de execução (Systemplane).

Verifique a instalação

Valide se o Matcher e as dependências obrigatórias dele estão prontos:

curl http://localhost:4018/readyz

O endpoint retorna 200 quando cada dependência obrigatória está pronta. Ele retorna 503 com os detalhes por verificação quando uma dependência obrigatória está indisponível. Configure os readiness probes do Kubernetes para usar esse endpoint.

Solução de problemas

Problemas comuns

Conexão recusada ao PostgreSQL

Causa: o PostgreSQL está fora do ar ou inacessível.
Resolução:

Verifique se o PostgreSQL está no ar: docker-compose ps postgres
Confira os valores de conexão no .env
Teste a conectividade: nc -zv localhost 5432
Revise os logs: docker-compose logs postgres

Timeout de conexão com o Redis

Causa: o Redis está fora do ar ou as credenciais estão incorretas.
Resolução:

Verifique se o Redis está no ar: docker-compose ps redis
Confirme REDIS_PASSWORD
Teste a conectividade: redis-cli -h localhost ping

Filas do RabbitMQ não criadas

Causa: o RabbitMQ ainda está na inicialização, ou o virtual host não existe.
Resolução:

Espere até o RabbitMQ ficar saudável
Acesse a UI de gerenciamento em http://localhost:15672
Verifique RABBITMQ_VHOST

Erros de autenticação

Causa: o serviço de Auth está inacessível ou o token é inválido.
Resolução:

Verifique PLUGIN_AUTH_ADDRESS
Desabilite o auth para desenvolvimento: PLUGIN_AUTH_ENABLED=false
Revise os logs do serviço de Auth

Falha na migração

Causa: as migrações do banco de dados não puderam ser aplicadas.
Resolução:

Verifique o status da migração: make migrate-status
Revise os logs da migração
Aplique as migrações manualmente: make migrate-up
Inspecione a tabela schema_migrations se precisar

Ver os logs

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

Modo debug

Habilite o log de debug para mais visibilidade:

LOG_LEVEL=debug docker-compose up app

​Docker compose (desenvolvimento)

​1. Acesse o projeto Matcher

​2. Configure o ambiente

​3. Suba os serviços

​4. Verifique a instalação

​Serviços do Docker compose

​Desenvolvimento com hot reload

​Kubernetes / helm (produção)

​Pré-requisitos

​1. Crie um namespace

​2. Configure os values

​3. Crie os secrets

​4. Instale o chart

​5. Verifique o deploy

​Upgrade

​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

​Rate limiting

​Swagger

​Idempotência

​Deduplicação

​Outbox

​Workers

​Agendador

​Arquivamento

​Discovery

​Infraestrutura

​Verifique a instalação

​Solução de problemas

​Problemas comuns

​Ver os 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. Suba os serviços

4. Verifique a instalação

Serviços do Docker compose

Desenvolvimento com hot reload

Kubernetes / helm (produção)

Pré-requisitos

1. Crie um namespace

2. Configure os values

3. Crie os secrets

4. Instale o chart

5. Verifique o deploy

Upgrade

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

Rate limiting

Swagger

Idempotência

Deduplicação

Outbox

Workers

Agendador

Arquivamento

Discovery

Infraestrutura

Verifique a instalação

Solução de problemas

Problemas comuns

Ver os logs

Modo debug

Próximos passos