Proxy Scraping Service

Sistema completo de scraping, validação e armazenamento de proxies anônimos em PostgreSQL. O serviço roda automaticamente uma vez ao dia, coletando proxies de múltiplas fontes, validando sua funcionalidade e anonimato, e armazenando apenas proxies ativos e anônimos no banco de dados.

Características

• Scraping Multi-Fonte: Suporta scraping de múltiplas URLs listadas em arquivo de configuração
• Suporte a Conteúdo Dinâmico: Utiliza Selenium para sites com JavaScript e paginação
• Validação Robusta: Testa conectividade e verifica anonimato de cada proxy antes de armazenar
• Filtro de Anonimato: Armazena APENAS proxies anônimos (sem vazamento de IP real)
• Prevenção de Duplicatas: Valida existência antes de inserir no banco
• Agendamento Inteligente: Executa automaticamente entre 2h-4h da madrugada (horário configurável)
• Containerizado: Deploy completo com Docker e Docker Compose
• Banco PostgreSQL: Schema otimizado com índices e constraints
• Logging Estruturado: Logs coloridos e níveis configuráveis
• Health Checks: Monitoramento de saúde dos containers

Arquitetura

proxy/
├── src/
│   ├── main.py           # Serviço principal e orquestração
│   ├── config.py         # Gerenciamento de configurações
│   ├── database.py       # Operações PostgreSQL
│   ├── validator.py      # Validação de proxies
│   └── scrapers.py       # Scrapers para múltiplas fontes
├── root/
│   └── proxy/
│       └── proxies.txt   # Lista de URLs para scraping
├── Dockerfile            # Build do container Python
├── docker-compose.yml    # Orquestração de serviços
├── init-db.sql          # Inicialização do banco
├── requirements.txt      # Dependências Python
├── .env.example         # Exemplo de variáveis de ambiente
└── README.md            # Esta documentação

Tecnologias Utilizadas

Core

• Python 3.11: Linguagem principal
• PostgreSQL 16: Banco de dados
• Docker & Docker Compose: Containerização

Bibliotecas Python

• psycopg2: Driver PostgreSQL
• requests: HTTP client para scraping e validação
• BeautifulSoup4: Parsing HTML
• Selenium: Scraping de conteúdo dinâmico
• APScheduler: Agendamento de tarefas
• pydantic: Validação de configurações
• colorlog: Logging estruturado

Instalação e Deploy

Pré-requisitos

• Docker 20.10+
• Docker Compose 2.0+
• 2GB RAM livre
• Conexão com internet

Deploy Rápido

1. Clone ou baixe o projeto:

git clone

2. Configure as variáveis de ambiente:

cp .env.example .env

Edite o arquivo .env e configure suas credenciais:

nano .env

Mínimo necessário:

POSTGRES_PASSWORD=your_secure_password_here

3. Verifique o arquivo de URLs:

cat root/proxy/proxies.txt

Adicione ou remova URLs conforme necessário. O arquivo já vem com fontes pré-configuradas.

4. Execute o serviço:

docker-compose up -d

5. Acompanhe os logs:

docker-compose logs -f proxy-scraper

Configuração

Variáveis de Ambiente

Todas as configurações podem ser ajustadas via arquivo .env:

PostgreSQL

POSTGRES_HOST=postgres          # Host do banco (padrão: postgres)
POSTGRES_PORT=5432              # Porta do banco
POSTGRES_DB=proxies             # Nome do database
POSTGRES_USER=postgres          # Usuário do banco
POSTGRES_PASSWORD=postgres      # Senha (ALTERAR EM PRODUÇÃO)

Validação de Proxies

PROXY_TIMEOUT=10                # Timeout em segundos para teste
VALIDATION_URL=http://httpbin.org/ip  # URL para validação

Scraping

SCRAPING_DELAY=2.0              # Delay entre requisições (segundos)
MAX_RETRIES=3                   # Tentativas em caso de erro

Agendamento

SCHEDULE_HOUR_START=2           # Hora inicial (UTC)
SCHEDULE_HOUR_END=4             # Hora final (UTC)

O serviço executará automaticamente uma vez ao dia em um horário aleatório entre SCHEDULE_HOUR_START e SCHEDULE_HOUR_END.

Logging

LOG_LEVEL=INFO                  # Níveis: DEBUG, INFO, WARNING, ERROR

Arquivo de URLs (proxies.txt)

O arquivo root/proxy/proxies.txt contém as URLs para scraping:

# Comentários começam com #
https://www.proxy-list.download/api/v1/get?type=http
https://api.proxyscrape.com/v2/?request=get&protocol=http

# Sites com Selenium (paginação)
https://www.freeproxy.world/?type=http&anonymity=4
https://free-proxy-list.net/

