================================================================================ 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 ================================================================================