Skip to content

Nginx Folha de referência

Servidor HTTP de alto desempenho e proxy reverso.

01

Primeiros Passos

Configuração Básica

A configuração do Nginx usa uma estrutura hierárquica de blocos. worker_processes define a quantidade de processos. O bloco http contém blocos server, que contêm blocos location. Sempre teste com nginx -t antes de recarregar.

nginx
# /etc/nginx/nginx.conf
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

# Test config: nginx -t
# Reload: nginx -s reload
# Start: systemctl start nginx

Diretivas e Contextos

Os contextos se aninham: main > events/http/mail > server > location. Diretivas simples terminam com ponto e vírgula; diretivas de bloco usam chaves. Algumas diretivas só são válidas em contextos específicos.

nginx
# Contexts are hierarchical blocks
# Global context (main) - outside any block
user nginx;
worker_processes auto;

# events context
events {
    worker_connections 1024;
}

# http context
http {
    # server context
    server {
        listen 80;
        # location context
        location / {
            root /var/www/html;
        }
    }
}

# Directives: simple (name value;) or block (name { ... })

Testar e Recarregar

nginx -t verifica a sintaxe E tenta abrir os arquivos referenciados (certificados, logs). Sempre execute antes do reload. O reload envia SIGHUP — os workers terminam as requisições atuais e então recarregam. restart causa breve indisponibilidade.

nginx
# test configuration for syntax errors
nginx -t

# test and print full config
nginx -T

# reload config without dropping connections
nginx -s reload

# stop gracefully (finishes current requests)
nginx -s quit

# stop immediately
nginx -s stop

# reopen log files (after log rotation)
nginx -s reopen

# systemd alternative
systemctl reload nginx
systemctl restart nginx

Contexto Main vs HTTP

worker_processes e events vivem no contexto main. Roteamento, proxy, cache e blocos server vivem no http. SSL, logging e gzip podem ser definidos no http e herdados por server/location.

nginx
# main context - global settings
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;

events {
    worker_connections 4096;
}

http {
    # all HTTP-related config lives here
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

Arquivos Include

Includes mantêm a configuração modular. O glob conf.d (*.conf) é a convenção moderna. sites-enabled com symlinks é o padrão Debian/Ubuntu. mime.types mapeia extensões de arquivo para Content-Type.

nginx
# main config: /etc/nginx/nginx.conf
http {
    include /etc/nginx/mime.types;
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

# /etc/nginx/conf.d/default.conf
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

# Disable a site: remove the file from sites-enabled/
# Available sites kept in sites-available/, symlinked into enabled/

Operações de Linha de Comando

nginx -V mostra as opções de compilação, incluindo quais módulos estão embutidos. -g define diretivas que sobrescrevem a configuração. -c é útil para testar configurações alternativas sem mexer na padrão.

nginx
# start nginx (if not managed by systemd)
nginx

# specify a custom config file
nginx -c /path/to/nginx.conf

# set a global directive from command line
nginx -g "worker_processes 4;"

# test config
nginx -t

# print version and build configuration
nginx -V

# send signal to master process
nginx -s reload
nginx -s stop
02

Blocos Server

Bloco Server Básico

Um bloco server define um host virtual. listen define a porta. server_name casa com o header Host. root define a raiz dos documentos. index especifica quais arquivos servir para requisições de diretório.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

Múltiplos Nomes de Servidor

O Nginx casa server_name por exatidão, depois curinga (*.foo.com), depois regex. O primeiro bloco server que casar atende a requisição. Use blocos separados para apps diferentes na mesma porta.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    # ...
}

server {
    listen 80;
    server_name api.example.com;
    # ...
}

# Wildcard: matches any single-level subdomain
server_name *.example.com;

# Regex (starts with ~)
server_name ~^www\d+\.example\.com$;

Servidor Padrão

default_server atende requisições cujo header Host não corresponde a nenhum server_name. O underscore é uma convenção (nome de host inválido, nunca casa com tráfego real). return 444 fecha a conexão sem resposta.

nginx
# mark a server block as default for the port
server {
    listen 80 default_server;
    server_name _;
    return 444;  # drop connection (no response)
}

# handles all requests that don't match another server_name
# _ is an invalid hostname, used as catch-all convention
# useful to block requests with no matching Host header

Diretiva Listen

listen pode vincular a um endereço específico, IPv6, socket UNIX ou definir o default_server. O parâmetro ssl habilita TLS para aquele listener. Múltiplas diretivas listen são permitidas num mesmo bloco server.

nginx
# listen on port 80
listen 80;

# IPv6
listen [::]:80;

# HTTPS (ssl flag)
listen 443 ssl;
listen [::]:443 ssl;

# specific address
listen 127.0.0.1:8080;

# default server for this port
listen 80 default_server;

# listen on UNIX socket
listen unix:/var/run/nginx.sock;

Casamento de Nomes de Servidor

A prioridade de casamento é exato > curinga inicial > curinga final > regex. As regexes são verificadas na ordem da configuração, então a primeira que casar vence. Aumente o hash bucket size se os nomes de servidor forem longos ou numerosos.

nginx
# Order of precedence (highest to lowest):
# 1. Exact name: example.com
# 2. Longest wildcard starting with *: *.example.com
# 3. Longest wildcard ending with *: www.*
# 4. First matching regex (in config order): ~^www\d+\.

# If nothing matches, the default_server handles it

# Tune hash sizes for many server names
http {
    server_names_hash_bucket_size 64;
    server_names_hash_max_size 512;
}

Servidor Catch-all

Um catch-all impede que requisições com headers Host arbitrários cheguem aos seus apps. return 301 redireciona para um host conhecido. return 444 derruba a conexão, útil contra scanners que batem direto no seu IP.

nginx
# catch all requests regardless of host header
server {
    listen 80 default_server;
    server_name _;  # invalid name, never matches real host

    return 301 https://$host$request_uri;
}

# or drop the connection silently
server {
    listen 80 default_server;
    server_name _;
    return 444;
}

# redirect unknown subdomains to main site
server {
    listen 80 default_server;
    return 301 https://example.com;
}
03

Blocos Location

Modificadores de Location

Modificadores mudam o comportamento de casamento: = (exato), ^~ (prefixo, pula regex), ~ (regex sensível a caixa), ~* (regex insensível a caixa), nenhum (prefixo). Regex é melhor para extensões de arquivo; prefixo para árvores de caminhos.

nginx
# exact match - fastest, stops search if matched
location = /favicon.ico {
    log_not_found off;
}

# prefix match with ^~ - skips regex if longest prefix matches
location ^~ /static/ {
    root /var/www;
}

# case-sensitive regex
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

# case-insensitive regex
location ~* \.(jpg|jpeg|png|gif|ico)$ {
    expires 30d;
}

# prefix match (no modifier)
location / {
    try_files $uri $uri/ /index.php;
}

Prioridade de Location

O Nginx avalia exato (=) primeiro, depois casamentos de prefixo (o mais longo vence), depois regex na ordem da configuração. ^~ faz um casamento de prefixo pular a avaliação de regex. Entender essa ordem evita surpresas com locations sobrepostos.

nginx
# Priority order (highest to lowest):
# 1. =     exact match
# 2. ^~    prefix match (skips regex if matched)
# 3. ~ ~*  regex (first match in config order)
# 4. (none) prefix match (longest wins)

location = /api {
    # exact, highest priority
}

location ^~ /assets/ {
    # prefix, beats regex
}

location ~ \.php$ {
    # regex
}

location /api/ {
    # prefix, lowest of these
}

Root vs Alias

root acrescenta a URI ao seu valor; alias substitui o prefixo casado. Use root quando a location mapeia para um subdiretório de uma árvore. Use alias quando o caminho da URI difere do caminho no sistema de arquivos. alias com regex precisa da captura $1.

nginx
# root: appends the full URI to the path
# request /img/cat.png -> /var/www/img/cat.png
location /img/ {
    root /var/www;
}

# alias: replaces the matched location part
# request /img/cat.png -> /data/images/cat.png
location /img/ {
    alias /data/images/;
}

# alias with regex requires capturing the path
location ~ ^/img/(.*)$ {
    alias /data/images/$1;
}

try_files

try_files verifica cada argumento em ordem; o último é o fallback (sem checagem de arquivo). $uri verifica o arquivo, $uri/ verifica o diretório. O fallback pode ser uma URI, =código ou @nomeado. Essencial para roteamento de SPAs e CMS.

nginx
# try files in order, fall back to last option
location / {
    try_files $uri $uri/ /index.html;
}

# serve index.php if file/dir not found (pretty URLs)
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# return 404 if nothing matches
location / {
    try_files $uri =404;
}

# named location as fallback
location / {
    try_files $uri $uri/ @drupal;
}

Locations Nomeados

Locations nomeados (@nome) são só internos — nunca casados diretamente por uma URI de requisição. São alvos de try_files, error_page e rewrite. Ótimos para compartilhar um bloco de configuração (como um handler de fallback) entre várias locations.

nginx
# named locations start with @, can't be reached externally
# used as try_files fallback or rewrite target

location / {
    try_files $uri $uri/ @app;
}

location @app {
    fastcgi_pass unix:/run/php.sock;
    # ... fastcgi config
}

# useful for organizing common error logic
location @error_page {
    return 500 "Internal Server Error";
}

# can also be used with error_page
error_page 404 @fallback;
location @fallback {
    proxy_pass http://backend;
}

Locations Aninhados

Locations podem se aninhar. Locations internos herdam e podem sobrescrever diretivas dos externos. Útil para tratar um caminho de forma especial dentro de um prefixo mais amplo (ex.: tamanho de corpo maior para uploads, ou servir arquivos estáticos de um sub-caminho).

nginx
location /api {
    # /api/users, /api/posts handled here
    proxy_pass http://backend;

    location /api/upload {
        # override for upload endpoint
        client_max_body_size 50M;
        proxy_pass http://upload_backend;
    }

    location ~ ^/api/static/(.*)$ {
        # regex inside prefix location
        root /var/www;
    }
}
04

Proxy Reverso

Proxy Pass Básico

proxy_pass encaminha requisições a um servidor upstream. Uma barra final no proxy_pass faz o prefixo da location casada ser substituído. Sem barra final, a URI original é passada adiante inalterada.

nginx
server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://localhost:3000;
    }
}

