Pular para o conteúdo
Documentação

Backends e servidores

Como criar backends, adicionar servidores, ajustar peso, backup, manutenção, health-check e sessão fixa no miniProxy.

R Regis Manze 20/11/2026 11 min de leitura

Um backend é um grupo de servidores que atende um ou mais domínios. O miniProxy recebe a requisição do visitante, descobre pelo domínio qual backend deve atender e distribui o tráfego entre os servidores desse backend, tirando do ar automaticamente quem parar de responder.

A lista de backends

Abra Backends no menu lateral (seção Infraestrutura). Cada linha mostra:

Coluna O que significa
Backend Nome do backend, o algoritmo de balanceamento e avisos como sessao fixa, check HTTP /caminho ou check personalizado. A etiqueta padrao marca o backend que recebe todo Host que não corresponde a nenhum domínio.
Servidores Endereço de cada servidor com uma bolinha de status (verde no ar, vermelho fora, cinza em manutenção, amarelo sem dados). A etiqueta bkp indica servidor de backup.
Dominios Os domínios que apontam para o backend (até 4, depois +N). +N path indica regras de path de outros domínios que caem aqui. sem uso avisa que nenhum domínio usa o backend.
Conn Conexões ativas agora.
Resp. Tempo médio de resposta dos servidores.
5xx Respostas de erro 5xx desde o último reload do HAProxy.

O status dos servidores atualiza sozinho a cada 5 segundos, sem recarregar a página. Use a busca no topo (backend, servidor, IP ou dominio...) para filtrar a lista.

