7.5 KiB

Raw Blame History

🤖 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:

Faça suas alterações nos arquivos de configuração (nginx/).
Valide e Deploye rodando o script abaixo no terminal do Windows:
```
python producao/scripts/deploy_pathfinder.py sync --all
```
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".
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. Scripts de Diagnóstico e Recuperação (2026-02-08)

Foram criados scripts auxiliares em producao/scripts/ para situações de emergência ou validação profunda. Use-os com cautela:

restore_nginx.py:
- Função: Força o upload do nginx.conf local para o servidor e reinicia o serviço.
- Uso: python producao/scripts/restore_nginx.py
- Quando usar: Se o deploy_pathfinder.py falhar ou se o Nginx não subir por erro de configuração crítica (ex: variáveis faltando).
fetch_logs.py:
- Função: Baixa logs específicos do servidor para análise local.
- Uso: python producao/scripts/fetch_logs.py
- Quando usar: Para investigar ataques ou erros sem precisar logar via SSH.
verify_time_and_logs.py:
- Função: Verifica a data do servidor e os últimos logs de acesso.
- Uso: python producao/scripts/verify_time_and_logs.py
- Quando usar: Para confirmar se o timezone está correto (-0300) e se o Nginx está gerando logs novos.

3. 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:
```
# 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.

7.5 KiB Raw Blame History