autoUpload/utils/README_anti_detection.md

反检测工具使用指南

概述

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

🎯 主要功能

1. 统一的反检测措施

• 标准化的浏览器启动参数
• 真实的用户代理字符串
• 合适的视口和环境设置
• 自动stealth脚本注入

2. 简化的API接口

• 一行代码创建反检测浏览器
• 统一的上下文配置
• 自动页面设置

3. 灵活的配置选项

• 支持有头/无头模式
• 可自定义浏览器参数
• 可自定义上下文选项

📚 API 参考

核心函数

create_stealth_browser()

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()

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()

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

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

参数：

• context: BrowserContext实例
• url: 要访问的URL

便捷函数

quick_setup_stealth_browser()

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

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. 基础使用（推荐）

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. 快速设置

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. 使用基础类

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()

🛡️ 反检测技术

浏览器参数

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'
]

环境伪装

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等主流浏览器
• 定期更新保持时效性

🧪 测试

运行测试脚本验证功能：

python examples/test_anti_detection.py

测试内容包括：

• 基础功能测试
• 快速设置测试
• 配置信息验证
• 不同模式测试

🔄 迁移指南

从旧版本迁移

旧代码：

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")

新代码：

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. 优先使用有头模式：

   headless=False  # 推荐，避免检测
   

2. 合理处理异常：

   try:
       browser, context, page = await quick_setup_stealth_browser(...)
       # 上传逻辑
   finally:
       await context.close()
       await browser.close()
   

3. 记录调试信息：

   from utils.anti_detection import get_anti_detection_info
   
   logger.info(f"反检测配置: {get_anti_detection_info()}")
   

4. 定期测试验证：

   • 使用测试脚本验证功能
   • 监控上传成功率
   • 及时调整策略

🔮 未来计划

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

---

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