No final da lista aparecem, em um grupo separado, os backends Internos do miniProxy (tabelas, WAF, Let's Encrypt). Eles são usados pelo próprio painel e não devem ser apagados nem editados à mão.

Criar um backend

  1. Em Backends, clique em Novo Backend.
  2. Preencha o formulário:
Campo O que informar
Nome do Backend Identificador sem espaços (letras, números, - e _), por exemplo bk_loja.
Algoritmo de balanceamento Round Robin (alterna entre os servidores), Least Connections (manda para quem tem menos conexões abertas) ou Source IP (o mesmo IP de visitante vai sempre para o mesmo servidor).
Nome do servidor Nome do primeiro servidor, por exemplo srv1.
IP / Hostname Endereço interno do servidor, por exemplo 192.0.2.50.
Porta Porta em que a aplicação responde (padrão 80).
MaxConn Máximo de conexões simultâneas para esse servidor (padrão 3000). Acima disso, as requisições esperam na fila.
Backend em HTTPS (TLS) Ligue quando o servidor só responde em HTTPS (porta 443). O miniProxy passa a falar TLS com ele.
  1. Clique em Criar Backend.

O backend nasce com um servidor e com health-check ligado. Ele ainda não recebe tráfego: é preciso apontar um domínio para ele (veja Domínios).

Dica: dá para criar o backend junto com o domínio, no assistente Adicionar Dominio, escolhendo Criar novo backend.

A tela do backend

Clique no nome de um backend para abrir a tela de detalhe. No topo aparece um resumo: quantos servidores estão no ar, fora e em manutencao, o balanceamento e quantos domínios usam o backend. As etiquetas PADRAO e INTERNO aparecem quando se aplicam.

A tela tem quatro áreas:

  • Servidores: a tabela com status ao vivo e os botões de cada servidor.
  • Configuracao do backend: nome, balanceamento, timeouts, sessão fixa, health-check e proteção passiva.
  • Dominios que usam este backend: lista dos domínios, com troca rápida de backend e criação de domínio novo.
  • Remover backend (no rodapé, em vermelho).

Tabela de servidores

Para cada servidor aparecem o status reportado pelo HAProxy (por exemplo UP, DOWN, MAINT) e o resultado do último teste, o endereço, as opções e as métricas Conn, Resp. e 5xx. Na coluna Opcoes podem aparecer as etiquetas:

Etiqueta Significado
HTTPS O miniProxy fala TLS com esse servidor.
backup Só recebe tráfego quando os servidores principais caem.
desabilitado Servidor em manutenção, sem receber tráfego.
sem check Sem health-check: o HAProxy nunca tira esse servidor do ar, mesmo que ele pare de responder.

Em seguida aparecem maxconn, peso e eventuais opções extras.

Se o backend ficar sem servidores, a tabela avisa: Nenhum servidor neste backend — o trafego dele da 503.

Adicionar ou editar um servidor

Adicionar um servidor a um backend no miniProxy

  1. Na tela do backend, clique em Adicionar servidor (abaixo da tabela) ou no lápis de um servidor existente (Editar todos os atributos).
  2. Preencha os campos:
Campo O que informar
Nome * Nome único dentro do backend.
IP / hostname * Endereço do servidor.
Porta Porta da aplicação (padrão 80).
MaxConn Limite de conexões simultâneas (padrão 3000).
Peso (0-256) Participação no balanceamento. Um servidor com peso 2 recebe o dobro de requisições de um com peso 1. Peso 0 não recebe tráfego novo. Em branco, vale o padrão do HAProxy (1).
Cookie Identificador do servidor no cookie de sessão fixa. Deixe em branco (auto) para o painel gerar a partir do nome.
Health-check Liga o teste periódico do servidor (recomendado).
Falar HTTPS com o servidor Use quando o servidor responde em HTTPS.
Backup (so recebe se os outros cairem) Transforma o servidor em reserva.
Desabilitado Coloca o servidor em manutenção.
Intervalo do check De quanto em quanto tempo o teste roda (padrão 3s).
Sobe apos (rise) Quantos testes seguidos com sucesso para o servidor voltar ao ar (padrão 2).
Cai apos (fall) Quantas falhas seguidas para o servidor sair do ar (padrão 3).
Opcoes extras (avancado) Opções da linha server do HAProxy que o painel não tem campo próprio, como send-proxy-v2. Elas são mantidas como estão.
  1. Clique em Salvar.

O rodapé do formulário lembra: a mudança afeta todos os domínios que usam aquele backend. Antes de gravar, o painel valida a configuração; se houver erro, nada é alterado.

Uma linha de servidor gerada fica, por exemplo, assim:

server srv2 192.0.2.51:80 cookie srv2 check maxconn 3000 weight 2 inter 3s rise 2 fall 3

Colocar um servidor em manutenção

Para tirar um servidor do balanceamento sem apagá-lo (por exemplo, para atualizar a aplicação):

  1. Na tabela de servidores, clique no botão de pausa (Desabilitar (manutencao)).
  2. O servidor fica cinza, com a etiqueta desabilitado, e para de receber tráfego na hora.
  3. Para voltar, clique no botão de play (Habilitar).

A mudança vale imediatamente (pelo socket de administração do HAProxy, sem reload) e também é gravada na configuração com a palavra disabled, então continua valendo depois de um reload ou reinício.

Atenção: colocar em manutenção ou remover o único servidor do backend tira do ar todos os domínios que usam esse backend.

Remover um servidor

Clique na lixeira (Remover) da linha do servidor e confirme. O servidor sai da configuração e o HAProxy é recarregado.

Configuração do backend

No card Configuracao do backend:

Campo O que faz
Nome Renomeia o backend. Os domínios que o usam são atualizados junto (renomear atualiza os dominios que o usam).
Balanceamento Algoritmo de distribuição: roundrobin (padrão), leastconn, source, first, static-rr, random ou uri.
Timeout conexao Quanto tempo esperar para abrir a conexão com o servidor (padrão 5s). Aceita 5s, 500ms, 2m.
Timeout resposta Quanto tempo esperar pela resposta da aplicação (padrão 30s). Aumente para relatórios ou exportações lentas.
Sessao fixa (cookie) O visitante fica sempre no mesmo servidor (veja abaixo).

Clique em Salvar configuracao para aplicar.

Health-check

O health-check é o teste que o HAProxy faz em cada servidor marcado com Health-check para decidir se ele está no ar.

Opção Como funciona
TCP (so testa a porta) Considera o servidor no ar se a porta aceitar conexão. Simples, mas não percebe uma aplicação travada que ainda aceita conexões.
HTTP (testa uma URL) Faz uma requisição HTTP e confere a resposta. Mostra os campos Metodo (GET, HEAD ou OPTIONS), Path (por exemplo /health), Host (opcional) (para aplicações que respondem por nome, como loja.exemplo.com.br) e Resposta esperada (por exemplo status 200-399).
personalizado (manter) Aparece quando a checagem foi escrita de uma forma que o painel não edita. Ela é preservada; ajuste pelo editor avançado.

O teste roda a cada Intervalo do check configurado em cada servidor.

Dica: prefira uma URL leve de verificação, que responda rápido e não dependa de login. Uma página pesada como health-check gera carga desnecessária na aplicação.

Proteção passiva

A opção Protecao passiva tira do ar o servidor que começar a devolver erros 5xx no tráfego real e o traz de volta aos poucos.

Campo O que informar
Erros seguidos Quantos erros seguidos tiram o servidor do ar (padrão 10, de 1 a 1000).
Subida gradual Tempo para o servidor voltar a receber a carga cheia depois de recuperado (padrão 30s).

Ela vale para os servidores com health-check que não são backup; quem devolve o servidor ao ar é o health-check ativo. Só fica disponível com 2 ou mais servidores ativos: com um só, tirá-lo do ar derrubaria o site inteiro.

Com Sessao fixa (cookie) ligada, o HAProxy grava no navegador do visitante o cookie SERVERID indicando qual servidor o atendeu, e as próximas requisições vão para o mesmo servidor. Isso é útil para aplicações que guardam a sessão (carrinho, login) na memória do servidor.

O miniProxy só mantém esse cookie em backends com 2 ou mais servidores:

  • Em um backend com um servidor só, a linha padrão do cookie é removida automaticamente ao gravar a configuração. Com um servidor não há o que fixar, e o cookie atrapalhava: a primeira resposta de cada visitante (inclusive CSS, JS e imagens) saía com Set-Cookie e Cache-Control: private, e a Cloudflare e o cache do HAProxy deixavam de guardar esses arquivos.
  • Quando o backend volta a ter 2 ou mais servidores e todos têm identificador de cookie, a linha é recolocada sozinha.

Dica: se você adicionou o segundo servidor e o backend não mostra sessao fixa, ligue Sessao fixa (cookie) e clique em Salvar configuracao. O painel gera o identificador de cada servidor.

Editor avançado

Em Editor avancado (texto do bloco no haproxy.cfg) você edita o bloco do backend como texto, para diretivas que o painel não tem campo. A primeira linha precisa continuar sendo backend <nome> (para renomear use o campo Nome) e não é permitido abrir outra seção dentro dele. Ao clicar em Validar e salvar, a configuração é testada com haproxy -c antes de gravar; se der erro, nada muda.

Diretivas que o painel não reconhece aparecem listadas em Outras diretivas (edite no avancado).

Domínios que usam o backend

No card Dominios que usam este backend você vê cada domínio com as etiquetas CF (atrás da Cloudflare), WAF bloq/det, restrito e regra(s) de path. Ali também é possível:

  • Mover um domínio para outro backend: escolha o destino no seletor da linha (ou 404 limpo) e clique no botão de troca (Mover).
  • Vincular: digite em trazer outro dominio para ca... um domínio que hoje usa outro backend e clique em Vincular.
  • Criar aqui: digite um domínio novo (por exemplo loja.exemplo.com.br) e clique em Criar aqui. O domínio e o www são criados apontando para este backend, sem certificado; emita o certificado depois na tela do domínio.

Remover um backend

No rodapé da tela do backend, clique em Remover backend e confirme. Os servidores são apagados e os domínios que usavam o backend passam a cair no backend padrão. O backend padrão e os backends internos não podem ser removidos.

Atenção: antes de remover, mova os domínios para outro backend. Caso contrário, os visitantes desses domínios passam a ver o site do backend padrão.

Veja também

Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!