From 9e3b792e0cca934f1ac2edaffea46e19079c541c Mon Sep 17 00:00:00 2001 From: salvacybersec Date: Thu, 13 Nov 2025 05:43:02 +0300 Subject: [PATCH] docs --- API.md | 30 +++++++++++++++++++---- README.md | 59 ++++++++++++++++++++++++++++++++++++++++++--- development_plan.md | 48 ++++++++++++++++++++++++++++++------ 3 files changed, 120 insertions(+), 17 deletions(-) diff --git a/API.md b/API.md index f05b98a..84213fe 100644 --- a/API.md +++ b/API.md @@ -87,7 +87,7 @@ YouTube kanalı için transcript feed'i oluşturur. | `channel` | string | ⚠️* | Channel handle (@username veya username) | | `channel_url` | string | ⚠️* | Full YouTube channel URL | | `format` | string | ❌ | Feed formatı: `Atom` (varsayılan) veya `Rss` | -| `max_items` | integer | ❌ | Maksimum transcript sayısı (varsayılan: 10, max: 100, 20'şer batch'ler halinde işlenir) | +| `max_items` | integer | ❌ | Maksimum transcript sayısı (varsayılan: 10, max: 100, 5'şer batch'ler halinde işlenir) | \* `channel_id`, `channel` veya `channel_url` parametrelerinden biri zorunludur. @@ -315,7 +315,9 @@ Sadece aşağıdaki formatlar kabul edilir: - Minimum: 1 - Maksimum: 100 - Varsayılan: 10 -- **Batch İşleme**: 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) +- **Batch İşleme**: 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) +- **Batch'ler Arası Bekleme**: 60-90 saniye random bekleme (human-like behavior) +- **İstekler Arası Bekleme**: 10-20 saniye random (blocking varsa 30-60 saniye) - **Veritabanı Kaydı**: Her batch işlendikten sonra hemen veritabanına kaydedilir, böylece sonraki sorgularda görülebilir ## CORS @@ -404,10 +406,11 @@ curl -H "X-API-Key: $API_KEY" \ 2. **Rate Limiting**: Her API key için farklı rate limit tanımlanabilir. Limit aşıldığında 60 saniye beklemeniz gerekir. 3. **Transcript İşleme**: - - Transcript'ler 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) + - Transcript'ler 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) - Her batch işlendikten sonra veritabanına kaydedilir - `max_items` parametresi ile her istekte işlenecek transcript sayısını kontrol edebilirsiniz (maksimum 100) - - Batch'ler arası 2 saniye bekleme süresi vardır + - Batch'ler arası 60-90 saniye random bekleme (human-like behavior) + - İstekler arası 10-20 saniye random bekleme (blocking varsa 30-60 saniye) - Yeni videolar için birkaç dakika gecikme olabilir 4. **Format Seçimi**: Atom formatı daha modern ve önerilir. RSS formatı eski RSS reader'lar için uygundur. @@ -415,10 +418,27 @@ curl -H "X-API-Key: $API_KEY" \ 5. **API Key Güvenliği**: API key'lerinizi güvenli tutun ve asla public repository'lere commit etmeyin. 6. **Batch İşleme Örneği**: - - `max_items=50` isteği: 20+20+10 batch'ler halinde işlenir + - `max_items=50` isteği: 5+5+5+5+5+5+5+5+5+5 batch'ler halinde işlenir - Her batch tamamlandığında veritabanına kaydedilir + - Batch'ler arası 60-90 saniye random bekleme - Sonraki sorgularda tüm işlenmiş transcript'ler görülebilir +7. **FlareSolverr Desteği**: + - YouTube bot korumasını aşmak için FlareSolverr kullanılabilir + - Config dosyasında `flaresolverr.url` ayarlanabilir + - FlareSolverr erişilemezse otomatik olarak normal istek yapılır + - Gerçek tarayıcı (headless browser) kullanarak istekler yapılır + +8. **Gerçek Tarayıcı Header'ları**: + - 7 farklı tarayıcı User-Agent'ı rotasyon ile kullanılır + - Tam tarayıcı header seti (Accept, Sec-Fetch-*, Referer, vb.) + - Her istekte random User-Agent seçilir + +9. **Detaylı Loglama**: + - Tüm işlemler kategorize edilmiş loglarla takip edilir + - Timestamp'li, seviyeli log sistemi (DEBUG, INFO, WARNING, ERROR) + - Docker logları ile kolay takip + ## Destek Sorularınız için GitHub Issues kullanabilirsiniz. diff --git a/README.md b/README.md index bfba142..f36640e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ YouTube video transkriptlerini otomatik olarak çıkarıp, tam metin içeren RSS - ✅ **API Key Authentication** - Tüm endpoint'ler API key gerektirir - ✅ **Güvenlik Önlemleri** - SQL injection, XSS, rate limiting koruması - ✅ **Transcript Cache** - 3 günlük cache ile YouTube IP blocking önleme +- ✅ **FlareSolverr Desteği** - Bot korumasını aşmak için FlareSolverr entegrasyonu +- ✅ **Gerçek Tarayıcı Header'ları** - User-Agent rotasyonu ve tam tarayıcı header seti +- ✅ **Detaylı Loglama** - Timestamp'li, kategorize edilmiş log sistemi - ✅ RSS-Bridge entegrasyonu (100+ video desteği) - ✅ Async rate limiting (AIOLimiter) - ✅ SpaCy ile Sentence Boundary Detection @@ -60,7 +63,7 @@ curl -H "X-API-Key: demo_key_12345" \ # Channel Handle ile (API key query parametresi) curl "http://localhost:5000/?channel=@tavakfi&format=Atom&api_key=demo_key_12345" -# Channel URL ile (max_items: her istekte işlenecek transcript sayısı, default: 10, max: 100, 20'şer batch'ler) +# Channel URL ile (max_items: her istekte işlenecek transcript sayısı, default: 10, max: 100, 5'şer batch'ler) curl -H "X-API-Key: demo_key_12345" \ "http://localhost:5000/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50" ``` @@ -109,6 +112,10 @@ rss_bridge: base_url: "https://rss-bridge.org/bridge01" format: "Atom" max_items: 100 # RSS-Bridge'den çekilecek video sayısı (web server'da max_items parametresi farklı) + +# FlareSolverr ayarları (YouTube IP blocking önleme için) +flaresolverr: + url: "http://192.168.1.27:8191/v1" # FlareSolverr API URL'i (devre dışı için null) ``` ### Güvenlik Yapılandırması @@ -146,22 +153,66 @@ Her API isteğinde kaç video transcript'inin işleneceğini kontrol eder: - **Varsayılan**: 10 transcript - **Maksimum**: 100 transcript - **Kullanım**: `?max_items=50` query parametresi ile belirtilir -- **Batch İşleme**: 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) +- **Batch İşleme**: 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) **Önemli Notlar:** - `max_items` parametresi **her istekte işlenecek transcript sayısını** belirler - RSS-Bridge'den daha fazla video çekilir (max_items × 2, minimum 50) çünkü bazı videolar transcript'siz olabilir -- **Batch İşleme**: YouTube IP blocking'i önlemek için 20'şer batch'ler halinde işlenir +- **Batch İşleme**: YouTube IP blocking'i önlemek için 5'şer batch'ler halinde işlenir +- **Batch'ler Arası Bekleme**: 60-90 saniye random bekleme (human-like behavior) - **Veritabanı Kaydı**: Her batch işlendikten sonra hemen veritabanına kaydedilir, böylece sonraki sorgularda görülebilir - İlk isteklerde daha az transcript görebilirsiniz; sonraki isteklerde cache'den daha fazla transcript döner **Örnek:** ```bash -# 50 transcript işle (20+20+10 batch'ler halinde) +# 50 transcript işle (5+5+5+5+5+5+5+5+5+5 batch'ler halinde) curl -H "X-API-Key: demo_key_12345" \ "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&max_items=50&format=Atom" ``` +### FlareSolverr Yapılandırması + +FlareSolverr, YouTube'un bot korumasını aşmak için gerçek tarayıcı kullanır: + +```yaml +# config/config.yaml +flaresolverr: + url: "http://192.168.1.27:8191/v1" # FlareSolverr API URL'i +``` + +veya environment variable: +```bash +export FLARESOLVERR_URL=http://192.168.1.27:8191/v1 +``` + +**FlareSolverr Avantajları:** +- Gerçek tarayıcı kullanımı (headless browser) +- Bot algılamasını aşma +- Cloudflare ve DDoS-GUARD korumasını bypass etme +- Otomatik fallback: FlareSolverr erişilemezse normal istek yapılır + +### Gerçek Tarayıcı Header'ları + +Sistem, gerçek tarayıcı gibi görünmek için: +- **User-Agent Rotasyonu**: 7 farklı tarayıcı User-Agent'ı (Chrome, Firefox, Safari, Edge) +- **Tam Header Seti**: Accept, Accept-Language, Sec-Fetch-*, Referer, vb. +- **Her İstekte Random**: Her istekte farklı User-Agent seçilir + +### Detaylı Loglama + +Sistem, tüm işlemleri kategorize edilmiş loglarla takip eder: + +- **`[RATE_LIMIT]`**: Rate limiting ve bekleme süreleri +- **`[TRANSCRIPT]`**: Transcript çıkarım işlemleri +- **`[PROCESS]`**: Genel işlem akışı +- **`[BATCH]`**: Batch işleme bilgileri +- **`[VIDEO]`**: Video seviyesi işlemler +- **`[CACHE]`**: Cache kontrolleri +- **`[FLARESOLVERR]`**: FlareSolverr istekleri +- **`[HEADERS]`**: Header yönetimi + +Log formatı: `YYYY-MM-DD HH:MM:SS | LEVEL | MODULE | MESSAGE` + ## Proje Yapısı ``` diff --git a/development_plan.md b/development_plan.md index f0dd5e6..5d9d58f 100644 --- a/development_plan.md +++ b/development_plan.md @@ -84,9 +84,23 @@ YouTube video transkriptlerini otomatik olarak çıkarıp, tam metin içeren RSS - **Retry-After Header**: 429 hatalarında `Retry-After` header'ını kullanma - Dinamik bekleme süresi (statik delay yerine) - Exponential backoff mekanizması +- **FlareSolverr Desteği**: Bot korumasını aşmak için FlareSolverr entegrasyonu + - FlareSolverr API üzerinden istek yapma + - Gerçek tarayıcı (headless browser) kullanımı + - Otomatik fallback: FlareSolverr erişilemezse normal istek +- **Gerçek Tarayıcı Header'ları**: Bot algılamasını önlemek için + - User-Agent rotasyonu (7 farklı tarayıcı) + - Tam tarayıcı header seti (Accept, Sec-Fetch-*, Referer, vb.) + - Her istekte random User-Agent seçimi +- **Detaylı Loglama**: Kategorize edilmiş log sistemi + - Timestamp'li, seviyeli loglar (DEBUG, INFO, WARNING, ERROR) + - Log kategorileri: [RATE_LIMIT], [TRANSCRIPT], [FLARESOLVERR], [HEADERS], vb. +- **IP Blocking Yönetimi**: + - IP blocking tespiti ve dinamik bekleme (5 dakika + block_count × 1 dakika, max 30 dakika) + - İstekler arası random bekleme (10-20 saniye, blocking varsa 30-60 saniye) - Timeout ve retry mekanizmaları -**Süre Tahmini**: 3-4 gün +**Süre Tahmini**: 5-6 gün (FlareSolverr ve header desteği ile) ### 2.2. Transcript Temizleme ve Dönüştürme (`transcript_cleaner.py`) @@ -335,9 +349,14 @@ channel_id = get_channel_id_from_handle(handle_url) - **Varsayılan**: 10 transcript - **Maksimum**: 100 transcript - **Kullanım**: `?max_items=50` query parametresi ile belirtilir - - **Batch İşleme**: 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) + - **Batch İşleme**: 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için) + - **Batch'ler Arası Bekleme**: 60-90 saniye random bekleme (human-like behavior) + - **İstekler Arası Bekleme**: 10-20 saniye random (blocking varsa 30-60 saniye) - **Veritabanı Kaydı**: Her batch işlendikten sonra hemen veritabanına kaydedilir - **RSS-Bridge Limit**: max_items × 2 kadar video çekilir (bazı videolar transcript'siz olabilir) + - **FlareSolverr Desteği**: Bot korumasını aşmak için FlareSolverr entegrasyonu + - **Gerçek Tarayıcı Header'ları**: User-Agent rotasyonu ve tam tarayıcı header seti + - **Detaylı Loglama**: Kategorize edilmiş, timestamp'li log sistemi - [ ] Transaction yönetimi (ACID compliance) - [ ] Connection pooling ve error handling @@ -458,6 +477,11 @@ channel_id = get_channel_id_from_handle(handle_url) enable_sbd: true paragraph_length: 3 + # FlareSolverr ayarları (YouTube IP blocking önleme için) + flaresolverr: + url: "http://192.168.1.27:8191/v1" # FlareSolverr API URL'i (devre dışı için null) + # veya environment variable: FLARESOLVERR_URL=http://192.168.1.27:8191/v1 + rss: title: "Channel Transcript Feed" description: "Full-text transcript RSS feed" @@ -624,12 +648,16 @@ jobs: ### 8.1. Performans Optimizasyonu **Görevler:** -- [ ] Paralel transcript çıkarımı (çoklu video için) -- [ ] Caching mekanizması -- [ ] Rate limiting yönetimi -- [ ] Batch processing optimizasyonu +- [x] Paralel transcript çıkarımı (çoklu video için) +- [x] Caching mekanizması (3 günlük transcript cache) +- [x] Rate limiting yönetimi (AIOLimiter ile async) +- [x] Batch processing optimizasyonu (5'şer batch'ler, 60-90 saniye bekleme) +- [x] FlareSolverr entegrasyonu (bot korumasını aşma) +- [x] Gerçek tarayıcı header'ları (User-Agent rotasyonu) +- [x] IP blocking yönetimi (dinamik bekleme, random delays) +- [x] Detaylı loglama sistemi -**Süre Tahmini**: 2-3 gün +**Süre Tahmini**: 2-3 gün (Tamamlandı) ### 8.2. Self-Hosted RSS-Bridge Deployment (Opsiyonel - Rate Limiting Sorunları İçin) @@ -670,7 +698,11 @@ jobs: ### 8.3. Monitoring ve Logging **Görevler:** -- [ ] Detaylı logging sistemi +- [x] Detaylı logging sistemi + - Python `logging` modülü entegrasyonu + - Kategorize edilmiş loglar: [RATE_LIMIT], [TRANSCRIPT], [PROCESS], [BATCH], [VIDEO], [CACHE], [FLARESOLVERR], [HEADERS] + - Timestamp'li, seviyeli log formatı (DEBUG, INFO, WARNING, ERROR) + - Docker logları ile kolay takip - [ ] Hata bildirimleri (email, webhook) - [ ] Feed health monitoring - [ ] İstatistikler (SQLite sorguları ile):