---
name: "lightpanda-crawl"
description: "Lightpanda 헤드리스 브라우저 기반 초고속 대량 텍스트 크롤링"
category: "development"
---

# lightpanda-crawl

대량 크롤링 시 사용하는 스킬. Lightpanda 헤드리스 브라우저 기반 초고속 텍스트 크롤링 전용.

## 래퍼 모듈
- 경로: `/home/jay/workspace/tools/lightpanda_crawler.py`
- CDP 엔드포인트: `ws://127.0.0.1:9333`

## 사용 예시

### 단일 페이지 크롤링
```python
from tools.lightpanda_crawler import LightpandaCrawler

async with LightpandaCrawler() as crawler:
    result = await crawler.fetch("https://example.com")
    print(result.title)   # 페이지 제목
    print(result.text)    # 텍스트 전문
    print(result.links)   # 링크 목록
```

### 대량 순차 크롤링
```python
async with LightpandaCrawler() as crawler:
    urls = ["https://example.com/1", "https://example.com/2", ...]
    # ⚠️ Lightpanda는 단일 context 제한으로 concurrency=1만 안정적
    results = await crawler.fetch_many(urls, concurrency=1)
```

### JS 실행 후 데이터 추출
```python
async with LightpandaCrawler() as crawler:
    data = await crawler.evaluate("https://example.com", "document.title")
```

### CSS 셀렉터 기반 구조화 추출
```python
async with LightpandaCrawler() as crawler:
    data = await crawler.extract_structured("https://example.com", {
        "title": "h1",
        "description": "meta[name=description]::attr(content)",
        "links": "a[href]::attr(href)"
    })
```

## 주의사항
- **스크린샷 불가**: Lightpanda는 렌더링 엔진이 없어 스크린샷/PDF를 생성할 수 없음. 스크린샷이 필요하면 Playwright+Chrome 사용.
- **병렬 크롤링 불가**: Lightpanda는 단일 browser context만 지원. `concurrency=1`로 순차 처리 필수. 병렬이 필요하면 Chrome 사용.
- **대용량 페이지 주의**: 1MB 이상 HTML(예: 위키백과 한글 문서)에서 TargetClosedError 발생 가능. Chrome fallback으로 자동 복구되나, 대용량 페이지는 Chrome 직접 사용 권장.
- **Cloudflare 차단**: Cloudflare Turnstile 등 봇 방지 기능이 있는 사이트는 크롤링 불가.
- **복잡한 SPA**: React/Vue 등 복잡한 SPA는 부분적으로 미지원될 수 있음.
- **라이선스**: AGPL-3.0. 내부 사용 OK, SaaS 제공 시 소스 공개 의무.

## Chrome Fallback
Lightpanda 서버에 연결할 수 없으면 자동으로 Chrome headless(port 9222)로 전환됨.
전환 시 로그에 경고 메시지가 출력됨.

## 성능 비교 (실측, 2026-03-25)
- 단일 페이지 속도: Lightpanda 47ms vs Chrome 980ms (example.com 기준, 약 20배)
- 메모리: 서버 상주 1MB (Chrome 대비 약 9배 절약)
- 12개 URL 순차 크롤링: 평균 545ms/페이지, 총 6.5초
- ⚠️ 병렬 크롤링: Lightpanda 불가 (단일 context). Chrome은 병렬 가능.