# proxy_pass with URI replacement (trailing slash matters)
location /api/ {
    proxy_pass http://backend/;  # /api/foo -> /foo
}

# without trailing slash, URI is preserved
location /api/ {
    proxy_pass http://backend;   # /api/foo -> /api/foo
}

Headers de Proxy

Por padrão, o nginx não passa o IP do cliente nem o host original. Definir X-Real-IP e X-Forwarded-For permite que o backend identifique o cliente real. X-Forwarded-Proto informa o scheme original, crítico para lógica de redirecionamento HTTPS.

nginx
location / {
    proxy_pass http://backend;

    # preserve original host
    proxy_set_header Host $host;

    # real client IP (not nginx's)
    proxy_set_header X-Real-IP $remote_addr;

    # forwarded-for chain
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # scheme (http or https)
    proxy_set_header X-Forwarded-Proto $scheme;

    # original host
    proxy_set_header X-Forwarded-Host $host;
}

Proxy com Upstream

Um bloco upstream define um pool nomeado de servidores que o proxy_pass pode referenciar. Isso habilita balanceamento de carga, health checks e conexões keepalive. Variáveis de upstream são úteis para registrar qual backend atendeu cada requisição.

nginx
# define a named pool of backend servers
upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080;
}

server {
    listen 80;

    location / {
        proxy_pass http://backend;
    }
}

# useful upstream variables:
# $upstream_addr, $upstream_status,
# $upstream_response_time, $upstream_cache_status

Timeouts de Proxy

proxy_connect_timeout é o limite do handshake TCP; os timeouts de leitura/envio valem para períodos ociosos durante a transferência de dados. Aumente read_timeout para endpoints lentos (exportações, inferência de IA). O keepalive do upstream reutiliza conexões para reduzir latência.

nginx
location / {
    proxy_pass http://backend;

    # connect timeout (TCP handshake to upstream)
    proxy_connect_timeout 5s;

    # time between reads from upstream (response)
    proxy_read_timeout 60s;

    # time between writes to upstream (request body)
    proxy_send_timeout 60s;

    # for slow backends (large uploads/downloads)
    proxy_read_timeout 300s;
}

# keepalive connections to upstream
upstream backend {
    server 10.0.0.1:8080;
    keepalive 32;
}

Buffering de Proxy

O buffering guarda a resposta do upstream em memória/disco antes de enviar ao cliente — eficiente para clientes lentos, mas quebra streaming. Desligue para SSE, WebSocket ou streaming em chunks. buffer_size é a primeira parte (headers); buffers guardam o resto.

nginx
location / {
    proxy_pass http://backend;

    # enable buffering (default on)
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;

    # busy buffers during streaming
    proxy_busy_buffers_size 16k;

    # disable for streaming/SSE
    proxy_buffering off;
    proxy_cache off;
}

# Server-Sent Events or streaming responses
location /events {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

Upgrade de WebSocket

WebSocket precisa de HTTP/1.1 mais os headers Upgrade e Connection. O bloco map converte o header Upgrade no valor correto de Connection (upgrade vs close). Um proxy_read_timeout longo evita que WebSockets ociosos sejam fechados.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    location /ws {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # keepalive for long-lived connections
        proxy_read_timeout 3600s;
    }
}
05

Balanceamento de Carga

Bloco Upstream

Um bloco upstream define servidores de backend. O balanceamento padrão é round-robin. max_fails e fail_timeout configuram health checks passivos: após max_fails falhas dentro de fail_timeout, o servidor é marcado fora por fail_timeout segundos.

nginx
upstream backend {
    server backend1.example.com weight=5;
    server backend2.example.com;
    server backend3.example.com max_fails=3 fail_timeout=30s;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

# default algorithm: round-robin
# max_fails: failed attempts before marking server down
# fail_timeout: window for counting fails AND downtime duration

Algoritmos de Balanceamento

round-robin distribui de forma uniforme; least_conn envia ao servidor menos carregado; ip_hash mantém um cliente no mesmo servidor (sessões fixas por IP); hash distribui por uma chave personalizada. O parâmetro consistent minimiza a redistribuição quando servidores são adicionados/removidos.

nginx
# round-robin (default) - even distribution
upstream backend {
    server s1.example.com;
    server s2.example.com;
}

# least connections - fewest active connections
upstream backend {
    least_conn;
    server s1.example.com;
    server s2.example.com;
}

# ip_hash - sticky by client IP (session persistence)
upstream backend {
    ip_hash;
    server s1.example.com;
    server s2.example.com;
}

# generic hash (key-based, e.g., by URI or header)
upstream backend {
    hash $request_uri consistent;
    server s1.example.com;
    server s2.example.com;
}

Round Robin Ponderado

weight controla a distribuição de tráfego proporcionalmente. O weight padrão é 1. Defina pesos maiores para servidores mais potentes, para que atendam uma fatia maior. Os pesos funcionam com round-robin, least_conn e ip_hash.

nginx
upstream backend {
    server s1.example.com weight=3;  # 3x traffic
    server s2.example.com weight=2;  # 2x traffic
    server s3.example.com weight=1;  # 1x traffic (default)
}

# total weight = 6
# s1 gets 3/6 = 50%, s2 gets 2/6 = 33%, s3 gets 1/6 = 17%

# useful when servers have different capacity
# e.g., a 4-core server gets weight=4, a 2-core gets weight=2

Health Checks

O nginx de código aberto usa health checks passivos (max_fails/fail_timeout) baseados em falhas reais de requisições. O NGINX Plus adiciona health checks ativos que sondam periodicamente uma URI. Um servidor precisa passar 'passes' checagens consecutivas para ser marcado saudável novamente.

nginx
upstream backend {
    server s1.example.com max_fails=3 fail_timeout=30s;
    server s2.example.com max_fails=3 fail_timeout=30s;

    # passive health check (default behavior):
    # 3 failures within 30s marks the server down
    # it stays down for fail_timeout (30s) before retry
}

# NGINX Plus active health check
upstream backend {
    server s1.example.com;
    server s2.example.com;
    health_check interval=10s fails=3 passes=2;
    health_check uri=/health;
}

Persistência de Sessão

ip_hash fornece sessões fixas por IP do cliente, mas falha se o IP muda (redes móveis). A diretiva hash com consistent oferece redistribuição mínima de chave quando o pool muda. sticky cookie (Plus) define um cookie para fixar um cliente a um servidor.

nginx
# ip_hash: routes by client IP (uses first 3 IPv4 octets)
upstream backend {
    ip_hash;
    server s1.example.com:8080;
    server s2.example.com:8080;
}

# sticky cookie (NGINX Plus only)
upstream backend {
    sticky cookie srv_id expires=1h domain=.example.com path=/;
    server s1.example.com;
    server s2.example.com;
}

# hash with consistent parameter for minimal redistribution
upstream backend {
    hash $http_x_session_id consistent;
    server s1.example.com;
    server s2.example.com;
}

Servidores Backup

Marcados com o parâmetro backup, esses servidores só recebem tráfego quando nenhum servidor principal estiver disponível. Padrão comum: os principais atendem o app; um backup atende uma página estática de manutenção. Servidores backup ficam fora do balanceamento normal.

nginx
upstream backend {
    server s1.example.com;
    server s2.example.com;

    # used only when all primaries are down
    server s3.example.com backup;
    server s4.example.com backup;
}

# backup servers receive traffic ONLY when all
# non-backup servers are unavailable
# useful for a maintenance page or DR fallback

upstream backend {
    server primary.example.com;
    server standby.example.com backup;
}
06

Configuração SSL/TLS

Servidor HTTPS Básico

O parâmetro ssl no listen habilita TLS. ssl_certificate aponta para a cadeia de certificados (cert do servidor + intermediários); ssl_certificate_key aponta para a chave privada. Sempre use fullchain.pem para que os clientes verifiquem a cadeia.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Configuração do Certificado SSL

Let's Encrypt guarda certificados em /etc/letsencrypt/live/<domínio>/. fullchain.pem inclui os intermediários; privkey.pem é a chave privada. O nginx suporta múltiplos tipos de certificado por servidor, selecionando conforme a capacidade do cliente.

nginx
# Let's Encrypt paths
ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

# multiple cert types (RSA + ECDSA) on one server
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.rsa.crt;
    ssl_certificate_key /etc/ssl/example.com.rsa.key;

    ssl_certificate     /etc/ssl/example.com.ecdsa.crt;
    ssl_certificate_key /etc/ssl/example.com.ecdsa.key;
}

Redirecionamento HTTP para HTTPS

O padrão mais limpo é um servidor dedicado na porta 80 que redireciona. $host preserva o hostname original. Usar if ($scheme) num bloco combinado funciona, mas a abordagem de servidor separado é preferida e evita as armadilhas do 'if is evil'.

nginx
# redirect all HTTP traffic to HTTPS
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# single server block handling both
server {
    listen 80;
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
}

Protocolos e Cifras SSL

