init repo
This commit is contained in:
LeoMortari
605
README.md
Normal file
605
README.md
Normal file
@@ -0,0 +1,605 @@
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
git clone
|
||||
```
|
||||
|
||||
2. **Configure as variáveis de ambiente**:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edite o arquivo `.env` e configure suas credenciais:
|
||||
|
||||
```bash
|
||||
nano .env
|
||||
```
|
||||
|
||||
Mínimo necessário:
|
||||
|
||||
```env
|
||||
POSTGRES_PASSWORD=your_secure_password_here
|
||||
```
|
||||
|
||||
3. **Verifique o arquivo de URLs**:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
5. **Acompanhe os logs**:
|
||||
|
||||
```bash
|
||||
docker-compose logs -f proxy-scraper
|
||||
```
|
||||
|
||||
## Configuração
|
||||
|
||||
### Variáveis de Ambiente
|
||||
|
||||
Todas as configurações podem ser ajustadas via arquivo `.env`:
|
||||
|
||||
#### PostgreSQL
|
||||
|
||||
```env
|
||||
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
|
||||
|
||||
```env
|
||||
PROXY_TIMEOUT=10 # Timeout em segundos para teste
|
||||
VALIDATION_URL=http://httpbin.org/ip # URL para validação
|
||||
```
|
||||
|
||||
#### Scraping
|
||||
|
||||
```env
|
||||
SCRAPING_DELAY=2.0 # Delay entre requisições (segundos)
|
||||
MAX_RETRIES=3 # Tentativas em caso de erro
|
||||
```
|
||||
|
||||
#### Agendamento
|
||||
|
||||
```env
|
||||
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
|
||||
|
||||
```env
|
||||
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:
|
||||
|
||||
```txt
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
**Iniciar com pgAdmin (gerenciamento do banco)**:
|
||||
|
||||
```bash
|
||||
docker-compose --profile admin up -d
|
||||
```
|
||||
|
||||
**Ver logs em tempo real**:
|
||||
|
||||
```bash
|
||||
docker-compose logs -f proxy-scraper
|
||||
```
|
||||
|
||||
**Parar serviços**:
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
**Parar e remover volumes (limpar banco)**:
|
||||
|
||||
```bash
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
**Reconstruir imagens**:
|
||||
|
||||
```bash
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Executar Scraping Imediato
|
||||
|
||||
Para executar o scraping imediatamente (sem esperar o agendamento):
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```sql
|
||||
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**:
|
||||
|
||||
```sql
|
||||
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**:
|
||||
|
||||
```sql
|
||||
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**:
|
||||
|
||||
```sql
|
||||
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**:
|
||||
|
||||
```sql
|
||||
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:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```env
|
||||
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**:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```python
|
||||
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()`:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user