속도 제한 설정

개요

Fess에는 시스템의 안정성과 성능을 유지하기 위한 속도 제한 기능이 있습니다. 이 기능을 통해 과도한 요청으로부터 시스템을 보호하고 공정한 리소스 배분을 실현할 수 있습니다.

속도 제한은 다음 장면에서 적용됩니다:

  • 검색 API나 AI 검색 모드 API를 포함한 모든 HTTP 요청(RateLimitFilter)

  • 크롤러 요청(크롤 설정에 의한 제어)

HTTP 요청 속도 제한

Fess로의 HTTP 요청 수를 IP 주소 단위로 제한할 수 있습니다. 이 제한은 검색 API, AI 검색 모드 API, 관리 화면 등 모든 HTTP 요청에 적용됩니다.

설정

app/WEB-INF/classes/fess_config.properties:

# 속도 제한 활성화(기본값: false)
rate.limit.enabled=true

# 윈도우당 최대 요청 수(기본값: 100)
rate.limit.requests.per.window=100

# 윈도우 크기(밀리초)(기본값: 60000)
rate.limit.window.ms=60000

동작

  • 속도 제한을 초과한 요청은 HTTP 429 (Too Many Requests)를 반환합니다

  • 제한 초과로 블록된 IP, 그리고 블록 IP 목록에 포함된 IP의 요청은 HTTP 403 (Forbidden)을 반환합니다

  • 응답 본문은 JSON 입니다(429 는 {"error":"rate_limit_exceeded",...,"retry_after":60} , 403 은 {"error":"ip_blocked",...} ). 429 에는 Retry-After 헤더가 붙습니다

  • 제한은 IP 주소 단위로 적용됩니다

  • IP별로 최초 요청부터 윈도우가 시작되며, 윈도우 기간 경과 후 카운트가 리셋됩니다(고정 윈도우 방식)

  • 제한 초과 시 IP가 rate.limit.block.duration.ms 기간 동안 블록됩니다

AI 검색 모드 속도 제한

AI 검색 모드 기능에는 LLM API 비용과 리소스 소비를 제어하기 위한 속도 제한이 있습니다. AI 검색 모드에는 위의 HTTP 요청 속도 제한에 더하여 AI 검색 모드 고유의 속도 제한도 설정할 수 있습니다.

AI 검색 모드 고유의 속도 제한 설정에 대해서는 :doc:`rag-chat`를 참조하세요.

참고

AI 검색 모드 속도 제한은 LLM 프로바이더 측의 속도 제한과 별도로 적용됩니다. 양쪽 제한을 고려하여 설정하세요.

크롤러 속도 제한

크롤러가 대상 사이트에 과도한 부하를 주지 않도록 요청 간격을 설정할 수 있습니다.

웹 크롤 설정

관리 화면의 “크롤러” -> “웹”에서 다음을 설정:

  • 요청 간격: 요청 사이의 대기 시간(밀리초)

  • 스레드 수: 병렬 크롤 스레드 수

권장 설정:

# 일반적인 사이트
intervalTime=1000
numOfThread=1

# 대규모 사이트(허가가 있는 경우)
intervalTime=500
numOfThread=3

robots.txt 준수

Fess는 기본적으로 robots.txt의 Crawl-delay 지시를 준수합니다.

# robots.txt 예
User-agent: *
Crawl-delay: 10

robots.txt 처리는 app/WEB-INF/classes/fess_config.properties 의 crawler.ignore.robots.txt 로 제어합니다(기본값: false). true 로 설정하면 Crawl-delay 를 포함한 robots.txt 처리가 비활성화됩니다.

# robots.txt를 무시한다(기본값: false)
crawler.ignore.robots.txt=false

Crawl-delay 는 접속 대상(오리진)별로 적용되며 상한은 60초입니다. 대기는 URL 단위로 이루어지므로, 증분 크롤링에서 하나의 URL 에 보내는 HEAD 와 GET 은 연이어 전송됩니다. 크롤링 설정의 「간격」은 이와 별도로 다음 URL 까지의 대기 시간으로 동작합니다.

robots.txt 는 RFC 9309 에 따라 해석됩니다. Allow: 와 Disallow: 는 가장 길게 일치한 규칙이 우선하며, 시작 URL 도 robots.txt 로 확인합니다. robots.txt 로 거부된 URL 은 fess-crawler.log 에 INFO 로 기록되며 장애 URL 에는 등록되지 않습니다.

429/503 응답 시 백오프

서버가 429 Too Many Requests 또는 503 Service Unavailable 을 반환하면 해당 오리진에 대한 접근을 일시적으로 멈추고 그 URL 을 최대 3회까지 재시도합니다. 대기 시간은 Retry-After 헤더가 있으면 그 값, 없으면 10초부터 시작하는 지수적 시간(최대 5분)입니다. 마지막 재시도도 실패하면 fess-crawler.log 에 WARN 이 출력됩니다.

robots.txt 를 가져올 수 없는 경우

