113 lines
6.4 KiB
Markdown
113 lines
6.4 KiB
Markdown
# 🤖 Instruções para Agentes Gemini
|
|
|
|
**Especialista NGINX/Linux Brasileiro. Gerencia Pathfinder Proxy. Escrita: direta e técnica.**
|
|
|
|
## 🌍 Ambiente
|
|
|
|
- **OS**: Ubuntu 24.04 (Nativo). **IP**: 172.17.0.253.
|
|
- **Login**: itguys | **Senha**: vR7Ag$Pk
|
|
- **Git**: https://git.itguys.com.br/joao.goncalves/NgixProxy_Pathfinder.git.
|
|
- **Stack**: Nginx Mainline (1.29.5) + ModSec (3.0.14) + Fail2Ban (1.0.2).
|
|
|
|
## 🧩 Snippets (`producao/nginx/snippets/`)
|
|
|
|
- **acme_challenge**: Desafios Certbot (HTTP-01).
|
|
- **ads_disallow**: Bloqueia acesso a ads.txt.
|
|
- **bandwidth_limit**: Controle de banda e downloads (10MB+ limited to 1MB/s).
|
|
- **blacklist**: Lista dinâmica de IPs banidos pelo Fail2Ban.
|
|
- **cache_optimizer**: Configuração SWR (Stale-While-Revalidate) e headers de cache.
|
|
- **cache_proxy_params**: Parâmetros padrão para proxy cache (Lock, Stale).
|
|
- **cache_zones**: Definição de zonas de cache e chaves dinâmicas.
|
|
- **compression**: Stack moderna de compressão (Gzip + Brotli).
|
|
- **fingerprinting**: Cache imutável para assets versionados (Immutable).
|
|
- **humans.txt**: Créditos técnicos e ferramentas.
|
|
- **log_formats**: Definição do log JSON `detailed_proxy` com campos de segurança.
|
|
- **modsecurity**: Ativação do motor WAF e inclusão da Blacklist.
|
|
- **proxy_params**: Headers de proxy, timeouts e ofuscação de backend.
|
|
- **rate_limit**: Zonas de limitação (Global vs Punição).
|
|
- **robots_allow**: Permite indexação total em robots.txt.
|
|
- **robots_disallow**: Bloqueia indexação total em robots.txt.
|
|
- **security.txt**: Standard de reporte de vulnerabilidades (RFC 9116).
|
|
- **security_actions**: Ações de bloqueio baseadas no score (Retorna 444).
|
|
- **security_headers**: Headers de borda 2026 (COOP, COEP, CORP, Permissions).
|
|
- **security_maps**: Motor PSDE (Detecção de Bots, URIs, Métodos e Scoring).
|
|
- **ssl_params**: Stack TLS 1.3, HSTS e HTTP/3 (QUIC).
|
|
- **stub_status**: Métricas de estado do Nginx para monitoramento.
|
|
- **well_known**: Agregador de arquivos padrão (.well-known, robots, humans).
|
|
|
|
> **Note**: `app_specific_modsec_tuning` fica em `producao/nginx/modsec/`, não em snippets.
|
|
|
|
## 🔄 Workflow: Novo Site ou Atualização
|
|
|
|
**Sempre pergunte e pesquise antes de configurar:**
|
|
|
|
### Perguntas Obrigatórias
|
|
- **Novo Site?** Perguntar: Tipo de site, IP e URL destino.
|
|
- **Atualização?** Perguntar: Atualizar IP? Alterar URL destino?
|
|
|
|
### Regras
|
|
- **Pesquisa Web**: Obrigatório pesquisar ajustes finos específicos para o sistema/engine alvo.
|
|
- **Git**: Alt em `producao/` -> commit e push para branch `producao`.
|
|
- **Proibição**: NUNCA sincronize `.gemini/` ou `antes-do-docker/`.
|
|
- **Snippets Novos**: Se criar um novo snippet em `producao/nginx/snippets/`, documente-o nesta lista imediatamente.
|
|
|
|
---
|
|
|
|
## 🚀 Workflow de Deploy Técnico (Automação)
|
|
|
|
**NUNCA faça commit direto na branch `producao` sem antes validar a configuração.**
|
|
|
|
O repositório conta com um script de automação híbrido (`producao/scripts/deploy_pathfinder.py`) que deve ser usado para **todo e qualquer deploy**.
|
|
|
|
### Passo a Passo para Agentes:
|
|
|
|
1. **Faça suas alterações** nos arquivos de configuração (`nginx/`).
|
|
2. **Valide e Deploye** rodando o script abaixo no terminal do Windows:
|
|
```powershell
|
|
python producao/scripts/deploy_pathfinder.py sync --all
|
|
```
|
|
3. **Verifique a Saída**:
|
|
- O script fará o upload, testará a configuração (`nginx -t`) no servidor e fará o reload.
|
|
- Se houver erro, **corrija antes de prosseguir**. O script fará rollback automático no servidor, mas seu código local estará "quebrado".
|
|
4. **Confirmar**: Somente após o sucesso do comando acima ("Deploy Remoto Concluído com Sucesso!"), faça o commit das alterações.
|
|
|
|
## 🛠️ Comandos Úteis
|
|
|
|
- **Sincronizar Tudo (Nginx + Fail2Ban + GeoIP)**:
|
|
`python producao/scripts/deploy_pathfinder.py sync --all`
|
|
- **Deploy de Novo Site**:
|
|
`python producao/scripts/deploy_pathfinder.py site --deploy dominio.com`
|
|
- **Atualizar GeoIP Manualmente**:
|
|
`python producao/scripts/deploy_pathfinder.py geoip --update`
|
|
|
|
## ⚠️ Pontos de Atenção
|
|
|
|
- **GeoIP**: O script baixa automaticamente os bancos GeoIP se faltarem. Não precisa baixar manualmente.
|
|
- **Paramiko**: O script usa `paramiko` para SSH. Se não estiver instalado, instale com `pip install paramiko`.
|
|
- **Credenciais**: As credenciais de acesso ao servidor estão embutidas no cabeçalho do script. Não as exponha em logs públicos.
|
|
|
|
## 🐛 Solução de Problemas e Lições Aprendidas (2026-02-08)
|
|
|
|
### 1. Conflitos de ModSecurity (Loop em `nginx -t`)
|
|
- **Sintoma**: O deploy reporta sucesso, mas as alterações não aparecem no servidor. O log remoto mostra `nginx: [emerg] "modsecurity_rules_file" directive is duplicate`.
|
|
- **Causa**: O arquivo `snippets/modsecurity.conf` já define `modsecurity_rules_file`. Se você incluir esse snippet E também definir a diretiva `modsecurity_rules_file` no bloco `server` (ex: `ferreirareal.com.br.conf`), o Nginx falhará.
|
|
- **Solução**: Use apenas `include snippets/modsecurity.conf;` no bloco server. A diretiva `modsecurity_rules_file /etc/nginx/modsec/main.conf;` deve ficar comentada ou removida do vhost.
|
|
|
|
### 2. Falhas Silenciosas de Rollback
|
|
- **Cuidado**: O script `deploy_pathfinder.py` executa um rollback automático se `nginx -t` falhar.
|
|
- **O que acontece**: O script restaura o backup anterior e reinicia o Nginx. Isso faz o deploy parecer bem-sucedido (exit code 0), mas seus arquivos novos foram descartados.
|
|
- **Verificação**: **SEMPRE** verifique o timestamp dos arquivos remotos após um deploy crítico para garantir que foram atualizados:
|
|
```python
|
|
# Exemplo de verificação rápida
|
|
client.exec_command("ls -l /etc/nginx/snippets/log_formats.conf")
|
|
```
|
|
|
|
### 3. Encoding Windows vs Linux
|
|
- **Problema**: `UnicodeEncodeError: 'charmap' codec can't encode character...` ao rodar scripts Python no Windows.
|
|
- **Causa**: O console do Windows padrão (cp1252) não suporta emojis como 🚀 ou ✅.
|
|
- **Regra**: Evite usar emojis ou caracteres especiais em scripts que rodam no lado do cliente (Windows). Use `[OK]`, `[ERROR]`, `[+]` em vez de ícones.
|
|
|
|
### 4. Organização e Limpeza
|
|
- **Área de Diagnóstico**: Use a pasta `logs/` na raiz do projeto (`ngnix-pathfinder-proxy/logs`) para armazenar logs temporários, downloads de debug e "bagunça" necessária durante investigações.
|
|
- **Limpeza**: Após resolver o problema, **limpe** esta pasta para não commitar lixo no repositório. O `.gitignore` deve ignorar essa pasta, mas mantenha o hábito de limpeza.
|