Formato:

• Uma URL por linha
• Linhas começando com # são ignoradas
• URLs vazias são ignoradas

Uso

Comandos Docker Compose

Iniciar todos os serviços:

docker-compose up -d

Iniciar com pgAdmin (gerenciamento do banco):

docker-compose --profile admin up -d

Ver logs em tempo real:

docker-compose logs -f proxy-scraper

Parar serviços:

docker-compose down

Parar e remover volumes (limpar banco):

docker-compose down -v

Reconstruir imagens:

docker-compose build --no-cache
docker-compose up -d

Executar Scraping Imediato

Para executar o scraping imediatamente (sem esperar o agendamento):

docker-compose exec proxy-scraper python src/main.py --immediate

Acessar pgAdmin (opcional)

Se iniciou com o profile admin:

1. Acesse: http://localhost:5050
2. Login: admin@admin.com / admin (configurável no .env)
3. Adicione servidor:
   • Host: postgres
   • Port: 5432
   • Database: proxies
   • Username: seu POSTGRES_USER
   • Password: seu POSTGRES_PASSWORD

Schema do Banco de Dados

Tabela proxies

CREATE TABLE proxies (
    id SERIAL PRIMARY KEY,
    ip_address INET NOT NULL,
    port INTEGER NOT NULL CHECK (port > 0 AND port <= 65535),
    protocol VARCHAR(10) NOT NULL CHECK (protocol IN ('HTTP', 'HTTPS', 'SOCKS4', 'SOCKS5')),
    username VARCHAR(255),
    password VARCHAR(255),
    country_code CHAR(2),
    country_name VARCHAR(100),
    city VARCHAR(100),
    is_active BOOLEAN DEFAULT TRUE,
    is_anonymous BOOLEAN DEFAULT FALSE,
    response_time_ms INTEGER,
    last_checked_at TIMESTAMP WITH TIME ZONE,
    last_successful_at TIMESTAMP WITH TIME ZONE,
    failure_count INTEGER DEFAULT 0,
    success_count INTEGER DEFAULT 0,
    usage INTEGER DEFAULT 0,
    source VARCHAR(255),
    notes TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT unique_proxy UNIQUE (ip_address, port, protocol)
);

Consultas Úteis

Listar todos os proxies ativos e anônimos:

SELECT ip_address, port, protocol, country_name, response_time_ms
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
ORDER BY response_time_ms ASC;

Estatísticas gerais:

SELECT
    COUNT(*) as total,
    COUNT(*) FILTER (WHERE is_active = TRUE) as active,
    COUNT(*) FILTER (WHERE is_anonymous = TRUE) as anonymous,
    COUNT(DISTINCT country_code) as countries,
    AVG(response_time_ms) as avg_response_time
FROM proxies;

Proxies por país:

SELECT country_name, COUNT(*) as total
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
GROUP BY country_name
ORDER BY total DESC;

Proxies mais rápidos:

SELECT ip_address, port, protocol, response_time_ms, country_name
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
ORDER BY response_time_ms ASC
LIMIT 10;

Funcionamento do Sistema

Fluxo de Execução

1. Agendamento: Serviço aguarda horário programado (2h-4h UTC por padrão)
2. Scraping: Lê URLs do proxies.txt e processa uma por vez
3. Parsing: Extrai informações de proxy (IP, porta, protocolo)
4. Deduplicação: Remove duplicatas da lista scraped
5. Validação: Testa cada proxy para:
   • Conectividade (timeout de 10s)
   • Anonimato (verifica vazamento de IP real)
6. Filtragem: Mantém APENAS proxies anônimos
7. Armazenamento: Insere no PostgreSQL (ignora duplicatas)
8. Estatísticas: Exibe métricas do processamento

Validação de Anonimato

O sistema verifica anonimato através de:

1. Headers HTTP: Detecta headers que revelam IP real:

   • X-Forwarded-For
   • X-Real-IP
   • Via
   • Forwarded

2. Análise de Response: Valida o IP retornado pela URL de teste

3. Critério Conservador: Em caso de dúvida, o proxy é marcado como não-anônimo

Tipos de Scraper

GenericHTMLScraper:

• Para sites estáticos
• Parsing com BeautifulSoup
• Extrai de tabelas HTML ou texto
• Rápido e eficiente

SeleniumScraper:

• Para sites dinâmicos (JavaScript)
• Suporta paginação automática
• Sites como freeproxy.world
• Mais lento mas completo

Monitoramento

Logs

O sistema gera logs estruturados e coloridos:

2025-11-21 02:15:30 - INFO - Starting proxy scraping job
2025-11-21 02:15:31 - INFO - Scraped 150 proxies from sources
2025-11-21 02:15:45 - INFO - 45 proxies validated successfully
2025-11-21 02:15:46 - INFO - Inserted 38 new anonymous proxies