robots.txt 를 가져오는 것이 5xx, 429, 타임아웃 등으로 실패하면, 해당 오리진의 URL 은 백오프가 끝날 때까지 큐로 되돌려집니다. 첫 실패 후 3회의 재시도도 실패하면, 그 크롤링 동안 해당 오리진의 모든 URL 이 크롤링 대상에서 제외되고 fess-crawler.log 에 WARN 이 한 번 출력됩니다. 15.8 이전에는 가져올 수 없었던 robots.txt 는 모두 허용으로 취급되었습니다. 이 동작으로 되돌리려면 웹 크롤링 설정의 「설정 파라미터」에 다음을 지정합니다.

client.robotsTxtAllowOnUnavailable=true

robots.txt 처리 자체를 비활성화하려면 client.robotsTxtEnabled=false (크롤링 설정별) 또는 crawler.ignore.robots.txt=true 를 사용합니다.

속도 제한 전체 설정 항목

app/WEB-INF/classes/fess_config.properties에서 설정 가능한 모든 프로퍼티입니다.

프로퍼티 설명 기본값
rate.limit.enabled 속도 제한 활성화 false
rate.limit.requests.per.window 윈도우당 최대 요청 수 100
rate.limit.window.ms 윈도우 크기(밀리초) 60000
rate.limit.block.duration.ms 제한 초과 시 IP 블록 기간(밀리초) 300000
rate.limit.retry.after.seconds Retry-After 헤더 값(초) 60
rate.limit.whitelist.ips 속도 제한에서 제외할 IP 주소(쉼표 구분) 127.0.0.1,::1
rate.limit.blocked.ips 블록할 IP 주소(쉼표 구분) (비어 있음)
rate.limit.trusted.proxies 신뢰하는 프록시 IP(X-Forwarded-For/X-Real-IP 취득원) 127.0.0.1,::1
rate.limit.cleanup.interval 클린업 간격(요청 수, 예약됨) 1000

참고

rate.limit.cleanup.interval 은 미래 확장을 위해 예약된 설정 항목입니다. 현재 구현에서는 요청 카운터 및 블록 IP 정보가 내부 캐시의 유효 기간(rate.limit.window.ms 및 rate.limit.block.duration.ms)에 따라 자동으로 클린업되므로, 이 설정값은 사용되지 않습니다.

고급 속도 제한 설정

커스텀 속도 제한

특정 조건에 따라 다른 속도 제한 로직을 적용하려면 커스텀 컴포넌트 구현이 필요합니다.

// RateLimitHelper 커스터마이즈 예
public class CustomRateLimitHelper extends RateLimitHelper {
    @Override
    public boolean allowRequest(String ip) {
        // 커스텀 로직
    }
}

제외 설정

특정 IP 주소를 속도 제한에서 제외하거나 블록할 수 있습니다.

# 화이트리스트 IP(속도 제한에서 제외, 쉼표 구분)
rate.limit.whitelist.ips=127.0.0.1,::1,192.168.1.100

# 블록 IP 목록(항상 블록, 쉼표 구분)
rate.limit.blocked.ips=203.0.113.50

# 신뢰하는 프록시 IP(쉼표 구분)
rate.limit.trusted.proxies=127.0.0.1,::1

참고

리버스 프록시를 사용하는 경우 rate.limit.trusted.proxies에 프록시의 IP 주소를 설정하세요. 신뢰하는 프록시에서의 요청만 X-Forwarded-For 및 X-Real-IP 헤더에서 클라이언트 IP를 취득합니다.

모니터링과 알림

속도 제한 상황을 모니터링하기 위한 설정:

로그 출력

속도 제한이 적용되면 로그에 기록됩니다:

<Logger name="org.codelibs.fess.helper.RateLimitHelper" level="INFO"/>

이 메시지는 INFO 레벨로 출력되므로 기본 로그 레벨(warn)에서는 기록되지 않습니다. 위의 Logger 를 log4j2.xml 에 추가하거나( 위치는 로그 설정 참조) FESS_LOG_LEVEL 을 info 로 변경하십시오.

문제 해결

정당한 요청이 차단됨

원인: 제한값이 너무 엄격함

해결 방법:

  1. rate.limit.requests.per.window 증가

  2. 특정 IP를 화이트리스트에 추가(rate.limit.whitelist.ips)

  3. 윈도우 크기(rate.limit.window.ms) 조정

속도 제한이 작동하지 않음

원인: 설정이 올바르게 반영되지 않음

확인 사항:

  1. rate.limit.enabled=true가 설정되어 있는지

  2. 설정 파일이 올바르게 읽혀지고 있는지

  3. Fess를 재시작했는지

성능 영향

속도 제한 체크 자체가 성능에 영향을 미치는 경우:

  1. 화이트리스트를 활용하여 신뢰할 수 있는 IP의 체크를 스킵

  2. 속도 제한을 무효화(rate.limit.enabled=false)

참고 정보