Gerapy를 이용한 웹 스크래핑: 설정, 문제 해결 및 팁

Gerapy는 Scrapy 배포를 위한 풀스택 솔루션입니다. 커밋 기록을 보면 일부 종속성 버전이 업데이트되었지만, 2022년 이후 실질적인 업데이트는 이루어지지 않았습니다. Gerapy를 시작하는 과정은 시행착오가 많은 어려운 과정일 수 있습니다.

이 가이드는 Gerapy 사용을 더 쉽게 하기 위해 존재합니다. 이 가이드를 마치면 다음과 같은 질문에 답할 수 있게 될 것입니다.

왜 Gerapy가 제 기본 Python 설치 환경에서 작동하지 않을까요?
Gerapy를 위해 Python과 pip를 어떻게 구성하나요?
관리자 계정은 어떻게 생성하나요?
첫 번째 스크레이퍼를 작성하는 방법은 무엇인가요?
스크레이퍼 문제 해결 방법은 무엇인가요?
스크레이퍼를 테스트하고 배포하는 방법은 무엇인가요?

Gerapy 소개

Gerapy가 실제로 무엇이며, 무엇이 독특한지 더 잘 이해해 보겠습니다.

Gerapy란 무엇인가요?

Gerapy는 Django 관리 대시보드와 Scrapyd API를 제공합니다. 이 서비스들은 스택 관리를 위한 간단하면서도 강력한 인터페이스를 제공합니다. 현재는 레거시 프로그램이지만 여전히 워크플로우를 개선하고 배포 속도를 높여줍니다. Gerapy는 DevOps 및 관리 중심 팀이 웹 스크래핑을 더 쉽게 접근할 수 있도록 합니다.

스크레이퍼 생성 및 모니터링을 위한 GUI 대시보드.
버튼 클릭만으로 스크레이퍼 배포.
발생하는 로그와 에러를 실시간으로 확인하세요.

Gerapy의 차별점은 무엇인가요?

Gerapy는 스크레이퍼 관리를 위한 원스톱 솔루션을 제공합니다. 레거시 코드와 종속성으로 인해 Gerapy를 시작하는 과정은 다소 번거롭습니다. 그러나 일단 작동하게 되면 대규모 스크레이퍼 처리를 위해 맞춤화된 완전한 도구 세트를 활용할 수 있습니다.

브라우저 내에서 스크레이퍼를 구축하세요.
명령줄을 건드리지 않고 Scrapyd에 배포하세요.
모든 크롤러와 스크레이퍼를 중앙 집중식으로 관리하세요.
스파이더 관리를 위한 Django 기반 프론트엔드.
쉬운 구축 및 배포를 위한 Scrapyd 기반 백엔드.
작업 자동화를 위한 내장 스케줄러.

Gerapy로 웹 스크래핑하는 방법

Gerapy 설정 과정은 번거롭습니다. 기술적 부채를 해결하고 소프트웨어 유지보수를 수행해야 합니다. 수많은 시행착오 끝에, Gerapy가 최신 버전의 Python과 호환되지 않는다는 사실을 알게 되었습니다. 최신 버전인 Python 3.13으로 설치를 시작했습니다. Gerapy의 종속성에는 너무 최신 버전이었습니다. 3.12를 시도했지만 여전히 종속성 문제만 더 발생했습니다.

결국 우리는 Python 3.10이 필요했습니다. 게다가, 더 이상 사용되지 않는 클래스를 수정하기 위해 Gerapy의 실제 코드 일부를 변경해야 했습니다. 그런 다음 Gerapy의 거의 모든 종속성을 수동으로 다운그레이드해야 했습니다. Python은 지난 3년 동안 상당한 변화를 겪었지만 Gerapy의 개발은 그 속도를 따라가지 못했습니다. 우리는 3년 전 Gerapy의 이상적인 조건을 재현해야 합니다.

프로젝트 설정

Python 3.10

먼저 Python 3.10을 설치해야 합니다. 이 버전은 완전히 사라진 것은 아니지만 더 이상 널리 사용 가능하지 않습니다. 기본 Ubuntu 및 Ubuntu 기반 Windows WSL에서는 apt로 설치할 수 있습니다.

sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev

