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.
# /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 nginxDiretivas 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.
# 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.
# 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 nginxContexto 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.
# 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.
# 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.
# 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 stopBlocos 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.
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.
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.
# 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 headerDiretiva 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.
# 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.
# 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.
# 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;
}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.
# 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.
# 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.
# 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.
# 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.
# 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).
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;
}
}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.
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.
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.
# 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_statusTimeouts 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.
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.
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.
# 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;
}
}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.
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 durationAlgoritmos 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.
# 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.
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=2Health 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.
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.
# 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.
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;
}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.
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.
# 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'.
# 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.
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.
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.
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;
}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.
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.cssDiretiva 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.
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 Forbiddentry_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.
# 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.
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.
# 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.
# 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;
}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).
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.
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.
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.
# 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 originalsBrotli
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.
# 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-EncodingGzip 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.
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
}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.
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.
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.
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.
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.
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, HITCache 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.
# 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 cacheRewrite 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.
# 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 redirectsDiretiva 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.
# 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 redirectFlags 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.
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 insteadCapturas 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.
# 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 readabilityDiretiva 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.
# 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 chainsDiretiva 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'.
# "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;
}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.
# 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.
# 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.
# 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.
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.
# 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.
# 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;
}
}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.
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.
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.
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.
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.
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 outtry_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.
# 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;
}
}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.
# 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.
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.
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.
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 aboveMú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.
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).
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 backendHeaders 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.
# 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.
# 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).
# 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.
# 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 supportReferrer-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.
# 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.
# 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;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.
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 defaultDeny 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.
# 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.
# 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.
# 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.
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.
# 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;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.
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.
# /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/.htpasswdAuth 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.
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.
# 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 authMó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.
# 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 -> errorAuth 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.
# 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 requestLogs
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.
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.
# 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.
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.
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.
# 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 thingDesativar 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.
# 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;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.
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.
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 immediatelylimit_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.
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.
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 rateLimite 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.
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.
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;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.
# 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.
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 65535keepalive_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'.
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.
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'.
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.
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 30sImplantaçã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.
# 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 nginxDocker 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.
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.
# 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 deploymentsMontagens 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.
# 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 directoryProxy 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 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.
# 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 unhealthySnippets de Nginx relacionados
Copy-paste ready code for common tasks.
Server Block
Configure a virtual host with root, index, and try_files.
Reverse Proxy
Forward requests to upstream HTTP services.
Load Balancing
Distribute traffic across multiple upstream servers.
HTTPS & SSL
Terminate TLS with certificates and HTTP/2.
Location Rules
Match request URIs with prefix, regex, and exact locations.
Rewrite & Redirect
Rewrite URIs and issue HTTP redirects.
Gzip Compression
Compress text responses to reduce bandwidth.
Proxy Caching
Cache upstream responses to reduce backend load.
Was this helpful?