docs: Update README.md (pt-BR) and Tech Specs

This commit is contained in:
João Pedro 2026-01-22 13:22:58 -03:00
parent cd1a164114
commit 058d1a22dd
2 changed files with 208 additions and 177 deletions

View File

@ -1,177 +1,122 @@
# NGINX Pathfinder Proxy - Documentação da Estrutura # NGINX Pathfinder Proxy - Documentação Técnica
## Visão Geral ## Visão Geral
Este projeto é um proxy reverso NGINX containerizado com suporte a: Projeto de infraestrutura para Proxy Reverso de Alta Disponibilidade, utilizando Containers Docker para modularidade e fácil manutenção.
- **HTTP/3 (QUIC)** - Protocolo moderno para melhor performance
- **Brotli** - Compressão avançada para menor uso de banda ## Arquitetura de Containers
- **High Availability** - Restart automático e cache stale
- **Validação Automática** - Verificação de DNS e SSL no startup 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). |
--- ---
## Estrutura de Pastas ## Automação SSL
O sistema possui um mecanismo de **auto-cura** para certificados SSL.
### Componentes
1. **Certbot**: Instalado dentro do container `nginx-proxy`.
2. **Volumes**:
- `ssl/`: Onde ficam os arquivos `.crt` e `.key` usados pelo NGINX.
- `certbot/`: Onde o Certbot guarda os arquivos originais do Let's Encrypt.
3. **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 (carregadas automaticamente) ├── conf.d/ # Configurações de sites (VHosts)
├── snippets/ # Trechos reutilizáveis de configuração ├── snippets/ # Trechos reutilizáveis
├── scripts/ # Scripts auxiliares (pre-flight.sh) │ ├── acme_challenge.conf # Snippet para validação Let's Encrypt
├── ssl/ # Certificados SSL/TLS │ ├── internal_networks.conf # IPs permitidos (VPN/Local)
├── legacy/ # Arquivos antigos do servidor original │ └── ...
├── 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 ├── .gemini/ # Documentação do projeto
├── Dockerfile # Build customizado do NGINX └── docker-compose.yml # Orquestração
├── docker-compose.yml # Orquestração do container
├── nginx.conf # Configuração principal do NGINX
└── deploy.sh # Script de deploy automatizado
``` ```
--- ---
## Arquivos Principais ## Módulos Especiais
### `Dockerfile` ### 1. Brotli & Headers More
Constrói uma imagem NGINX customizada baseada em Alpine Linux com: O container `nginx-proxy` é construído manualmente (`Dockerfile`) para incluir módulos que não vêm por padrão no Alpine:
- Módulo Brotli (compressão) - `nginx-mod-http-brotli`
- Módulo headers_more (manipulação de headers) - `nginx-mod-http-headers-more`
- Ferramentas de diagnóstico (dig, openssl, curl)
### `docker-compose.yml` ### 2. ModSecurity (WAF)
Orquestra o container com: Rodar o WAF em container separado (`modsecurity`) evita a necessidade de compilar o ModSecurity no NGINX principal, facilitando atualizações e isolando falhas. Se o WAF falhar, o Proxy pode ser exposto diretamente mudando as portas no `docker-compose.yml` (Bypass de emergência).
- **Portas**: 80 (HTTP), 443 (HTTPS), 443/udp (HTTP/3)
- **Volumes**: conf.d, ssl, snippets, cache, logs
- **Restart**: always (alta disponibilidade)
- **Variável**: HOST_PUBLIC_IP (injetada pelo deploy.sh)
### `nginx.conf`
Configuração principal que:
- Carrega os módulos (Brotli, headers_more)
- Inclui snippets do `/etc/nginx/snippets/`
- Inclui sites do `/etc/nginx/conf.d/`
### `deploy.sh`
Script de deploy que:
1. Detecta o IP público do servidor
2. Grava no `.env`
3. Build da imagem Docker
4. Testa configuração com `nginx -t`
5. Inicia o container
--- ---
## Pasta `snippets/` ## Fluxo de Deploy Atualizado
Contém configurações reutilizáveis incluídas no `nginx.conf`:
| Arquivo | Função |
|---------|--------|
| `rate_limit.conf` | Define zonas de rate limiting |
| `security_maps.conf` | Maps para detecção de bots e IPs internos |
| `log_formats.conf` | Formato JSON detalhado para logs |
| `cache_zones.conf` | Define todas as zonas de cache |
| `custom_errors.conf` | Páginas de erro customizadas |
---
## Pasta `conf.d/`
Contém configurações individuais de cada site/sistema. Cada arquivo `.conf` representa um virtual host.
**Padrão de nomenclatura**: `dominio.conf` (ex: `itguys.com.br.conf`)
**Estrutura típica de um site**:
```nginx
upstream nome_backend {
server IP:PORTA;
}
server {
listen 80;
server_name dominio.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name dominio.com;
ssl_certificate /etc/letsencrypt/live/dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/dominio.com/privkey.pem;
proxy_cache STATIC;
proxy_cache_use_stale error timeout;
location / {
proxy_pass http://nome_backend;
}
}
```
---
## Pasta `scripts/`
### `pre-flight.sh`
Script executado ANTES do NGINX iniciar. Valida:
- Se `HOST_PUBLIC_IP` está definida
- Se os domínios configurados apontam para o IP correto
- Logs de warning se houver inconsistências
---
## Pasta `legacy/`
Contém arquivos do servidor original (synced via proxy-sinc). **Não são usados diretamente** - servem como referência.
---
## Fluxo de Deploy
```mermaid ```mermaid
graph LR graph TD
A[deploy.sh] --> B[Detecta IP] Start[Deploy] --> DetectIP[Detectar IP Público]
B --> C[Gera .env] DetectIP --> Build[Docker Build (NGINX + Certbot)]
C --> D[Docker Build] Build --> Up[Docker Compose Up]
D --> E[nginx -t] Up --> PreFlight[Pre-Flight Script]
E --> F[Docker Up]
F --> G[pre-flight.sh] PreFlight --> DNSCheck[Validar DNS dos Domínios]
G --> H[NGINX Start] 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
``` ```
--- ---
## Variáveis de Ambiente ## Comandos Operacionais
| Variável | Descrição |
|----------|-----------|
| `HOST_PUBLIC_IP` | IP público do servidor (detectado automaticamente) |
---
## Comandos Úteis
**Verificar status dos serviços:**
```bash ```bash
# Deploy completo docker compose ps
./deploy.sh
# Rebuild após alterações
docker compose build && docker compose up -d
# Testar configuração
docker compose run --rm nginx-proxy nginx -t
# Ver logs
docker compose logs -f
# Recarregar configuração sem restart
docker compose exec nginx-proxy nginx -s reload
``` ```
--- **Verificar validade dos SSL (Log):**
```bash
docker compose logs nginx-proxy | grep "SSL"
```
## Notas Importantes **Forçar renovação SSL manualmente:**
```bash
docker compose exec nginx-proxy /scripts/renew_ssl.sh
```
1. **SSL**: Os certificados devem estar em `/etc/letsencrypt/` no host ou montados via volume **Banir um IP manualmente:**
2. **ModSecurity**: Alguns sites usam WAF que requer módulo adicional (não incluído por padrão) ```bash
3. **HTTP/2**: O formato antigo `listen 443 ssl http2` está deprecated, usar `http2 on;` separado docker compose exec fail2ban fail2ban-client set nginx-badbots banip 1.2.3.4
```
**Adicionar novo site:**
1. Criar `conf.d/novo-site.conf`
2. `docker compose restart nginx-proxy`
3. O script de startup irá validar o DNS e injetar o suporte ACME automaticamente.

