Advanced Configuration - JinsongRoh/pydoll-mcp GitHub Wiki

⚙️ 고급 설정 - 성능 최적화 및 스텔스 설정

PyDoll MCP Server는 다양한 고급 설정을 통해 성능 최적화와 스텔스 기능을 제공합니다. 이 페이지에서는 전문적인 브라우저 자동화를 위한 고급 설정 방법을 안내합니다.

📋 목차

[환경 변수 설정](#환경-변수-설정)
[브라우저 성능 최적화](#브라우저-성능-최적화)
[스텔스 모드 설정](#스텔스-모드-설정)
[네트워크 최적화](#네트워크-최적화)
[캡차 우회 설정](#캡차-우회-설정)
[메모리 및 리소스 관리](#메모리-및-리소스-관리)
[디버깅 및 로깅](#디버깅-및-로깅)
[보안 및 개인정보 보호](#보안-및-개인정보-보호)

🔧 환경 변수 설정

기본 환경 변수

Claude Desktop 설정에서 환경 변수를 통해 서버 동작을 제어할 수 있습니다:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYDOLL_DEBUG": "false",
        "PYDOLL_HEADLESS": "true",
        "PYDOLL_STEALTH_MODE": "true",
        "PYDOLL_CAPTCHA_BYPASS": "true",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

고급 환경 변수

더 세밀한 제어를 위한 고급 환경 변수:

{
  "env": {
    "PYDOLL_MAX_BROWSERS": "3",
    "PYDOLL_MAX_TABS_PER_BROWSER": "5",
    "PYDOLL_TIMEOUT_DEFAULT": "30",
    "PYDOLL_RETRY_ATTEMPTS": "3",
    "PYDOLL_CACHE_ENABLED": "true",
    "PYDOLL_PERFORMANCE_MODE": "optimized",
    "PYDOLL_MEMORY_LIMIT": "2048",
    "PYDOLL_THREAD_POOL_SIZE": "10"
  }
}

🚀 브라우저 성능 최적화

성능 최적화 설정

브라우저 시작 시 성능을 최적화하기 위한 설정:

# 브라우저 시작 시 성능 최적화 옵션
performance_config = {
    "headless": True,                    # 헤드리스 모드 활성화
    "disable_images": True,              # 이미지 로딩 비활성화
    "disable_css": False,                # CSS는 유지 (레이아웃 유지)
    "disable_javascript": False,         # JavaScript 유지
    "disable_plugins": True,             # 플러그인 비활성화
    "disable_extensions": True,          # 확장 프로그램 비활성화
    "disable_dev_shm_usage": True,       # /dev/shm 사용 비활성화
    "disable_gpu": True,                 # GPU 가속 비활성화
    "no_sandbox": True,                  # 샌드박스 비활성화 (Docker용)
    "single_process": False,             # 단일 프로세스 모드
    "disable_background_timer_throttling": True,
    "disable_renderer_backgrounding": True,
    "disable_backgrounding_occluded_windows": True,
    "disable_features": [
        "VizDisplayCompositor",
        "TranslateUI",
        "BlinkGenPropertyTrees"
    ]
}

메모리 최적화

메모리 사용량을 줄이기 위한 설정:

memory_config = {
    "max_old_space_size": "2048",        # V8 엔진 메모리 제한
    "memory_pressure_off": True,        # 메모리 압박 알림 비활성화
    "max_unused_heap_memory": "64",     # 미사용 힙 메모리 제한
    "gc_interval": "100",               # 가비지 컬렉션 간격
    "disable_background_networking": True,
    "disable_background_timer_throttling": True,
    "disable_ipc_flooding_protection": True
}

렌더링 최적화

렌더링 성능을 향상시키기 위한 설정:

render_config = {
    "disable_2d_canvas_clip_aa": True,
    "disable_2d_canvas_image_chromium": True,
    "disable_accelerated_2d_canvas": True,
    "disable_accelerated_jpeg_decoding": True,
    "disable_accelerated_mjpeg_decode": True,
    "disable_accelerated_video_decode": True,
    "disable_gpu_video_decode": True,
    "use_gl": "swiftshader",            # 소프트웨어 렌더링 사용
    "disable_software_rasterizer": False
}

🕵️ 스텔스 모드 설정

기본 스텔스 설정

봇 탐지를 우회하기 위한 기본 스텔스 설정:

stealth_config = {
    "user_agent_randomization": True,    # 사용자 에이전트 무작위화
    "viewport_randomization": True,      # 뷰포트 크기 무작위화
    "timezone_spoofing": True,          # 시간대 스푸핑
    "language_spoofing": True,          # 언어 설정 스푸핑
    "webrtc_spoofing": True,            # WebRTC IP 숨기기
    "canvas_fingerprint_randomization": True,
    "webgl_fingerprint_randomization": True,
    "audio_fingerprint_randomization": True,
    "font_fingerprint_randomization": True,
    "screen_resolution_spoofing": True,
    "hardware_concurrency_spoofing": True,
    "device_memory_spoofing": True
}

고급 스텔스 기능

더 정교한 탐지 우회를 위한 고급 설정:

advanced_stealth_config = {
    "mouse_movement_humanization": True,  # 인간적인 마우스 움직임
    "typing_pattern_humanization": True,  # 인간적인 타이핑 패턴
    "scroll_behavior_humanization": True, # 인간적인 스크롤 동작
    "click_delay_randomization": True,    # 클릭 지연 무작위화
    "navigation_delay_randomization": True,
    "request_header_randomization": True,
    "tls_fingerprint_randomization": True,
    "browser_fingerprint_rotation": True,
    "proxy_rotation": True,              # 프록시 순환 사용
    "dns_over_https": True,             # DNS over HTTPS 사용
    "webdriver_property_removal": True,  # WebDriver 속성 제거
    "chrome_runtime_removal": True,     # Chrome 런타임 흔적 제거
    "notification_permission_spoofing": True,
    "geolocation_spoofing": True,
    "battery_api_spoofing": True,
    "media_device_spoofing": True
}

브라우저 프로파일 무작위화

브라우저 프로파일을 무작위화하여 탐지를 어렵게 만드는 설정:

profile_randomization = {
    "user_agents": [
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
    ],
    "screen_resolutions": [
        {"width": 1920, "height": 1080},
        {"width": 1366, "height": 768},
        {"width": 1440, "height": 900},
        {"width": 1536, "height": 864}
    ],
    "languages": ["en-US", "en-GB", "ko-KR", "ja-JP"],
    "timezones": [
        "America/New_York",
        "Europe/London", 
        "Asia/Tokyo",
        "Asia/Seoul"
    ]
}

🌐 네트워크 최적화

네트워크 설정

네트워크 성능과 안정성을 위한 설정:

network_config = {
    "timeout": 30,                      # 기본 타임아웃 (초)
    "retry_attempts": 3,                # 재시도 횟수
    "retry_delay": 1,                   # 재시도 간격 (초)
    "connection_pool_size": 100,        # 연결 풀 크기
    "max_connections_per_host": 10,     # 호스트당 최대 연결
    "enable_http2": True,               # HTTP/2 활성화
    "enable_compression": True,         # 압축 활성화
    "tcp_nodelay": True,                # TCP 지연 없음
    "tcp_keepalive": True,              # TCP 연결 유지
    "dns_cache_timeout": 300,           # DNS 캐시 타임아웃
    "request_cache_enabled": True,      # 요청 캐시 활성화
    "response_cache_enabled": True,     # 응답 캐시 활성화
    "cache_max_size": "100MB",          # 캐시 최대 크기
    "bandwidth_throttling": False,      # 대역폭 제한
    "latency_simulation": False         # 지연 시뮬레이션
}

프록시 설정

프록시 서버를 통한 네트워크 라우팅:

proxy_config = {
    "enabled": True,
    "type": "socks5",                   # http, socks4, socks5
    "host": "127.0.0.1",
    "port": 9050,
    "username": None,
    "password": None,
    "rotation_enabled": True,           # 프록시 순환 사용
    "rotation_interval": 300,           # 순환 간격 (초)
    "proxy_list": [
        {"host": "proxy1.example.com", "port": 8080},
        {"host": "proxy2.example.com", "port": 8080}
    ],
    "bypass_list": [                    # 프록시 우회 목록
        "localhost",
        "127.0.0.1",
        "*.local"
    ]
}

🔐 캡차 우회 설정

Cloudflare 우회 설정

Cloudflare Turnstile 캡차 우회를 위한 설정:

cloudflare_config = {
    "enabled": True,
    "auto_solve": True,                 # 자동 해결 활성화
    "solve_timeout": 30,                # 해결 타임아웃 (초)
    "retry_attempts": 3,                # 재시도 횟수
    "human_behavior_simulation": True,  # 인간 행동 시뮬레이션
    "mouse_movement_realistic": True,   # 현실적인 마우스 움직임
    "click_timing_randomization": True, # 클릭 타이밍 무작위화
    "challenge_detection_delay": 2,     # 챌린지 감지 지연 (초)
    "success_verification_delay": 3,    # 성공 확인 지연 (초)
    "failure_retry_delay": 5,           # 실패 시 재시도 지연 (초)
    "debug_mode": False,                # 디버그 모드
    "screenshot_on_failure": True       # 실패 시 스크린샷 저장
}

reCAPTCHA 우회 설정

reCAPTCHA v3 우회를 위한 설정:

recaptcha_config = {
    "enabled": True,
    "v3_enabled": True,                 # reCAPTCHA v3 지원
    "v2_enabled": True,                 # reCAPTCHA v2 지원
    "invisible_enabled": True,          # 비가시적 reCAPTCHA 지원
    "solve_timeout": 45,                # 해결 타임아웃 (초)
    "score_threshold": 0.5,             # v3 점수 임계값
    "audio_challenge_enabled": True,    # 오디오 챌린지 지원
    "image_challenge_enabled": True,    # 이미지 챌린지 지원
    "ai_solver_enabled": True,          # AI 해결사 사용
    "manual_fallback": False,           # 수동 해결 대체
    "challenge_retry_limit": 5,         # 챌린지 재시도 제한
    "success_rate_tracking": True,      # 성공률 추적
    "performance_monitoring": True      # 성능 모니터링
}

💾 메모리 및 리소스 관리

메모리 관리 설정

메모리 사용량을 효율적으로 관리하기 위한 설정:

memory_management = {
    "max_memory_usage": "2048MB",       # 최대 메모리 사용량
    "memory_cleanup_interval": 300,     # 메모리 정리 간격 (초)
    "tab_memory_limit": "512MB",        # 탭당 메모리 제한
    "cache_memory_limit": "256MB",      # 캐시 메모리 제한
    "garbage_collection_aggressive": True,
    "memory_pressure_handling": True,
    "oom_protection": True,             # Out of Memory 보호
    "swap_usage_limit": "1024MB",       # 스왑 사용량 제한
    "memory_leak_detection": True,      # 메모리 누수 감지
    "resource_monitoring": True,        # 리소스 모니터링
    "auto_cleanup_enabled": True,       # 자동 정리 활성화
    "cleanup_threshold": 80             # 정리 임계값 (%)
}

리소스 최적화

시스템 리소스 사용량을 최적화하기 위한 설정:

resource_optimization = {
    "cpu_usage_limit": 80,              # CPU 사용량 제한 (%)
    "thread_pool_size": 10,             # 스레드 풀 크기
    "process_priority": "normal",       # 프로세스 우선순위
    "disk_cache_size": "1GB",           # 디스크 캐시 크기
    "temp_file_cleanup": True,          # 임시 파일 정리
    "log_rotation_enabled": True,       # 로그 순환 활성화
    "log_max_size": "100MB",            # 로그 최대 크기
    "log_retention_days": 7,            # 로그 보존 기간
    "resource_monitoring_interval": 60, # 리소스 모니터링 간격 (초)
    "auto_scaling_enabled": True,       # 자동 스케일링 활성화
    "load_balancing": True,             # 로드 밸런싱 활성화
    "connection_pooling": True          # 연결 풀링 활성화
}

🔍 디버깅 및 로깅

로깅 설정

상세한 로깅을 위한 설정:

logging_config = {
    "level": "INFO",                    # DEBUG, INFO, WARNING, ERROR, CRITICAL
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "file_logging": True,               # 파일 로깅 활성화
    "console_logging": True,            # 콘솔 로깅 활성화
    "log_file": "pydoll_mcp.log",       # 로그 파일 이름
    "max_file_size": "10MB",            # 최대 파일 크기
    "backup_count": 5,                  # 백업 파일 수
    "rotation_interval": "daily",       # 순환 간격
    "structured_logging": True,         # 구조화된 로깅
    "json_format": False,               # JSON 형식
    "include_stack_trace": True,        # 스택 트레이스 포함
    "log_requests": True,               # HTTP 요청 로깅
    "log_responses": True,              # HTTP 응답 로깅
    "log_errors": True,                 # 오류 로깅
    "log_performance": True,            # 성능 로깅
    "sensitive_data_masking": True      # 민감한 데이터 마스킹
}

디버깅 도구

개발 및 디버깅을 위한 도구 설정:

debugging_config = {
    "debug_mode": False,                # 디버그 모드
    "verbose_logging": False,           # 상세 로깅
    "screenshot_on_error": True,        # 오류 시 스크린샷
    "save_page_source": True,           # 페이지 소스 저장
    "network_logging": True,            # 네트워크 로깅
    "console_logging": True,            # 브라우저 콘솔 로깅
    "performance_profiling": True,      # 성능 프로파일링
    "memory_profiling": True,           # 메모리 프로파일링
    "execution_tracing": True,          # 실행 추적
    "step_by_step_debugging": False,    # 단계별 디버깅
    "breakpoint_enabled": False,        # 중단점 활성화
    "interactive_debugging": False,     # 대화형 디버깅
    "debug_output_dir": "./debug",      # 디버그 출력 디렉토리
    "debug_session_recording": True     # 디버그 세션 녹화
}

🛡️ 보안 및 개인정보 보호

보안 설정

브라우저 보안을 강화하기 위한 설정:

security_config = {
    "disable_web_security": False,      # 웹 보안 비활성화 (개발용)
    "disable_features": [
        "VizDisplayCompositor",
        "TranslateUI",
        "MediaRouter"
    ],
    "enable_features": [
        "NetworkService",
        "VizServiceDisplay"
    ],
    "certificate_transparency": True,   # 인증서 투명성
    "hsts_enabled": True,               # HSTS 활성화
    "mixed_content_blocking": True,     # 혼합 콘텐츠 차단
    "insecure_content_blocking": True,  # 비보안 콘텐츠 차단
    "xss_protection": True,             # XSS 보호
    "content_security_policy": True,    # CSP 활성화
    "referrer_policy": "strict-origin-when-cross-origin",
    "permissions_policy": True,         # 권한 정책 활성화
    "feature_policy": True,             # 기능 정책 활성화
    "sandbox_enabled": True,            # 샌드박스 활성화
    "site_isolation": True              # 사이트 격리
}

개인정보 보호 설정

개인정보를 보호하기 위한 설정:

privacy_config = {
    "do_not_track": True,               # Do Not Track 활성화
    "disable_background_sync": True,    # 백그라운드 동기화 비활성화
    "disable_background_fetch": True,   # 백그라운드 페치 비활성화
    "disable_push_messaging": True,     # 푸시 메시징 비활성화
    "disable_notifications": True,      # 알림 비활성화
    "disable_geolocation": True,        # 위치 정보 비활성화
    "disable_camera": True,             # 카메라 비활성화
    "disable_microphone": True,         # 마이크 비활성화
    "disable_sensors": True,            # 센서 비활성화
    "disable_webrtc": True,             # WebRTC 비활성화
    "disable_webgl": True,              # WebGL 비활성화
    "disable_canvas_reading": True,     # 캔버스 읽기 비활성화
    "disable_font_access": True,        # 폰트 접근 비활성화
    "disable_clipboard_access": True,   # 클립보드 접근 비활성화
    "clear_data_on_exit": True,         # 종료 시 데이터 정리
    "incognito_mode": True,             # 시크릿 모드
    "private_browsing": True            # 개인 브라우징
}

🎯 성능 모니터링 및 최적화

성능 모니터링

실시간 성능 모니터링을 위한 설정:

performance_monitoring = {
    "enabled": True,
    "metrics_collection": True,         # 메트릭 수집
    "response_time_tracking": True,     # 응답 시간 추적
    "resource_usage_tracking": True,    # 리소스 사용량 추적
    "memory_usage_tracking": True,      # 메모리 사용량 추적
    "network_usage_tracking": True,     # 네트워크 사용량 추적
    "error_rate_tracking": True,        # 오류율 추적
    "success_rate_tracking": True,      # 성공률 추적
    "throughput_tracking": True,        # 처리량 추적
    "latency_tracking": True,           # 지연 시간 추적
    "concurrent_connections": True,     # 동시 연결 수 추적
    "alert_thresholds": {
        "cpu_usage": 80,                # CPU 사용량 임계값 (%)
        "memory_usage": 85,             # 메모리 사용량 임계값 (%)
        "error_rate": 5,                # 오류율 임계값 (%)
        "response_time": 30             # 응답 시간 임계값 (초)
    },
    "reporting_interval": 60,           # 보고 간격 (초)
    "dashboard_enabled": True,          # 대시보드 활성화
    "export_metrics": True,             # 메트릭 내보내기
    "metric_retention": 30              # 메트릭 보존 기간 (일)
}

자동 최적화

자동 성능 최적화를 위한 설정:

auto_optimization = {
    "enabled": True,
    "adaptive_timeout": True,           # 적응형 타임아웃
    "dynamic_retry": True,              # 동적 재시도
    "load_balancing": True,             # 로드 밸런싱
    "auto_scaling": True,               # 자동 스케일링
    "resource_allocation": True,        # 리소스 할당 최적화
    "cache_optimization": True,         # 캐시 최적화
    "connection_pooling": True,         # 연결 풀링 최적화
    "memory_optimization": True,        # 메모리 최적화
    "cpu_optimization": True,           # CPU 최적화
    "network_optimization": True,       # 네트워크 최적화
    "optimization_interval": 300,       # 최적화 간격 (초)
    "performance_baseline": True,       # 성능 기준선 설정
    "anomaly_detection": True,          # 이상 감지
    "predictive_optimization": True,    # 예측 최적화
    "ml_optimization": False            # 머신러닝 최적화
}

📝 설정 예시

최고 성능 모드

최고 성능을 위한 설정 예시:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "WARNING",
        "PYDOLL_HEADLESS": "true",
        "PYDOLL_DISABLE_IMAGES": "true",
        "PYDOLL_DISABLE_CSS": "true",
        "PYDOLL_DISABLE_JAVASCRIPT": "false",
        "PYDOLL_MAX_BROWSERS": "5",
        "PYDOLL_MAX_TABS": "10",
        "PYDOLL_MEMORY_LIMIT": "4096",
        "PYDOLL_PERFORMANCE_MODE": "maximum",
        "PYDOLL_CACHE_ENABLED": "true",
        "PYDOLL_COMPRESSION": "true",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

최고 스텔스 모드

최고 스텔스를 위한 설정 예시:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "ERROR",
        "PYDOLL_STEALTH_MODE": "maximum",
        "PYDOLL_FINGERPRINT_RANDOMIZATION": "true",
        "PYDOLL_USER_AGENT_ROTATION": "true",
        "PYDOLL_PROXY_ROTATION": "true",
        "PYDOLL_HUMAN_BEHAVIOR": "true",
        "PYDOLL_CAPTCHA_BYPASS": "true",
        "PYDOLL_ANTI_DETECTION": "true",
        "PYDOLL_CANVAS_SPOOFING": "true",
        "PYDOLL_WEBGL_SPOOFING": "true",
        "PYDOLL_TIMEZONE_SPOOFING": "true",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

균형 모드

성능과 스텔스의 균형을 맞춘 설정 예시:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYDOLL_HEADLESS": "true",
        "PYDOLL_STEALTH_MODE": "balanced",
        "PYDOLL_PERFORMANCE_MODE": "balanced",
        "PYDOLL_CAPTCHA_BYPASS": "true",
        "PYDOLL_DISABLE_IMAGES": "false",
        "PYDOLL_MAX_BROWSERS": "3",
        "PYDOLL_MAX_TABS": "5",
        "PYDOLL_MEMORY_LIMIT": "2048",
        "PYDOLL_HUMAN_BEHAVIOR": "true",
        "PYDOLL_USER_AGENT_ROTATION": "true",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

🔄 설정 적용 방법

1. Claude Desktop 설정 파일 수정

설정 파일 위치:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. 환경 변수 설정

시스템 환경 변수로 설정:

# Windows
set PYDOLL_LOG_LEVEL=INFO
set PYDOLL_STEALTH_MODE=true

# Linux/macOS
export PYDOLL_LOG_LEVEL=INFO
export PYDOLL_STEALTH_MODE=true

3. 설정 검증

설정이 올바르게 적용되었는지 확인:

python -m pydoll_mcp.cli test-installation --verbose
python -m pydoll_mcp.cli status --config

🚨 주의사항

성능 vs 스텔스 트레이드오프

고성능 모드: 빠른 실행이지만 탐지 가능성 증가
고스텔스 모드: 탐지 회피 우수하지만 성능 저하
균형 모드: 성능과 스텔스의 적절한 균형

메모리 관리

메모리 제한 설정을 너무 낮게 하면 성능 저하 발생
시스템 메모리의 50-70% 이하로 제한 권장

법적 및 윤리적 고려사항

웹사이트의 이용약관 및 robots.txt 준수
과도한 요청으로 서버 부하 방지
개인정보 보호 및 데이터 처리 정책 준수

이 고급 설정을 통해 PyDoll MCP Server를 최적화하여 더 효율적이고 안전한 브라우저 자동화를 구현할 수 있습니다.