Desative protocolos antigos (SSLv3, TLSv1.0/1.1). TLS 1.3 é o mais rápido e seguro. Use o Mozilla SSL Configuration Generator para um perfil testado. O cache shared:SSL acelera a retomada de sessão entre workers.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    # modern configuration (Mozilla SSL Config Generator)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # session settings
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
}

HSTS

HSTS diz aos navegadores para sempre usar HTTPS no domínio, prevenindo ataques de SSL-stripping. max-age é em segundos (31536000 = 1 ano). includeSubDomains cobre cada um dos subdomínios. preload submete o site a uma lista embutida nos navegadores — praticamente irreversível, use com cuidado.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    # HSTS: force HTTPS for 1 year (include subdomains)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # preload list (be very careful — requires permanent HTTPS)
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
}

# Preload commits your domain to a browser-baked HTTPS-only list.
# Only enable preload after verifying all subdomains work on HTTPS.

OCSP Stapling

OCSP stapling permite que o nginx busque e sirva o status de revogação do certificado, economizando uma ida e volta do cliente ao responder OCSP. ssl_trusted_certificate é necessário para verificar a resposta OCSP. Um resolver é preciso para que o nginx alcance o servidor OCSP.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    ssl_stapling on;
    ssl_stapling_verify on;

    # trust chain for verification
    ssl_trusted_certificate /etc/ssl/example.com/chain.pem;

    # DNS resolver needed for OCSP requests
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
}
07

Servindo Arquivos Estáticos

Servir Arquivos Estáticos

root define a raiz dos documentos; o nginx mapeia a URI da requisição para um caminho de arquivo. try_files verifica o arquivo, depois o diretório, depois retorna 404. Definir root no nível do server faz todas as locations herdarem, mas você pode sobrescrever por location.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    location / {
        try_files $uri $uri/ =404;
    }
}

# root set at server level is inherited by all locations
# request /images/logo.png -> /var/www/html/images/logo.png
# request /css/style.css   -> /var/www/html/css/style.css

Diretiva Index

index lista os arquivos a tentar quando a requisição é para um diretório. O primeiro arquivo existente é servido. Se nenhum existir e autoindex estiver desligado, o nginx retorna 403. A ordem importa — liste os arquivos preferidos primeiro.

nginx
server {
    listen 80;
    root /var/www/html;

    # try these files in order when request targets a directory
    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ =404;
    }
}

# request / -> tries /var/www/html/index.html, then index.htm
# request /about/ -> tries /var/www/html/about/index.html
# if no index file found and autoindex off -> 403 Forbidden

try_files para SPA

SPAs usam roteamento no cliente, então caminhos desconhecidos devem servir index.html. try_files $uri $uri/ /index.html faz exatamente isso. Cacheie assets com hash por um ano com immutable, já que os nomes endereçados por conteúdo garantem uma URL nova quando o conteúdo muda.

nginx
# Single Page Application (React, Vue, Angular)
server {
    listen 80;
    root /var/www/spa;

    location / {
        # serve static files, fall back to index.html for client routing
        try_files $uri $uri/ /index.html;
    }

    # cache static assets aggressively (filename usually hashed)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Autoindex (Listagem de Diretório)

autoindex gera uma listagem HTML do diretório. Útil para sites de download de arquivos. Desligue exact_size para legibilidade e ligue localtime para timestamps corretos. Nunca habilite em diretórios com arquivos sensíveis — sempre pareie com controle de acesso.

nginx
location /files/ {
    autoindex on;
    autoindex_exact_size off;  # human-readable sizes (KB, MB)
    autoindex_localtime on;    # show local time instead of UTC
    root /var/www;
}

# /files/        -> directory listing
# /files/doc.pdf -> downloads the file
# /files/sub/    -> listing of subdirectory

# disable for security on sensitive directories
location /private/ {
    autoindex off;
    deny all;
}

Headers de Expiração

expires define o Cache-Control max-age. immutable diz aos navegadores que o arquivo nunca muda (pula revalidação). Para assets com hash (file.abc123.js), 1y + immutable é ideal. HTML deve sempre revalidar, para que os usuários recebam atualizações imediatamente.

nginx
# cache static assets for a year
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# never cache HTML (always revalidate)
location ~* \.html$ {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

# short cache for API responses
location /api/ {
    add_header Cache-Control "no-cache";
}

Desativar Log para Estáticos

Requisições de assets estáticos e favicon/robots poluem os access logs. access_log off para o registro; log_not_found off suprime entradas de 404 no log. Isso mantém os logs focados em tráfego significativo e reduz I/O de disco em sites movimentados.

nginx
# don't log requests for static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    access_log off;
    log_not_found off;
    expires 1y;
}

# don't log favicon requests (often 404 from browsers)
location = /favicon.ico {
    log_not_found off;
    access_log off;
}

# don't log robots.txt
location = /robots.txt {
    log_not_found off;
    access_log off;
}
08

Compressão Gzip

Habilitar Gzip

gzip comprime respostas, reduzindo banda. gzip_vary adiciona 'Vary: Accept-Encoding' para caches. gzip_proxied any comprime para requisições via proxy. comp_level 6 equilibra CPU e tamanho. min_length 256 pula respostas minúsculas (o custo supera o ganho).

nginx
http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 256;
    gzip_types
        text/plain
        text/css
        text/xml
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
}

Tipos do Gzip

gzip_types lista os tipos MIME a comprimir. text/html é sempre comprimido por padrão. Não comprima formatos binários já comprimidos (imagens, vídeo, arquivos) — você desperdiça CPU sem reduzir tamanho e pode até aumentar a saída.

nginx
http {
    gzip on;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        application/rss+xml
        application/atom+xml
        image/svg+xml
        font/ttf
        font/otf
        application/vnd.ms-fontobject;

    # text/html is always compressed (implicitly, cannot disable)
    # DON'T compress already-compressed: jpg, png, gif, mp4, zip, gz
}

Nível de Compressão Gzip

comp_level troca CPU por compressão. 6 é o ponto ideal — 9 usa muito mais CPU por <2% de redução. min_length evita comprimir respostas minúsculas, em que o custo do header gzip supera a economia. gzip_disable exclui o IE6 legado, que tem suporte a gzip quebrado.

nginx
http {
    gzip on;
    gzip_comp_level 6;  # 1-9, higher = more compression, more CPU

    # level 1: fast, low compression
    # level 6: good balance (recommended default)
    # level 9: slow, marginal size gain

    # minimum response size to compress (bytes)
    gzip_min_length 256;

    # disable gzip for old browsers
    gzip_disable "MSIE [1-6]\.";
}

Gzip Static

gzip_static serve arquivos .gz pré-construídos, eliminando o custo de CPU da compressão em runtime. O passo de build cria os .gz junto aos originais. O nginx serve o .gz a clientes que enviam Accept-Encoding: gzip, e o original aos demais. Ideal para pipelines de assets estáticos.

nginx
# serve pre-compressed .gz files (no runtime compression cost)
# requires ngx_http_gzip_static_module

location / {
    gzip_static on;
    # on:     serve .gz if it exists
    # always: serve .gz even without Accept-Encoding header

    root /var/www/html;
}

# pre-compress files at build time:
# find /var/www/html -type f ( -name "*.css" -o -name "*.js" \
#   -o -name "*.html" ) -exec gzip -k -9 {} \;
# creates file.css.gz, file.js.gz alongside the originals

Brotli

Brotli supera o gzip para conteúdo de texto, especialmente em níveis mais altos de compressão. Requer o módulo terceiro ngx_brotli. brotli_static serve arquivos .br pré-construídos. Navegadores modernos anunciam 'br' no Accept-Encoding, então o nginx escolhe o melhor disponível.

nginx
# requires ngx_brotli module (not built-in)
http {
    brotli on;
    brotli_comp_level 6;
    brotli_types
        text/plain
        text/css
        application/javascript
        application/json
        image/svg+xml;

    # serve pre-compressed .br files
    brotli_static on;
}

# Brotli typically 10-20% smaller than gzip for text
# supported by all modern browsers (not IE)
# nginx can serve both .br and .gz; picks based on Accept-Encoding

Gzip para Proxy

Por padrão, o nginx não comprime respostas via proxy (para evitar comprimir duas vezes upstreams já comprimidos). gzip_proxied any habilita para todas as requisições via proxy. gzip_vary garante que os caches guardem versões separadas para clientes comprimidos/não comprimidos.

nginx
http {
    gzip on;
    gzip_proxied any;
    # gzip_proxied controls compression for proxied requests:
    # off:           never compress proxied requests
    # expired:       compress if response has Expires header
    # no-cache:      compress if Cache-Control: no-cache
    # no-store:      compress if Cache-Control: no-store
    # private:       compress if Cache-Control: private
    # no_last_modified: compress if no Last-Modified header
    # no_etag:       compress if no ETag header
    # auth:          compress if Authorization header present
    # any:           compress all proxied requests

    gzip_vary on;  # add "Vary: Accept-Encoding" header
}
09

Cache

Proxy Cache

proxy_cache guarda respostas de upstream no disco. keys_zone define uma zona de memória compartilhada para chaves de cache (10m ≈ 80.000 chaves). max_size limita o uso de disco; inactive remove entradas não acessadas naquele período. use_temp_path=off escreve direto no cache, por velocidade.

nginx
http {
    # define cache zone on disk
    proxy_cache_path /var/cache/nginx levels=1:2
        keys_zone=api_cache:10m
        max_size=1g
        inactive=60m
        use_temp_path=off;

    server {
        location /api/ {
            proxy_pass http://backend;
            proxy_cache api_cache;
            proxy_cache_valid 200 10m;
            proxy_cache_valid 404 1m;
        }
    }
}

