Limites e timeouts no Nginx: protegendo o servidor e evitando travamentos

Por que limites e timeouts importam

Limites e timeouts no Nginx são mecanismos de proteção e previsibilidade. Eles evitam que um cliente (intencionalmente ou não) mantenha conexões abertas por tempo demais, envie dados muito lentamente, faça uploads gigantes sem controle ou prenda o servidor aguardando respostas de um upstream (sua aplicação) que está lenta ou travada.

Na prática, você usa:

• Limites (ex.: client_max_body_size) para controlar tamanho e consumo de recursos.
• Timeouts de cliente (ex.: client_body_timeout, client_header_timeout, keepalive_timeout, send_timeout) para lidar com conexões lentas/instáveis e evitar “pendurar” workers.
• Timeouts de proxy (ex.: proxy_connect_timeout, proxy_read_timeout, proxy_send_timeout) para controlar quanto o Nginx espera ao falar com a aplicação.

Diretivas comuns e o que elas afetam

client_max_body_size (limite de upload)

Define o tamanho máximo do corpo da requisição (por exemplo, uploads via POST/PUT). Se o cliente enviar mais do que o permitido, o Nginx retorna 413 Request Entity Too Large sem repassar para a aplicação.

• Impacto: protege disco/memória e evita que a aplicação receba uploads gigantes.
• Onde usar: no http (global), no server (por site) ou no location (por endpoint de upload).

client_header_timeout (tempo para receber headers)

Tempo máximo que o Nginx espera para receber os headers completos do cliente. Ajuda a mitigar clientes lentos e alguns padrões de ataque que enviam headers “a conta-gotas”.

• Impacto: conexões muito lentas podem ser encerradas antes de completar a requisição.

client_body_timeout (tempo para receber o body)

Tempo máximo entre leituras do corpo da requisição. Em uploads lentos/instáveis, se o cliente parar de enviar dados por mais tempo que esse valor, o Nginx encerra a conexão.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

• Impacto: uploads em redes ruins podem falhar se o timeout for agressivo; por outro lado, evita conexões presas consumindo recursos.

keepalive_timeout (tempo de conexão ociosa em keep-alive)

Define por quanto tempo uma conexão HTTP persistente pode ficar ociosa aguardando a próxima requisição. Valores altos aumentam reutilização de conexão, mas podem manter muitas conexões abertas e consumir recursos.

• Impacto: em tráfego alto, keep-alive longo pode aumentar uso de memória/FDs; em tráfego moderado, melhora latência.

send_timeout (tempo para enviar resposta ao cliente)

Tempo máximo entre operações de envio para o cliente. Se o cliente estiver recebendo muito lentamente (download lento), e o Nginx não conseguir enviar dados por tempo maior que esse valor, a conexão é encerrada.

• Impacto: protege contra clientes que “seguram” o download e prendem recursos.

proxy_connect_timeout (tempo para conectar no upstream)

Tempo máximo para estabelecer conexão TCP (e, se aplicável, handshake) com o upstream (sua aplicação). Não é o tempo total de resposta; é só para conectar.

• Impacto: se o upstream estiver indisponível/lento para aceitar conexões, o Nginx falha mais rápido.

proxy_send_timeout (tempo para enviar requisição ao upstream)

Tempo máximo entre operações de envio do request do Nginx para o upstream. Se o upstream estiver lento para receber (backpressure), pode estourar.

• Impacto: protege o Nginx de ficar preso tentando empurrar dados para uma aplicação saturada.

proxy_read_timeout (tempo para ler resposta do upstream)

Tempo máximo entre leituras da resposta do upstream. É o timeout mais associado a endpoints demorados: se a aplicação ficar muito tempo sem enviar nenhum byte de resposta, o Nginx encerra e retorna erro (geralmente 504 Gateway Timeout).

• Impacto: endpoints longos (relatórios, exportações, chamadas externas) podem falhar se esse valor for baixo.

Valores iniciais recomendados (ponto de partida)

Os valores abaixo são um ponto de partida seguro para ambientes pequenos (uma ou poucas instâncias), equilibrando proteção e compatibilidade. Ajuste conforme seu tráfego e comportamento real.

Observação prática: se você tem endpoints realmente longos (2–10 minutos), prefira repensar o desenho (processamento assíncrono, filas, polling) em vez de apenas aumentar proxy_read_timeout globalmente. Quando não for possível, aumente apenas no location específico.

Configuração prática (exemplos)

1) Base segura no nível http (global)

Use como padrão para o servidor inteiro e refine por server/location quando necessário.

http {    client_max_body_size 10m;    client_header_timeout 10s;    client_body_timeout 30s;    keepalive_timeout 15s;    send_timeout 30s;    proxy_connect_timeout 5s;    proxy_send_timeout 30s;    proxy_read_timeout 60s;}

