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.

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.

​
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.

​
Relação entre tenant e organização

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 da plataforma — ledgers, contas, transações e saldos são todos escopados ao seu tenant automaticamente.

​
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.

​
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. Para habilitá-lo, defina MULTI_TENANT_ENABLED=true no ambiente do ledger (e do CRM, se aplicável). Uma vez habilitado, a plataforma requer um serviço Tenant Manager em execução e autenticação em cada requisição.

​
Configurações principais

Essas variáveis se aplicam tanto ao Ledger quanto ao componente CRM:
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 serviço Tenant Manager. Obrigatório quando o multi-tenant está habilitado.—
MULTI_TENANT_SERVICE_API_KEYAPI key para autenticar com o Tenant Manager. 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 contra o Tenant Manager.—
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 do Tenant Manager

Protege contra indisponibilidades do Tenant Manager 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 Tenant Manager.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 CACHE_TTL_SEC e 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 Tenant Manager.
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

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.