Zona de Cache

levels=1:2 cria uma árvore de diretórios de dois níveis a partir do hash MD5 da chave de cache, para evitar arquivos demais num único diretório. Zonas separadas por tipo de conteúdo permitem ajustar max_size e inactive independentemente — estático cacheado por mais tempo, API por pouco tempo.

nginx
http {
    proxy_cache_path /var/cache/nginx
        levels=1:2              # directory hierarchy depth
        keys_zone=my_cache:10m  # zone name + shared memory size
        max_size=1g             # max disk size for cache
        inactive=60m            # remove if not accessed in 60min
        use_temp_path=off;      # write directly (faster, no temp copy)

    # multiple zones for different content types
    proxy_cache_path /var/cache/static levels=1:2
        keys_zone=static:10m max_size=500m inactive=24h;
    proxy_cache_path /var/cache/api levels=1:2
        keys_zone=api:10m max_size=200m inactive=10m;
}

Chave de Cache

A chave de cache determina a unicidade do cache. A chave padrão pode causar colisões entre hosts virtuais — inclua $host. Para conteúdo por usuário, inclua um identificador de usuário. proxy_cache_bypass pula o cache (mas ainda armazena); proxy_no_cache não armazena a resposta.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # default key: $scheme$proxy_host$request_uri
    proxy_cache_key "$scheme$request_method$host$request_uri";

    # include user-specific data to avoid cross-user leaks
    proxy_cache_key "$scheme$host$request_uri$http_x_user_id";

    # bypass cache for authenticated users
    proxy_cache_bypass $http_authorization;
    proxy_no_cache $http_authorization;
}

Validade do Cache

proxy_cache_valid define TTLs por código de status. 0s ou omitir um status impede cacheá-lo. proxy_cache_lock serializa cache misses concorrentes para a mesma chave — só uma requisição bate no upstream; as demais esperam a resposta cacheada.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # cache by response status code
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_valid 500 502 503 504 0s;  # don't cache errors

    # fallback for any other status
    proxy_cache_valid any 1m;

    # cache lock: collapse concurrent misses into one upstream call
    proxy_cache_lock on;
    proxy_cache_lock_timeout 5s;
}

Bypass do Cache

proxy_cache_bypass pula a leitura do cache (vai ao upstream), mas pode ainda armazenar a resposta. proxy_no_cache pula o armazenamento. O header X-Cache-Status é inestimável para depuração — HIT significa servido do cache, MISS significa buscado do upstream.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # bypass cache (always go to upstream)
    proxy_cache_bypass $http_authorization $arg_nocache;

    # don't store in cache
    proxy_no_cache $http_authorization;

    # add header showing cache status for debugging
    add_header X-Cache-Status $upstream_cache_status;
}

# $upstream_cache_status values:
# MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, HIT

Cache do Navegador

O cache do navegador reduz a latência de visitas repetidas. immutable pula a revalidação por completo (só seguro para nomes de arquivo endereçados por conteúdo). no-cache significa revalidar toda vez (ainda permite GET condicional). no-store significa nunca guardar. Pareie com ETags para respostas 304 eficientes.

nginx
# cache static assets in the browser
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# HTML - revalidate always
location ~* \.html$ {
    add_header Cache-Control "no-cache, must-revalidate";
    etag on;
}

# API responses - never cache
location /api/ {
    add_header Cache-Control "no-store";
}

# public:    any cache (browser, CDN) may store
# private:   only the browser may store
# immutable: file never changes, skip revalidation
# no-store:  never cache
10

Rewrite de URL

Diretiva return

return é a forma mais simples de redirecionar ou responder. Interrompe o processamento imediatamente. Use 301 para redirecionamento permanente, 302 para temporário. Você pode retornar um código de status com corpo (200, 418) ou um redirecionamento para uma URL. Prefira return a rewrite para redirecionamentos.

nginx
# simplest redirect/rewrite - return stops processing
server {
    location /old {
        return 301 /new;
    }

    location /external {
        return 301 https://example.com$request_uri;
    }

    location /api {
        return 200 "OK\n";
    }

    location /teapot {
        return 418 "I'm a teapot";
    }
}

# return is preferred over rewrite for simple redirects

Diretiva rewrite

rewrite casa a URI contra uma regex e a substitui. last reavalia o casamento de location com a nova URI (como recomeçar). break para o rewrite, mas permanece na location atual. redirect/permanent enviam um redirecionamento ao navegador.

nginx
# rewrite regex replacement [flag]
server {
    # rewrite /old/* to /new/* preserving the captured part
    rewrite ^/old/(.*)$ /new/$1 permanent;

    # rewrite old blog URLs to new structure
    rewrite ^/blog/(\d{4})/(\d{2})/(.*)$ /articles/$1/$2/$3 last;

    # capture with named groups
    rewrite ^/download/(.*)$ /assets/$1 last;
}

# flags:
# last:      re-search locations with the new URI
# break:     stop rewrite, continue in current location
# redirect:  302 temporary redirect
# permanent: 301 permanent redirect

Flags do Rewrite

last vs break é a parte mais confusa. last reexecuta a busca de location (útil quando o rewrite mira uma location diferente). break para o rewrite, mas permanece (útil quando o rewrite só ajusta um caminho interno). redirect/permanent mudam a URL do navegador.

nginx
location / {
    # last: restart location matching with new URI
    rewrite ^/api/(.*)$ /backend/$1 last;

    # break: stop processing rewrites, stay in current location
    rewrite ^/static/(.*)$ /assets/$1 break;

    # redirect: 302 temporary redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 redirect;

    # permanent: 301 permanent redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 permanent;
}

# avoid rewrite inside if blocks - use location + try_files instead

Capturas Nomeadas

Capturas nomeadas (?<nome>pattern) criam variáveis ($nome) mais claras que as posicionais $1, $2. Funcionam tanto em regex de location quanto em rewrite. Os valores capturados ficam disponíveis em proxy_pass, fastcgi_param, add_header e log_format dentro daquela location.

nginx
# named captures in regex locations
location ~ ^/users/(?<username>[a-z]+)/?$ {
    proxy_pass http://backend/users/$username;
}

# named captures in rewrite
location / {
    rewrite ^/articles/(?<year>\d{4})/(?<slug>[a-z-]+)/?$
        /blog?year=$year&slug=$slug last;
}

# named captures become variables: $year, $slug, $username
# accessible in proxy_pass, fastcgi_pass, headers, etc.
# safer than $1, $2 positional captures for readability

Diretiva map

map constrói uma tabela de consulta de uma variável para outra, avaliada preguiçosamente. É muito mais eficiente e legível que cadeias de if. O ramo default trata valores não casados. Casamentos de regex (prefixados com ~) são verificados em ordem.

nginx
# map creates a new variable based on another variable's value
map $http_host $backend {
    default            "http://default.backend";
    "a.com"            "http://a.backend";
    "b.com"            "http://b.backend";
    "~^.*\.app\.com$" "http://app.backend";
}

server {
    server_name a.com b.com;
    location / {
        proxy_pass $backend;
    }
}

# map is evaluated lazily and cached per request
# more efficient than if/else chains

Diretiva if (Cuidado)

if tem comportamento surpreendente dentro de blocos location — pode reescrever configurações de forma imprevisível. Os únicos usos universalmente seguros são return e rewrite. Para checagens de existência de arquivo, use try_files. Para lógica complexa, use map ou blocos location separados. Veja a wiki: 'If Is Evil'.

nginx
# "if is evil" — use sparingly! Only safe for:
# return / rewrite, and with these checks:
#   -f, -d, -e, -x (file/dir/exists/executable)
#   =, !=, ~, ~* (string/regex comparison)

location / {
    if ($request_method = POST) {
        return 405;
    }

    if ($http_user_agent ~* "bot") {
        return 403;
    }

    # BAD: don't do this inside if
    # if (-f $request_filename) { ... }
    # use try_files instead
    try_files $uri $uri/ /index.html;
}
11

Redirecionamento

Redirecionamento Permanente (301)

301 significa 'movido permanentemente' — navegadores e buscadores o cacheiam, então use-o só para mudanças realmente permanentes. Teste redirecionamentos com 302 primeiro para não fixar um erro. O 301 passa autoridade de links (SEO) para a nova URL.

nginx
# 301 - permanent redirect (cached by browsers indefinitely)
server {
    listen 80;
    server_name old-domain.com;

    # redirect entire site to a new domain
    return 301 https://new-domain.com$request_uri;
}

location /old-page {
    return 301 /new-page;
}

# 301 caches indefinitely in browsers — test with 302 first!
# Search engines treat 301 as a permanent move and update indexes.

Redirecionamento Temporário (302)

302 converte POST em GET ao redirecionar (comportamento histórico). 307 e 308 preservam o verbo — importante para reenviar POSTs. 303 converte explicitamente para GET (útil após envio de formulário, para evitar duplo envio ao atualizar). Escolha conforme o verbo deva ser preservado ou não.

nginx
# 302 - temporary redirect (not cached by default)
location /maintenance {
    return 302 /maintenance.html;
}

# 307 - temporary, preserves HTTP method (POST stays POST)
location /api/v1 {
    return 307 /api/v2;
}

# 308 - permanent, preserves HTTP method
location /api/v1 {
    return 308 /api/v2;
}

# 303 - see other (always uses GET for the new request)
location /form-submit {
    return 303 /success;
}

Redirecionar www para non-www

Escolha uma forma canônica (www ou non-www) e redirecione a outra. Dois blocos server é o padrão mais limpo: o não canônico só redireciona. $request_uri preserva o caminho e a query string. Aplique a mesma lógica para redirecionamentos HTTPS.

