Spring Cloud Gateway + Auth-Service MSA 구축 중 발생한 오류와 트러블슈팅

1. 프로젝트 개요

• Gateway + Auth-Service를 분리한 MSA 환경 구축
• Gateway에서 JWT 인증 처리, Auth-Service는 인증 토큰 발급 담당
• Docker 컨테이너로 개별 배포

---

 

2. 주요 문제와 해결 과정

문제 1: Gateway에서 Auth-Service로 요청 시 404 Not Found 발생

• Gateway application.yml에서 routes 설정에 StripPrefix 옵션과 경로 매핑이 맞지 않아 발생
• 예) Gateway에 /auth/login 요청이 오면, StripPrefix=1일 경우 /login으로 바뀌는데, Auth-Service의 컨트롤러가 /auth/login으로만 매핑되어 있어 404 발생
  해결:
• Gateway StripPrefix 옵션과 Auth-Service 컨트롤러의 @RequestMapping 경로를 일치시킴
• 또는 StripPrefix=0으로 설정해 Gateway가 경로를 그대로 전달하도록 변경

---

문제 2: Auth-Service 컨테이너 포트 불일치 문제

• Docker 컨테이너에서는 8081:8081 포트 매핑을 했으나, Auth-Service가 실제로는 내부에서 8080 포트로 실행됨
• Gateway가 http://auth_service_app:8081로 요청을 보내도 Auth-Service 내부 서버가 8081을 열지 않아 연결 실패 또는 404 발생
  해결:
• Auth-Service application.yml에서 server.port를 8081로 변경하여 컨테이너 내부 포트와 일치시킴
• 또는 Docker 포트 매핑을 8080:8080으로 변경해 내부 포트와 맞춤

---

문제 3: Spring Cloud Gateway 최신 버전 설정 관련 Deprecated 경고

• 최신 Spring Cloud Gateway (2025.0.0+)에서는 spring.cloud.gateway.routes 설정이 deprecated 됨
• 의존성으로 spring-cloud-starter-gateway-server-webflux를 사용할 경우, 설정 경로가 spring.cloud.gateway.server.webflux.routes로 바뀌어야 함
• 하지만 기존 문서 및 예제들은 구 버전 spring.cloud.gateway.routes 형태 사용
  해결:
• 버전을 다운그레이드 하여 안정적인 이전 버전을 사용하거나
• 설정을 최신 스펙에 맞춰 spring.cloud.gateway.server.webflux.routes 형태로 변경
• 두 경우에 맞는 build.gradle 의존성과 설정을 맞춤

---

문제 4: Gateway Security 설정과 JWT 필터 적용

• Gateway에서 Spring Security를 WebFlux 기반으로 적용하는 과정에서 @EnableWebFluxSecurity 필요
• SecurityWebFilterChain에서 /auth/** 경로는 permitAll 설정하고 JWT 필터를 적절한 위치에 등록
• JWT 토큰이 없거나 유효하지 않으면 401 Unauthorized 반환하도록 구현
  팁: Gateway가 인증을 책임지고, Auth-Service는 인증 로직 없이 단순 토큰 발급 서비스로 운영하는 것이 관리 편리

---

3. 마무리

• MSA 환경 구축 시 네트워크, 포트, 경로 매핑, 보안 정책이 꼼꼼히 맞아야 정상 동작
• 최신 라이브러리와 버전을 쓸 때는 문서의 변경사항과 deprecated 경고에 주의
• Docker 컨테이너 내부 포트와 외부 포트 매핑이 일치하는지 꼭 확인
• Gateway에서 인증 처리 후 내부 서비스로 요청 포워딩 시 경로 변환 설정을 꼼꼼히 체크

---

4. 참고 자료

• Spring Cloud Gateway 공식 문서
• Spring Security WebFlux 문서
• Docker 네트워크 및 포트 매핑 관련 공식 가이드