5.1 KiB

Raw Blame History

NGINX Pathfinder Proxy - Documentação Técnica

Visão Geral

Projeto de infraestrutura para Proxy Reverso de Alta Disponibilidade, utilizando Containers Docker para modularidade e fácil manutenção.

Arquitetura de Containers

O projeto roda sobre 3 serviços orquestrados via docker-compose.yml:

Serviço	Imagem	Porta Exposta	Função
modsecurity	`owasp/modsecurity-crs:nginx-alpine`	`80`, `443`	Frontend (WAF). Recebe todo o tráfego da internet, filtra ataques (SQLi, XSS) e encaminha requisições limpas para o Proxy.
nginx-proxy	`alpine` (Custom Build)	`8080` (Interna)	Backend Proxy. Gerencia vhosts, terminação SSL, cache, compressão Brotli e roteamento para as aplicações finais.
fail2ban	`crazymax/fail2ban`	-	Watchdog. Lê logs compartilhados dos dois containers acima e bane IPs maliciosos diretamente no host (via iptables).

Automação SSL

O sistema possui um mecanismo de auto-cura para certificados SSL.

Componentes

Certbot: Instalado dentro do container nginx-proxy.
Volumes:
- ssl/: Onde ficam os arquivos .crt e .key usados pelo NGINX.
- certbot/: Onde o Certbot guarda os arquivos originais do Let's Encrypt.
Scripts:
- scripts/inject_acme.sh: Varre todos os arquivos em conf.d/ e injeta o snippet de validação ACME (.well-known) se não existir.
- scripts/renew_ssl.sh:
  1. Verifica a data de expiração de cada certificado ativo.
  2. Se faltar 3 dias ou menos, dispara certbot renew.
  3. Copia os novos arquivos gerados para a pasta ssl/.
  4. Recarrega o NGINX.

Agendamento

Cron: Configurado no pre-flight.sh para rodar todos os dias às 01:00 AM.
Startup: A verificação também roda a cada reinício do container.

Estrutura de Arquivos

.
├── conf.d/              # Configurações de sites (VHosts)
├── snippets/            # Trechos reutilizáveis
│   ├── acme_challenge.conf # Snippet para validação Let's Encrypt
│   ├── internal_networks.conf # IPs permitidos (VPN/Local)
│   └── ...
├── scripts/             # Scripts de automação
│   ├── pre-flight.sh    # Entrypoint (DNS Check + Cron Setup)
│   ├── inject_acme.sh   # Injetor de config ACME
│   └── renew_ssl.sh     # Lógica de renovação
├── ssl/                 # Certificados em uso
├── fail2ban/            # Configs do Fail2ban
│   ├── jail.d/          # Definição das prisões
│   └── filter.d/        # Regex de detecção
├── .gemini/             # Documentação do projeto
└── docker-compose.yml   # Orquestração

Módulos Especiais

1. Brotli & Headers More

O container nginx-proxy é construído manualmente (Dockerfile) para incluir módulos que não vêm por padrão no Alpine:

nginx-mod-http-brotli
nginx-mod-http-headers-more

2. ModSecurity (WAF)

Rodar o WAF em container separado (modsecurity) evita a necessidade de compilar o ModSecurity no NGINX principal.

Arquitetura Customizada:

Injeção de Template: Um arquivo modsec.conf.template local é montado durante o boot para contornar limitações de permissão do container oficial. Ele instrui o NGINX a carregar regras customizadas.
Regras Modulares: Localizadas em modsec_rules/, divididas por aplicação (gitea-rule-exceptions.conf, nextcloud...).
Global: global-exceptions.conf define apenas a whitelist de rede.
Bypass de Emergência: Se o WAF falhar, altere as portas no docker-compose.yml para expor o nginx-proxy diretamente.

Fluxo de Deploy Atualizado

graph TD
    Start[Deploy] --> DetectIP[Detectar IP Público]
    DetectIP --> Build[Docker Build (NGINX + Certbot)]
    Build --> Up[Docker Compose Up]
    Up --> PreFlight[Pre-Flight Script]
    
    PreFlight --> DNSCheck[Validar DNS dos Domínios]
    DNSCheck --> CronSetup[Configurar Cron Job]
    CronSetup --> SSLCheck[Verificar Validade SSL]
    
    SSLCheck -- Vence > 3 dias --> StartNginx[Iniciar NGINX]
    SSLCheck -- Vence <= 3 dias --> Renew[Rodar renew_ssl.sh]
    Renew --> StartNginx

Comandos Operacionais

Verificar status dos serviços:

docker compose ps

Verificar validade dos SSL (Log):

docker compose logs nginx-proxy | grep "SSL"

Forçar renovação SSL manualmente:

docker compose exec nginx-proxy /scripts/renew_ssl.sh

Reload Zero-Downtime (Blue-Green Logic): Este comando valida a configuração e executa um reload gracioso (nginx -s reload), onde novos workers assumem as novas configurações enquanto os antigos terminam as requisições correntes.

./scripts/reload.sh   # Linux
./scripts/reload.ps1  # Windows PowerShell

Banir um IP manualmente:

docker compose exec fail2ban fail2ban-client set nginx-badbots banip 1.2.3.4

Adicionar novo site:

Criar conf.d/novo-site.conf
docker compose restart nginx-proxy
O script de startup irá validar o DNS e injetar o suporte ACME automaticamente.

5.1 KiB Raw Blame History