nginx
# www to non-www
server {
    listen 80;
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 80;
    server_name example.com;
    # ... main site config
}

# non-www to www (reverse direction)
server {
    listen 80;
    server_name example.com;
    return 301 https://www.example.com$request_uri;
}

Redirecionar HTTP para HTTPS

$host preserva o hostname original, então o redirecionamento funciona para qualquer server_name. $request_uri preserva o caminho e a query. Para portas não padrão, acrescente :porta a $host. Um bloco server dedicado na porta 80 é mais limpo que checagens if por location.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# with a non-standard HTTPS port
server {
    listen 8080;
    return 301 https://$host:8443$request_uri;
}

# redirect only a specific path
location /secure {
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
}

Redirecionar para Outro Domínio

Para migrações de domínio, $request_uri preserva o caminho completo e a query, para que os links não quebrem. Use rewrite com captura quando a estrutura do caminho muda. 301 é o correto para migrações permanentes — transfere o ranking SEO para o novo domínio.

nginx
# domain migration — preserve all paths
server {
    listen 80;
    server_name old.com www.old.com;
    return 301 https://new.com$request_uri;
}

# preserve path and query string
location /docs/ {
    return 301 https://docs.new.com$request_uri;
}

# with path rewrite using capture groups
location /old-blog/ {
    rewrite ^/old-blog/(.*)$ https://blog.new.com/$1 permanent;
}

Redirecionamento por Caminho

Redirecionamentos por caminho são úteis para limpeza de URLs (remover barras finais, extensões de arquivo) e mudanças de conteúdo. Locations com regex e capturas ($1) permitem reescrita flexível de caminhos. Redirecionamentos baseados em parâmetros de query usam $arg_nome para ler parâmetros individuais.

nginx
# redirect specific paths
location /promo/2023 {
    return 301 /promo/2024;
}

# remove trailing slash
location ~ ^/(.*)/$ {
    return 301 /$1;
}

# remove .html extension
location ~ ^/(.*)\.html$ {
    return 301 /$1;
}

# redirect based on query parameter
location /download {
    if ($arg_version = "1") {
        return 301 /download?v=2;
    }
}
12

FastCGI (PHP-FPM)

Configuração Básica do PHP-FPM

fastcgi_pass envia requisições PHP ao PHP-FPM via socket UNIX (mais rápido, apenas local) ou porta TCP. include fastcgi_params define variáveis CGI padrão. SCRIPT_FILENAME diz ao PHP qual arquivo executar — combinando a raiz de documentos com o caminho do script.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/laravel/public;
    index index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        # or: fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Parâmetros FastCGI

fastcgi_params define variáveis de ambiente passadas ao PHP. SCRIPT_FILENAME é a mais crítica — sem ela, o PHP não acha o script. Parâmetros personalizados (APP_ENV, DB_HOST) permitem injetar configuração sem modificar o app. PATH_INFO habilita URLs limpas em alguns frameworks.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # standard CGI parameters
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;

    # custom application parameters
    fastcgi_param APP_ENV production;
    fastcgi_param DB_HOST db.internal;

    # flag for HTTPS (so PHP knows the original scheme)
    fastcgi_param HTTPS $https_flag;
}

Cache FastCGI

fastcgi_cache armazena respostas PHP, reduzindo drasticamente a carga para páginas cacheáveis. fastcgi_cache_use_stale serve uma resposta cacheada vencida se o backend falhar ou der timeout — melhora a resiliência. Cuidado para não cachear conteúdo por usuário ou autenticado.

nginx
http {
    fastcgi_cache_path /var/cache/nginx/php
        levels=1:2
        keys_zone=phpcache:100m
        max_size=1g
        inactive=60m;

    server {
        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php-fpm.sock;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

            fastcgi_cache phpcache;
            fastcgi_cache_valid 200 10m;
            fastcgi_cache_key $scheme$host$request_uri;
            fastcgi_cache_use_stale error timeout invalid_header;
        }
    }
}

Buffers FastCGI

Buffers guardam a resposta PHP antes de enviar ao cliente. Buffers pequenos fazem o nginx escrever em disco (lento) para respostas grandes. Se você vê erros 'upstream sent too big header', aumente fastcgi_buffer_size. Para respostas grandes de API, use buffers maiores e menos numerosos.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # buffer settings
    fastcgi_buffering on;
    fastcgi_buffer_size 16k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 32k;

    # for large responses (e.g., PHP generating big JSON)
    fastcgi_buffers 64 16k;
    fastcgi_buffer_size 32k;

    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Timeouts FastCGI

fastcgi_read_timeout é quanto tempo o nginx espera o PHP produzir saída. Scripts longos (importações de dados, geração de relatórios, chamadas de IA) precisam de valores maiores. Garanta que o max_execution_time do PHP seja pelo menos tão alto, senão o PHP dá timeout primeiro.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    fastcgi_connect_timeout 5s;
    fastcgi_read_timeout 300s;    # for long-running scripts
    fastcgi_send_timeout 300s;

    # increase for very slow PHP scripts (imports, exports, reports)
    fastcgi_read_timeout 600s;
}

# also adjust max_execution_time in php.ini to match
# otherwise PHP kills the script before nginx times out

try_files com PHP

try_files $uri $uri/ /index.php?$args é o padrão para frameworks PHP (WordPress, Laravel, Drupal). Ele serve arquivos/diretórios reais; caso contrário, roteia para index.php com a query string. $args preserva os parâmetros de query originais.

nginx
# WordPress-style pretty URLs
server {
    root /var/www/wordpress;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # deny access to sensitive files
    location ~* /wp-config.php {
        deny all;
    }
}
13

Proxy de WebSocket

Proxy de WebSocket

WebSocket exige HTTP/1.1 mais os headers Upgrade e Connection. O bloco map converte o header Upgrade do cliente no valor correto de Connection: 'upgrade' para WebSocket, 'close' para HTTP normal. O read_timeout longo mantém conexões WebSocket ociosas vivas.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name ws.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 3600s;  # 1 hour
        proxy_send_timeout 3600s;
    }
}

Headers de Upgrade

HTTP/1.1 é obrigatório para WebSocket (HTTP/2 trata multiplexação de forma diferente). Connection pode ser fixado em 'upgrade', mas a abordagem com variável de map também trata requisições não WebSocket na mesma location. Passe Host para que o backend valide o header Origin.

nginx
location /ws {
    proxy_pass http://backend;

    # HTTP/1.1 is required for the Upgrade mechanism
    proxy_http_version 1.1;

    # pass the Upgrade header through
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # preserve host for origin checks on the backend
    proxy_set_header Host $host;

    # real client IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Timeout de WebSocket

O proxy_read_timeout padrão (60s) fecha conexões WebSocket ociosas. Defina-o alto (86400s = 24h) para manter as conexões vivas entre mensagens. proxy_buffering off garante que as mensagens cheguem ao cliente imediatamente, em vez de serem agrupadas.

nginx
location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # WebSocket connections are long-lived
    # default 60s would close them during idle periods
    proxy_read_timeout 86400s;  # 24 hours
    proxy_send_timeout 86400s;

    # disable buffering for real-time messages
    proxy_buffering off;
}

Proxy Socket.io

Socket.io começa com HTTP long-polling e depois atualiza para WebSocket, se disponível. Ambos os transportes passam pelo mesmo proxy_pass, então uma location trata tudo. Passar X-Forwarded-Proto permite que o socket.io saiba que está atrás de HTTPS e construa URLs corretas.

