Dominando a Configuração do Nginx: Diretivas Essenciais Explicadas

A configuração do Nginx fica muito mais fácil quando você entende onde cada diretiva pode ser usada. Se sua regra proxy_pass, root ou try_files estiver no contexto errado, o Nginx pode rejeitar a configuração ou tratar as requisições de forma inesperada.

Este guia aborda as diretivas essenciais que você usará ao servir arquivos estáticos, fazer proxy reverso de uma aplicação, habilitar compressão e recarregar alterações com segurança.

A Estrutura de Configuração do Nginx

Os arquivos de configuração do Nginx geralmente ficam em /etc/nginx/ em pacotes Linux. O arquivo principal é comumente /etc/nginx/nginx.conf, e ele frequentemente inclui arquivos de /etc/nginx/conf.d/. Pacotes Debian e Ubuntu costumam usar sites-available/ e sites-enabled/; muitas outras distribuições não.

A configuração é hierárquica, organizada em blocos ou diretivas. Blocos principais incluem:

events: Configura o processamento de conexões.
http: Contém configurações gerais de HTTP e servidores virtuais.
server: Define um servidor virtual para uma porta e nome de host.
location: Escolhe como tratar URIs de requisição correspondentes.

Diretivas são pares chave-valor que controlam o comportamento do Nginx. Elas podem ser globais ou aninhadas dentro de blocos.

Diretivas Essenciais Explicadas

O Bloco `http`

O bloco http engloba configurações que se aplicam globalmente ao tráfego HTTP. É aqui que você define configurações comuns para seu servidor web.

include: Esta diretiva permite incluir outros arquivos de configuração, ajudando a modularizar sua configuração. É comumente usada para separar configurações de diferentes sites ou aplicações.
```
http {
    include       mime.types;
    default_type  application/octet-stream;

    # Incluir configurações de servidor do diretório conf.d
    include /etc/nginx/conf.d/*.conf;
}
```

log_format: Define formatos de log personalizados para logs de acesso e erro do Nginx. Isso é essencial para logging e análise detalhados.

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

    access_log  /var/log/nginx/access.log  main;
    error_log   /var/log/nginx/error.log;
    # ... outras diretivas http
}

sendfile: Otimiza transferências de arquivos permitindo que o kernel envie arquivos diretamente do disco para o cliente, ignorando o espaço do usuário. Defina como on para desempenho.
```
http {
    sendfile        on;
    # ...
}
```
tcp_nopush e tcp_nodelay: Ajustam o comportamento TCP para respostas HTTP. tcp_nopush é comumente usado com sendfile para otimizar o envio de pacotes, enquanto tcp_nodelay ajuda a evitar atrasos em conexões keepalive.
```
http {
    tcp_nopush     on;
    tcp_nodelay    on;
    # ...
}
```

O Bloco `server`

Cada bloco server define um servidor virtual, permitindo que o Nginx trate requisições para diferentes nomes de domínio ou endereços IP no mesmo servidor.

listen: Especifica o endereço IP e/ou porta na qual o servidor ouvirá por conexões de entrada.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    # ...
}

server_name: Define os nomes do servidor. O Nginx usa isso para corresponder ao cabeçalho Host da requisição de entrada.
```
server {
    listen 80;
    server_name mydomain.org *.mydomain.org;
    # ...
}
```
root: Define a raiz do documento. O Nginx constrói o caminho do arquivo anexando a URI da requisição a este diretório.
```
server {
    listen 80;
    server_name localhost;
    root /var/www/html;
    index index.html index.htm;
    # ...
}
```
index: Especifica o arquivo padrão a ser servido quando um diretório é solicitado.
```
server {
    # ...
    index index.html index.htm default.html;
    # ...
}
```

error_page: Define páginas de erro personalizadas para códigos de status HTTP específicos.

server {
    # ...
    error_page 404 /404.html;
    location = /404.html {
        root /usr/share/nginx/html;
        internal;
    }
    # ...
}

