Arquitetura de configuração do Nginx: nginx.conf, includes e organização de arquivos

Estrutura típica de diretórios e arquivos de configuração

O Nginx lê suas configurações a partir de um arquivo principal (geralmente nginx.conf) e, a partir dele, pode carregar outros arquivos usando include. Essa arquitetura permite separar responsabilidades (globais, HTTP, sites, snippets), reduzir duplicação e facilitar manutenção.

Os caminhos variam por distribuição, mas uma estrutura comum em Linux é:

• /etc/nginx/nginx.conf: arquivo principal (ponto de entrada).
• /etc/nginx/conf.d/*.conf: arquivos adicionais incluídos (muito usado para vhosts simples).
• /etc/nginx/sites-available/: definições de sites (vhosts) disponíveis (padrão em algumas distros).
• /etc/nginx/sites-enabled/: links simbólicos para os sites ativos.
• /etc/nginx/snippets/: trechos reutilizáveis (headers, TLS, padrões de proxy, etc.).
• /var/log/nginx/: logs (access/error) por padrão.

Nem todas as instalações terão sites-available/sites-enabled; muitas usam apenas conf.d. O importante é ter um padrão consistente e previsível.

O papel do nginx.conf e como os include funcionam

O nginx.conf normalmente contém: configurações globais (processos, usuário), o bloco http com defaults para HTTP, e include para carregar arquivos de sites e snippets.

Exemplo típico (simplificado) de /etc/nginx/nginx.conf:

Continue em nosso aplicativo e ...

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

ou continue lendo abaixo...

Baixar o aplicativo

user  nginx;                 # ou www-data, dependendo do sistema (opcional em alguns casos) worker_processes auto; error_log  /var/log/nginx/error.log warn; pid        /run/nginx.pid; events {     worker_connections 1024; } http {     include       /etc/nginx/mime.types;     default_type  application/octet-stream;     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;     sendfile        on;     keepalive_timeout  65;     # Carrega configurações adicionais     include /etc/nginx/conf.d/*.conf;     # Em distros que usam sites-enabled:     include /etc/nginx/sites-enabled/*; }

O include aceita curingas (globs) como *.conf. A ordem de carregamento segue a ordem em que os include aparecem e, dentro do glob, costuma ser ordem lexicográfica (por nome do arquivo). Por isso, naming consistente ajuda a controlar precedência.

Organização recomendada: projetos pequenos e naming consistente

Opção A: usando sites-available e sites-enabled

Boa quando você quer ativar/desativar sites facilmente via links simbólicos.

• /etc/nginx/sites-available/exemplo.com.conf
• /etc/nginx/sites-available/api.exemplo.com.conf
• /etc/nginx/sites-enabled/exemplo.com.conf -> ../sites-available/exemplo.com.conf

Recomendação de naming:

• Um arquivo por domínio/serviço (vhost): exemplo.com.conf, api.exemplo.com.conf, app-interno.conf.
• Evite nomes genéricos como site.conf ou default.conf para projetos reais.
• Se precisar garantir ordem, use prefixos numéricos: 10-exemplo.com.conf, 20-api.exemplo.com.conf. Use com parcimônia.

Opção B: usando apenas conf.d

Boa para setups simples e portáveis. Estrutura:

• /etc/nginx/conf.d/10-exemplo.com.conf
• /etc/nginx/conf.d/20-api.exemplo.com.conf
• /etc/nginx/conf.d/snippets/ (se você preferir manter snippets dentro de conf.d, embora /etc/nginx/snippets seja mais comum)

Separação por domínio/serviço: cada arquivo define um ou mais blocos server relacionados ao mesmo domínio (por exemplo, HTTP e HTTPS do mesmo host) para manter coesão.

Separação por responsabilidade (recomendado)

Mesmo em projetos pequenos, separar por responsabilidade evita repetição e facilita auditoria:

• vhosts: arquivos com blocos server (um por domínio/serviço).
• snippets: blocos reutilizáveis incluídos dentro de server ou location.
• upstreams (quando aplicável): um arquivo para pools de backend (ex.: upstreams.conf) incluído dentro de http.

Passo a passo prático: montando uma organização limpa com snippets

O objetivo é: (1) manter nginx.conf enxuto, (2) ter um arquivo por site/serviço, (3) reutilizar padrões via snippets.

1) Defina includes no nginx.conf

Garanta que o http inclua seus vhosts e snippets (snippets normalmente são incluídos “sob demanda” dentro dos vhosts):

http {     # ... defaults globais do http ...     include /etc/nginx/conf.d/*.conf;     include /etc/nginx/sites-enabled/*; }

Use apenas um dos padrões (conf.d ou sites-enabled) para evitar carregar o mesmo vhost duas vezes.

2) Crie snippets reutilizáveis

Exemplo: headers comuns (segurança e cache variam por projeto; aqui é apenas um modelo).

# /etc/nginx/snippets/common-headers.conf add_header X-Content-Type-Options nosniff always; add_header X-Frame-Options SAMEORIGIN always; add_header Referrer-Policy strict-origin-when-cross-origin always;

Exemplo: parâmetros comuns de proxy (útil quando você faz reverse proxy para apps):

# /etc/nginx/snippets/proxy-common.conf proxy_http_version 1.1; 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; proxy_connect_timeout 5s; proxy_send_timeout 60s; proxy_read_timeout 60s;

3) Crie um vhost por domínio/serviço

Exemplo de arquivo por domínio (HTTP simples), incluindo snippets:

# /etc/nginx/sites-available/exemplo.com.conf server {     listen 80;     server_name exemplo.com www.exemplo.com;     access_log /var/log/nginx/exemplo.com.access.log main;     error_log  /var/log/nginx/exemplo.com.error.log warn;     include /etc/nginx/snippets/common-headers.conf;     location / {         root /var/www/exemplo.com/public;         index index.html;     } }

Exemplo de serviço API como reverse proxy (mantendo padrão de naming e snippets):

# /etc/nginx/sites-available/api.exemplo.com.conf upstream api_backend {     server 127.0.0.1:3000;     # Em balanceamento básico, você adicionaria mais servers aqui } server {     listen 80;     server_name api.exemplo.com;     access_log /var/log/nginx/api.exemplo.com.access.log main;     error_log  /var/log/nginx/api.exemplo.com.error.log warn;     include /etc/nginx/snippets/common-headers.conf;     location / {         include /etc/nginx/snippets/proxy-common.conf;         proxy_pass http://api_backend;     } }

Observação: o bloco upstream deve ficar dentro do contexto http. Como os arquivos de vhost são incluídos dentro de http (via include no nginx.conf), isso funciona.

4) Ative/desative sites (se usar sites-enabled)

Ativar um site normalmente significa criar um link simbólico:

ln -s /etc/nginx/sites-available/exemplo.com.conf /etc/nginx/sites-enabled/exemplo.com.conf ln -s /etc/nginx/sites-available/api.exemplo.com.conf /etc/nginx/sites-enabled/api.exemplo.com.conf

Desativar é remover o link em sites-enabled (sem apagar o arquivo em sites-available).

Hierarquia de contextos: main, http, server, location

A configuração do Nginx é organizada em contextos (blocos). Cada diretiva só pode aparecer em certos contextos. Entender isso evita erros e ajuda a planejar includes.

Como a herança de diretivas funciona

Muitas diretivas “descem” do contexto mais amplo para o mais específico. Em geral:

• Você define um padrão em http (por exemplo, formato de log, timeouts, headers).
• Um server pode herdar esse padrão e sobrescrever o que for específico daquele domínio.
• Um location pode herdar do server e sobrescrever para uma rota específica.

Exemplo prático de herança e sobrescrita com logs:

http {     log_format main '$remote_addr - $request $status';     access_log /var/log/nginx/access.log main;     server {         server_name exemplo.com;         # sobrescreve o access_log apenas para este domínio         access_log /var/log/nginx/exemplo.com.access.log main;         location /admin/ {             # desliga log de acesso só para /admin/             access_log off;         }     } }

Nem toda diretiva herda da mesma forma. Algumas são “acumulativas” (podem ser declaradas múltiplas vezes), outras substituem completamente o valor anterior. Quando estiver em dúvida, verifique a documentação da diretiva e em quais contextos ela é permitida.

Includes e contexto: onde incluir cada coisa

• Arquivos com server { ... } devem ser incluídos dentro de http.
• Arquivos com location { ... } (snippets de location) devem ser incluídos dentro de um server (ou dentro de outro location, quando fizer sentido).
• Arquivos com diretivas globais (ex.: worker_processes) só fazem sentido no main, então não devem ser incluídos dentro de http.

Um erro comum é incluir um snippet com diretivas de http dentro de server (ou vice-versa), gerando mensagens do tipo “directive is not allowed here”.

Padronização e versionamento: práticas recomendadas

Comentários úteis e padronizados

Comentários ajudam manutenção quando explicam o “porquê”, não o óbvio. Um padrão simples por arquivo:

# dominio: exemplo.com # responsavel: time-web # objetivo: site estático institucional # dependencias: /etc/nginx/snippets/common-headers.conf # ultima_alteracao: 2026-01-10

Evite comentários desatualizados; prefira registrar histórico no controle de versão.

Blocos reutilizáveis com snippets

Centralize padrões repetidos em /etc/nginx/snippets:

• common-headers.conf
• proxy-common.conf
• gzip.conf (se você padronizar compressão)
• tls-params.conf (quando houver HTTPS, para evitar duplicação)

Isso reduz divergência entre vhosts e facilita aplicar mudanças globais.

Versionamento (Git) e fluxo de mudanças

Uma prática comum é versionar /etc/nginx (ou um subconjunto) em um repositório Git privado. Sugestões:

• Versione: nginx.conf, vhosts, snippets e arquivos de upstream.
• Não versione segredos em texto puro (chaves privadas, senhas). Se houver TLS, versionar apenas certificados públicos e manter chaves fora do repositório (ou usar um cofre/secret manager).
• Use commits pequenos e descritivos: “Ajusta timeout do proxy para api.exemplo.com”.
• Padronize revisão: toda mudança passa por nginx -t antes de aplicar.

Estratégia de templates e consistência entre ambientes

Para manter dev/homolog/prod parecidos:

• Use os mesmos arquivos base e altere apenas o necessário (por exemplo, endpoints de upstream) via arquivos separados incluídos por ambiente.
• Exemplo: /etc/nginx/conf.d/00-env.conf com variáveis/ajustes do ambiente (quando aplicável) e vhosts iguais.

Mesmo sem automação avançada, a consistência de naming, separação por domínio/serviço e uso de snippets já reduz bastante erros operacionais.