Pular para o conteúdo principal
Multi-tenancy permite que um único deployment atenda múltiplos clientes independentes — chamados tenants — com isolamento completo de dados entre eles. Cada tenant opera como se tivesse seu próprio ambiente dedicado, mesmo que a infraestrutura subjacente seja compartilhada. Na Lerian, o multi-tenancy está disponível em deployments SaaS (sempre ativo) e BYOC Multi-Tenant.

​
Produtos que suportam multi-tenancy

O mesmo modelo de tenant baseado em JWT se aplica em toda a plataforma. Suportados atualmente:
ProdutoSuporte multi-tenantNotas
Midaz (Ledger + CRM)✅ SimOrganizações, ledgers, contas, transações e saldos são escopados ao tenant.
Tracer✅ SimRegras, limites, validações e eventos de auditoria são escopados ao tenant. Cada tenant tem seu próprio catálogo de regras e limites.
Reporter✅ SimRelatórios rodam apenas sobre os dados do tenant chamador.
A integração com qualquer um desses produtos é idêntica do ponto de vista da API — o JWT carrega a claim tenantId e o serviço resolve o tenant automaticamente.

​
Como funciona

O isolamento de tenant é garantido na camada de aplicação por meio do seu token de autenticação.
  1. Você se autentica via Access Manager e recebe um JWT.
  2. Esse token inclui um claim tenantId que identifica o seu tenant.
  3. Em cada requisição à API, a plataforma resolve o seu tenant a partir do token automaticamente.
  4. Todas as operações — criar organizações, consultar ledgers, registrar transações — são escopadas ao seu tenant.
Você nunca precisa passar um identificador de tenant em headers ou no corpo das requisições. O token cuida disso.
O multi-tenancy é transparente no nível da API. Seu código de integração é o mesmo seja em single-tenant ou multi-tenant — a única diferença é que deployments multi-tenant exigem autenticação em toda requisição.

​
Como o escopo de tenant aparece em cada produto

O tenantId do JWT escopa todo recurso que o usuário chamador pode ver ou criar. O modelo de recursos varia por produto:

​
Midaz

Um tenant não é a mesma coisa que uma organização. Um único tenant pode criar e gerenciar múltiplas organizações — por exemplo, para representar subsidiárias, filiais regionais ou diferentes unidades de negócio. 
Tenant (resolvido a partir do JWT)
├── Organização A
│   ├── Ledger 1
│   └── Ledger 2
├── Organização B
│   └── Ledger 3
Quando você lista organizações, só enxerga as que pertencem ao seu tenant. O mesmo se aplica a todos os recursos do Midaz — ledgers, contas, transações e saldos são todos escopados ao seu tenant automaticamente.

​
Tracer

O Tracer escopa seu catálogo diretamente sob o tenant — não há camada de organização. 
Tenant (resolvido a partir do JWT)
├── Regras
├── Limites
├── Validações
└── Eventos de auditoria
Quando você lista regras ou limites, só enxerga entradas criadas pelo seu tenant. Validações são executadas contra as regras e limites do próprio tenant, nunca contra os de outro tenant. Eventos de auditoria também são escopados ao tenant — até a verificação da cadeia de hash roda apenas sobre a cadeia do tenant chamador.

​
Outros produtos

Reporter e o resto da plataforma seguem o mesmo padrão: o tenant é o escopo mais externo, e o JWT é a única fonte de verdade para identificar a qual tenant o chamador pertence.

​
Isolamento de dados

Os dados de cada tenant são isolados no nível de banco de dados. Cada tenant opera em um banco de dados separado, o que significa:
  • Dados de diferentes tenants nunca são armazenados juntos.
  • Consultas de um tenant não conseguem alcançar os dados de outro tenant.
  • Mesmo que dois tenants criem estruturas organizacionais idênticas, seus dados permanecem completamente separados.
Esse isolamento é garantido por um middleware que roteia cada requisição para o banco de dados correto com base no claim tenantId do seu JWT. Não existe caminho na API para contornar isso.
Operadores BYOC podem escolher entre isolamento por banco de dados ou por schema, dependendo dos requisitos de infraestrutura. Veja Modos de isolamento abaixo.

​
Modos de isolamento