nginx
server {
    listen 80;
    server_name socket.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;

        proxy_read_timeout 86400s;

        # socket.io needs these for correct client IP and scheme
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# socket.io uses both polling (HTTP) and WebSocket transports
# both are handled by the proxy_pass above

Múltiplos Caminhos WebSocket

Serviços WebSocket diferentes podem ser roteados por caminho para backends diferentes. Cada location precisa dos mesmos headers de upgrade. O bloco map é definido uma vez no nível http e compartilhado. Ajuste o read_timeout por serviço — chat pode ser ativo com frequência; notificações podem ficar ociosas por horas.

nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    # chat application
    location /ws/chat/ {
        proxy_pass http://chat_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }

    # notifications service
    location /ws/notify/ {
        proxy_pass http://notify_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400s;
    }
}

WSS (WebSocket Seguro)

WSS é WebSocket sobre TLS. O nginx termina o TLS (cuida do certificado) e faz proxy de um WebSocket puro ao backend. O backend não precisa de configuração TLS. Este é o setup padrão de produção — navegadores exigem WSS para páginas HTTPS (regras de mixed-content).

nginx
server {
    listen 443 ssl;
    server_name ws.example.com;

    ssl_certificate     /etc/ssl/ws.example.com.crt;
    ssl_certificate_key /etc/ssl/ws.example.com.key;

    location / {
        proxy_pass http://backend:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }
}

# browser connects with wss://ws.example.com
# nginx terminates TLS, proxies plain WebSocket to the backend
14

Headers de Segurança

X-Frame-Options

X-Frame-Options impede que seu site seja embutido em iframes, bloqueando ataques de clickjacking. SAMEORIGIN permite que suas próprias páginas se embebam. O substituto moderno é CSP frame-ancestors, mais flexível. always garante que o header seja enviado também em respostas de erro.

nginx
# prevent clickjacking (your site embedded in an iframe)
add_header X-Frame-Options "SAMEORIGIN" always;

# options:
# DENY          - no framing at all
# SAMEORIGIN    - only same-site can frame
# ALLOW-FROM    - deprecated, use CSP frame-ancestors instead

# modern equivalent via Content-Security-Policy
add_header Content-Security-Policy "frame-ancestors 'self'" always;

X-Content-Type-Options

nosniff diz aos navegadores para confiar no header Content-Type e não farejar o conteúdo. Sem ele, um navegador poderia executar uma imagem enviada como HTML se farejasse conteúdo HTML. É um header de baixo esforço e alto valor — sempre habilite.

nginx
# prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;

# forces the browser to respect the declared Content-Type
# prevents XSS via uploaded files (e.g., an image containing HTML
# being executed as a script)

# related: block Adobe Flash / PDF cross-domain policies
add_header X-Permitted-Cross-Domain-Policies "none" always;

Content-Security-Policy

CSP é a defesa mais poderosa contra XSS — ele lista as fontes permitidas para scripts, estilos, imagens etc. Comece com Report-Only para achar violações sem quebrar nada, depois imponha. 'self' significa mesma origem; 'unsafe-inline' permite scripts/estilos inline (necessário em muitos apps).

nginx
# strict CSP — restricts where resources can load from
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" always;

# report-only mode (logs violations without blocking)
add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;

X-XSS-Protection

X-XSS-Protection habilitava o filtro embutido de XSS refletido do navegador. Navegadores modernos removeram esse recurso em favor do CSP. mode=block impedia a sanitização (que poderia introduzir novas vulnerabilidades) e apenas bloqueava a página. Incluir é inofensivo para navegadores legados, mas CSP é a defesa real.

nginx
# legacy XSS auditor (older browsers)
add_header X-XSS-Protection "1; mode=block" always;

# values:
# 0              - disable the filter
# 1              - enable (sanitize)
# 1; mode=block  - enable and block the page entirely

# NOTE: deprecated in modern browsers (Chrome, Edge, Safari removed it)
# CSP is the modern replacement, but this doesn't hurt to include
# for legacy browser support

Referrer-Policy

Referrer-Policy controla quanta informação de URL vaza via o header Referer quando os usuários clicam em links. strict-origin-when-cross-origin (o padrão dos navegadores) envia a URL completa para requisições de mesma origem, mas só a origem para cross-origin, e nada ao descer para HTTP.

nginx
# control what the Referer header contains
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# options:
# no-referrer                  - never send Referer
# no-referrer-when-downgrade   - default; no Referer on HTTPS->HTTP
# same-origin                  - only same-site
# origin                       - send only scheme+host
# strict-origin                - origin, but not on downgrade
# origin-when-cross-origin     - full for same, origin for cross
# strict-origin-when-cross-origin - recommended default
# unsafe-url                   - send full URL (not recommended)

Permissions-Policy

Permissions-Policy permite desativar recursos do navegador (câmera, microfone, geolocalização etc.) mesmo que a página os solicite. Um () vazio desativa o recurso por completo. Isso limita o raio de dano de um XSS — um script comprometido não pode ligar a câmera se a policy proíbe.

nginx
# control which browser features the page can use
# (formerly Feature-Policy)
add_header Permissions-Policy "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=()" always;

# allow only for same origin
add_header Permissions-Policy "geolocation=(self), microphone=(self)" always;

# allow for specific origins
add_header Permissions-Policy "camera=(self https://trusted.com)" always;
15

Controle de Acesso

Allow/Deny por IP

Regras allow/deny são avaliadas em ordem; a primeira que casa vence. O deny all final bloqueia tudo que não foi explicitamente permitido. Útil para restringir painéis de administração a IPs corporativos. Regras podem usar faixas CIDR ou IPs únicos, e suportam IPv4 e IPv6.

nginx
location /admin {
    allow 192.168.1.0/24;     # internal network
    allow 10.0.0.0/8;         # VPN range
    allow 203.0.113.5;        # specific IP
    deny all;

    proxy_pass http://backend;
}

# rules are checked in order — first match wins
# if no rule matches, access is allowed by default

Deny All

deny all bloqueia tudo; pareie com allow para uma whitelist. O inverso — negar IPs específicos e permitir o resto — é uma blacklist. Whitelists são mais seguras (negação por padrão). Sem allow/deny explícito, o acesso é permitido, então sempre termine com deny all em áreas restritas.

nginx
# deny all access to a location
location /private {
    deny all;
    return 403;
}

# deny specific IPs, allow everyone else
location / {
    deny 192.168.1.100;        # block one IP
    deny 203.0.113.0/24;       # block a range
    allow all;
}

# deny a range, allow the rest
location /api {
    deny 10.0.0.0/8;
    allow all;
    proxy_pass http://backend;
}

Permitir Sub-rede

Faixas de IP privado (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) não são roteáveis na internet, então permiti-las restringe o acesso a redes internas. Para IPv6, ::1 é localhost. Combine com uma VPN para acesso remoto seguro a ferramentas internas.

nginx
# allow only local/private networks
location /internal {
    allow 192.168.0.0/16;     # private class B
    allow 172.16.0.0/12;      # private class B range
    allow 10.0.0.0/8;         # private class A
    deny all;

    root /var/www/internal;
}

# IPv6
location / {
    allow 2001:db8::/32;      # example IPv6 range
    allow ::1;                # IPv6 localhost
    deny all;
}

Módulo Geo

geo é otimizado para consultas de IP usando uma árvore radix — muito mais rápido que uma lista longa de allow/deny. Ele define uma variável (aqui $allowed_ip) com base no IP do cliente. A forma 'ranges' suporta faixas de IP início-fim. Use a variável em if() ou map para controle de acesso flexível.

nginx
# map IPs to values (binary search, very fast)
geo $allowed_ip {
    default        0;
    192.168.0.0/24 1;
    10.0.0.0/8     1;
    203.0.113.5    1;
}

server {
    location /admin {
        if ($allowed_ip = 0) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# geo with IP ranges (uses 'ranges' directive)
geo $country_code {
    ranges;
    default                 ZZ;
    10.0.0.0-10.255.255.255 US;
}

Limite por IP (limit_req)

limit_req_zone define uma taxa por IP usando $binary_remote_addr (compacto). limit_req a aplica. burst permite picos curtos (fila de até 20). nodelay atende o pico imediatamente em vez de estrangular — bom para APIs. Sem nodelay, requisições em excesso são atrasadas, não rejeitadas.

nginx
http {
    # define rate limit zone (10 requests/sec per IP)
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=mylimit burst=20 nodelay;
            proxy_pass http://backend;
        }
    }
}

# $binary_remote_addr uses binary form (more memory-efficient)
# 10m zone stores ~160,000 unique IP addresses
# rate=10r/s: 10 requests per second per IP
# burst=20: allow 20 requests to queue
# nodelay: serve the burst immediately (no artificial delay)

Bloqueio por País (GeoIP)

O módulo GeoIP mapeia IPs de clientes para códigos de país usando um banco de dados MaxMind. Combinado com map, você pode bloquear ou permitir países inteiros. Nota: o GeoLite2 gratuito da MaxMind exige o módulo terceiro maxminddb (o módulo GeoIP legado usa o formato .dat mais antigo). A precisão não é 100% — use só para filtragem grossa.

nginx
# requires the GeoIP module and a MaxMind database
geoip_country /usr/share/GeoIP/GeoIP.dat;

map $geoip_country_code $allowed_country {
    default yes;
    CN no;
    RU no;
    KP no;
}

server {
    location / {
        if ($allowed_country = no) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# GeoIP2 (maxminddb module) for the newer GeoLite2 format
# maxminddb /etc/nginx/geoip2/GeoLite2-Country.mmdb;
# $geoip2_country_code source=$remote_addr country iso_code;
16

Autenticação

Configuração do Basic Auth

auth_basic aciona o diálogo nativo de usuário/senha do navegador. A string do realm ('Admin Area') é exibida ao usuário. auth_basic_user_file aponta para um arquivo htpasswd. Use auth_basic off para desativar autenticação numa sub-location que deve ser pública.

nginx
location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

location /public {
    # disable auth inherited from parent location
    auth_basic off;
}

# create users with htpasswd (apache2-utils / httpd-tools):
# htpasswd -c /etc/nginx/.htpasswd user1   (create file)
# htpasswd /etc/nginx/.htpasswd user2      (append, no -c)

Arquivo htpasswd

O arquivo htpasswd guarda pares usuário:hash. bcrypt (-B) é o hash mais forte; MD5 (-m, padrão) é aceitável; SHA1 (-s) é fraco; PLAIN é inseguro. Restrinja as permissões do arquivo para que só o nginx possa lê-lo — o arquivo contém hashes de senha que não devem vazar.

nginx
# /etc/nginx/.htpasswd format:
# user1:$apr1$qHR...$hashedpassword
# user2:{PLAIN}plaintext       (insecure!)
# user3:{SHA}base64sha1hash

# generate with htpasswd:
# -c  create new file (overwrites!)
# -B  bcrypt (most secure, recommended)
# -m  MD5 (default, APR1)
# -s  SHA1

# bcrypt (recommended)
# htpasswd -B /etc/nginx/.htpasswd user1

# protect the file permissions
chown root:nginx /etc/nginx/.htpasswd
chmod 640 /etc/nginx/.htpasswd

Auth para Location Específica

auth_basic é herdado por locations aninhados. Para tornar um sub-caminho público, defina auth_basic off. Isso é útil quando a maior parte de /admin exige auth, mas /admin/health (um endpoint de health check) deve ser acessível sem credenciais para ferramentas de monitoramento.

nginx
server {
    # no auth at server level

    location /admin {
        auth_basic "Admin";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }

    location /admin/api {
        # inherits auth from /admin
        proxy_pass http://admin_api;
    }

    location /admin/public {
        # explicitly disable inherited auth
        auth_basic off;
        proxy_pass http://public_api;
    }
}

Allow/Deny com Auth

satisfy any significa que passar na checagem de IP OU na autenticação concede acesso — conveniente para usuários internos (sem senha) enquanto exige senha de usuários externos. satisfy all exige ambos — a opção mais restritiva, útil para áreas altamente sensíveis.

nginx
# satisfy: ALL (default) or ANY
location / {
    # allow corporate IPs without password
    # require password from outside the corporate network
    satisfy any;

    allow 192.168.0.0/16;
    deny all;

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

# satisfy all: must pass BOTH IP check AND auth
# satisfy any: pass EITHER IP check OR auth

Módulo Auth Request

auth_request envia uma subrequisição interna a um serviço de auth antes da requisição principal. O serviço valida o token (JWT, cookie de sessão etc.) e retorna 2xx (permite) ou 401/403 (nega). internal impede acesso externo a /auth. Isso desacopla a autenticação do seu app.

nginx
# delegate authentication to a subrequest (OAuth, JWT, etc.)
location / {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {
    internal;                    # can't be called directly
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

# auth-service returns:
# 2xx -> allow (continue to backend)
# 401/403 -> deny (return to client)
# other -> error

Auth JWT

A validação de JWT pode ser feita no próprio processo com njs (módulo JavaScript do nginx) para baixa latência, ou delegada a um serviço externo via auth_request. O njs executa um subconjunto de JavaScript dentro do nginx — rápido, mas limitado. A abordagem com auth_request é mais flexível e agnóstica de linguagem.

nginx
# requires the njs (nginx JavaScript) module
js_import auth.js;

location /api/ {
    js_content auth.validateJwt;
    proxy_pass http://backend;
}

# auth.js defines the validateJwt function:
# function validateJwt(r) {
#     var token = r.headersIn.Authorization;
#     if (!token || !verifyJwt(token)) {
#         r.return(401);
#         return;
#     }
# }

# alternative: use auth_request with an external JWT validator service
# more portable than njs, but adds a network hop per request
17

Logs

Access Log

access_log registra toda requisição. log_format define quais campos capturar. O formato padrão 'combined' é compatível com Apache. Para sites de alto tráfego, buffer+flush reduz o I/O de disco ao agrupar escritas. syslog envia logs a um servidor central para agregação.

nginx
http {
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log main;
    # or use the built-in 'combined' format
    access_log /var/log/nginx/access.log combined;
}

# disable access log
access_log off;

# log to syslog
access_log syslog:server=localhost,facility=local7 main;

# buffer writes (reduce I/O)
access_log /var/log/nginx/access.log main buffer=32k flush=5s;

Error Log

error_log captura erros do nginx e problemas de upstream. O nível filtra a severidade — warn é um bom padrão. debug é muito verboso (use só para solução de problemas) e exige um build de depuração. memory: bufferiza logs na RAM — útil para diagnosticar problemas de inicialização que o log em disco não captura.

nginx
# error log location and severity level
error_log /var/log/nginx/error.log warn;

# levels (low to high severity):
# debug, info, notice, warn, error, crit, alert, emerg

# debug requires nginx built with --with-debug
error_log /var/log/nginx/error.log debug;

# log to memory (for debugging, lost on restart)
error_log memory:32m debug;

# disable (NOT recommended — hides real errors)
error_log /dev/null crit;

Formatos de Log

Formatos de log personalizados capturam o que importa para você. request_time é o tempo total de processamento; upstream_response_time isola o backend. escape=json produz JSON válido para agregadores de log (ELK, Loki, Datadog). Sem escape=json, caracteres especiais nas URIs podem quebrar a análise do JSON.

nginx
http {
    # combined (Apache-compatible, the default)
    log_format combined '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';

    # main with upstream timing
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct="$upstream_connect_time" '
                    'urt="$upstream_response_time"';

    # JSON format for log aggregation (ELK, Loki, etc.)
    log_format json escape=json
        '{"time":"$time_iso8601",'
        '"remote":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"bytes":$body_bytes_sent,'
        '"ua":"$http_user_agent"}';
}

Log Condicional

O parâmetro if= registra condicionalmente com base numa variável. map $status permite registrar só erros (4xx/5xx), reduzindo ruído e uso de disco em sites de alto tráfego. A variável deve ser 0/vazia para pular o registro, não zero para registrar.

nginx
http {
    # don't log successful 2xx/3xx, only errors
    map $status $loggable {
        ~^[23]  0;
        default 1;
    }

    server {
        access_log /var/log/nginx/access.log main if=$loggable;
    }
}

# skip logging for static assets
map $request_uri $log_skip {
    default                    1;
    ~*\.(jpg|png|gif|css|js)$  0;
}
access_log /var/log/nginx/access.log main if=$log_skip;

Rotação de Logs

logrotate renomeia e comprime logs antigos. postrotate envia USR1 ao nginx, que reabre seus arquivos de log — sem isso, o nginx continua escrevendo no arquivo renomeado. sharedscripts roda o postrotate uma vez (não por arquivo). delaycompress comprime na segunda rotação, para que o log mais recente fique descomprimido.

nginx
# logrotate config: /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        if [ -f /var/run/nginx.pid ]; then
            kill -USR1 $(cat /var/run/nginx.pid)
        fi
    endscript
}

# USR1 signal tells nginx to reopen log files
# without dropping connections
# nginx -s reopen does the same thing

Desativar Logs

Desativar access_log para health checks e assets estáticos reduz bastante o ruído dos logs e o I/O de disco. log_not_found off suprime entradas de 404 no log (útil para favicon.ico). Sempre mantenha error_log habilitado ao menos no nível 'error' — falhas silenciosas são difíceis de diagnosticar.

nginx
# disable access log entirely
access_log off;

# disable for a specific location
location /health {
    access_log off;
    return 200 "ok\n";
}

# disable for static assets
location ~* \.(jpg|png|gif|ico|css|js)$ {
    access_log off;
    log_not_found off;
}

# only log errors (reduce error log verbosity)
error_log /var/log/nginx/error.log error;
18

Limitação de Taxa

limit_req_zone

limit_req_zone define um limite de taxa chaveado por uma variável (geralmente o IP do cliente). O tamanho da zona (10m) determina quantas chaves únicas podem ser acompanhadas. rate é a frequência de requisições permitida. Defina as zonas no contexto http e aplique-as no contexto location com limit_req.

nginx
http {
    # 10 requests per second per IP
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    # 1 request per second per IP (for login)
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

    # 100 requests per minute per IP
    limit_req_zone $binary_remote_addr zone=general:10m rate=100r/m;
}

# $binary_remote_addr uses binary form (more memory-efficient than text)
# 10m zone stores ~160,000 unique IP addresses
# rate can be per second (r/s) or per minute (r/m)

limit_req

limit_req aplica uma zona a uma location. burst permite picos curtos (fila de até N requisições em excesso). nodelay atende o pico em velocidade máxima em vez de espaçá-lo — bom para APIs em que a latência importa. Sem burst, toda requisição acima da taxa é rejeitada imediatamente.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            proxy_pass http://backend;
        }

        location /login {
            limit_req zone=api burst=5 nodelay;
            proxy_pass http://backend;
        }
    }
}

# burst: max number of requests allowed to queue
# nodelay: serve the burst immediately (no artificial throttling)
# without burst: requests exceeding the rate get 503 immediately

limit_conn

limit_conn limita conexões concorrentes, não a taxa de requisições. Útil para impedir que um único IP abra centenas de downloads simultâneos. Combinado com limit_req (taxa), oferece proteção contra picos e contra concorrência. limit_conn_zone usa o mesmo padrão de zona por chave.

nginx
http {
    # limit concurrent connections per IP
    limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;

    # limit total connections per server name
    limit_conn_zone $server_name zone=conn_per_server:10m;

    server {
        limit_conn conn_per_ip 10;
        limit_conn conn_per_server 1000;

        location /download {
            limit_conn conn_per_ip 1;  # one download at a time per IP
            proxy_pass http://backend;
        }
    }
}

Fila de Burst

burst é o tamanho da fila para requisições em excesso. nodelay atende o pico inteiro imediatamente (bom para APIs). delay=N atende N imediatamente e estrangula o restante para a taxa configurada (mais suave). Sem nodelay, todas as requisições em excesso são atrasadas para casar com a taxa, espalhando a carga uniformemente.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            # burst=20: allow 20 requests to queue
            # nodelay: serve them immediately (no artificial delay)
            limit_req zone=api burst=20 nodelay;

            # delay: first 10 immediate, next 10 delayed, rest rejected
            limit_req zone=api burst=20 delay=10;

            proxy_pass http://backend;
        }
    }
}

