# 브라우저 전략 가이드 (Lightpanda vs Chrome)

**버전**: 1.0
**작성일**: 2026-03-28
**담당**: 개발2팀 UX/UI

---

## 개요

시스템에는 두 가지 브라우저 백엔드가 존재합니다. 작업의 특성에 따라 적절한 브라우저를 선택하여 성능과 안정성을 최적화합니다.

### Lightpanda
- **연결**: `ws://127.0.0.1:9333`
- **관리**: systemd 사용자 서비스 (`systemctl --user status lightpanda`)
- **특징**: 텍스트 크롤링 전용, 매우 빠르고 가벼움
- **라이선스**: AGPL-3.0

### Chrome
- **로컬**: `ws://127.0.0.1:9222` (headless 모드)
- **원격**: `100.116.204.95:9222`
- **특징**: 완전한 렌더링 엔진, 스크린샷/PDF 지원, 로그인 세션 유지
- **사용**: Playwright CDP를 통해 접근

### 공통 레이어
모든 브라우저는 **Playwright CDP** 인터페이스로 통합됩니다.

---

## 브라우저 선택 전략표

| 용도 | 권장 브라우저 | 이유 |
|------|-------------|------|
| 대량 자동화 (뉴스 크롤링, 텍스트 추출) | Lightpanda | 11배 빠름, RAM 1/9 수준 |
| 병렬 작업 (여러 URL 동시 처리) | Chrome | Lightpanda는 concurrency=1 제한 |
| 리소스 절감 (서버 부하 최소화) | Lightpanda | 111MB vs 1GB+ |
| 로그인 필요 (Firebase, Meta, Google Ads 등) | Chrome | 쿠키/세션 유지 |
| 호환성 중요 (SPA, React, 복잡한 JS) | Chrome | 완전한 렌더링 엔진 |
| 봇 감지 우회 필요 | Chrome | User-Agent, 지문 등 모의 가능 |
| 스크린샷/PDF 캡처 | Chrome | Lightpanda 렌더링 불가 |

---

## 의사결정 트리

다음 질문에 따라 브라우저를 선택하세요:

```
1단계: 스크린샷/PDF 캡처 필요?
  ├─ YES → Chrome ✓
  └─ NO → 2단계로

2단계: 로그인/세션 유지 필요?
  ├─ YES → Chrome ✓
  └─ NO → 3단계로

3단계: SPA/복잡한 JavaScript?
  ├─ YES → Chrome ✓
  └─ NO → 4단계로

4단계: 봇 감지 우회 필요?
  ├─ YES → Chrome ✓
  └─ NO → 5단계로

5단계: 병렬 처리 필요 (동시 여러 URL)?
  ├─ YES → Chrome ✓
  └─ NO → Lightpanda ✓ (권장)
```

---

## 코드 사용법

### 1. browser_router.py 사용 (권장)

자동으로 적절한 브라우저를 선택합니다:

```python
from tools.browser_router import get_browser

# 텍스트 크롤링 → Lightpanda
browser = await get_browser("crawl")

# 스크린샷 → Chrome
browser = await get_browser("screenshot")

# 로그인 세션 → Chrome
browser = await get_browser("login")
```

**용도(purpose) 매핑**:
- `crawl`, `bulk`, `text`: Lightpanda (healthy일 때)
- `login`, `screenshot`, `pdf`, `spa`, `stealth`: Chrome

### 2. Lightpanda 직접 사용

텍스트 추출 전용:

```python
from tools.lightpanda_crawler import LightpandaCrawler

async with LightpandaCrawler() as crawler:
    result = await crawler.fetch("https://example.com")
    # result는 CrawlResult 데이터클래스
    text_content = result.text  # .title, .html, .links, .meta 등
```

**특징**:
- 텍스트만 추출 (HTML 렌더링 불가)
- Chrome fallback 내장 (Lightpanda 실패 시 자동 전환)

### 3. Chrome Playwright 직접 사용

완전한 렌더링과 상호작용:

```python
from playwright.async_api import async_playwright

async with async_playwright() as pw:
    browser = await pw.chromium.connect_over_cdp("ws://127.0.0.1:9222")
    page = await browser.new_page()

    # 페이지 탐색
    await page.goto("https://example.com")

    # 스크린샷 캡처
    await page.screenshot(path="output.png")

    # JavaScript 실행
    result = await page.evaluate("() => document.title")

    # 로그인 등 상호작용
    await page.fill("input[name='email']", "user@example.com")
    await page.click("button[type='submit']")

    await browser.close()
```

---

## 코드 아키텍처

### 주요 모듈

| 모듈 | 역할 | 사용 시점 |
|-----|------|----------|
| `tools/browser_router.py` | 용도에 따라 브라우저 선택 | 어떤 브라우저를 쓸지 불명확할 때 |
| `tools/lightpanda_crawler.py` | Lightpanda 래퍼 (텍스트 전용) | 텍스트 크롤링 전용 |
| `scripts/browser.py` | 원격 Chrome CDP CLI 도구 | 독립 실행, 테스트용 |
| Playwright | Chrome 직접 제어 | 스크린샷, 로그인, 복잡한 상호작용 |

### 관계도

```
browser_router.py (선택만 담당)
  ↓
  ├─→ lightpanda_crawler.py (텍스트 크롤링)
  │     └─→ Lightpanda WS (ws://127.0.0.1:9333)
  │
  └─→ Playwright (Chrome 제어)
        └─→ Chrome CDP (ws://127.0.0.1:9222)
```

---

## Lightpanda 제한사항

Lightpanda 선택 시 다음을 고려하세요:

| 제한사항 | 영향 | 해결책 |
|---------|------|-------|
| **concurrency=1** | 동시에 1개 연결만 가능 | 순차 처리 또는 Chrome 병렬 사용 |
| **스크린샷/PDF 불가** | 렌더링된 이미지 불가 | Chrome 필수 |
| **Cloudflare Turnstile 차단** | 일부 보호된 사이트 접근 불가 | Chrome으로 우회 필요 |
| **복잡한 SPA 미지원** | React 등 단순 동적 콘텐츠만 가능 | Chrome 권장 |
| **AGPL-3.0 라이선스** | 코드 공개 의무 | 내부 사용만 가능 |

---

## 서비스 관리

### Lightpanda 서비스

상태 확인:
```bash
systemctl --user status lightpanda
```

포트: `9333`

헬스체크:
```bash
curl -s http://127.0.0.1:9333/json/version
```

### Chrome Headless

로컬 CDP 포트: `9222`
원격 CDP 주소: `100.116.204.95:9222`

---

## 성능 비교

| 지표 | Lightpanda | Chrome |
|-----|-----------|--------|
| 메모리 | ~111MB | ~1GB+ |
| 처리 속도 | 11배 빠름 | 기준 |
| 동시 연결 | 1 | 무제한 |
| 렌더링 | 텍스트만 | 완전 |

---

## FAQ

**Q: 단순 텍스트만 필요한데 Lightpanda가 느리다면?**
A: 병렬 처리가 필요하다면 Chrome을 여러 개 병렬로 실행하거나, 배치 작업으로 순차 처리하되 시간을 분산하세요.

**Q: Chrome은 항상 안전한가?**
A: 로그인 정보는 로컬 저장되며, 원격 Chrome 사용 시 네트워크 보안을 확인하세요.

**Q: Lightpanda 서비스가 다운되면?**
A: browser_router와 lightpanda_crawler에는 자동 fallback이 내장되어 Chrome으로 전환됩니다.

**Q: 어떤 브라우저로 시작할지 모르겠으면?**
A: 위의 "의사결정 트리"를 따르거나, 확실하지 않으면 Chrome으로 시작하세요. 나중에 필요시 Lightpanda로 최적화할 수 있습니다.

---

## 참고

- Lightpanda 공식: https://lightpanda.io
- Playwright 문서: https://playwright.dev
- 문의: 개발2팀 UX/UI