Operadores BYOC escolhem o quão fortemente os tenants são isolados na camada de armazenamento. A escolha é feita por serviço, então diferentes produtos — ou até diferentes tenants no mesmo produto — podem usar modos diferentes.
  • DATABASE — cada tenant recebe um banco de dados dedicado. Isolamento máximo, custo mais alto.
  • SCHEMA — cada tenant recebe um schema dedicado dentro de um banco de dados compartilhado. Densidade eficiente, custo mais baixo.

​
DATABASE vs. SCHEMA

DimensãoDATABASESCHEMA
Isolamento físicoCompleto — banco de dados separado por tenant.Lógico — schema separado dentro de um banco de dados compartilhado.
Blast radiusConfinado ao banco de dados de um único tenant.Mais amplo — um incidente no nível do banco de dados pode afetar todos os tenants daquela instância.
Restore seletivoRestaure um tenant de forma independente, incluindo point-in-time recovery.Mais difícil — restores operam sobre o banco de dados compartilhado; o restore por tenant exige extrair um único schema.
CustoMais alto — a infraestrutura escala por tenant.Mais baixo — os tenants compartilham uma instância de banco de dados.
Isolamento de performanceForte — os tenants não competem dentro do mesmo banco de dados.Mais fraco — os tenants compartilham os recursos da instância e podem competir entre si.
Melhor paraTenants grandes, regulados, de alto volume ou sensíveis a noisy neighbor.Muitos tenants menores, onde densidade e eficiência de custo importam.

​
Blast radius

O blast radius é o escopo de tenants afetados quando algo dá errado — uma migration que falha, um índice corrompido, uma query descontrolada ou um restore. No modo DATABASE, o blast radius é um único tenant, porque cada tenant é fisicamente separado. No modo SCHEMA, o blast radius é mais amplo, porque os tenants compartilham uma instância de banco de dados e, portanto, compartilham sua superfície de falha e manutenção. Minimizar o blast radius é a principal razão para colocar tenants regulados ou de alto valor no modo DATABASE.

​
Outros datastores

A distinção entre DATABASE e SCHEMA acima se aplica ao PostgreSQL. Outros datastores aplicam o isolamento de tenants de forma diferente:
  • MongoDB usa um banco de dados separado por tenant (um banco de dados por tenantId). Isso se aplica tanto no modo DATABASE quanto no modo SCHEMA — o MongoDB não usa schemas, então a unidade de isolamento é sempre um banco de dados dedicado nomeado a partir do tenantId.
  • RabbitMQ usa um virtual host (vhost) separado por tenant. O vhost é provisionado automaticamente durante o fluxo de onboarding do tenant e é nomeado a partir do tenantId. As credenciais têm escopo no vhost, então um consumidor mal configurado não consegue acessar as filas de outro tenant.
Restore seletivo: o restore por tenant é suportado para PostgreSQL e MongoDB — ambos têm escopo por tenant. O estado do RabbitMQ é efêmero por natureza, então “restaurar” significa reprovisionar o vhost e reentregar quaisquer mensagens não confirmadas (unacked) a partir do armazenamento persistente quando aplicável.

​
Migrando de SCHEMA para DATABASE

Um tenant pode ser promovido do modo SCHEMA para o DATABASE à medida que cresce, sem reemitir tokens nem alterar a identidade do tenant — o isolamento é uma propriedade do serviço, não do tenant.
1

Provisione um banco de dados dedicado

A plataforma provisiona um novo banco de dados isolado para o tenant e executa as migrations, conforme descrito em provisionamento automático.
2

Migre os dados do tenant

Os dados do tenant são movidos do schema no banco de dados compartilhado para o novo banco de dados dedicado.
3

Reaponte o serviço

O registro de serviço do tenant é atualizado para a configuração do modo DATABASE. A claim tenantId permanece inalterada, então as integrações continuam funcionando sem modificação.
Começar no modo SCHEMA e promover tenants individuais para o modo DATABASE mantém os custos iniciais baixos enquanto reserva bancos de dados dedicados para os tenants que precisam deles. Veja Casos de uso para exemplos práticos.

​
O que isso significa para você

​
Se você é um cliente SaaS

Nada muda na forma como você usa a API. Autentique, obtenha seu token e faça requisições. A plataforma cuida do isolamento de forma transparente. Você não precisa gerenciar identificadores de tenant nem se preocupar com vazamento de dados entre clientes.

​
Se você é um operador BYOC rodando multi-tenant

Você configura quais tenants existem e como seus bancos de dados são provisionados. Seus clientes se autenticam pelo Access Manager e recebem tokens escopados. A plataforma roteia cada requisição para o banco de dados do tenant correto automaticamente.