# without burst: requests over rate get 503 immediately
# with burst: excess requests queue (default delayed)
# nodelay: queue served at full speed (allows spikes)
# delay=N: first N immediate, rest throttled to the rate

Limite de Taxa por IP

Defina zonas separadas por tipo de endpoint com taxas apropriadas. Endpoints de API toleram taxas maiores; endpoints de auth (login, redefinição de senha) precisam de limites estritos para prevenir força bruta; uploads precisam de taxas bem baixas para evitar abuso. burst dá uma pequena folga para picos legítimos.

nginx
http {
    # different limits for different endpoints
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=auth:10m rate=1r/s;
    limit_req_zone $binary_remote_addr zone=upload:10m rate=2r/m;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
        }

        location /login {
            limit_req zone=auth burst=5 nodelay;
        }

        location /upload {
            limit_req zone=upload burst=3 nodelay;
            client_max_body_size 100M;
        }
    }
}

Resposta Personalizada de Limite

Por padrão, requisições limitadas recebem 503 (Service Unavailable). 429 (Too Many Requests) é semanticamente mais correto e o que a maioria das APIs espera. Use error_page para retornar um corpo JSON explicando o limite. Inclua um header Retry-After para que os clientes saibam quando recuar.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_status 429;  # default is 503

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;

            # custom error response
            error_page 429 = @rate_limited;
        }

        location @rate_limited {
            default_type application/json;
            return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
        }
    }
}

