크롤러 기본 설정

개요

Fess 의 크롤러는 웹사이트나 파일 시스템 등에서 자동으로 콘텐츠를 수집하여 검색 인덱스에 등록하는 기능입니다. 본 가이드에서는 크롤러의 기본 개념과 설정 방법에 대해 설명합니다.

크롤러의 기본 개념

크롤러란

크롤러(Crawler)는 지정된 URL이나 파일 경로를 시작점으로 하여 링크를 따라가며 자동으로 콘텐츠를 수집하는 프로그램입니다.

Fess 의 크롤러는 다음과 같은 특징이 있습니다:

멀티 프로토콜 지원: HTTP/HTTPS, 파일 시스템, SMB, FTP 등
스케줄 실행: 정기적인 자동 크롤링
증분 크롤링: 변경된 콘텐츠만 업데이트
병렬 처리: 여러 URL 동시 크롤링
로봇 규약 준수: robots.txt 준수

크롤러의 종류

Fess 에서는 대상에 따라 다음과 같은 크롤러 유형이 있습니다.

크롤러 유형
유형	대상	용도
웹 크롤러	웹사이트(HTTP/HTTPS)	공개 웹사이트, 인트라넷 웹사이트
파일 크롤러	파일 시스템, SMB, FTP	파일 서버, 공유 폴더
데이터 스토어 크롤러	데이터베이스	RDB, CSV, JSON 등의 데이터 소스

크롤링 설정 생성

기본 크롤링 설정 추가

관리 화면 접속

브라우저에서 http://localhost:8080/admin 에 접속하여 관리자로 로그인합니다.
크롤러 설정 화면 열기

왼쪽 메뉴에서 「크롤러」→「웹」또는「파일 시스템」을 선택합니다.
새 설정 생성