148
README.md
View File

@ -1,61 +1,147 @@
# Serviço de Sincronização de Configurações - Proxy-Sinc # NGINX Pathfinder Proxy
Este repositório contém as configurações e os scripts de automação para o serviço `proxy-sinc`, desenhado para automatizar o controlo de versões de ficheiros de configuração de servidores Linux para um repositório Git (Gitea). Solução moderna de Proxy Reverso containerizado, construída com NGINX, ModSecurity WAF e automação de SSL.
O objetivo é criar um sistema robusto, auto-documentado e fácil de gerir para o backup e o histórico de alterações de configurações críticas como as do Nginx e do Fail2ban. ## 🚀 Funcionalidades
## Funcionalidades Principais Implementadas pelo Instalador ### 🛡️ Segurança em Primeiro Lugar
- **ModSecurity WAF**: Conjunto de Regras OWASP (CRS) integrado rodando como proxy sidecar/frontend.
- **Fail2ban**: Serviço "cão de guarda" que bane IPs com comportamento suspeito (bots ruins, excesso de erros 4xx/5xx).
- **Mapas de Segurança**: Bloqueio automatizado de User-Agents maliciosos e restrições de rede interna.
### Gestão de Dependências ### ⚡ Performance
- **HTTP/3 (QUIC)**: Habilitado para conexões modernas de baixa latência.
- **Compressão Brotli**: Melhores taxas de compressão que o Gzip padrão.
- **Headers More**: Manipulação avançada de cabeçalhos para respostas limpas.
* Verifica e instala automaticamente as dependências necessárias (`git`, `rsync`) usando `apt`. ### 🔒 SSL Automatizado
- **Renovação Zero-Touch**: O Certbot integrado verifica a validade diariamente.
- **Auto-Renovação**: Renova automaticamente certificados próximos do vencimento (<= 3 dias).
- **Injeção Inteligente**: Injeta automaticamente os snippets de desafio ACME nas configurações dos sites.
### Configuração Interativa e Segura ---
* Pede ao utilizador a URL do repositório, o nome de utilizador do Gitea e um Token de Acesso (que fica oculto durante a digitação) para a autenticação. ## 🛠️ Como Trabalhar neste Repositório
* A URL do repositório é reconfigurada para incluir as credenciais, permitindo que as operações `git` futuras (como o `git push`) sejam executadas de forma não-interativa. ### Pré-requisitos
- Docker & Docker Compose instalados
- Acesso à internet (para baixar imagens e validar SSL)
### Identidade de Commit Automática ### 1. Implantar o Servidor (Deploy)
Para iniciar toda a infraestrutura:
```bash
./deploy.sh
```
*Este script detecta seu IP público, configura o ambiente e sobe os containers.*
* O nome do autor dos commits é automaticamente definido como o hostname completo do servidor (ex: `srvproxy001.itguys.com.br`). ### 2. Adicionar um Novo Site
Todas as configurações de sites ficam na pasta `conf.d/`.
* O email do autor é gerado automaticamente a partir do hostname (ex: `srvproxy001@itguys.com.br`). 1. **Crie o arquivo de configuração**:
Crie um arquivo `.conf` em `conf.d/` (ex: `meusite.com.br.conf`). Use um dos arquivos existentes como modelo.
**Modelo Básico (com SSL):**
```nginx
# Backend (para onde vai o tráfego)
upstream meu_backend {
server 192.168.1.10:8080;
}
### Gestão Inteligente de SSL # Redirecionamento HTTP -> HTTPS
server {
listen 80;
server_name meusite.com.br;
include /etc/nginx/snippets/acme_challenge.conf; # Importante para SSL
return 301 https://$host$request_uri;
}
* O script testa automaticamente a conexão com o Gitea. Se detetar um problema de certificado SSL (comum em ambientes internos), ele configura o repositório local para ignorar a verificação SSL, garantindo que a sincronização funcione. # Bloco HTTPS
server {
listen 443 ssl;
http2 on;
server_name meusite.com.br;
### Registo de Deploy ssl_certificate /etc/nginx/ssl/meusite.com.br.crt;
ssl_certificate_key /etc/nginx/ssl/meusite.com.br.key;
* Na primeira instalação num novo servidor, o script cria um ficheiro de registo (`_deployment_logs/hostname.md`) no repositório, documentando quem (utilizador do Gitea) instalou o serviço e quando, criando uma trilha de auditoria. include /etc/nginx/snippets/ssl_params.conf;
### Instalação como Serviço `systemd` location / {
proxy_pass http://meu_backend;
include /etc/nginx/includes/proxy_backend.conf;
}
}
```
* Gera e instala um serviço `systemd` (`proxy-sinc.service`) e um `timer` (`proxy-sinc.timer`). 2. **Aplique as alterações**:
```bash
docker compose restart nginx-proxy
```
*No reinício, o script de pre-flight validará o DNS e injetará configurações de SSL necessárias.*
* Esta abordagem é superior ao `cron` pois integra-se perfeitamente com o sistema de logs `journald`, permitindo uma gestão fácil com `systemctl status`, `start`, `stop`, etc. ### 3. Modificar Configurações Globais
As configurações globais são modularizadas na pasta `snippets/`.
* O timer está configurado para executar o script de sincronização **a cada minuto**. - **Rate Limiting**: Edite `snippets/rate_limit.conf` para ajustar os limites de requisições por segundo.
- **Bloqueio de Bots**: Edite `snippets/security_maps.conf` para adicionar novos User-Agents à lista negra.
- **Cache**: Edite `snippets/cache_zones.conf` para definir novas zonas ou tempos de cache.
### Sincronização Dinâmica de Ficheiros ### 4. Gerenciar Certificados SSL
O sistema gerencia isso automaticamente, mas você pode intervir manualmente se necessário.
* O script principal de sincronização (`commit_configs.sh`) agora lê os caminhos a serem versionados a partir de um ficheiro de configuração central (`/etc/proxy-sinc/paths.conf`). - **Verificar Validade**:
Verifique os logs do startup para ver o status de todos os domínios:
```bash
docker compose logs nginx-proxy | grep "SSL"
```
* Isto permite que os administradores adicionem ou removam ficheiros e pastas para sincronização no futuro, simplesmente editando este ficheiro de texto, sem precisar de alterar o script. - **Forçar Renovação**:
Se precisar renovar um certificado imediatamente:
```bash
docker compose exec nginx-proxy /scripts/renew_ssl.sh
```
### Auto-Versionamento ### 5. Monitorar e Debugar
* O script `commit_configs.sh` foi desenhado para se incluir a si mesmo e a todos os seus ficheiros de configuração e de serviço (`.service`, `.timer`, `man page`, `paths.conf`) no repositório Git. Desta forma, qualquer alteração na própria automação também é versionada. - **Verificar Status dos Containers**:
```bash
docker compose ps
```
### Funcionalidade de Auto-Atualização - **Ver Logs em Tempo Real**:
```bash
docker compose logs -f
```
* Instala um novo comando no sistema, `proxy-sinc-update`. - **Verificar se o WAF (ModSecurity) bloqueou algo**:
```bash
docker compose logs modsecurity | grep "Access denied"
```
* Quando executado, este comando baixa a versão mais recente do `setup.sh` a partir de uma URL pré-definida no repositório Gitea e executa-a, permitindo uma atualização fácil e centralizada de toda a automação. - **Verificar Banimentos do Fail2ban**:
```bash
docker compose exec fail2ban fail2ban-client status nginx-badbots
```
### Documentação Integrada (`man page`) ---
* Gera e instala uma página de manual (`man proxy-sinc`) no sistema. ## 🏗️ Visão Geral da Stack
* O manual explica o que o serviço faz, como o gerir, como o atualizar e, o mais importante, como adicionar novos caminhos de ficheiros para serem sincronizados, tornando a ferramenta fácil de usar para qualquer membro da equipa no futuro. ```mermaid
graph LR
Internet((Internet)) --> WAF[Container ModSecurity]
WAF -- Tráfego Limpo --> Proxy[Container NGINX Proxy]
Proxy --> Backend1[App 1]
Proxy --> Backend2[App 2]
Logs[Logs Compartilhados]
WAF -.-> Logs
Proxy -.-> Logs
F2B[Container Fail2ban]
F2B -- Lê --> Logs
F2B -- Bane IP --> WAF
```
---
*Mantido por IT Guys*