​
Se você está rodando single-tenant (BYOC ou desenvolvimento local)

O multi-tenancy é desabilitado por padrão. Sua configuração existente continua funcionando sem alterações. Nenhum claim de tenant no JWT é necessário, e a autenticação pode ser opcional dependendo da sua configuração.

​
Configuração (operadores BYOC)

O multi-tenancy é desabilitado por padrão em cada produto. Para habilitá-lo, defina MULTI_TENANT_ENABLED=true no ambiente de cada produto que você quer rodar em modo multi-tenant (Midaz, Tracer, Reporter). Uma vez habilitado, o produto requer autenticação em cada requisição e um endpoint do serviço de multi-tenancy acessível.

​
Configurações principais

Essas variáveis se aplicam a todo produto com suporte a multi-tenant (Midaz Ledger, Midaz CRM, Tracer, Reporter):
VariávelDescriçãoPadrão
MULTI_TENANT_ENABLEDHabilita o modo multi-tenant. Quando false, a plataforma roda em modo single-tenant.false
MULTI_TENANT_URLURL do endpoint do serviço de multi-tenancy. Obrigatório quando o multi-tenant está habilitado.—
MULTI_TENANT_SERVICE_API_KEYAPI key para autenticar com o serviço de multi-tenancy. Obrigatória quando o multi-tenant está habilitado.—
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SECFrequência (segundos) com que a plataforma revalida as configurações dos tenants a partir do serviço.—
MULTI_TENANT_CACHE_TTL_SECPor quanto tempo (segundos) a configuração de um tenant é cacheada localmente antes de ser buscada novamente. Use 0 para desabilitar o cache.120

​
Circuit breaker

Protege contra indisponibilidades do serviço de multi-tenancy falhando rápido quando o serviço está indisponível:
VariávelDescriçãoPadrão
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLDFalhas consecutivas antes de o circuito abrir.5
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SECPor quanto tempo (segundos) o circuito permanece aberto antes de tentar novamente.30

​
Cache no Redis

O modo multi-tenant usa o Redis para cachear as configurações dos tenants entre instâncias:
VariávelDescriçãoPadrão
MULTI_TENANT_REDIS_HOSTHostname do servidor Redis.—
MULTI_TENANT_REDIS_PORTPorta do servidor Redis.6379
MULTI_TENANT_REDIS_PASSWORDSenha de autenticação do Redis.—
MULTI_TENANT_REDIS_TLSHabilita TLS para a conexão com o Redis.false

​
Configurações específicas do CRM

Essas variáveis estão disponíveis apenas no componente CRM e controlam o comportamento do pool de conexões para conexões de banco de dados multi-tenant:
VariávelDescriçãoPadrão
MULTI_TENANT_TIMEOUTTimeout (segundos) do cliente HTTP para as requisições ao serviço de multi-tenancy.30
MULTI_TENANT_MAX_TENANT_POOLSNúmero máximo de pools de conexão de banco de dados concorrentes (um por tenant ativo).100
MULTI_TENANT_IDLE_TIMEOUT_SECPor quanto tempo (segundos) antes de um pool de conexões de tenant inativo ser removido.300
Para a maioria dos deployments, os valores padrão funcionam bem. Ajuste MULTI_TENANT_CACHE_TTL_SEC e MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC com base em quão frequentemente você adiciona ou modifica tenants — valores menores significam propagação mais rápida das mudanças de tenants, valores maiores reduzem a carga sobre o serviço de multi-tenancy.
MULTI_TENANT_ENABLED=true requer PLUGIN_AUTH_ENABLED=true. A autenticação precisa estar ativa para que o isolamento de tenants funcione — a plataforma resolve os tenants a partir do claim do JWT.

​
Páginas relacionadas

Provisionamento automático

Como os bancos de dados, o broker e as credenciais de um tenant são provisionados.

Casos de uso

Quando escolher isolamento DATABASE vs. SCHEMA, com um caminho de migração.

Modelos de deployment

Entenda as diferenças entre SaaS, BYOC Single-Tenant e BYOC Multi-Tenant.

Segurança

Saiba mais sobre as garantias de isolamento de tenant e o modelo de responsabilidade compartilhada.

Access Manager

Entenda como a autenticação e a resolução de tenant baseada em JWT funcionam.

Organizações

Saiba como as organizações são estruturadas dentro de um tenant.