# 反检测工具使用指南

## 概述

`utils/anti_detection.py` 提供了统一的反自动化检测工具，供所有社交媒体上传器使用。

## 🎯 主要功能

### 1. 统一的反检测措施
- 标准化的浏览器启动参数
- 真实的用户代理字符串
- 合适的视口和环境设置
- 自动stealth脚本注入

### 2. 简化的API接口
- 一行代码创建反检测浏览器
- 统一的上下文配置
- 自动页面设置

### 3. 灵活的配置选项
- 支持有头/无头模式
- 可自定义浏览器参数
- 可自定义上下文选项

## 📚 API 参考

### 核心函数

#### `create_stealth_browser()`
```python
async def create_stealth_browser(
    playwright: Playwright,
    headless: bool = True,
    executable_path: Optional[str] = None,
    custom_args: Optional[List[str]] = None
) -> Browser
```

创建具有反检测功能的浏览器实例。

**参数：**
- `playwright`: Playwright实例
- `headless`: 是否使用无头模式（默认True）
- `executable_path`: 自定义浏览器路径（可选）
- `custom_args`: 额外的浏览器参数（可选）

#### `create_stealth_context()`
```python
async def create_stealth_context(
    browser: Browser,
    account_file: str,
    headless: bool = True,
    custom_options: Optional[Dict[str, Any]] = None
) -> BrowserContext
```

创建具有反检测功能的浏览器上下文。

**参数：**
- `browser`: Browser实例
- `account_file`: Cookie文件路径
- `headless`: 是否为无头模式
- `custom_options`: 自定义上下文选项（可选）

#### `setup_stealth_page()`
```python
async def setup_stealth_page(
    context: BrowserContext, 
    url: str
) -> Page
```

创建并设置具有反检测功能的页面。

**参数：**
- `context`: BrowserContext实例
- `url`: 要访问的URL

### 便捷函数

#### `quick_setup_stealth_browser()`
```python
async def quick_setup_stealth_browser(
    playwright: Playwright,
    account_file: str,
    target_url: str,
    headless: bool = True,
    executable_path: Optional[str] = None
) -> Tuple[Browser, BrowserContext, Page]
```

一键创建完整的反检测浏览器环境。

### 工具类

#### `SocialMediaUploader`
```python
class SocialMediaUploader:
    def __init__(self, headless: bool = True, executable_path: Optional[str] = None)
    
    async def create_browser_session(
        self, 
        playwright: Playwright, 
        account_file: str,
        target_url: str,
        custom_browser_args: Optional[List[str]] = None,
        custom_context_options: Optional[Dict[str, Any]] = None
    ) -> Tuple[Browser, BrowserContext, Page]
    
    async def close_session(self)
```

基础上传器类，提供完整的会话管理。

## 🔧 使用示例

### 1. 基础使用（推荐）

```python
from utils.anti_detection import create_stealth_browser, create_stealth_context, setup_stealth_page

async def upload(self, playwright: Playwright) -> None:
    # 创建反检测浏览器
    browser = await create_stealth_browser(
        playwright=playwright,
        headless=self.headless,
        executable_path=self.local_executable_path
    )
    
    # 创建反检测上下文
    context = await create_stealth_context(
        browser=browser,
        account_file=self.account_file,
        headless=self.headless
    )
    
    # 创建反检测页面
    page = await setup_stealth_page(context, "https://example.com")
    
    # 执行上传逻辑...
    
    # 清理
    await context.close()
    await browser.close()
```

### 2. 快速设置

```python
from utils.anti_detection import quick_setup_stealth_browser

async def upload(self, playwright: Playwright) -> None:
    browser, context, page = await quick_setup_stealth_browser(
        playwright=playwright,
        account_file=self.account_file,
        target_url="https://example.com",
        headless=self.headless,
        executable_path=self.local_executable_path
    )
    
    # 执行上传逻辑...
    
    # 清理
    await context.close()
    await browser.close()
```

### 3. 使用基础类

```python
from utils.anti_detection import SocialMediaUploader

class MyUploader(SocialMediaUploader):
    async def upload(self, playwright: Playwright) -> None:
        browser, context, page = await self.create_browser_session(
            playwright=playwright,
            account_file=self.account_file,
            target_url="https://example.com"
        )
        
        # 执行上传逻辑...
        
        await self.close_session()
```

## 🛡️ 反检测技术

### 浏览器参数
```python
STANDARD_BROWSER_ARGS = [
    '--no-sandbox',
    '--disable-blink-features=AutomationControlled',  # 核心
    '--disable-web-security',
    '--disable-features=VizDisplayCompositor',
    '--disable-dev-shm-usage',
    '--disable-infobars',
    '--disable-extensions',
    '--disable-gpu',
    '--no-first-run',
    '--no-default-browser-check',
    '--lang=zh-CN'
]
```

### 环境伪装
```python
DEFAULT_CONTEXT_OPTIONS = {
    'viewport': {'width': 1920, 'height': 1080},
    'locale': 'zh-CN',
    'timezone_id': 'Asia/Shanghai',
    'device_scale_factor': 1,
    'has_touch': False,
    'is_mobile': False
}
```

### 用户代理轮换
- 自动从真实浏览器用户代理池中选择
- 支持Chrome、Firefox等主流浏览器
- 定期更新保持时效性

## 🧪 测试

运行测试脚本验证功能：

```bash
python examples/test_anti_detection.py
```

测试内容包括：
- 基础功能测试
- 快速设置测试
- 配置信息验证
- 不同模式测试

## 🔄 迁移指南

### 从旧版本迁移

**旧代码：**
```python
browser_args = [
    '--no-sandbox',
    '--disable-blink-features=AutomationControlled',
    # ... 更多参数
]

browser = await playwright.chromium.launch(
    headless=self.headless, 
    executable_path=self.local_executable_path,
    args=browser_args
)

context_options = {
    'storage_state': f"{self.account_file}",
    'viewport': {'width': 1920, 'height': 1080},
    # ... 更多选项
}

context = await browser.new_context(**context_options)
context = await set_init_script(context)
page = await context.new_page()
await page.goto("https://example.com")
```

**新代码：**
```python
from utils.anti_detection import create_stealth_browser, create_stealth_context, setup_stealth_page

browser = await create_stealth_browser(
    playwright=playwright,
    headless=self.headless,
    executable_path=self.local_executable_path
)

context = await create_stealth_context(
    browser=browser,
    account_file=self.account_file,
    headless=self.headless
)

page = await setup_stealth_page(context, "https://example.com")
```

## 💡 最佳实践

1. **优先使用有头模式**：
   ```python
   headless=False  # 推荐，避免检测
   ```

2. **合理处理异常**：
   ```python
   try:
       browser, context, page = await quick_setup_stealth_browser(...)
       # 上传逻辑
   finally:
       await context.close()
       await browser.close()
   ```

3. **记录调试信息**：
   ```python
   from utils.anti_detection import get_anti_detection_info
   
   logger.info(f"反检测配置: {get_anti_detection_info()}")
   ```

4. **定期测试验证**：
   - 使用测试脚本验证功能
   - 监控上传成功率
   - 及时调整策略

## 🔮 未来计划

- [ ] 支持更多浏览器类型
- [ ] 动态指纹管理
- [ ] 智能检测规避
- [ ] 性能优化
- [ ] 更多测试用例

---

**注意**：反检测技术需要根据目标平台的变化进行调整，建议定期更新和测试。