docs: atualiza README.md com guias de instalação nativa e padrões ouro
This commit is contained in:
parent
0d395f42c5
commit
326a3711f0
146
README.md
146
README.md
|
|
@ -1,54 +1,110 @@
|
|||
# Nginx Pathfinder Proxy - Repositório de Configuração
|
||||
# 🛡️ Nginx Pathfinder Proxy
|
||||
|
||||
Este repositório é a fonte da verdade para as configurações do **Pathfinder Proxy**. Ele armazena as definições de domínios, segurança e parâmetros do Nginx e Fail2Ban.
|
||||
Este repositório é o núcleo de inteligência e configuração do **Pathfinder Proxy**, instalado nativamente em **Ubuntu 24.04**. Ele combina performance extrema (HTTP/3, Brotli) com um motor de segurança multicamadas (PSDE + WAF + Fail2Ban).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Repositório de Configuração (Config Management):**
|
||||
> Este repositório **NÃO** gerencia a execução do Docker, build de imagens ou certificados SSL. Ele serve apenas para versionar os arquivos `.conf` que serão baixados no servidor.
|
||||
---
|
||||
|
||||
## 🧠 O que este repositório armazena:
|
||||
* **Gerenciamento de Sites:** Definição de VHosts em `nginx/conf.d/`.
|
||||
* **Snippets Reutilizáveis:** Componentes modulares (SSL, Proxy, WAF) em `nginx/snippets/`.
|
||||
* **Segurança Dinâmica:** Estrutura para `blacklist.conf` (alimentada externamente).
|
||||
* **Fail2Ban:** Regras de jails e filters customizados em `fail2ban/`.
|
||||
## 🏗️ Estrutura de Pastas e Componentes
|
||||
|
||||
## 📂 Estrutura de Pastas
|
||||
```text
|
||||
.
|
||||
├── nginx/
|
||||
│ ├── nginx.conf # Configuração mestre (Global)
|
||||
│ ├── conf.d/ # Arquivos de site (Ex: ferreirareal.com.br.conf)
|
||||
│ ├── snippets/ # Peças modulares (SSL, ModSec, Proxy, Blacklist)
|
||||
│ ├── dynamic/ # Configurações dinâmicas (Blacklist - gerado pelo Fail2Ban)
|
||||
│ └── modsec/ # Regras do WAF
|
||||
└── fail2ban/ # Configurações do sidecar de segurança
|
||||
```
|
||||
A configuração é modular para permitir manutenção rápida e alta disponibilidade.
|
||||
|
||||
## 🛠️ Como Adicionar um Site
|
||||
1. Crie o arquivo em `nginx/conf.d/meusite.conf`.
|
||||
2. Utilize os snippets para manter o padrão e segurança:
|
||||
- `nginx.conf`: O "cérebro" global. Configura workers, logs JSON e carrega os módulos dinâmicos.
|
||||
- `conf.d/`: Contém as definições de cada site (**VHosts**).
|
||||
- `snippets/`: Componentes reutilizáveis (SSL, Proxy, Cache, WAF).
|
||||
- `modsec/`: Configuração do ModSecurity e regras do **OWASP Core Rule Set**.
|
||||
- `dynamic/`: Arquivos modificados em tempo real (ex: `blacklist.conf` pelo Fail2Ban).
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Guia de Snippets (Uso Obrigatório)
|
||||
|
||||
Para garantir o **Padrão Ouro**, todo site deve incluir os snippets básicos:
|
||||
|
||||
1. `include snippets/ssl_params.conf;`: Ativa TLS 1.3, HSTS e anuncia **HTTP/3 (QUIC)**.
|
||||
2. `include snippets/proxy_params.conf;`: Headers padrão para o backend não perder o IP real do cliente.
|
||||
3. `include snippets/modsecurity.conf;`: Ativa o WAF e a Blacklist dinâmica.
|
||||
4. `include snippets/security_actions.conf;`: Toma a decisão final de bloquear (`444`) se o motor PSDE detectar risco alto.
|
||||
5. `include snippets/cache_optimizer.conf;`: Otimiza a entrega de estáticos com cache inteligente.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Motor de Segurança PSDE (Pathfinder Security Engine)
|
||||
|
||||
Diferente de firewalls comuns, o Pathfinder usa o `security_maps.conf` para calcular um **Security Score** em tempo real baseado em:
|
||||
- **Bad Bots:** Crawlers maliciosos e ferramentas de scan.
|
||||
- **Suspicious URIs:** Tentativas de acesso a `.env`, `wp-admin`, `.git`, etc.
|
||||
- **Methods:** Bloqueio de métodos HTTP incomuns em rotas sensíveis.
|
||||
- **Risk Level:** Traduz o score em níveis (Limpo, Suspeito, Crítico) para os logs JSON.
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Padrões Ouro de Configuração
|
||||
|
||||
### 1. Servidor de Arquivos (Performance & Caching)
|
||||
Focado em minimizar uso de CPU e maximizar I/O.
|
||||
```nginx
|
||||
server {
|
||||
listen 443 quic reuseport; # Suporte a HTTP/3
|
||||
listen 443 ssl;
|
||||
server_name meusite.com.br;
|
||||
|
||||
# Certificados (Gerenciados no Servidor/Portainer)
|
||||
ssl_certificate /etc/letsencrypt/live/meusite.com.br/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/meusite.com.br/privkey.pem;
|
||||
|
||||
include snippets/ssl_params.conf;
|
||||
include snippets/proxy_params.conf;
|
||||
include snippets/modsecurity.conf;
|
||||
|
||||
location / {
|
||||
proxy_pass http://ip_interno:porta;
|
||||
}
|
||||
location /files/ {
|
||||
sendfile on;
|
||||
tcp_nopush on;
|
||||
aio on;
|
||||
directio 512;
|
||||
include snippets/cache_optimizer.conf;
|
||||
proxy_cache_valid 200 30d; # Cache longo
|
||||
add_header Content-Disposition "attachment"; # Força download
|
||||
}
|
||||
```
|
||||
3. Commit e Push para a branch `producao`.
|
||||
4. No servidor (Portainer/Docker), faça o Pull das alterações.
|
||||
|
||||
## ⚙️ Notas Operacionais
|
||||
* **Logs e SSL:** As pastas `logs`, `ssl` e `certbot` não são versionadas aqui para segurança. Elas existem apenas no servidor.
|
||||
* **Fail2Ban:** O Fail2Ban lê os logs do Nginx e escreve bloqueios em `nginx/dynamic/blacklist.conf`.
|
||||
### 2. Streaming de Vídeo (Continuidade & Buffer)
|
||||
Evita travamentos e economiza banda com suporte a *Range Requests*.
|
||||
```nginx
|
||||
location /stream/ {
|
||||
proxy_pass http://backend;
|
||||
proxy_set_header Range $http_range;
|
||||
proxy_set_header If-Range $http_if_range;
|
||||
proxy_cache_key "$host$request_uri$http_range";
|
||||
|
||||
# Tuning de Buffer para vídeo
|
||||
proxy_buffers 32 16k;
|
||||
proxy_buffer_size 64k;
|
||||
proxy_read_timeout 300s;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. API Pesada / Traccar (Real-time & WebSocket)
|
||||
Focado em manter conexões persistentes e rate limiting agressivo.
|
||||
```nginx
|
||||
location /api/ {
|
||||
proxy_pass http://backend;
|
||||
|
||||
# Suporte a WebSocket (Vital para Traccar/Mobile)
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# Rate Limit Estreito para APIs
|
||||
limit_req zone=global_limit burst=20 nodelay;
|
||||
|
||||
# Timeouts curtos para liberar recursos
|
||||
proxy_connect_timeout 5s;
|
||||
proxy_send_timeout 30s;
|
||||
proxy_read_timeout 30s;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Como Operar
|
||||
|
||||
### Sincronização
|
||||
As alterações feitas aqui devem ser enviadas para a branch `producao`. No servidor, a sincronização é feita via `git pull` na pasta `/etc/nginx`.
|
||||
|
||||
### Validação
|
||||
Sempre teste a configuração antes do reload:
|
||||
```bash
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Logs
|
||||
Para auditoria de segurança, use o log JSON:
|
||||
`tail -f /var/log/nginx/access_json.log | jq` (necessário instalar o `jq`)
|
||||
|
|
|
|||
Loading…
Reference in New Issue