tasteby/docs/design/337-stats-bot-ratelimit/README.md

설계서: 통계 방문 카운트 봇 필터 + 레이트리밋 (#337)

상태: Approved 작성: [AI] Architect · 최종수정: 2026-06-15 추적성 — Redmine: #337 · 부모: #274 (현행화 backend-stats, 09-Done) · 구현 파일: backend-java/build.gradle, backend-java/src/main/java/com/tasteby/controller/StatsController.java, backend-java/src/main/java/com/tasteby/util/BotDetector.java (신규), backend-java/src/main/java/com/tasteby/service/RateLimitService.java (신규) · 테스트: 수동 (curl로 봇 UA + 같은 IP 다중 호출)

1. 목적 (Why)

POST /api/stats/visit이 인증 없이 누구나 호출 가능 + 봇/크롤러 필터 없음 → (a) 일반 봇이 사이트 인덱싱하면서 카운터 인플레이션, (b) 악의적 새로고침 어뷰즈로 통계 왜곡. 또한 페이지 로드마다 DB write QPS 증가 — 클라이언트 어뷰즈에 취약.

2. 범위 (Scope)

• 포함
  • User-Agent 기반 봇 패턴 필터 (Googlebot, bingbot, crawler 등 일반 패턴).
  • IP 기반 레이트리밋: 같은 IP에서 1분에 1회만 카운트 (Bucket4j + Redis).
  • X-Forwarded-For 헤더 우선 (Nginx Ingress 뒤이므로).
  • 봇/리밋 초과: 200 응답하되 카운터 미증가 (사용자 경험 영향 X).
• 제외 (out of scope)
  • WAF 수준 봇 차단 (Cloudflare 등).
  • UU(고유 방문자) — 별도 후속 (쿠키/세션).
  • Redis INCR 기반 비동기 통계 (DB write 분리) — 별도 후속.

3. 인수조건

• build.gradle에 bucket4j-redis 추가.
• User-Agent에 'bot'/'crawler'/'spider' 포함 시 카운트 skip + 디버그 로그.
• 같은 IP에서 60초 안에 두 번째 visit 호출 시 카운트 skip.
• 응답은 항상 { "ok": true, "counted": bool } 형태.
• 봇/리밋 초과 호출도 200 응답 (사용자 페이지 로드 지장 X).
• 운영 배포 후 회귀 없음 — 통계 카운터가 정상 증가.

4. 컨텍스트 & 제약

• Bucket4j 8.x + Redis backend (Lettuce 호환).
• 메모리만 사용하는 경우(단일 파드) ConcurrentLinkedHashMap도 가능하나 ShedLock 사례처럼 멀티 파드 미래 대비 Redis.
• 운영 트래픽 작아 Bucket4j 부하 미미.
• 1분 1회 정책은 동일 IP에서 사용자가 페이지 새로고침해도 영향 작음. 너무 빡빡하면 다중 사용자 NAT(회사/카페) 영향 → 1분/IP는 균형.

5. 아키텍처 개요

사용자 페이지 로드
   │
   ▼  POST /api/stats/visit  (X-Forwarded-For: client-ip)
StatsController.recordVisit(req)
   │
   ├─ BotDetector.isBot(userAgent) → skip
   │
   ├─ RateLimitService.tryConsume(clientIp) → false면 skip
   │
   ▼
StatsService.recordVisit() → DB MERGE

6. 데이터 모델

Redis 키:

• bucket4j:visit:<ip> — Bucket4j가 자동 관리 (token bucket state)

응답:

{ "ok": true, "counted": true }   // 정상 카운트
{ "ok": true, "counted": false }  // 봇/리밋 초과

7. 함수 명세

함수	책임	시그니처	비고
BotDetector.isBot(ua)	UA 문자열 봇 패턴 매칭	static boolean isBot(String)	순수 함수
RateLimitService.tryConsume(key)	Bucket4j 1 토큰 소비	boolean tryConsume(String)	Bucket 1/min
StatsController.recordVisit(req) (수정)	봇 + IP 필터 후 카운트	@PostMapping("/visit")	request 헤더 활용

8. 흐름

1. POST /api/stats/visit 진입.
2. X-Forwarded-For 우선 → 없으면 request.getRemoteAddr().
3. User-Agent 검사 (isBot true면 counted=false).
4. IP 레이트 검사 (tryConsume false면 counted=false).
5. 통과 시 recordVisit() 호출.
6. 응답 {ok:true, counted: ...}.

9. 엣지케이스

• 여러 IP가 헤더에 chain: X-Forwarded-For 첫 번째(원본 클라이언트) 사용.
• 헤더 위조: Nginx Ingress 뒤라 외부 위조는 어렵지만, 신뢰는 가정.
• Redis 다운: Bucket4j Redis 에러 → fail open(즉, counted=true 진행). 통계는 약간 부풀지만 사용자 경험 우선.
• 빈 UA: 봇 판정 안 함 (정상 모바일 앱일 수도).

10. 테스트

• 수동:

  curl -X POST -H "User-Agent: Googlebot/2.1" https://www.tasteby.net/api/stats/visit
  → counted=false
  curl -X POST -H "User-Agent: Mozilla/5.0" https://www.tasteby.net/api/stats/visit
  → counted=true
  (즉시 재호출) → counted=false (rate limit)
  

11. 리스크 & 대안

• 선택: Bucket4j + Redis backend + UA 정규식.
• 대안 A: 메모리 LRU만 사용 — 단일 파드는 OK, 멀티 파드는 어뷰즈 가능.
• 대안 B: Nginx Ingress에서 rate limit — 인프라 분리 깔끔. 다만 봇 UA 필터는 ingress nginx 모듈 추가 부담, 어플리케이션 가시성↓.
• 대안 C: 비동기 큐(@Async 또는 Redis INCR) — DB write 부담 해소. 본 이슈는 어뷰즈 차단이 우선이라 후속으로 분리.

12. 미해결 질문

• UU(쿠키 기반 고유 방문자) — 별도 후속 (#274 후속 #337의 잔여 항목으로 분리).
• Bucket4j 1분 정책의 적정성 — 운영 1주일 관찰 후 조정.
• 봇 UA 화이트리스트(친화적 검색 엔진은 카운트 포함?) — 현재 일괄 skip.