> ## 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.
# Configuração multi-tenant
> Configure o Matcher para autenticação ciente de tenant e pools PostgreSQL específicos por tenant.
Para as requisições multi-tenant aceitas, o Matcher primeiro deriva o contexto de tenant do JWT autorizado e depois o usa para resolver a infraestrutura PostgreSQL específica do tenant pelo Tenant Manager. É um modo de deploy, não um toggle de runtime: valide-o em um ambiente fora de produção antes de habilitá-lo em uma instalação compartilhada.
## Requisitos
***
Antes de habilitar o modo multi-tenant:
* Defina `MULTI_TENANT_ENABLED=true` e `PLUGIN_AUTH_ENABLED=true`. O Matcher rejeita a inicialização multi-tenant sem a aplicação da autorização.
* Use `AUTH_PROVIDER=plugin-auth`.
* Defina `MULTI_TENANT_URL` como uma URL HTTPS apenas com a origem em staging e produção, mais uma `MULTI_TENANT_SERVICE_API_KEY` não vazia. `MULTI_TENANT_ENVIRONMENT` é opcional e recai em `ENV_NAME` quando não está definida. O `http` em texto puro é permitido no desenvolvimento local. Nos outros ambientes ele também exige um `MULTI_TENANT_ALLOW_INSECURE_HTTP=true` explícito.
* Defina `ENVIRONMENT_NAME` (ou `ENV_NAME`) como `staging` ou `production`.
* Forneça um claim `tenant_id` ou `tenantId` válido nas requisições autenticadas por `plugin-auth`.
* Mantenha o banco do tenant padrão disponível no pool raiz para as cargas do tenant padrão e as ferramentas operacionais.
O Matcher resolve pools PostgreSQL dedicados para os tenants que não são o padrão. O tenant padrão usa o pool raiz. Ele não troca de schema de tenant com o `SET search_path` do PostgreSQL. As credenciais específicas do tenant, as fronteiras de rede e a configuração do Tenant Manager continuam fazendo parte da fronteira de isolamento.
## Identidade do tenant
***
Com `AUTH_PROVIDER=plugin-auth` no modo multi-tenant, o Matcher deriva a identidade do tenant de um claim JWT `tenant_id` ou `tenantId` válido. Ele não aceita um seletor de tenant controlado pelo chamador vindo do corpo da requisição, de parâmetros de consulta ou de headers arbitrários. Os deploys single-tenant e com autenticação desabilitada usam o tenant padrão configurado.
## Controles do pool de conexões
***
| Controle | Escopo | Efeito |
| ---------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | Ambiente de bootstrap | Padrão e teto rígido de conexões abertas do PostgreSQL por tenant. O padrão é `0`; quando as duas variáveis de limite de conexão são `0`, a lib-commons usa os padrões de 25 abertas / 5 ociosas e os tetos de 200 abertas / 50 ociosas. É independente dos ajustes `POSTGRES_MAX_*` do pool raiz. Mude-o pela configuração de deploy e reinicie o Matcher. |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | Ambiente de bootstrap | Padrão e teto rígido complementares de conexões ociosas; compartilha o comportamento de fallback do `0` acima. Mude-o pela configuração de deploy e reinicie o Matcher. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Configuração de runtime do Systemplane | Número máximo de pools de tenant que o Matcher pode manter abertos; o padrão é `100` e o valor deve ser positivo. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Configuração de runtime do Systemplane | Timeout de pool ocioso usado pelo gerenciador de pools de tenant; o padrão é `300` segundos e o valor deve ser positivo. O novo valor é aplicado pelo Systemplane sem reiniciar. |
Nos limites configurados, o gerenciador de pools de tenant do Matcher remove o pool ocioso usado há mais tempo quando resolver um novo tenant passaria de `MULTI_TENANT_MAX_TENANT_POOLS`. O tenant removido é resolvido de novo sob demanda. Valide o comportamento de migração e de falha contra a integração em produção do Tenant Manager.
## Infraestrutura compartilhada
***
O Matcher delega a resolução da infraestrutura ciente de tenant ao serviço de plataforma de multi-tenancy. Não suponha um nome fixo de virtual host do RabbitMQ, uma convenção de header de mensagem, um formato de chave do Redis, um TTL de cache ou um prefixo S3 só a partir do Matcher. Essas convenções são específicas de cada componente e de cada deploy. Revise a documentação de infraestrutura e de plataforma correspondente antes de construir uma integração em torno delas.
## Como habilitar o modo
***
1. Provisione e verifique o tenant padrão e os tenants que o Matcher deve atender.
2. Configure o provedor de autenticação, o Tenant Manager, a conectividade com o PostgreSQL e as variáveis de ambiente de bootstrap.
3. Suba o Matcher e confirme os health checks e uma requisição autenticada com escopo de tenant.
4. Observe a contagem de pools de tenant e o uso de conexões de banco sob a carga esperada.
5. Faça o rollout do deploy apenas depois de exercitar o comportamento de isolamento e de falha no ambiente de destino.
Mudar a topologia de tenants, as credenciais do banco ou os limites de conexão do PostgreSQL por pool é uma mudança de infraestrutura. Aplique-a pelo processo de deploy. O Systemplane não pode mudar esses valores de bootstrap sem um restart.
## Próximos passos
***
Revise os valores que o Matcher pode mudar pelo Systemplane.
Revise a autenticação, o isolamento de tenant e os controles de TLS das dependências.