「신규 생성」버튼을 클릭합니다.
기본 정보 입력
- 이름: 크롤링 설정 식별명(예: 사내 위키)
- URL: 크롤링 시작 URL(예: https://wiki.example.com/)
- 크롤링 간격: 크롤링 실행 빈도(예: 1시간마다)
- 스레드 수: 병렬 크롤링 수(예: 5)
- 깊이: 링크를 따라갈 계층 깊이(예: 3)
저장

「생성」버튼을 클릭하여 설정을 저장합니다.

웹 크롤러 설정 예제

사내 인트라넷 사이트 크롤링

이름: 사내 포털
URL: http://intranet.example.com/
크롤링 간격: 1일 1회
스레드 수: 10
깊이: 무제한(-1)
최대 접근 수: 10000

공개 웹사이트 크롤링

이름: 제품 사이트
URL: https://www.example.com/products/
크롤링 간격: 1주일에 1회
스레드 수: 5
깊이: 5
최대 접근 수: 1000

파일 크롤러 설정 예제

로컬 파일 시스템

이름: 문서 폴더
URL: file:///home/share/documents/
크롤링 간격: 1일 1회
스레드 수: 3
깊이: 무제한(-1)

SMB/CIFS(Windows 파일 공유)

이름: 파일 서버
URL: smb://fileserver.example.com/share/
크롤링 간격: 1일 1회
스레드 수: 5
깊이: 무제한(-1)

인증 정보 설정

인증이 필요한 사이트나 파일 서버에 접근하는 경우 인증 정보를 설정합니다.

관리 화면에서「크롤러」→「인증」선택
「신규 생성」클릭

인증 정보 입력:

호스트명: wiki.example.com
포트: 443
인증 방식: Basic 인증
사용자명: crawler_user
비밀번호: ********

「생성」클릭

크롤링 실행

수동 실행

설정한 크롤링을 즉시 실행하는 경우:

크롤링 설정 목록에서 대상 설정 선택
「시작」버튼 클릭
「스케줄러」메뉴에서 작업 실행 상태 확인

스케줄 실행

정기적으로 크롤링을 실행하는 경우:

「스케줄러」메뉴 열기
「Default Crawler」작업 선택

스케줄 표현식 설정(Cron 형식)

# 매일 오전 2시에 실행
0 0 2 * * ?

# 매시간 0분에 실행
0 0 * * * ?

# 월요일부터 금요일까지 오후 6시에 실행
0 0 18 ? * MON-FRI

「업데이트」클릭

크롤링 상태 확인

실행 중인 크롤링 상태 확인:

「스케줄러」메뉴 열기
실행 중인 작업 확인
로그에서 세부 정보 확인:
```
tail -f /var/log/fess/fess_crawler.log
```

기본 설정 항목

크롤링 대상 제한

URL 패턴에 의한 제한

특정 URL 패턴만 크롤링 대상으로 하거나 제외할 수 있습니다.

포함할 URL 패턴(정규 표현식):

# /docs/ 하위만 크롤링
https://example\.com/docs/.*

제외할 URL 패턴(정규 표현식):

# 특정 디렉토리 제외
.*/admin/.*
.*/private/.*

# 특정 파일 확장자 제외
.*\.(jpg|png|gif|css|js)$

깊이 제한

링크를 따라갈 계층 깊이 제한:

0: 시작 URL만
1: 시작 URL과 거기서 링크된 페이지
-1: 무제한(모든 링크 따라가기)

최대 접근 수

크롤링할 페이지 수의 상한:

최대 접근 수: 1000

1000페이지까지 크롤링한 후 중지합니다.

병렬 크롤링 수(스레드 수)

동시에 크롤링할 URL 수를 지정합니다.

권장 스레드 수
환경	권장값	설명
소규모 사이트(〜1만 페이지)	3〜5	대상 서버 부하 억제
중규모 사이트(1만〜10만 페이지)	5〜10	균형 잡힌 설정
대규모 사이트(10만 페이지 이상)	10〜20	고속 크롤링 필요
파일 서버	3〜5	파일 I/O 부하 고려

경고

스레드 수를 너무 많이 늘리면 크롤링 대상 서버에 과도한 부하를 줍니다. 적절한 값을 설정하십시오.

크롤링 간격

크롤링을 실행할 빈도를 지정합니다.

# 시간 지정
크롤링 간격: 3600000  # 밀리초(1시간)

# 또는 스케줄러에서 설정
0 0 2 * * ?  # 매일 오전 2시

파일 크기 설정

크롤링할 파일 크기의 상한을 설정할 수 있습니다.

가져올 파일 크기 상한

크롤러 설정의「설정 매개변수」에 다음을 추가:

client.maxContentLength=10485760

10MB까지의 파일을 가져옵니다. 기본값은 제한 없음입니다.

참고

큰 파일을 크롤링하는 경우 메모리 설정도 조정하십시오. 자세한 내용은 메모리 설정 를 참조하십시오.

인덱싱할 파일 크기 상한

파일 종류별로 인덱싱할 크기의 상한을 설정할 수 있습니다.

기본값:

HTML 파일: 2.5MB
기타 파일: 10MB

설정 파일: app/WEB-INF/classes/crawler/contentlength.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//DBFLUTE//DTD LastaDi 1.0//EN"
        "http://dbflute.org/meta/lastadi10.dtd">
<components namespace="fessCrawler">
        <include path="crawler/container.xml" />

        <component name="contentLengthHelper"
                class="org.codelibs.fess.crawler.helper.ContentLengthHelper" instance="singleton">
                <property name="defaultMaxLength">10485760</property><!-- 10M -->
                <postConstruct name="addMaxLength">
                        <arg>"text/html"</arg>
                        <arg>2621440</arg><!-- 2.5M -->
                </postConstruct>
                <postConstruct name="addMaxLength">
                        <arg>"application/pdf"</arg>
                        <arg>5242880</arg><!-- 5M -->
                </postConstruct>
        </component>
</components>

PDF 파일을 5MB까지 처리하는 설정을 추가했습니다.

경고

처리할 파일 크기를 늘리는 경우 크롤러의 메모리 설정도 늘리십시오.

단어 길이 제한

개요

영숫자만으로 이루어진 긴 문자열이나 연속된 기호는 인덱스 크기 증가나 성능 저하를 유발합니다. 따라서 Fess 에서는 기본적으로 다음과 같은 제한을 두고 있습니다:

연속된 영숫자: 20자까지
연속된 기호: 10자까지

설정 방법

fess_config.properties 를 편집합니다.

기본 설정:

crawler.document.max.alphanum.term.size=20
crawler.document.max.symbol.term.size=10

예: 제한을 완화하는 경우

crawler.document.max.alphanum.term.size=50
crawler.document.max.symbol.term.size=20

참고

긴 영숫자 문자열로 검색해야 하는 경우(예: 일련 번호, 토큰 등) 이 값을 크게 설정하십시오. 단, 인덱스 크기가 증가합니다.

프록시 설정

개요

인트라넷 내부에서 외부 사이트를 크롤링하는 경우 방화벽에 의해 차단될 수 있습니다. 이 경우 프록시 서버를 통해 크롤링합니다.

설정 방법

관리 화면의 크롤링 설정에서「설정 매개변수」에 다음을 추가합니다.

기본 프록시 설정:

client.proxyHost=proxy.example.com
client.proxyPort=8080

인증이 필요한 프록시:

client.proxyHost=proxy.example.com
client.proxyPort=8080
client.proxyUsername=proxyuser
client.proxyPassword=proxypass

특정 호스트를 프록시에서 제외:

client.nonProxyHosts=localhost|127.0.0.1|*.example.com

시스템 전체 프록시 설정

모든 크롤링 설정에서 동일한 프록시를 사용하는 경우 환경 변수로 설정할 수 있습니다.

export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080
export no_proxy=localhost,127.0.0.1,.example.com

robots.txt 설정

개요

robots.txt 는 크롤러에 대해 크롤링 가부를 지시하는 파일입니다. Fess 는 기본적으로 robots.txt 를 준수합니다.

설정 방법

robots.txt 를 무시하는 경우 fess_config.properties 를 편집합니다.

crawler.ignore.robots.txt=true

경고

외부 사이트를 크롤링하는 경우 robots.txt 를 준수하십시오. 무시하면 서버에 과도한 부하를 주거나 이용 약관을 위반할 수 있습니다.

User-Agent 설정

크롤러의 User-Agent를 변경할 수 있습니다.

관리 화면에서 설정

크롤링 설정의「설정 매개변수」에 추가:

client.userAgent=MyCompanyCrawler/1.0

시스템 전체 설정

fess_config.properties 에서 설정:

crawler.user.agent=MyCompanyCrawler/1.0

인코딩 설정

크롤링 데이터 인코딩

fess_config.properties 에서 설정:

crawler.crawling.data.encoding=UTF-8

파일명 인코딩

파일 시스템의 파일명 인코딩:

crawler.document.file.name.encoding=UTF-8

크롤링 문제 해결

크롤링이 시작되지 않음

확인 사항:

스케줄러가 활성화되어 있는지 확인
- 「스케줄러」메뉴에서「Default Crawler」작업이 활성화되어 있는지 확인
크롤링 설정이 활성화되어 있는지 확인
- 크롤링 설정 목록에서 대상 설정이 활성화되어 있는지 확인

로그 확인

tail -f /var/log/fess/fess.log
tail -f /var/log/fess/fess_crawler.log

크롤링이 중간에 중지됨

가능한 원인:

메모리 부족
- fess_crawler.log 에 OutOfMemoryError 가 없는지 확인
- 크롤러 메모리 늘리기(자세한 내용은 메모리 설정)
네트워크 오류
- 타임아웃 설정 조정
- 재시도 설정 확인
크롤링 대상 오류
- 404 오류가 빈번하게 발생하지 않는지 확인
- 로그에서 오류 세부 정보 확인

특정 페이지가 크롤링되지 않음

확인 사항:

URL 패턴 확인
- 제외 URL 패턴에 해당하지 않는지 확인
robots.txt 확인
- 대상 사이트의 /robots.txt 확인
인증 확인
- 인증이 필요한 페이지의 경우 인증 설정 확인
깊이 제한
- 링크 계층이 깊이 제한을 초과하지 않는지 확인
최대 접근 수
- 최대 접근 수에 도달하지 않았는지 확인

크롤링이 느림

대책:

스레드 수 늘리기
- 병렬 크롤링 수 늘리기(단, 대상 서버 부하 주의)
불필요한 URL 제외
- 이미지나 CSS 파일 등을 제외 URL 패턴에 추가
타임아웃 설정 조정
- 응답이 느린 사이트의 경우 타임아웃을 짧게 설정
크롤러 메모리 늘리기
- 자세한 내용은 메모리 설정

모범 사례

크롤링 설정 권장 사항

적절한 스레드 수 설정

대상 서버에 과도한 부하를 주지 않도록 적절한 스레드 수를 설정합니다.
URL 패턴 최적화

불필요한 파일(이미지, CSS, JavaScript 등)을 제외하여 크롤링 시간을 단축하고 인덱스 품질을 향상시킵니다.
깊이 제한 설정

사이트 구조에 맞게 적절한 깊이를 설정합니다. 무제한(-1)은 사이트 전체를 크롤링하는 경우에만 사용합니다.
최대 접근 수 설정

예상치 못하게 많은 페이지를 크롤링하지 않도록 상한을 설정합니다.
크롤링 간격 조정

업데이트 빈도에 맞게 적절한 간격을 설정합니다. - 자주 업데이트되는 사이트: 1시간〜수 시간마다 - 업데이트가 적은 사이트: 1일〜1주일마다

스케줄 설정 권장 사항

야간 실행

서버 부하가 낮은 시간대(예: 새벽 2시)에 실행합니다.
중복 실행 방지

이전 크롤링이 완료된 후 다음 크롤링을 시작하도록 설정합니다.
오류 시 알림

크롤링 실패 시 이메일 알림을 설정합니다.

참고 정보

크롤러 고급 설정 - 크롤러 고급 설정
썸네일 이미지 설정 - 썸네일 설정
메모리 설정 - 메모리 설정
로그 설정 - 로그 설정

메뉴

크롤러 기본 설정

개요

크롤러의 기본 개념

크롤러란

크롤러의 종류

크롤링 설정 생성

기본 크롤링 설정 추가

웹 크롤러 설정 예제

사내 인트라넷 사이트 크롤링

공개 웹사이트 크롤링

파일 크롤러 설정 예제

로컬 파일 시스템

SMB/CIFS(Windows 파일 공유)

인증 정보 설정

크롤링 실행

수동 실행

스케줄 실행

크롤링 상태 확인

기본 설정 항목

크롤링 대상 제한

URL 패턴에 의한 제한

깊이 제한

최대 접근 수

병렬 크롤링 수(스레드 수)

크롤링 간격

파일 크기 설정

가져올 파일 크기 상한

인덱싱할 파일 크기 상한

단어 길이 제한

개요

설정 방법

프록시 설정

개요

설정 방법

시스템 전체 프록시 설정

robots.txt 설정

개요

설정 방법

User-Agent 설정

관리 화면에서 설정

시스템 전체 설정

인코딩 설정

크롤링 데이터 인코딩

파일명 인코딩

크롤링 문제 해결

크롤링이 시작되지 않음

크롤링이 중간에 중지됨

특정 페이지가 크롤링되지 않음

크롤링이 느림

모범 사례

크롤링 설정 권장 사항

스케줄 설정 권장 사항

참고 정보