Docs/ Infraestrutura/ Escalonamento

Escalonamento

Escale suas aplicações horizontalmente com contagens manuais de réplicas ou regras de escalonamento automático baseadas no uso de recursos.

Escalonamento Manual

A forma mais simples de escalar é definir um número fixo de réplicas. Cada réplica é um contêiner idêntico rodando sua aplicação. O sh0 distribui requisições de entrada entre todas as réplicas saudáveis.

Navegue até sua aplicação no painel.
Abra Configurações → Escalonamento.
Defina a Contagem de Réplicas para o número desejado.
Clique em Aplicar. O sh0 criará ou encerrará contêineres para corresponder.

Manual scaling panel with replica count slider

Note

Escalar para cima é quase instantâneo -- novos contêineres iniciam em segundos. Escalar para baixo drena graciosamente as conexões antes de parar os contêineres (período de graça de 30 segundos por padrão).

Regras de Auto-Scaling

O auto-scaling ajusta dinamicamente o número de réplicas com base no uso de recursos em tempo real. Quando o uso excede um limite, o sh0 adiciona réplicas. Quando cai, réplicas são removidas.

Auto-scaling configuration with CPU and memory thresholds

Limite de CPU

Defina um percentual alvo de utilização de CPU. Quando o uso médio de CPU entre todas as réplicas exceder esse limite por um período sustentado (padrão: 60 segundos), o sh0 adiciona uma nova réplica.

Parâmetro	Padrão	Descrição
`cpu_threshold`	70%	Percentual de uso de CPU que aciona o scale-up
`scale_up_cooldown`	60s	Tempo mínimo entre eventos de scale-up
`scale_down_cooldown`	300s	Tempo mínimo entre eventos de scale-down

Limite de Memória

Similar à CPU, você pode definir um limite de utilização de memória. Quando o uso médio de memória excede o limite, o sh0 escala para cima. Isso é especialmente útil para aplicações intensivas em memória como serviços Node.js ou Java.

Tip

Comece com escalonamento baseado em CPU para a maioria das cargas de trabalho. Adicione escalonamento baseado em memória apenas se sua aplicação for limitada por memória. Usar ambos simultaneamente funciona -- o sh0 escala para cima quando qualquer um dos limites é excedido.

Mínimo e Máximo de Réplicas

O auto-scaling opera dentro de limites que você define:

Mínimo de Réplicas: O número mínimo de contêineres sempre em execução. Defina pelo menos 1 para alta disponibilidade, ou 2 para implantações sem tempo de inatividade.
Máximo de Réplicas: O limite superior para escalonamento. Isso evita que o escalonamento descontrolado consuma todos os recursos do servidor.

Scaling Configuration

{
  "min_replicas": 2,
  "max_replicas": 10,
  "cpu_threshold": 70,
  "memory_threshold": 80,
  "scale_up_cooldown_seconds": 60,
  "scale_down_cooldown_seconds": 300
}

Min and max replica settings in the scaling panel

Warning

Definir o máximo de réplicas muito alto em um único servidor pode esgotar a memória e CPU disponíveis, causando degradação de todas as réplicas. Monitore os recursos do seu servidor e defina limites adequadamente.

Balanceamento de Carga entre Réplicas

O sh0 usa o Caddy como proxy reverso para distribuir tráfego entre réplicas. A estratégia de balanceamento de carga é round-robin por padrão, garantindo distribuição uniforme de requisições.

Comportamentos principais:

Health checks: Réplicas não saudáveis são automaticamente removidas do pool do balanceador de carga.
Drenagem graciosa: Ao escalar para baixo, conexões existentes são drenadas antes do contêiner ser parado.
Afinidade de sessão: Não habilitado por padrão. Se sua aplicação requer sticky sessions, configure nas configurações da aplicação.
Suporte a WebSocket: Conexões WebSocket são devidamente proxiadas e mantidas entre réplicas.

Load balancer dashboard showing traffic distribution across replicas

Escalonamento via API

Você pode gerenciar o escalonamento programaticamente pela API REST. Isso é útil para pipelines CI/CD ou automação personalizada.

Definir contagem de réplicas:

Terminal

curl -X PUT https://your-server:9000/api/apps/my-app/scaling \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"replicas": 4}'

Configurar auto-scaling:

Terminal

curl -X PUT https://your-server:9000/api/apps/my-app/scaling \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_scaling": true,
    "min_replicas": 2,
    "max_replicas": 8,
    "cpu_threshold": 75,
    "memory_threshold": 85
  }'

Obter status atual de escalonamento:

Terminal

curl https://your-server:9000/api/apps/my-app/scaling \
  -H "Authorization: Bearer YOUR_TOKEN"

Melhores Práticas

Torne sua aplicação stateless: Armazene sessões no Redis ou banco de dados, não em memória. Aplicações stateless escalam sem esforço.
Defina limites de recursos: Defina limites de CPU e memória por contêiner para que uma réplica não prive as outras.
Use health checks: Configure um endpoint de health check para que o sh0 possa detectar e substituir réplicas não saudáveis automaticamente.
Comece com mínimo de 2 réplicas: Isso garante zero tempo de inatividade durante implantações (padrão blue-green).
Monitore antes de escalar: Use o painel de métricas para entender seu uso base de recursos antes de definir limites de auto-scaling.
Teste o comportamento de scale-down: Garanta que sua aplicação lida corretamente com shutdown gracioso (SIGTERM) para evitar requisições descartadas.

Tip

Para configurações multi-servidor, réplicas são distribuídas entre nós automaticamente. Veja o guia Multi-Servidor para detalhes sobre escalonamento inteligente de nós.

Storage & Volumes

Multi-Server