설치 여부는 --version 플래그로 확인할 수 있습니다.

python3.10 --version

모든 과정이 정상적으로 완료되면 아래와 유사한 출력이 표시됩니다.

Python 3.10.17

프로젝트 폴더 생성

먼저 새 폴더를 만듭니다.

 mkdir gerapy-environment

다음으로, 새 프로젝트 폴더로 이동( cd )하고 가상 환경을 설정해야 합니다.

cd gerapy-environment
python3.10 -m venv venv

환경을 활성화합니다.

source venv/bin/activate

환경이 활성화되면 사용 중인 Python 버전을 확인할 수 있습니다.

python --version

보시다시피, 이제 Python은 가상 환경 내에서 기본적으로 3.10 설치본을 사용합니다.

Python 3.10.17

의존성 설치

아래 명령어는 Gerapy와 필요한 종속성 버전을 설치합니다. 보시다시피, pip==을 사용하여 많은 레거시 패키지를 수동으로 지정해야 합니다.

pip install setuptools==80.8.0
pip install scrapy==2.7.1 gerapy==0.9.13 scrapy-splash==0.8.0 scrapy-redis==0.7.3 scrapyd==1.2.0 scrapyd-client==1.2.0 pyopenssl==23.2.0 cryptography==41.0.7 twisted==21.2.0

이제 init 명령어로 실제 Gerapy 프로젝트를 생성하겠습니다.

gerapy init

다음으로, gerapy 폴더로 cd 이동하여 migrate를 실행하여 데이터베이스를 생성합니다.

cd gerapy
gerapy migrate

이제 관리자 계정을 생성할 차례입니다. 이 명령어는 기본적으로 관리자 권한을 부여합니다.

gerapy initadmin

마지막으로 Gerapy 서버를 시작합니다.

gerapy runserver

다음과 같은 출력이 표시됩니다.

StatReloader로 파일 변경 감시 중
시스템 점검 수행 중...

시스템 점검 결과 문제 없음 (0개 숨김).
INFO - 2026-05-24 13:49:16,241 - process: 1726 - scheduler.py - gerapy.server.core.scheduler - 105 - scheduler - successfully synced task with jobs with force
May 24, 2026 - 13:49:16
Django 버전 2.2.28, 설정 'gerapy.server.server.settings' 사용 중
개발 서버 시작: http://127.0.0.1:8000/
CONTROL-C로 서버 종료.

대시보드 사용하기

http://127.0.0.1:8000/에 접속하면 로그인 화면이 표시됩니다. 기본 계정 이름과 비밀번호는 모두 admin입니다. 로그인 후 Gerapy 대시보드로 이동합니다.

“프로젝트” 탭을 클릭하고 새 프로젝트를 생성하세요. 이 프로젝트를 quotes라고 명명하겠습니다.

대상 사이트 설정

이제 새 스파이더를 생성합니다. 새 프로젝트 내에서 “스파이더 추가” 버튼을 클릭하세요. “시작 URL” 섹션에 https://quotes.toscrape.com을 추가합니다. “도메인” 아래에 quotes.toscrape.com을 입력하세요.

추출 로직

다음으로 추출 로직을 추가합니다. 아래 parse() 함수는 CSS 선택자를 사용하여 페이지에서 인용문을 추출합니다. 선택자에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

“내부 코드” 섹션으로 스크롤하여 파싱 함수를 추가하세요.

def parse(self, response):
    quotes = response.css('div.quote')
    print(f"Found {len(quotes)} quotes")
    for quote in quotes:
        text = quote.css('span.text::text').get()
        author = quote.css('small.author::text').get()
        print(f"Text: {text}, Author: {author}")
        yield {
            'text': text,
            'author': author,
        }

이제 화면 오른쪽 하단에 있는 “저장” 버튼을 클릭하세요. 지금 스파이더를 실행하면 치명적인 오류가 발생합니다. Gerapy는 Scrapy의 BaseItem을 사용하려고 합니다. 그러나 BaseItem은 몇 년 전에 Scrapy에서 제거되었습니다.

BaseItem 오류 수정

이 오류를 해결하려면 Scrapy의 내부 코드를 직접 수정해야 합니다. 명령줄에서 수행할 수 있지만, 검색 기능이 있는 GUI 텍스트 편집기를 사용하는 것이 훨씬 쉽습니다.

