> ## 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 em tempo de execução (Systemplane) > Leia e atualize a configuração em tempo de execução do Matcher pela API de chave-valor do Systemplane. Ajuste rate limits, intervalos de workers e o número máximo de pools de tenant sem reiniciar o serviço. O Systemplane permite ver e alterar as configurações do Matcher que têm suporte sem reiniciar o serviço. O comportamento de aplicação varia conforme a chave: configurações de tempo de requisição podem valer na próxima requisição, enquanto uma recarga de configuração para e reinicia um worker em execução quando a configuração dele muda. ## Por que usar o Systemplane *** Em um deploy tradicional, mudar um valor de configuração significa atualizar variáveis de ambiente e reiniciar o serviço. O Systemplane elimina esse tempo de indisponibilidade para muitas configurações: * **Ajuste rate limits** durante picos de tráfego sem um novo deploy * **Calibre os intervalos dos workers** conforme a carga observada. Uma recarga de configuração realinha o worker afetado e o reinicia quando a configuração em execução dele muda * **Atualize o número máximo de pools de tenant** conforme os padrões de tráfego mudam. As configurações de conexões por pool do PostgreSQL exigem mudança de ambiente e reinicialização * **Inspecione os valores atuais em tempo de execução** para diagnosticar problemas de produção sem vasculhar logs ## Como funciona *** O Systemplane oferece uma API de gerenciamento plana no formato chave-valor. Todas as chaves de configuração ficam em um único namespace sob `/system/matcher`. ### Endpoints | Endpoint | Método | O que faz | | ---------------------- | ------ | ----------------------------------------------- | | `/system/matcher` | `GET` | Lista todas as chaves e os valores atuais delas | | `/system/matcher/:key` | `GET` | Obtém o valor atual de uma chave específica | | `/system/matcher/:key` | `PUT` | Atualiza o valor de uma chave específica | A instância do Matcher em execução serve esses endpoints diretamente. Eles não ficam sob `/v1`. Use os caminhos acima exatamente como mostrado. ## Permissões *** As rotas de configuração e de catálogo do Systemplane usam a mesma autenticação das rotas da API do Matcher. Com a autenticação habilitada, essas rotas exigem a permissão RBAC `system-runtime-config:admin` (recurso `system-runtime-config`, ação `admin`). `GET /system/matcher/streaming/manifest` é uma rota separada e exige `streaming-manifest:read`. Com a autenticação desabilitada, todos os endpoints ficam acessíveis sem restrição. ## Comportamentos de aplicação *** Você pode mudar apenas alguns valores de configuração em tempo de execução. Cada chave tem um **comportamento de aplicação** que indica quando as mudanças passam a valer: | Comportamento | O que acontece | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Apenas bootstrap** | O valor é lido uma vez na inicialização. Você deve reiniciar o serviço para as mudanças passarem a valer. | | **Leitura ao vivo** | As mudanças passam a valer imediatamente na próxima requisição. | | **Reconstrução do bundle** | As mudanças disparam uma atualização do estado interno. Passa a valer em segundos. | | **Realinhamento de worker** | Uma recarga de configuração realinha os workers. Se a configuração de um worker em execução mudou, o Matcher para e reinicia o worker. | A API do systemplane NÃO registra a maioria das chaves que são apenas bootstrap. Você gerencia essas chaves exclusivamente por variáveis de ambiente. Isso evita uma armadilha em que um PUT de admin pareceria ter sucesso, mas o processo em execução continuaria usando o valor do boot em silêncio. As chaves registradas do Swagger são uma exceção: elas ficam visíveis no Systemplane, mas continuam sendo apenas bootstrap (veja a nota abaixo). ## Chaves de configuração mais comuns *** Abaixo estão as chaves que você ajusta com mais frequência, organizadas por categoria. Para a lista completa, chame `GET /system/matcher`. ### Chaves ajustáveis em tempo de execução Você pode mudar estas chaves sem reiniciar o Matcher: `swagger.enabled`, `swagger.host` e `swagger.schemes` são registradas e ficam visíveis no Systemplane, mas não são controles ao vivo. O Matcher captura os valores de montagem do Swagger e dos handlers no bootstrap, então um `PUT` em tempo de execução não muda o comportamento da UI nem da especificação em execução. Em vez disso, mude a configuração de inicialização delas e reinicie o Matcher. | Chave | Variável de ambiente | Descrição | | --------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `server.body_limit_bytes` | `HTTP_BODY_LIMIT_BYTES` | Tamanho máximo do corpo da requisição para rotas com buffer (positivo e no máximo 128 MiB). Uploads em streaming usam `ingestion.max_upload_bytes`. | | `cors.allowed_origins` | `CORS_ALLOWED_ORIGINS` | Origens CORS permitidas | | `cors.allowed_methods` | `CORS_ALLOWED_METHODS` | Métodos CORS permitidos | | `cors.allowed_headers` | `CORS_ALLOWED_HEADERS` | Headers CORS permitidos | | `rate_limit.enabled` | `RATE_LIMIT_ENABLED` | Habilita ou desabilita o rate limit global | | `rate_limit.max` | `RATE_LIMIT_MAX` | Máximo de requisições por janela de rate limit | | `rate_limit.expiry_sec` | `RATE_LIMIT_EXPIRY_SEC` | Duração da janela de rate limit (segundos) | | `rate_limit.export_max` | `EXPORT_RATE_LIMIT_MAX` | Rate limit do endpoint de exportação | | `rate_limit.dispatch_max` | `DISPATCH_RATE_LIMIT_MAX` | Rate limit do endpoint de despacho | | `rate_limit.admin_max` | `ADMIN_RATE_LIMIT_MAX` | Rate limit do plano de administração (`/system`) | | `idempotency.retry_window_sec` | `IDEMPOTENCY_RETRY_WINDOW_SEC` | Janela para repetir requisições idempotentes que falharam | | `idempotency.success_ttl_hours` | `IDEMPOTENCY_SUCCESS_TTL_HOURS` | Por quanto tempo as chaves de idempotência concluídas ficam em cache | | `fetcher.discovery_interval_sec` | `FETCHER_DISCOVERY_INTERVAL_SEC` | Base do TTL do lock distribuído que serializa as atualizações manuais do Discovery; o lease em tempo de execução é 2× esse valor | | `export_worker.enabled` | `EXPORT_WORKER_ENABLED` | Habilita ou desabilita o worker de exportação | | `export_worker.poll_interval_sec` | `EXPORT_WORKER_POLL_INTERVAL_SEC` | Com que frequência o worker de exportação procura novos jobs | | `cleanup_worker.enabled` | `CLEANUP_WORKER_ENABLED` | Habilita ou desabilita o worker de limpeza | | `cleanup_worker.interval_sec` | `CLEANUP_WORKER_INTERVAL_SEC` | Intervalo do worker de limpeza | | `scheduler.interval_sec` | `SCHEDULER_INTERVAL_SEC` | Intervalo de polling do agendador | | `archival.enabled` | `ARCHIVAL_WORKER_ENABLED` | Liga ou desliga o worker de arquivamento criado no boot. Se o arquivamento estava desabilitado no boot, o Systemplane não pode criar o worker | | `webhook.timeout_sec` | `WEBHOOK_TIMEOUT_SEC` | Timeout do despacho de webhook/callback | | `callback_rate_limit.per_minute` | `CALLBACK_RATE_LIMIT_PER_MIN` | Máximo de callbacks por sistema externo por minuto | | `deduplication.ttl_sec` | `DEDUPE_TTL_SEC` | TTL de deduplicação em segundos | ### Chaves multi-tenant (ajustáveis em tempo de execução) Estas chaves controlam o comportamento multi-tenant, e você pode ajustá-las sem reiniciar. Veja [Modo multi-tenant](/pt/products/matcher/configuration/matcher-multi-tenant) para detalhes. Habilitar o modo multi-tenant em si (`tenancy.multi_tenant_enabled` / `MULTI_TENANT_ENABLED`) é **apenas bootstrap**. O Matcher lê essa chave uma vez na inicialização. Mudar essa chave exige uma reinicialização. A API do Systemplane não registra ela, e você não pode ligar nem desligar essa chave em tempo de execução. Veja a tabela de chaves apenas bootstrap abaixo. | Chave | Variável de ambiente | Descrição | | --------------------------------------- | ------------------------------- | ---------------------------------------------------- | | `tenancy.multi_tenant_url` | `MULTI_TENANT_URL` | URL do serviço de multi-tenancy | | `tenancy.multi_tenant_max_tenant_pools` | `MULTI_TENANT_MAX_TENANT_POOLS` | Máximo de pools de tenant simultâneos | | `tenancy.multi_tenant_idle_timeout_sec` | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Timeout de ociosidade para remoção de pool de tenant | | `tenancy.multi_tenant_cache_ttl_sec` | `MULTI_TENANT_CACHE_TTL_SEC` | TTL do cache de configuração de tenant | ### Chaves apenas bootstrap (exigem reinicialização) A API do systemplane não registra estas chaves. Mude essas chaves por variáveis de ambiente e reinicie: | Chave | Variável de ambiente | Descrição | | ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------ | | `tenancy.multi_tenant_enabled` | `MULTI_TENANT_ENABLED` | Habilita a infraestrutura multi-tenant. Lida uma vez na inicialização; exige uma reinicialização para mudar. | | `app.env_name` | `ENV_NAME` | Nome do ambiente da aplicação | | `telemetry.enabled` | `ENABLE_TELEMETRY` | Habilita o OpenTelemetry | | `app.log_level` | `LOG_LEVEL` | Nível de log da aplicação (debug, info, warn, error, fatal) | | `server.address` | `SERVER_ADDRESS` | Endereço de escuta do servidor HTTP | | `postgres.primary_host` | `POSTGRES_HOST` | Host do banco de dados primário | | `postgres.primary_port` | `POSTGRES_PORT` | Porta do banco de dados primário | | `postgres.primary_db` | `POSTGRES_DB` | Nome do banco de dados primário | | `redis.host` | `REDIS_HOST` | Host do Redis | | `rabbitmq.host` | `RABBITMQ_HOST` | Host do RabbitMQ | | `auth.enabled` | `PLUGIN_AUTH_ENABLED` | Habilita o middleware de autenticação | | `auth.host` | `PLUGIN_AUTH_ADDRESS` | Endereço do serviço de Auth | ## Boas práticas *** Chame `GET /system/matcher` para ver todos os valores atuais em tempo de execução antes de fazer qualquer mudança. Isso confirma o que o processo usa de fato. Os valores podem divergir das variáveis de ambiente depois de chamadas PUT anteriores. O comportamento de aplicação em tempo de execução varia conforme a chave, e mudanças em workers podem reiniciar o worker afetado. Teste em um ambiente de staging antes de aplicar em produção. Se uma chave não aparece em `GET /system/matcher`, ela é apenas bootstrap. Atualize a variável de ambiente e reinicie o serviço. Não existe caminho em tempo de execução para esses valores. Uma chave visível ainda pode ser apenas bootstrap quando a documentação dela diz isso: as chaves registradas do Swagger aceitam um `PUT` em tempo de execução, mas passam a valer apenas depois de uma reinicialização. ## Próximos passos *** Habilite e configure o isolamento de tenants. Configure o despacho de exceções para sistemas externos. Configure as regras de correspondência de transações. Autenticação, autorização e proteção de dados.