TL;DR

이 레포는 Playwright로 Xianyu 웹을 자동 크롤링하고 OpenAI 호환 멀티모달 모델로 상품 텍스트와 이미지를 분석해 웹 UI에서 실시간 및 정기 모니터링, 알림 전송을 제공하는 Docker 중심의 통합 솔루션이다. FastAPI를 백엔드로 사용하고 SQLite를 기본 저장소로 채택해 초기 설치와 로컬 운영이 간편하며 Docker 이미지에 Chromium을 포함해 브라우저 의존성을 제거했다. 작업 단위로 AI 기준 생성, 키워드 규칙, 지역·가격 필터, 계정·프록시 회전을 조합해 대규모 모니터링의 안정성을 확보하도록 설계되었으며 알림은 ntfy.sh·企业微信·Bark·Telegram·Webhook 등으로 전달된다. 단점으로는 OpenAI 호환 모델 API 키와 모델 사용이 필수이며, 고빈도·대규모 수집 환경에서는 SQLite 대신 외부 DB 전환이 권장된다.

주요 기능

• 작업을 생성하고 관리하는 웹 UI를 제공하며 작업별 키워드, 가격 범위, 지역 셀렉터, 정시 스케줄을 세부 설정할 수 있다. UI는 작업 상태·로그·결과 브라우징을 지원해 운영 상태를 한 곳에서 확인할 수 있다. AI 기반 판정과 키워드 규칙을 병행해 자동화된 필터링을 바로 적용할 수 있다.
• Playwright 기반 크롤러가 검색·페이징·상세 페이지 진입을 자동화하고 상품 이미지와 메타를 로컬에 임시 저장한다. 크롤러는 계정 컨텍스트와 프록시를 분리해 다중 계정 병행 작업에서 세션 충돌을 최소화한다. Docker 이미지에 Chromium이 내장되어 별도 브라우저 설치 없이 컨테이너에서 곧바로 실행된다.
• OpenAI 호환 모델을 통한 멀티모달 분석을 백그라운드 job으로 실행해 AI 판단 기준을 생성하고 개별 결과에 추천 태그를 붙인다. AI 호출은 비동기 처리로 작업 제출 후 별도 프로그래스 팝업을 통해 진행 상황을 확인하도록 설계되어 응답 지연으로 인한 UI 정지를 피한다. 모델 엔드포인트와 API 키는 환경변수로 분리되어 배포 시 교체가 가능하다.
• 알림 채널로 ntfy.sh, 企业微信, Bark, Telegram, Webhook 등을 지원해 AI 추천 또는 규칙 적중 시 즉시 통보를 보낼 수 있다. 알림은 작업별로 토글 가능하며 실패 재시도 및 전송 로그를 관리할 수 있다. 다양한 전송 옵션을 통해 수신 환경에 맞춘 통합 알림이 가능하다.
• 프록시 풀과 계정 회전 로직을 통해 풍부한 실패 대응을 제공하며 작업 실패 임계치와 일시 중지 규칙으로 반복 실패 시 자동 완화 동작을 수행한다. 작업이 풍부한 페이싱이나 차단을 만날 때 자동으로 다른 계정/프록시로 전환해 재시도를 시도한다. 이 기능은 대량 모니터링에서 지속성을 확보하는 데 초점을 맞추었다.

어떻게 동작하는가

사용자가 UI에서 작업을 생성하면 FastAPI 기반 백엔드가 작업을 스케줄링하거나 즉시 Playwright 스파이더를 실행해 Xianyu 페이지를 순회하며 상품 목록과 상세 이미지를 수집한다. 수집된 데이터는 SQLite에 저장되며 상품 이미지와 텍스트는 OpenAI 호환 모델로 전송되어 멀티모달 분석을 수행한 뒤 추천·위험 태그와 판단 근거를 기록하고 필요 시 외부 알림 채널로 전달한다.

해결 문제

Xianyu(闲鱼) 같은 대형 중고 거래 플랫폼에서 수동 검색으로는 놓치기 쉬운 희소 상품과 조건에 맞는 매물을 자동으로 탐지하는 문제를 해결한다. 또한 크롤링·계정관리·모델기준 생성·알림 전송 등 운영 전반을 통합된 웹 UI와 Docker 배포로 간소화한다.