가상 환경의 소스 파일 디렉토리로이동합니다.

cd venv/lib/python3.10/site-packages/gerapy/server/core

VSCode에서 폴더를 열려면 아래 명령어를 사용하세요.

code .

parser.py 파일을 열면 문제의 원인을 찾을 수 있습니다.

이 줄을 다음과 같이 변경해야 합니다.

from scrapy import Item

Replacing BaseItem with Item in Our
Imports

BaseItem 임포트를 제거했으므로, 모든 BaseItem 인스턴스를 Item으로 교체해야 합니다. 유일한 인스턴스는 run_callback() 함수에 있습니다. 변경 사항을 저장한 후 편집기를 닫으세요.

Replacing BaseItem with Item Throughout the File

스파이더를 실행하면 이제 새로운 오류가 발생합니다.

REQUEST_FINGERPRINTER_IMPLEMENTATION Deprecation Error

REQUEST_FINGERPRINTER_IMPLEMENTATION 사용 중단 문제 해결

분명하지는 않지만, Gerapy는 실제로 우리의 설정을 스파이더에 직접 주입합니다. 현재 폴더에서 cd로 나가서 projects 폴더로 들어갑니다.

cd
cd gerapy-environment/gerapy/projects/quotes

다시 한번 텍스트 편집기를 엽니다.

code .

이제 스파이더 파일을 엽니다. 파일명은 quotes.py이며 spiders 폴더 내에 위치합니다. 스파이더 클래스 내부에 parse() 함수가 보일 것입니다. 파일 하단에는 custom_settings라는 배열이 있습니다. Gerapy가 설정값을 스파이더에 직접 주입한 것입니다.

새로운 설정을 하나 추가해야 합니다. 2.7을 사용해야 합니다. 2.6은 계속해서 오류를 발생시킵니다. 이는 수많은 시행착오 끝에 발견한 사실입니다.

"REQUEST_FINGERPRINTER_IMPLEMENTATION": "2.7",

이제 Gerapy의 실행 버튼으로 스파이더를 실행하면 모든 오류가 해결됩니다. 아래에서 볼 수 있듯이, 오류 메시지 대신 “Follow Request”만 표시됩니다.

모든 것 통합하기

스크레이퍼 빌드하기

Gerapy의 “프로젝트” 탭으로 돌아가면 해당 프로젝트의 “빌드됨” 열에 “X”가 표시됩니다. 이는 스크레이퍼가 배포용 실행 파일로 빌드되지 않았음을 의미합니다.

“배포(deploy)” 버튼을 클릭하세요. 이제 “빌드(build)”를 클릭하세요.

스케줄러 사용하기

스크레이퍼를 특정 시간 또는 간격으로 실행하도록 예약하려면 “작업”을 클릭한 후 새 작업을 생성하세요. 그런 다음 원하는 예약 설정을 선택합니다.

완료 후 “생성” 버튼을 클릭하세요.

Gerapy로 스크래핑할 때의 제한 사항

의존성

레거시 코드로 인해 많은 제한 사항이 발생하며, 본 문서에서 이를 직접 해결했습니다. Gerapy를 실행하기 위해 내부 소스 코드를 직접 수정해야 했습니다. 시스템 내부 구조를 건드리는 것이 불편하다면 Gerapy는 적합하지 않습니다. BaseItem 오류 기억하시나요?

Gerapy의 종속성은 계속 진화하지만 Gerapy 자체는 시간이 멈춘 상태입니다. 계속 사용하려면 설치 환경을 직접 유지 관리해야 합니다. 이는 유지보수라는 형태의 기술적 부채와 실제적인 시행착오 과정을 수반합니다.

아래 코드 조각을 떠올려 보세요. 이 버전 번호들은 하나하나 꼼꼼한 시행착오 과정을 통해 찾아낸 것입니다. 종속성이 깨지면 작동하는 버전을 찾을 때까지 계속해서 다른 버전 번호를 시도해야 합니다. 이 튜토리얼만 해도 10개 종속성의 작동 버전을 찾기 위해 시행착오를 거쳐야 했습니다. 시간이 지날수록 이 문제는 더욱 악화될 것입니다.

