Files
clean-architecture-backend-…/docs/security/rate-limiting.md
T
DongHyeonka 1444d1e0df
pr / gradle (pull_request) Failing after 7m18s
pr / vulnerabilities (pull_request) Successful in 1m1s
pr / done (pull_request) Canceled after 0s
docs(security): 요청률 제한은 기본 off·ingress 책임임을 명시한다
W4 red team BE-OBS-A 소유자 결정(2026-11-12): 요청 빈도 제한은 앱 기본 off로 두고
ingress/gateway 책임으로 명시한다. 앱은 크기/양 bound는 이미 강제하고, 빠진 축은
요청 빈도 하나이며 그것은 앞단이 서비스 전체 기준으로 보는 게 맞다.

docs/security/rate-limiting.md에 자세(기본 off·ingress 책임)와 앞단에서 안 거는
배포를 위한 앱 내 redis limiter 켜는 법(모듈·env·client-ip 주의)을 적는다. 운영
매뉴얼(docs/work/operate.md 파생 서비스 절)과 PR 체크리스트(docs/manual/
11-checklist.md inbound)에서 가리켜, 파생 서비스가 릴리스 전에 "요청률을 어디서
거는가"를 정하게 한다.

동작/코드 변경 없음(문서만).
2026-11-12 01:15:07 +09:00

2.2 KiB

요청률 제한 (rate limiting) — 기본 OFF, ingress 책임

  • 결정: 소유자, 2026-11-12 (W4 red team BE-OBS-A).

자세(posture)

이 템플릿은 요청 빈도(rate) 제한을 앱에서 기본으로 켜지 않는다(APP_RATE_LIMIT_ENABLED 기본 false). 요청률 제한은 ingress/gateway의 책임이다. 파생 서비스는 앞단(ingress-nginx·API gateway·CDN·WAF)에서 IP·클라이언트·경로별 요청률을 건다.

이것은 보호가 없다는 뜻이 아니다. 앱은 크기/양 bound를 이미 강제한다: 업로드/다운로드 크기·range 수, 메시지 payload(64KB), GraphQL complexity(10000)·page-size(100)·depth/alias, gRPC 메시지(1MiB)·deadline, 연결 수(WS 1000)·send-buffer. 빠진 것은 요청 빈도 한 축이고, 그것은 앞단이 서비스 전체(여러 인스턴스) 기준으로 보는 게 맞다.

앞단에서 안 거는 배포라면 — 앱 내 limiter 켜기

redis 기반 limiter를 쓸 수 있다(fail-closed):

  1. 모듈을 런타임에 둔다: runtimeOnly project(':adapter:outbound:cache-redis').
  2. APP_REDIS_ENABLED=true + redis 접속(APP_*_REDIS_*).
  3. APP_RATE_LIMIT_ENABLED=true, APP_RATE_LIMIT_PROVIDER=redis, APP_RATE_LIMIT_FAILURE_POLICY=fail-closed.
  4. 클라이언트 IP 해석: 운영 정본은 APP_SERVER_FORWARD_HEADERS_STRATEGY=native + Tomcat remoteip.internal-proxies로 getRemoteAddr() 하나를 쓴다. APP_RATE_LIMIT_CLIENT_IP_MODE의 XFF-왼쪽 모드는 호출자가 위조할 수 있으니 신뢰 프록시 체인이 설 때만 쓴다(docs/capability-status.md, I-5a·NEW-10c).

자세한 키는 docs/registries/env-keys.yaml의 APP_RATE_LIMIT_*, 모듈 기본값은 src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml.

파생 서비스가 정할 것 (릴리스 전 확인)

  • 이 서비스의 요청률 제한을 어디서 거는가(ingress / app / 둘 다)를 배포 설계에 적는다.
  • ingress에서 건다면 그 규칙(IP·경로·버스트)을 배포 repo에 둔다. 앱에서 건다면 위 4단계 + redis 용량.
  • 둘 다 안 걸면 그것이 의식적 결정임을 적는다(내부 전용·앞단 보호 있음 등).