init repo

2025-11-21 18:23:19 -03:00
commit 23c8133f3d
20 changed files with 4481 additions and 0 deletions
--- a/PROJECT_SUMMARY.txt
+++ b/PROJECT_SUMMARY.txt
@@ -0,0 +1,360 @@
+================================================================================
+                    PROXY SCRAPING SERVICE - PROJECT SUMMARY
+================================================================================
+
+PROJETO COMPLETO DE SCRAPING DE PROXIES
+Status: PRODUCTION READY
+Data: 2025-11-21
+
+================================================================================
+ESTRUTURA DO PROJETO
+================================================================================
+
+proxy/
+├── src/                          # Código-fonte Python
+│   ├── __init__.py              # Package initialization
+│   ├── main.py                  # Serviço principal + agendamento
+│   ├── config.py                # Gerenciamento de configurações
+│   ├── database.py              # Operações PostgreSQL
+│   ├── validator.py             # Validação de proxies
+│   └── scrapers.py              # Scrapers multi-fonte
+│
+├── root/proxy/                   # Volume montado
+│   └── proxies.txt              # URLs para scraping
+│
+├── Dockerfile                    # Container Python + Chrome
+├── docker-compose.yml            # Orquestração de serviços
+├── init-db.sql                  # Schema PostgreSQL
+├── requirements.txt              # Dependências Python
+│
+├── .env.example                 # Template de configuração
+├── .gitignore                   # Git ignore rules
+├── Makefile                     # Comandos úteis
+├── quick-start.sh               # Script de setup rápido
+│
+└── Documentação:
+    ├── README.md                # Documentação principal
+    ├── ARCHITECTURE.md          # Arquitetura técnica
+    ├── QUERIES.md               # SQL queries úteis
+    └── PROJECT_SUMMARY.txt      # Este arquivo
+
+================================================================================
+COMPONENTES PRINCIPAIS
+================================================================================
+
+1. SERVIÇO DE SCRAPING (main.py)
+   - Orquestração do fluxo completo
+   - Agendamento automático (2-4 AM UTC)
+   - Logging estruturado
+   - Métricas e estatísticas
+
+2. SCRAPERS (scrapers.py)
+   - GenericHTMLScraper: Sites estáticos
+   - SeleniumScraper: Conteúdo dinâmico + paginação
+   - ScraperFactory: Seleção automática
+   - Suporte a múltiplas fontes
+
+3. VALIDADOR (validator.py)
+   - Teste de conectividade
+   - Verificação de anonimato
+   - Validação paralela (20 threads)
+   - Medição de response time
+
+4. DATABASE (database.py)
+   - Connection pooling
+   - Operações CRUD
+   - Prevenção de duplicatas
+   - Estatísticas agregadas
+
+5. CONFIGURAÇÃO (config.py)
+   - Pydantic Settings
+   - Validação de tipos
+   - Suporte a .env
+   - Valores padrão
+
+================================================================================
+FUNCIONALIDADES IMPLEMENTADAS
+================================================================================
+
+✓ Scraping de múltiplas fontes
+✓ Suporte a paginação (Selenium)
+✓ Validação de conectividade
+✓ Verificação de anonimato
+✓ Armazenamento apenas de proxies anônimos
+✓ Prevenção de duplicatas
+✓ Agendamento automático diário
+✓ Logging colorido e estruturado
+✓ Docker + Docker Compose
+✓ PostgreSQL com schema otimizado
+✓ Health checks
+✓ pgAdmin (opcional)
+✓ Makefile com comandos úteis
+✓ Script de quick start
+✓ Documentação completa
+
+================================================================================
+TECNOLOGIAS UTILIZADAS
+================================================================================
+
+Backend:
+- Python 3.11
+- psycopg2 (PostgreSQL driver)
+- requests (HTTP client)
+- BeautifulSoup4 (HTML parsing)
+- Selenium + Chrome (dynamic content)
+- APScheduler (job scheduling)
+- pydantic (settings validation)
+- colorlog (structured logging)
+
+Database:
+- PostgreSQL 16
+- Connection pooling
+- Indexes otimizados
+- Triggers e constraints
+
+Infrastructure:
+- Docker + Docker Compose
+- Multi-stage builds
+- Volume mounts
+- Health checks
+- pgAdmin 4 (admin)
+
+================================================================================
+COMANDOS PRINCIPAIS
+================================================================================
+
+SETUP INICIAL:
+  ./quick-start.sh                 # Setup completo automático
+  make setup                       # Criar .env
+  cp .env.example .env            # Configuração manual
+
+BUILD E DEPLOY:
+  docker-compose build            # Build da imagem
+  docker-compose up -d            # Iniciar serviços
+  docker-compose down             # Parar serviços
+
+OPERAÇÃO:
+  make logs                       # Ver logs em tempo real
+  make immediate                  # Executar scraping agora
+  make stats                      # Ver estatísticas do banco
+  make admin                      # Iniciar com pgAdmin
+
+MANUTENÇÃO:
+  make restart                    # Reiniciar serviços
+  make clean                      # Limpar tudo (remove volumes)
+  docker-compose build --no-cache # Rebuild completo
+
+DESENVOLVIMENTO:
+  make dev-install                # Setup ambiente local
+  make dev-run                    # Executar localmente
+  make shell                      # Shell no container
+
+================================================================================
+CONFIGURAÇÕES IMPORTANTES (.env)
+================================================================================
+
+PostgreSQL:
+  POSTGRES_HOST=postgres
+  POSTGRES_PORT=5432
+  POSTGRES_DB=proxies
+  POSTGRES_USER=postgres
+  POSTGRES_PASSWORD=your_secure_password  # ALTERAR!
+
+Validação:
+  PROXY_TIMEOUT=10
+  VALIDATION_URL=http://httpbin.org/ip
+
+Scraping:
+  SCRAPING_DELAY=2.0
+  MAX_RETRIES=3
+
+Agendamento:
+  SCHEDULE_HOUR_START=2           # UTC
+  SCHEDULE_HOUR_END=4             # UTC
+
+Logging:
+  LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
+
+================================================================================
+FLUXO DE EXECUÇÃO
+================================================================================
+
+1. STARTUP
+   ├── Carregar configurações (.env)
+   ├── Conectar ao PostgreSQL
+   ├── Configurar scheduler
+   └── Executar job inicial (opcional)
+
+2. JOB DE SCRAPING
+   ├── Ler URLs de proxies.txt
+   ├── Scrape de cada URL (uma por vez)
+   ├── Deduplicação de proxies
+   ├── Validação paralela (conectividade + anonimato)
+   ├── Filtrar apenas proxies anônimos
+   ├── Inserir no banco (skip duplicatas)
+   └── Exibir estatísticas
+
+3. AGENDAMENTO
+   └── Aguardar próximo horário (2-4 AM)
+
+================================================================================
+VALIDAÇÃO DE ANONIMATO
+================================================================================
+
+O sistema verifica:
+  ✓ Headers que revelam IP real (X-Forwarded-For, Via, etc.)
+  ✓ IP retornado na resposta
+  ✓ Múltiplos IPs (indica forwarding)
+
+Critério: CONSERVADOR
+  - Em caso de dúvida, marca como não-anônimo
+  - Apenas proxies 100% anônimos são armazenados
+
+================================================================================
+SCHEMA DO BANCO DE DADOS
+================================================================================
+
+Tabela: proxies
+  Campos principais:
+    - id (SERIAL PRIMARY KEY)
+    - ip_address (INET)
+    - port (INTEGER)
+    - protocol (VARCHAR: HTTP, HTTPS, SOCKS4, SOCKS5)
+    - country_code, country_name, city
+    - is_active, is_anonymous (BOOLEAN)
+    - response_time_ms (INTEGER)
+    - success_count, failure_count
+    - source, notes
+    - timestamps (created_at, updated_at, last_checked_at)
+
+  Constraints:
+    - UNIQUE (ip_address, port, protocol)
+    - CHECK port range (1-65535)
+    - CHECK protocol enum
+
+  Indexes:
+    - idx_active_protocol
+    - idx_country
+    - idx_last_checked
+    - idx_response_time
+    - idx_usage
+
+================================================================================
+FONTES DE PROXY (proxies.txt)
+================================================================================
+
+Pré-configuradas:
+  • https://www.proxy-list.download/api/v1/get?type=http
+  • https://api.proxyscrape.com/v2/...
+  • https://www.freeproxy.world/...
+  • https://free-proxy-list.net/
+  • https://www.sslproxies.org/
+
+Formato:
+  - Uma URL por linha
+  - Linhas com # são comentários
+  - Linhas vazias são ignoradas
+
+================================================================================
+PERFORMANCE ESPERADA
+================================================================================
+
+Com configurações padrão:
+  Scraping: 100-500 proxies em 2-5 minutos
+  Validação: ~20 proxies/segundo (20 workers)
+  Armazenamento: <1 segundo para 100 proxies
+  Taxa de sucesso: 20-40% (proxies anônimos)
+
+Recursos:
+  RAM: ~1GB (scraper) + 256MB (postgres)
+  CPU: 1-2 cores
+  Disco: ~100MB + dados
+
+================================================================================
+SEGURANÇA
+================================================================================
+
+Implementado:
+  ✓ Non-root user no container (UID 1000)
+  ✓ Prepared statements (SQL injection)
+  ✓ Connection pooling (DoS prevention)
+  ✓ Senhas via environment variables
+  ✓ Read-only volumes
+  ✓ Health checks
+  ✓ Input validation (Pydantic)
+
+Recomendações para produção:
+  ! Alterar senhas padrão
+  ! Configurar firewall
+  ! Setup backup automático
+  ! Implementar monitoring
+  ! Usar SSL/TLS para pgAdmin
+  ! Rate limiting nas APIs
+
+================================================================================
+TROUBLESHOOTING RÁPIDO
+================================================================================
+
+Problema: Container não inicia
+  → docker-compose logs proxy-scraper
+  → Verificar .env
+  → Verificar proxies.txt
+
+Problema: Nenhum proxy é inserido
+  → Verificar LOG_LEVEL=DEBUG
+  → Proxies podem não ser anônimos
+  → Proxies podem já existir no banco
+
+Problema: Selenium falha
+  → docker-compose build --no-cache
+  → Verificar logs do Chrome
+
+Problema: PostgreSQL connection refused
+  → docker-compose ps postgres
+  → Aguardar health check
+  → Verificar credenciais
+
+================================================================================
+EXTENSÕES FUTURAS
+================================================================================
+
+Possíveis melhorias:
+  • API REST para consumir proxies
+  • Dashboard web em tempo real
+  • Cache Redis
+  • Machine learning para qualidade
+  • Geolocation avançada
+  • Proxy rotation service
+  • Webhook notifications
+  • Prometheus/Grafana metrics
+
+================================================================================
+DOCUMENTAÇÃO ADICIONAL
+================================================================================
+
+README.md          - Guia completo de uso e instalação
+ARCHITECTURE.md    - Arquitetura técnica detalhada
+QUERIES.md         - SQL queries úteis e exemplos
+.env.example       - Template de configuração
+
+Links úteis:
+  • PostgreSQL docs: https://www.postgresql.org/docs/
+  • Selenium docs: https://www.selenium.dev/documentation/
+  • Docker docs: https://docs.docker.com/
+  • Python requests: https://requests.readthedocs.io/
+
+================================================================================
+CONTATO E SUPORTE
+================================================================================
+
+Este projeto foi criado como uma solução production-ready para scraping,
+validação e gerenciamento de proxies anônimos.
+
+Criado com Claude Code - Anthropic
+Data: 2025-11-21
+
+Para questões ou melhorias, consulte a documentação ou abra uma issue.
+
+================================================================================
+                            FIM DO RESUMO
+================================================================================