Níveis de log:

• DEBUG: Informações detalhadas de cada operação
• INFO: Progresso e estatísticas (padrão)
• WARNING: Problemas não-críticos
• ERROR: Erros que precisam atenção

Health Check

O container possui health check integrado:

docker-compose ps

Verifica conectividade com o banco a cada 60 segundos.

Métricas

Após cada execução, o sistema exibe:

• Total de proxies scraped
• Taxa de validação
• Proxies inseridos vs duplicados
• Estatísticas do banco
• Tempo de execução

Troubleshooting

Container não inicia

Verificar logs:

docker-compose logs proxy-scraper

Problemas comuns:

• Arquivo proxies.txt não existe
• Credenciais PostgreSQL incorretas
• PostgreSQL não está pronto (aguarde health check)

Nenhum proxy é inserido

Causas possíveis:

1. Proxies não são anônimos (validação falha)
2. Proxies já existem no banco
3. Todos os proxies falharam na validação

Verificar:

# Ver logs detalhados
docker-compose logs proxy-scraper | grep -i "anonymous\|validated"

# Executar com nível DEBUG
# Edite .env: LOG_LEVEL=DEBUG
docker-compose restart proxy-scraper

Selenium/Chrome não funciona

Erro: "Chrome binary not found"

Solução:

# Reconstruir imagem
docker-compose build --no-cache proxy-scraper
docker-compose up -d

Problemas de conexão PostgreSQL

Erro: "Connection refused" ou "could not connect"

Verificar:

# Status do PostgreSQL
docker-compose ps postgres

# Logs do PostgreSQL
docker-compose logs postgres

# Testar conexão manual
docker-compose exec postgres psql -U postgres -d proxies -c "\dt"

Performance lenta

Otimizações:

1. Ajuste PROXY_TIMEOUT para valor menor (padrão: 10s)
2. Reduza número de URLs em proxies.txt
3. Aumente workers de validação (edite src/main.py, max_workers=20)

Segurança

Recomendações para Produção

1. Altere senhas padrão:

POSTGRES_PASSWORD=senha_forte_e_unica
PGADMIN_PASSWORD=outra_senha_forte

2. Não exponha portas desnecessárias:

   • Remova ports do serviço postgres no docker-compose.yml
   • Use apenas através de pgAdmin ou conexões internas

3. Use volumes nomeados:

   • Já configurado no docker-compose.yml
   • Dados persistem entre restarts

4. Atualize regularmente:

docker-compose pull
docker-compose build --no-cache
docker-compose up -d

5. Firewall:
   • Bloqueie acesso externo às portas do Docker
   • Use apenas localhost ou VPN

Extensões e Customizações

Adicionar novo scraper

Edite src/scrapers.py:

class CustomScraper(ProxyScraper):
    def scrape(self) -> List[Dict[str, Any]]:
        # Sua lógica aqui
        proxies = []
        # ... scraping logic ...
        return proxies

Modificar critérios de anonimato

Edite src/validator.py, método _check_anonymity():

def _check_anonymity(self, response, proxy_ip):
    # Customize validation logic
    pass

Adicionar campos ao banco

1. Modifique init-db.sql
2. Atualize models em src/database.py
3. Recrie o banco:

docker-compose down -v
docker-compose up -d

Integrar com API externa

Modifique src/main.py para exportar ou notificar serviços externos após scraping.

Performance

Benchmarks Típicos

Com configurações padrão:

• Scraping: 100-500 proxies em 2-5 minutos
• Validação: 20 proxies/segundo (max_workers=20)
• Armazenamento: < 1 segundo

Otimizações

• Pool de conexões PostgreSQL (já implementado)
• Validação concorrente com ThreadPoolExecutor
• Cache de webdriver no Selenium
• Índices otimizados no banco

Suporte e Contribuições

Estrutura do Código

• Modular: Cada arquivo tem responsabilidade única
• Type Hints: Código totalmente tipado
• Documentado: Docstrings em todas as funções
• Error Handling: Try/catch em operações críticas
• Logging: Rastreamento completo de execução

Desenvolvimento Local

# Criar virtualenv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

# Executar localmente (requer PostgreSQL rodando)
export POSTGRES_HOST=localhost
python src/main.py --immediate

Licença

Este projeto é fornecido como está, sem garantias. Use por sua conta e risco.

Changelog

v1.0.0 (2025-11-21)

• Implementação inicial completa
• Suporte a múltiplas fontes de proxy
• Validação de anonimato
• Agendamento automático
• Deploy com Docker Compose
• Documentação completa

---

Criado com Claude Code - Sistema production-ready de scraping de proxies anônimos.