nukking/amazon-scraper repository overview

⁠Amazon Scraper

SessionBridge 허브와 Browserless 웹소켓을 결합하여 대규모 아마존 상품 리스트 및 상세 페이지 생성을 목적으로 하는 강건한(Robust) 스크래퍼 템플릿입니다.

⁠기능 스펙

• 도메인 분리: ProductParser 가 Buybox, Review, Variant 등의 하위 도메인별 파서로 완전히 모듈화되어 있습니다.
• 성능 최적화: Request Interception 기술을 빌트인하여 페이지 렌더링에 불필요한 리소스를 강제 차단합니다. 이미지/스크립트 파싱 생략 등 극한의 속도 튜닝 옵션 제공.
• 오류 복원력 강화: Captcha / 로봇 탐지 시 즉각 BotDetectedError 를 throw하며 409, 404 통신 에러 등 인프라 에러 시 가시성 높은 에러 원인을 제공합니다.
• 프록시 오버라이드 지원: 타겟팅 국가 코드(US, KR) 변경을 CLI에서 즉시 덮어쓸 수 있습니다.

⁠시작하기

⁠1. 인프라 기동 (Docker)

로컬에 Browserless 렌더링 컨테이너를 올립니다.

docker-compose up -d

⁠2. 패키지 설치

npm install

⁠3. 환경 변수 설정

최상단 디렉토리에 .env 파일을 구성해야 합니다. 가장 중요한 속성값은 아래와 같습니다.

# 기본 SessionBridge 타겟 국가 및 프록시 설정
COUNTRY_CODE=US
PROXY_ENABLED=false
PROXY_URL=http://<YOUR_PROXY_IP>:<PORT>

# SessionBridge Hub 연결 권한
SESSION_BRIDGE_HUB_URL=http://<YOUR_IP>:3003/
SESSION_BRIDGE_API_KEY=dev-api-key-change-in-production
SESSION_BRIDGE_CLIENT_ID=amazon-scraper-worker-1

# 스크린샷 남기기 여부
SCREENSHOT_ENABLED=true

⁠CLI 명령어 모음

모든 수집 및 제어 로직은 단일 진입점 bin/amazon-scraper.js을 통해 제공됩니다.

⁠명령어 구조

node bin/amazon-scraper.js <명령어> [옵션]

명령어 종류:

• list: 상품 리스트 수집 (키워드 또는 URL 기준)
• product: 단일 상품 상세 정보 수집 (ASIN 또는 URL 기준)
• batch: (list 실행 후 product 연속 수집) 일괄 수집 파이프라인

⁠공통 제어 플래그 (모든 명령어 사용 가능)

속도 최적화 및 디버깅, 프록시 타겟팅을 위해 모든 명령어에 공통으로 덧붙일 수 있는 플래그들입니다.

⁠1. [List 명령어] 리스트 검색 수집

키워드, 혹은 카테고리 URL로 진입하여 여러 개의 상품 정보(간략)들을 추출합니다.

전용 옵션:

• -k, --keyword : 검색 키워드 (이것 또는 -u 필수)
• -u, --url : 검색 결과를 직접 지정할 리스팅 URL
• -p, --pages : 수집할 최대 페이지 수 (기본값: 1)
• -n, --max : 수집할 최대 상품 수 (기본값: 30)

사용 예시:

# 기본 검색 (기본 1페이지 최대 30개 수집)
node bin/amazon-scraper.js list -k "laptop"

# 한국(KR) 세션을 사용하여 최대 2페이지 100개까지 수집 + 스폰서 광고 상품 무시 + 이미지 로드 끄기
node bin/amazon-scraper.js list -k "keyboard" -n 100 -p 2 -c KR -s -i

⁠2. [Product 명령어] 상품 상세 수집

선택한 특정 단일 상품(ASIN 참조)에 접속하여 스펙, 옵션, 리뷰 등 모든 세부 상세 정보를 긁어옵니다.

전용 옵션:

• -a, --asin : 수집할 대상 상품의 ASIN 문자열 (이것 또는 -u 필수)
• -u, --url : 직접 지정할 상품 상세 페이지 URL

사용 예시:

# ASIN 기준 기본 단일 조회
node bin/amazon-scraper.js product -a B07V5K6LSF

# 상품 상세 정보가 필요하나 옵션(Variant)과 이미지 파싱 로직을 건너뛰어 초경량의 속도로 응답받기
node bin/amazon-scraper.js product -a B07V5K6LSF -v -i

⁠3. [Batch 명령어] 원스톱 파이프라인 자동화

별도 코드 구축 없이 list 작업 후 획득한 URL들을 순차적으로 product로 밀어넣어 일괄 수집하는 강력한 명령어입니다. 결과를 하나로 모아 results/batch_***.json 단위로 도출해냅니다.

전용 옵션:

• -k, --keyword / -u, --url : 검색 타겟
• -p, --pages / -n, --max : 1단계(리스트) 탐색 범위 (배치의 기본 max값은 10개입니다)
• -d, --delay : 상품 상세 페이지 진입 전 각 스크래핑 사이에 둘 딜레이 ms (기본값: 2000)

사용 예시:

# "usb hub"를 1페이지에서 5개 수집한 뒤, 1초(1000ms) 딜레이 간격으로 상세 옵션 파싱 전부 제외(-v)하고 실행
node bin/amazon-scraper.js batch -k "usb hub" -n 5 -p 1 -d 1000 -v

(참고: 배치 작업 시 활성화된 SessionBridge 쿠키가 즉각 확보되지 않는 경우 404 혹은 409 통신 에러를 반환하며 중단될 수 있습니다. 터미널의 에러 로그 지침에 따라 봇 타겟팅 국가 및 세션 가용량을 확인하세요.)

⁠디렉토리 구조

• bin/amazon-scraper.js : 통합 애플리케이션 CLI 진입 스크립트
• src/scraper.js : 통합 스크래핑 제어 코어 및 HTTP 세션 모듈
• src/list-parser.js : 리스트 및 카테고리 HTML 페이지 분석 로직
• src/product-parser.js : 옵션 처리 및 서브 파서들을 감싸는 상세 분석 Facade
• src/parsers/ : 도메인별 (Buybox, Review, Image, Variant 등) 순수 파서 모듈 모음
• src/utils/ : BrowserManager, FileManager 기반 인프라 로직 분리 모음
• _tests/ : 과거 실험용 스크립트 및 디버그용 파일 모음 (현재 미사용)
• results/ : JSON 저장 폴더
• screenshots/ : 캡처 파일 저장 영역