차별점

• 웹 기반 완결형 관리 인터페이스를 내장해 작업 생성, AI 기준 편집, 로그 확인, 결과 브라우징을 단일 애플리케이션에서 수행할 수 있다. 대부분 스크립트형 모니터와 달리 비개발자도 설정을 조작해 워크플로를 운영할 수 있다. UI는 작업별 진행 상태와 결과를 시계열로 보여 운영성을 높였다.
• Docker 이미지에 Chromium을 포함해 컨테이너 단위로 브라우저 의존성을 해결하므로 초기 배포 시 브라우저 설치 관련 오류를 줄인다. 이 방식은 로컬·서버 환경 간 설정 차이를 줄여 반복 가능한 배포를 가능하게 한다. 또한 docker-compose로 전체 스택을 원클릭 기동할 수 있도록 제공된다.
• 멀티모달 AI 분석을 작업 생성 파이프라인에 통합해 단순 키워드 필터링보다 더 풍부한 상품 판별 정보를 생성한다. AI 기반 생성 규칙과 수동 키워드 규칙을 병행해 유연한 트리거 구성이 가능하다. AI 생성 작업은 백그라운드 job으로 처리되어 사용자 인터페이스의 응답성을 보장한다.
• 계정 바인딩과 프록시 풀 회전, 실패 임계치 기반 대체 로직을 내장해 장시간 대규모 크롤링 운영에서 세션 및 차단 문제에 대응하는 기능을 제공한다. 단일 계정 의존형 접근보다 재시도와 회복력이 뛰어나다. 이로 인해 장기 모니터링 작업의 안정성이 개선된다.

사용 사례

• 희귀 모델이나 특정 가격대의 중고 제품을 자동으로 감시하고 새 매물이 등록되면 즉시 알림을 받을 목적으로 사용할 수 있다. 키워드와 지역, 가격 조건을 조합해 타깃 필터를 설정하면 사람이 상시 모니터링하지 않아도 조건 적합 상품만 선별해서 볼 수 있다. AI 판단을 결합하면 사진 기반 상태 불일치나 의심스러운 판매 이력을 자동으로 표시할 수 있다.
• 중고 제품 리셀러가 다수 계정으로 시장을 폭넓게 감시하고 가격 변동을 데이터베이스에 축적해 가격 히스토리를 기반으로 매입 타이밍을 결정하는 데 활용할 수 있다. 수집된 가격 히스토리는 단일 파일 기반 SQLite에 저장되어 간단한 분석을 빠르게 수행할 수 있다. 일정 주기로 데이터를 내보내 CSV로 추출해 외부 분석 도구와 연계할 수 있다.
• 제품 연구나 시장조사 목적으로 특정 키워드군의 공급·가격 추세를 장기간 수집하는 데 적합하다. Cron 기반 정기 작업으로 주기적인 스냅샷을 자동 수집하고 AI 분석 결과를 누적해 트렌드 리포트를 만들 수 있다. 알림 기능을 통해 이상 변동 발생 시 즉시 운영자에게 통보할 수 있다.

시작하기

레포를 클론한 뒤 .env.example을 복사해 .env에 OpenAI API 키와 모델 이름, 웹 인증 정보를 설정하고 docker compose up -d로 전체 스택을 기동하면 기본 UI를 통해 즉시 접근이 가능하다. 개발 환경에서는 python -m src.app 또는 uvicorn src.app:app으로 백엔드를 직접 실행하고 web-ui에서 npm install 및 npm run dev로 프론트엔드를 띄워 로컬 개발을 진행할 수 있다.

요구사항

• Python 3.10 이상이 필요하며 Playwright 및 Chromium 설치가 권장된다.
• Node.js와 npm이 필요하며 프론트엔드 빌드를 위해 권장 Node 버전이 README에 명시되어 있다.
• Docker 및 docker-compose가 권장되며 Docker 이미지에는 Chromium이 포함되어 있어 별도 브라우저 설치가 불필요하다.

이미지 분석