pip install setuptools==80.8.0
pip install scrapy==2.7.1 gerapy==0.9.13 scrapy-splash==0.8.0 scrapy-redis==0.7.3 scrapyd==1.2.0 scrapyd-client==1.2.0 pyopenssl==23.2.0 cryptography==41.0.7 twisted==21.2.0

운영 체제 제한 사항

이 튜토리얼을 처음 시도할 때, 우리는 기본 Windows를 사용해 보았습니다. 이렇게 해서 Python 버전으로 인한 초기 제한 사항을 발견하게 되었습니다. 현재 Python 안정 버전은 3.9, 3.11, 3.13으로 제한됩니다. OS와 상관없이 여러 버전의 Python을 관리하는 것은 어렵습니다. 그러나 Ubuntu는 deadsnakes PPA 저장소를 제공합니다.

deadsnakes 없이도 호환되는 Python 버전을 찾을 수는 있지만, 그 경우에도 PATH 문제를 처리하고 기본 설치된 python과 python3.10을 구분해야 합니다. Windows와 macOS에서는 네이티브로 처리할 수 있을 가능성이 있지만, 다른 해결 방법을 찾아야 할 것입니다. 우분투 및 기타 apt 기반 리눅스 배포판에서는 최소한 PATH에 직접 설치된 구버전 파이썬에 빠르게 접근할 수 있는 재현 가능한 환경을 확보할 수 있습니다.

Gerapy를 통한 프록시 통합

기본 Scrapy와 마찬가지로 프록시 통합도 쉽게 수행할 수 있습니다. Gerapy의 설정 주입 방식의 진정한 정신에 따라, 프록시를 스파이더에 직접 주입할 수 있습니다. 아래 예시에서는 Web Unlocker를 사용하여 연결하기 위해 HTTPPROXY_ENABLED 및 HTTPPROXY_PROXY 설정을 추가합니다.

"HTTPPROXY_ENABLED": True,
"HTTPPROXY_PROXY": "http://brd-customer-<your-username>-zone-<your-zone-name>:<your-password>@brd.superproxy.io:33335"

프록시 통합 후의 전체 스파이더 코드입니다. 사용자 이름, 존, 비밀번호를 본인의 것으로 교체해야 합니다.

Gerapy의 실행 가능한 대안

Scrapyd: Gerapy 및 거의 모든 Scrapy 스택의 실제 백본입니다. Scrapyd를 사용하면 평범한 HTTP 요청을 통해 모든 것을 관리하고 원한다면 대시보드를 구축할 수 있습니다.
스크래핑 함수: 당사의 스크래핑 함수를 사용하면 스크레이퍼를 클라우드에 직접 배포하고 온라인 IDE에서 편집할 수 있습니다. Gerapy와 유사한 대시보드를 제공하지만 더 유연하고 현대적입니다.

결론

급변하는 세상에서 Gerapy는 레거시 제품입니다. 실질적인 유지보수가 필요하며 직접 손을 더럽혀야 합니다. Gerapy 같은 도구는 스크래핑 환경을 중앙화하고 단일 대시보드에서 모든 것을 모니터링할 수 있게 합니다. DevOps 환경에서는 Gerapy가 실질적인 유용성과 가치를 제공합니다.

Scrapy가 적합하지 않다면, 데이터 수집 요구를 충족할 수 있는 다양한 대안을 제공합니다. 아래 제품들은 그 중 일부입니다.

커스텀 스크레이퍼: 코드 없이 스크레이퍼를 생성하고 당사 클라우드 인프라에 배포하세요.
데이터셋: 웹 전반에서 매일 업데이트되는 과거 데이터셋에 접근하세요. 손끝에서 바로 활용 가능한 인터넷 역사 라이브러리입니다.
주거용 프록시: 직접 코드를 작성하든 AI로 스크래핑하든, 실제 주거용 인터넷 연결을 통한 지오타겟팅 기능으로 인터넷에 접속할 수 있습니다.

지금 무료 체험에 가입하고 데이터 수집을 한 단계 업그레이드하세요!

문의하기 무료 체험 시작하기

Gerapy 웹 스크래핑: 풀 스택 Scrapy 배포 가이드