O Bloco `location`

O bloco location é usado para corresponder URIs de requisição e determinar como o Nginx deve processá-las. É aqui que você configura o roteamento para diferentes partes da sua aplicação.

Correspondência de URIs: Locations podem corresponder a strings exatas, prefixos ou expressões regulares. Correspondências exatas usam =, expressões regulares usam ~ ou ~*, e prefixos simples correspondem pelo prefixo da URI.

location /images/ {
    # Diretivas para requisições começando com /images/
}

location = /favicon.ico {
    # Correspondência exata para /favicon.ico
}

location ~ \.php$ {
    # Correspondência regex para arquivos terminados em .php
}

proxy_pass: Encaminha requisições para um servidor upstream. Cuidado com a barra no final, pois ela altera como o Nginx reescreve o prefixo correspondido.

location /api/ {
    proxy_pass http://backend-service:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

alias: Mapeia uma location para um caminho no sistema de arquivos sem anexar a URI original completa. É frequentemente usado para ativos estáticos armazenados fora da raiz principal do documento.
```
location /static/ {
    alias /var/www/app/assets/;
}
```
Com alias, inclua a barra no final tanto na location quanto no caminho para mapeamentos de diretório. alias substitui o prefixo da location correspondida pelo caminho do alias, enquanto root anexa a URI ao caminho raiz.
try_files: Verifica a existência de arquivos em uma ordem especificada e serve o primeiro encontrado, ou retorna um código/URI especificado.
```
location / {
    try_files $uri $uri/ /index.html;
}
```
Isso é comum para aplicações de página única. Se um arquivo ou diretório solicitado não existir, o Nginx serve index.html para que o roteador do lado do cliente possa lidar com o caminho.

Diretivas de Segurança e Desempenho

ssl_certificate e ssl_certificate_key: Essenciais para configurar HTTPS. Essas diretivas apontam para seus arquivos de certificado SSL e chave privada.

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

    ssl_certificate /etc/letsencrypt/live/secure.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/secure.example.com/privkey.pem;

    # ... outras configurações SSL
}

gzip: Ativa ou desativa a compressão gzip para tipos de resposta selecionados. Frequentemente reduz o tamanho da transferência para ativos de texto, mas evite comprimir arquivos já comprimidos, como a maioria das imagens.

http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    # ...
}

expires: Controla cabeçalhos de cache para ativos estáticos. Use tempos de cache longos para arquivos com fingerprint, e tempos mais curtos para arquivos que mantêm a mesma URL entre implantações.
```
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 30d;
    add_header Cache-Control "public";
}
```

Comandos Comuns do Nginx

Para gerenciar o Nginx e aplicar alterações de configuração, você usará frequentemente estes comandos:

Testar configuração: Verifica erros de sintaxe nos arquivos de configuração do Nginx.
```
sudo nginx -t
```
Recarregar configuração: Recarrega graciosamente a configuração do Nginx sem interromper conexões ativas.
```
sudo systemctl reload nginx
# ou
sudo service nginx reload
```

Reiniciar Nginx: Para e depois inicia o serviço Nginx.

sudo systemctl restart nginx
# ou
sudo service nginx restart

Verificar status: Mostra o status atual do serviço Nginx.

sudo systemctl status nginx
# ou
sudo service nginx status

Um Exemplo Mínimo Funcional

Este exemplo serve uma aplicação de página única do disco e faz proxy de requisições de API para um servidor de aplicação:

server {
    listen 80;
    server_name example.com;

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

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Execute sudo nginx -t antes de cada recarregamento. Esse único hábito detecta erros de sintaxe antes que se transformem em indisponibilidade.

Conclusão

A maioria dos erros com o Nginx vem do contexto e do tratamento de caminhos. Coloque configurações gerais de HTTP em http, regras específicas de host em server, roteamento de URI em location, e teste cada alteração com nginx -t antes de recarregar.