2) Ajuste por endpoint de upload (aumentar limite e tolerância)

Para um endpoint como /upload, você normalmente aumenta client_max_body_size e pode aumentar client_body_timeout (clientes em redes ruins podem pausar).

server {    # ...    location /upload {        client_max_body_size 200m;        client_body_timeout 120s;        proxy_read_timeout 120s;        proxy_send_timeout 120s;        proxy_pass http://app_upstream;    }}

Dica: mantenha o limite grande apenas onde precisa. Isso reduz risco de abuso em outras rotas.

3) Ajuste por endpoint lento (aumentar apenas proxy_read_timeout)

Para um endpoint que demora para responder (ex.: /reports/export), aumente o tempo de leitura do upstream somente ali.

location /reports/export {    proxy_read_timeout 300s;    proxy_connect_timeout 5s;    proxy_send_timeout 30s;    proxy_pass http://app_upstream;}

Se a aplicação passa longos períodos sem enviar nenhum byte, o Nginx considera “silêncio” e o timeout conta. Se a aplicação puder enviar progresso (mesmo pequenos chunks), isso ajuda a manter a conexão viva sem aumentar tanto o timeout.

4) Conexões instáveis (equilíbrio entre tolerância e proteção)

Em cenários com muitos clientes mobile/instáveis, é comum:

• aumentar um pouco client_body_timeout para uploads;
• manter client_header_timeout relativamente baixo (headers deveriam chegar rápido);
• não exagerar em keepalive_timeout para não acumular conexões ociosas.

http {    client_header_timeout 10s;    client_body_timeout 60s;    keepalive_timeout 10s;    send_timeout 30s;}

Método seguro de ajuste incremental com testes

Passo a passo

1. Defina metas por cenário: qual o maior upload esperado? qual o tempo máximo aceitável para um endpoint? qual o perfil de rede dos clientes?

2. Comece com valores moderados e específicos: aplique aumentos apenas em location que precisa (upload e endpoint lento), mantendo defaults mais restritivos no restante.

3. Recarregue e valide sintaxe: após alterar, valide e recarregue o Nginx (sem reiniciar processos à força).

4. Teste com casos controlados (abaixo) e observe os códigos de resposta: 413 (limite de body), 408 (timeout de cliente), 504 (timeout de upstream), além de mensagens no error_log.

5. Ajuste em incrementos pequenos: aumente 25–50% por vez (ou em degraus como 60s → 90s → 120s), sempre com teste e observação de impacto.

6. Evite aumentar globalmente por “um caso”: se só um endpoint é lento, ajuste só nele.

Testes práticos por cenário

Cenário A: upload grande (validar client_max_body_size e client_body_timeout)

Objetivo: garantir que uploads legítimos passam e uploads excessivos falham com 413.

• Teste de limite: tente enviar um arquivo um pouco maior que o permitido e confirme 413.
• Teste de rede lenta: simule upload lento (por exemplo, limitando taxa no cliente) e verifique se não estoura client_body_timeout. Se estourar, aumente client_body_timeout apenas no endpoint de upload.

Cenário B: endpoint lento (validar proxy_read_timeout)

Objetivo: evitar 504 em rotas demoradas, sem abrir demais o restante do site.

• Chame o endpoint que demora e meça o tempo real de resposta.
• Se ocorrer 504, aumente proxy_read_timeout no location específico até cobrir o pior caso + margem (ex.: pior caso 120s → configure 180s).
• Se o endpoint às vezes “trava” sem responder, aumentar timeout só mascara o problema; use logs da aplicação para identificar gargalos.

Cenário C: conexões instáveis (validar keepalive_timeout, send_timeout e timeouts de cliente)

Objetivo: reduzir travamentos por conexões presas e melhorar resiliência sem manter recursos ocupados indefinidamente.

• Downloads lentos: se clientes reclamam de download interrompido, verifique se send_timeout está baixo demais. Aumente com cautela.
• Muitas conexões ociosas: se há muitos sockets abertos sem tráfego, reduza keepalive_timeout.
• Headers lentos: se há erros de timeout antes de chegar na aplicação, avalie client_header_timeout (geralmente não precisa ser alto).

Erros comuns e como evitar

• Aumentar tudo globalmente: isso amplia a janela para conexões presas e pode piorar consumo de recursos. Prefira ajustes por rota.
• Confundir proxy_read_timeout com “tempo total da requisição”: ele mede o tempo entre leituras da resposta do upstream; se a aplicação não envia nada por muito tempo, estoura mesmo que o processamento continue.
• Ignorar o código de erro: 413 aponta limite de body; 504 aponta upstream sem resposta a tempo; 408 aponta cliente lento/incompleto.
• Não testar com rede lenta: timeouts de body e send aparecem mais em condições reais (Wi‑Fi ruim, 4G oscilando) do que em rede local.