# also available: limit_conn_status 429;
19

Ajuste de Desempenho

worker_processes

worker_processes deve corresponder à contagem de núcleos de CPU — auto faz isso automaticamente. Cada worker é um processo single-thread que trata muitas conexões via event loop. worker_cpu_affinity fixa workers a núcleos específicos, melhorando a localidade de cache. A afinidade auto deixa o escalonador do SO decidir.

nginx
# main context
worker_processes auto;  # one per CPU core (recommended)

# or set an explicit count
worker_processes 4;

# each worker handles connections independently
# 'auto' uses the number of available CPU cores

# CPU affinity (pin workers to specific cores)
worker_processes auto;
worker_cpu_affinity auto;

# or manual bitmask (one mask per worker)
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

worker_connections

worker_connections é por worker; a capacidade total é worker_processes * worker_connections. Também é limitado pelo limite de descritores de arquivo do SO (worker_rlimit_nofile). Você precisa elevar tanto o limite do nginx quanto o do SO (limits.conf ou LimitNOFILE do systemd). multi_accept agarra todas as conexões pendentes de uma vez.

nginx
events {
    # connections per worker process
    worker_connections 4096;

    # accept multiple connections at once under high load
    multi_accept on;
}

# total max connections = worker_processes * worker_connections
# but also bounded by worker_rlimit_nofile (file descriptor limit)

# main context — raise the FD limit
worker_rlimit_nofile 65535;

# also raise system limits (outside nginx):
# /etc/security/limits.conf:
#   * soft nofile 65535
#   * hard nofile 65535

keepalive_timeout

O keepalive do cliente reutiliza conexões para múltiplas requisições, reduzindo latência. keepalive_timeout é quanto tempo uma conexão ociosa permanece aberta. O keepalive de upstream (a diretiva keepalive no upstream) cacheia conexões aos backends — defina Connection como vazio para que o nginx não envie 'close'.

nginx
http {
    # keep-alive timeout (client side)
    keepalive_timeout 65s;
    keepalive_requests 1000;  # max requests per connection

    # upstream keepalive (reuse connections to backends)
    upstream backend {
        server 10.0.0.1:8080;
        keepalive 32;  # cache of 32 idle upstream connections
    }

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # clear to enable keepalive
    }
}

sendfile e tcp_nopush

sendfile usa um caminho zero-copy do kernel para enviar arquivos, contornando buffers de user-space — muito mais rápido para arquivos estáticos. tcp_nopush trabalha com sendfile para enviar headers e o início do arquivo num único pacote. tcp_nodelay desativa Nagle para baixa latência. aio threads descarrega o I/O de disco do event loop.

nginx
http {
    # use kernel sendfile() for static files (zero-copy)
    sendfile on;

    # send headers + start of file in one TCP packet
    tcp_nopush on;

    # disable Nagle's algorithm (send small packets immediately)
    tcp_nodelay on;

    # for static file serving
    location /static/ {
        sendfile on;
        tcp_nopush on;
        aio threads;  # asynchronous I/O via thread pool
        root /var/www;
    }
}

# sendfile: zero-copy file transfer (kernel space, no user-space copy)
# tcp_nopush: coalesce headers + file data into one packet
# tcp_nodelay: don't wait to batch small packets (low latency)

Tamanhos de Buffer

Ajuste os buffers ao seu tráfego. client_max_body_size limita o tamanho de upload (padrão 1M — pequeno demais para uploads de arquivos). Buffers de proxy/fastcgi guardam respostas de upstream; buffers pequenos demais transbordam para o disco. large_client_header_buffers tratam URLs/cookies longos. Monitore erros de 'buffer overflow'.

nginx
http {
    # client body buffer (in-memory before writing to disk)
    client_body_buffer_size 16k;
    client_max_body_size 50m;

    # client header buffers
    client_header_buffer_size 1k;
    large_client_header_buffers 4 8k;

    # proxy buffers (responses from upstream)
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 16k;

    # fastcgi buffers (responses from PHP-FPM, etc.)
    fastcgi_buffer_size 4k;
    fastcgi_buffers 8 4k;
}

# if a request body exceeds client_body_buffer_size,
# nginx writes it to a temp file (slower)

Cache de Arquivos Abertos

open_file_cache cacheia descritores de arquivo e metadados, evitando chamadas de sistema open()/stat() repetidas para arquivos populares. Isso acelera bastante o serviço de arquivos estáticos. valid controla com que frequência o nginx reverifica o arquivo (captura atualizações). min_uses evita cachear requisições pontuais. Cacheie erros também, para evitar opens falhos repetidos.

nginx
http {
    open_file_cache max=10000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    server {
        root /var/www/html;

        location / {
            open_file_cache max=10000 inactive=20s;
            open_file_cache_valid 30s;
            try_files $uri $uri/ =404;
        }
    }
}

# caches file descriptors, sizes, modification times
# reduces stat() and open() syscalls for popular files
# max=10000: cache up to 10000 files
# inactive=20s: remove if not accessed in 20 seconds
# min_uses=2: only cache files accessed 2+ times
# valid=30s: re-validate cache every 30s
20

Implantação com Docker

Nginx no Docker

A imagem oficial do nginx serve /usr/share/nginx/html por padrão e lê a configuração de /etc/nginx. Monte sua configuração e conteúdo como volumes. :ro (somente leitura) impede que o contêiner modifique arquivos do host. nginx -s reload aplica mudanças de configuração sem recriar o contêiner.

nginx
# run the official nginx image
docker run -d --name nginx \
    -p 80:80 -p 443:443 \
    -v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v /var/www/html:/usr/share/nginx/html:ro \
    -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \
    nginx:latest

# interactive shell into the running container
docker exec -it nginx sh

# reload config without restarting the container
docker exec nginx nginx -s reload

# view logs
docker logs nginx
docker logs -f nginx

Docker Compose

Docker Compose orquestra o nginx com seus backends. expose torna uma porta disponível para serviços ligados (não para o host). depends_on garante que o backend inicie primeiro. restart: unless-stopped sobrevive a reinicializações, mas respeita paradas manuais. Monte os logs com permissão de escrita (sem :ro) para que o nginx possa escrevê-los.

nginx
version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./html:/usr/share/nginx/html:ro
      - ./certs:/etc/nginx/certs:ro
      - ./logs:/var/log/nginx
    depends_on:
      - backend
    restart: unless-stopped

  backend:
    image: myapp:latest
    expose:
      - "3000"

Imagem Nginx Personalizada

Assar a configuração na imagem torna as implantações imutáveis e reproduzíveis — sem mounts de volume em runtime. A variante alpine mantém a imagem minúscula (~7MB de base). Ideal para Kubernetes ou CI/CD, onde você quer um artefato autocontido. Reconstrua para atualizar a configuração.

nginx
# Dockerfile
FROM nginx:alpine

# copy custom config
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/

# copy static files
COPY html/ /usr/share/nginx/html/

# copy SSL certificates
COPY certs/ /etc/nginx/certs/

# build and run
# docker build -t mynginx .
# docker run -d -p 80:80 mynginx

# alpine is ~7MB; the image stays small
# bake config in for immutable deployments

Montagens de Volume

Montagens de volume permitem iterar na configuração sem reconstruir a imagem — ideal para desenvolvimento. Montar um diretório é robusto; montar um único arquivo pode quebrar se o arquivo do host não existir (o Docker cria um diretório no lugar). Volumes nomeados persistem entre recriações de contêiner e são gerenciados pelo Docker.

nginx
# mount config and content as volumes (dev workflow)
docker run -d --name nginx \
    -p 80:80 \
    -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
    -v $(pwd)/html:/usr/share/nginx/html:ro \
    -v $(pwd)/logs:/var/log/nginx \
    nginx:alpine

# read-only mounts (:ro) for security
# logs need write access (no :ro)
# use named volumes for persistent data:
#   -v nginx_logs:/var/log/nginx

# IMPORTANT: mounting a single file (nginx.conf) requires
# the file to exist on the host, or Docker creates a directory

Proxy Reverso no Docker

No Docker Compose, os serviços resolvem uns aos outros pelo nome do serviço (app1, app2). O upstream do nginx pode referenciar esses nomes diretamente — sem necessidade de endereços IP. Isso torna o nginx um balanceador de carga poderoso para apps conteinerizados. Use a rede padrão do Compose ou defina uma personalizada para isolamento.

nginx
# nginx as reverse proxy for other containers
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app1
      - app2
    restart: unless-stopped

  app1:
    image: myapp:latest

  app2:
    image: myapp:latest

# nginx.conf:
# upstream apps {
#     server app1:3000;
#     server app2:3000;
# }
# server {
#     listen 80;
#     location / { proxy_pass http://apps; }
# }

Health Check

Health checks permitem que o Docker (e orquestradores como o Swarm) saibam se o nginx está realmente servindo, não apenas rodando. wget --spider verifica o status HTTP sem baixar o corpo. start_period atrasa a primeira checagem para que o nginx inicialize. No Kubernetes, use um probe readiness/liveness em vez do HEALTHCHECK do Docker.

nginx
# Dockerfile with a health check
FROM nginx:alpine

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1

COPY nginx.conf /etc/nginx/nginx.conf

# docker-compose health check
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

# start_period gives nginx time to boot before checking
# a failed health check marks the container unhealthy

Was this helpful?