kimfishes 님의 블로그

PGVector Window 설치 방법

kimfishes — Tue, 7 Apr 2026 16:01:06 +0900

https://kimfishes.tistory.com/17

LLM (Ollama) RAG 구현 전 pgvector VS Qdrant 중 무엇이 좋을까

https://kimfishes.tistory.com/3 SpringAI 사용해서 LLM (Ollama) 연결 + Resilience4j 도입 (Spring Boot)고객센터에 사용자가 문의 게시물을 작성하면 관리자에게 디스코드로 알림이 가고, 관리자가 답변을 달아주기

kimfishes.tistory.com

구현하려는 전체 구조

[사용자] → [백엔드 (Spring)]
                ↓
        [Embedding 생성 (Ollama)]
                ↓
        [PostgreSQL + pgvector]
                ↓
        [유사도 검색]
                ↓
        [응답 생성]

PGVector 설치 (Window 설치법)

- PostgreSQL은 이미 설치되어 있으므로 PGVvector의 추가 설치법만 작성합니다.

- 현재 설치법은 Window OS 설치법이므로 Linux는 git에 접속하여 설치법 대로 따라하시면 됩니다.

https://github.com/pgvector/pgvector

GitHub - pgvector/pgvector: Open-source vector similarity search for Postgres

Open-source vector similarity search for Postgres. Contribute to pgvector/pgvector development by creating an account on GitHub.

github.com

- 윈도우 검색창에 x64 Native Tools Command Prompt for VS 2022 검색

- nmake /? 이라고 명령을 입력했을 때 이러한 결과처럼 나온다면 C++ 설치 필요

- 이번에도 윈도우에서 Visual Studio Installer를 검색 후

Installer가 열리면

설치된 Visual Studio 2022 Community 옆에 수정(Modify) 클릭
Desktop development with C++ 체크
설치

- 설치 후 nmake /? 이러한 화면이 나오면 성공

- git에 쓰여진 대로 입력해주면 설치 끝

set "PGROOT=C:\Program Files\PostgreSQL\18"
cd %TEMP%
git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector
nmake /F Makefile.win
nmake /F Makefile.win install

PostgreSQL에 터미널로 접속하거나 pgAdmin을 사용해 PostgreSQL에 "벡터 기능" 추가

- CREATE EXTENSION vector;

RAG 구현 전 Vector DB 선택 (PGVector VS Qdrant 중 무엇이 좋을까?)

kimfishes — Tue, 7 Apr 2026 13:57:32 +0900

https://kimfishes.tistory.com/3

SpringAI 사용해서 LLM (Ollama) 연결 + Resilience4j 도입 (Spring Boot)

고객센터에 사용자가 문의 게시물을 작성하면 관리자에게 디스코드로 알림이 가고, 관리자가 답변을 달아주기 전 AI가 먼저 문의글에 맞게 답변을 달아주는 기능을 구현하려고 한다.디스코드(Di

kimfishes.tistory.com

기존 Ollama로 LLM을 사용하던 상황에서도 기본적인 대화는 가능하다.
하지만 예를 들어:

“고객센터 몇 시에 종료되나요?”
“환불은 언제까지 가능하죠?”
“구독 해지는 바로 되나요?”

이 질문들은 정확한 정책/운영 정보를 요구한다.

LLM은:

일반적인 지식은 잘 답하지만
우리 회사의 최신 정책은 모른다
잘못된 정보를 그럴듯하게 만들어낼 수 있다 (hallucination)

즉, 단순히 “학습시킨다”는 개념으로 해결할 수 없다.

그래서 등장하는 개념이 바로 RAG다.

RAG란 무엇인가

RAG(Retrieval-Augmented Generation)는

“LLM이 답을 만들기 전에, 먼저 관련 정보를 검색해서 참고하게 만드는 구조”

사용자가 질문한다.
질문을 벡터로 변환한다.
의미가 비슷한 문서를 검색한다.
검색된 문서를 LLM 프롬프트에 넣는다.
LLM이 해당 문서를 기반으로 답변을 생성한다.

즉,

LLM = 답변 생성기
Vector DB = 의미 기반 검색 엔진
DB/파일 = 정답 원문 저장소

이 세 가지가 조합되는 구조다.

왜 Vector DB가 필요한가

기존 LIKE 검색으로는 부족하다.

FAQ에 이런 문장이 있다고 해보자.

“고객센터 게시물에 계좌번호와 성함을 남기시면 2~3일 내 환불 처리됩니다.”

사용자 질문:

“환불은 어떻게 하나요?”
“돈 돌려받으려면 어디에 써야 돼요?”
“결제 취소하면 언제 입금돼요?”

키워드 검색은 표현이 조금만 달라져도 놓친다.

반면 벡터 검색은:

“환불”
“돈 돌려받다”
“결제 취소”

를 의미적으로 가깝게 인식한다.

문장을 숫자 벡터로 변환하고, 코사인 유사도 기반으로 가장 가까운 문서를 찾는다.

Vector DB는 이 벡터 저장/검색을 빠르게 처리해 주는 DB다.

이때 답변 데이터는 어디에 저장해야 하는가?

정답이 절대 틀리면 안 되는 정책은 반드시 정형 DB에 저장해야 한다.

예:

환불 가능 기간
운영 시간
약관
적용 시작/종료일
회원 등급별 정책

DB = 정책 원문 + 메타데이터 (정답 SSOT)
Vector DB = 검색 인덱스 (임베딩) 사용

흐름

정책을 DB에 저장
정책 텍스트를 임베딩 생성
벡터를 Vector DB에 저장
질문이 오면 Vector DB에서 후보 검색
최종 출력은 DB의 최신 활성 정책 사용

즉, Vector DB는 검색용 인덱스일 뿐, 정답 저장소가 아니다.

pgvector vs Qdrant

Vector DB를 위해 이 둘을 선택하는 과정에서 고민이 발생했다.

Postgres + pgvector
Qdrant (전용 Vector DB)

벤치마크

https://www.tigerdata.com/blog/pgvector-vs-qdrant

이 블로그의 벤치마크를 보면 결론은 의외로 단순하다.

사용 패턴에 따라 달라지지만 둘 사이에 성능 차이는 크지 않다.

Qdrant는 단일 쿼리 latency 측면에서 강점
pgvector(+pgvectorscale)는 throughput 측면에서 강점
대규모(수천만 벡터) 환경에서도 둘 다 충분히 고성능

“Qdrant가 압도적으로 빠르다”도 아니고
“pgvector가 압도적으로 낫다”도 아니다.

만약 나의 상황이 MySQL만 사용 중이라면?

현재 메인 DB는 MySQL
pgvector를 쓰려면 Postgres를 새로 띄워야 한다
Qdrant를 써도 서버를 새로 띄워야 한다

결론:

어차피 서버 하나는 추가된다.

그렇다면 선택 기준은 “성능”이 아니라 역할 분리와 단순성이 된다.

Qdrant를 선택하는 경우 장점은?

1) 벡터 검색에만 집중된 구조

벡터 저장
유사도 검색
ANN 인덱싱

이러한 목적에 최적화된 DB로 불필요한 SQL 레이어가 없다.

2) MySQL과 역할이 명확히 분리됨

MySQL = 정책 원문 + 비즈니스 데이터
Qdrant = 검색 인덱스

도메인 분리가 명확하다.

3) RAG에 바로 맞는 API 구조

REST 기반으로 바로 연동 가능하고, Collection 개념도 직관적이다.

4) 운영 부담이 크게 다르지 않음

pgvector를 쓰려면 Postgres를 도입해야 한다.

백업
모니터링
권한 관리
운영 전략

어차피 새로운 DB를 관리해야 한다면, 벡터 전용 DB를 두는 것이 구조적으로 더 명확하다라고도 볼 수 있음

Spring Boot
 ├─ MySQL (정책/정답 저장)
 ├─ Qdrant (벡터 검색 인덱스)
 └─ Ollama (LLM)

흐름:

정책은 MySQL에 저장
임베딩 생성 후 Qdrant에 저장
질문 들어오면 Qdrant로 후보 검색
MySQL에서 최신 활성 정책 조회
Ollama가 답변 생성

Spring Boot 4에서 외부 API 호출 무엇을 선택해야 할까?

kimfishes — Fri, 27 Mar 2026 22:13:17 +0900

Spring Boot에서 외부 API를 호출해야 하는 경우 RestClient vs WebClient vs Feign Client vs WebFlux 중 무엇을 선택해야 좋을지 궁금해서 끄적여 보았습니다.

1. RestTemplate은 왜 고려하지 않는지?

과거에는 RestTemplate이 기본 선택이었습니다. 하지만 현재는 유지보수 모드이며, Spring 공식 문서에서도 신규 프로젝트에서는 사용을 권장하지 않음

따라서 Boot 4 기준에서는:

RestTemplate → 구버전
RestClient / WebClient / Feign Client / WebFlux → 사용 권장

2. RestClient란?

RestClient는 Spring Framework 6.1부터 도입된 최신 동기 HTTP 클라이언트

특징

동기 방식 (Blocking)
코드가 간결하고 직관적
Spring MVC와 궁합이 좋음
Boot 4 공식 권장 방식
빌더 패턴으로 가독성 우수

예시 코드

RestClient restClient = RestClient.create();

KakaoUserInfo response = restClient.get()
        .uri("https://api.kakao.com/v2/user/me")
        .header("Authorization", "Bearer " + token)
        .retrieve()
        .body(KakaoUserInfo.class);

기존 RestTemplate보다 훨씬 가독성이 좋고 체이닝 방식이라 깔끔함

3. WebClient란?

WebClient는 Spring의 리액티브(비동기, 논블로킹) HTTP 클라이언트

특징

비동기(Non-blocking)
대규모 트래픽에 유리
병렬 API 호출 가능
리액티브 아키텍처에 적합
Reactor 기반 Mono/Flux 반환

예시 코드

WebClient webClient = WebClient.create();

KakaoUserInfo response = webClient.get()
        .uri("https://api.kakao.com/v2/user/me")
        .header("Authorization", "Bearer " + token)
        .retrieve()
        .bodyToMono(KakaoUserInfo.class)
        .block();  // MVC에서는 block() 호출 필요

주의: MVC 환경에서는 결국 .block()을 호출해야 하므로 비동기의 장점이 줄어드는 경우가 많음

4. WebFlux란?

WebFlux는 Spring이 제공하는 완전한 리액티브 웹 프레임워크입니다. 단순한 HTTP 클라이언트가 아니라 서버 프레임워크

특징

완전한 논블로킹/비동기 아키텍처
Netty를 기반으로 한 리액티브 서버
Mono/Flux로 스트림 처리
MVC를 완전히 대체하는 선택지
고성능, 저리소스 사용
함수형 프로그래밍 지원

MVC vs WebFlux 아키텍처 비교

서버	Tomcat (Servlet 기반)	Netty (리액티브 기반)
스레드 모델	스레드 풀 (요청당 1 스레드)	이벤트 루프 (스레드 수 최소화)
동작 방식	블로킹	논블로킹
메모리 사용	높음 (스레드당 메모리)	낮음 (스레드 수 적음)
동시 연결	제한적	매우 많음
학습곡선	낮음	높음

WebFlux 예시 코드 (서버)

@RestController
@RequestMapping("/api")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    // Mono: 단일 값 반환
    @GetMapping("/users/{id}")
    public Mono<User> getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
    
    // Flux: 여러 값 스트림 반환
    @GetMapping("/users")
    public Flux<User> getAllUsers() {
        return userService.findAll();
    }
}

WebFlux 예시 코드 (서비스)

@Service
public class UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    // 단일 값
    public Mono<User> findById(Long id) {
        return Mono.fromCallable(() -> userRepository.findById(id))
                .filterWhen(opt -> Mono.just(opt.isPresent()))
                .map(opt -> opt.get());
    }
    
    // 스트림 값
    public Flux<User> findAll() {
        return Flux.fromIterable(userRepository.findAll());
    }
}

WebFlux + WebClient 조합 (병렬 처리)

@Service
public class OrderService {
    
    private final WebClient webClient = WebClient.create();
    
    // Mono 반환 - 리액티브 완성
    public Mono<Order> createOrder(OrderRequest req) {
        Mono<Payment> paymentMono = webClient.post()
                .uri("http://payment-service/pay")
                .bodyValue(req.getPayment())
                .retrieve()
                .bodyToMono(Payment.class);
        
        Mono<Stock> stockMono = webClient.get()
                .uri("http://stock-service/check/{id}", req.getProductId())
                .retrieve()
                .bodyToMono(Stock.class);
        
        Mono<Shipping> shippingMono = webClient.get()
                .uri("http://shipping-service/quote")
                .retrieve()
                .bodyToMono(Shipping.class);
        
        // 세 개 API를 병렬로 호출 - 완전한 비동기 (block() 없음!)
        return Mono.zip(paymentMono, stockMono, shippingMono)
                .map(tuple -> new Order(tuple.getT1(), tuple.getT2(), tuple.getT3()));
    }
}

주목: WebFlux에서는 .block()을 호출하지 않습니다. 완전한 논블로킹 구조를 유지

5. Feign Client란?

Feign Client는 Netflix가 개발한 선언적 HTTP 클라이언트로, Spring Cloud에서 제공

특징

인터페이스 기반 선언적 방식
어노테이션으로 HTTP 요청 정의
동기 방식 (Blocking)
MSA 환경에서 표준처럼 사용
자동 로드밸런싱 지원 (Eureka 연동 시)
에러 처리 및 재시도 로직 자동화 가능

의존성

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

기본 예시 코드

@FeignClient(name = "kakao-api", url = "https://api.kakao.com")
public interface KakaoFeignClient {
    
    @GetMapping("/v2/user/me")
    KakaoUserInfo getUserInfo(
        @RequestHeader("Authorization") String token
    );
}

// 사용
@Service
public class OAuthService {
    
    @Autowired
    private KakaoFeignClient kakaoClient;
    
    public KakaoUserInfo getKakaoUser(String token) {
        return kakaoClient.getUserInfo("Bearer " + token);
    }
}

Feign의 강력한 기능

1. 자동 로드밸런싱 (Eureka 연동)

@FeignClient(name = "user-service")  // Eureka에서 자동 조회
public interface UserFeignClient {
    @GetMapping("/users/{id}")
    User getUser(@PathVariable Long id);
}

2. 재시도 로직 자동화

@FeignClient(name = "payment-service", 
             configuration = FeignConfig.class)
public interface PaymentFeignClient {
    @GetMapping("/payment/{id}")
    Payment getPayment(@PathVariable Long id);
}

@Configuration
public class FeignConfig {
    @Bean
    public Retryer retryer() {
        return new Retryer.Default(100, 1000, 3);  // 3회 재시도
    }
}

3. 타임아웃 설정

@Configuration
public class FeignConfig {
    @Bean
    public Request.Options options() {
        return new Request.Options(
            5, TimeUnit.SECONDS,   // 연결 타임아웃
            5, TimeUnit.SECONDS,   // 읽기 타임아웃
            true                   // 리다이렉트 허용
        );
    }
}

4. 에러 처리

@Component
public class FeignErrorDecoder implements ErrorDecoder {
    @Override
    public Exception decode(String methodKey, Response response) {
        if (response.status() == 404) {
            return new UserNotFoundException("User not found");
        }
        if (response.status() == 500) {
            return new ServerException("Server error");
        }
        return new FeignException("API call failed");
    }
}

5. 완전한 설정 예시

@FeignClient(
    name = "payment-service",
    url = "http://payment-service:8080",
    configuration = PaymentFeignConfig.class
)
public interface PaymentFeignClient {
    
    @PostMapping("/payments")
    PaymentResponse processPayment(@RequestBody PaymentRequest request);
    
    @GetMapping("/payments/{id}")
    PaymentResponse getPayment(@PathVariable Long id);
}

@Configuration
public class PaymentFeignConfig {
    
    // 재시도 로직
    @Bean
    public Retryer retryer() {
        return new Retryer.Default(100, 1000, 3);
    }
    
    // 타임아웃
    @Bean
    public Request.Options options() {
        return new Request.Options(5, TimeUnit.SECONDS, 5, TimeUnit.SECONDS, true);
    }
    
    // 에러 처리
    @Bean
    public ErrorDecoder errorDecoder() {
        return new PaymentErrorDecoder();
    }
    
    // 로깅
    @Bean
    public Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

6. 무엇을 선택해야 할까?

RestClient를 선택해야 하는 경우

Spring MVC 기반 프로젝트
OAuth 토큰 발급 / 유저 조회 같은 단순 API 호출
외부 API 연동 (카카오, 구글, 네이버 등)
복잡한 병렬 처리 필요 없음
코드 단순성이 중요
대부분의 일반적인 백엔드 서비스

WebClient를 선택해야 하는 경우

WebFlux 기반 리액티브 서버
동시에 여러 외부 API 호출해야 함
고트래픽 마이크로서비스
논블로킹 구조가 필요한 경우
대규모 배치 작업
MSA + 고성능 환경

WebFlux를 선택해야 하는 경우

완전한 리액티브 아키텍처 필요
실시간 스트리밍 데이터 처리
매우 높은 동시 연결 수 (10,000+)
마이크로서비스 환경에서 응답 시간이 매우 중요
함수형 프로그래밍 스타일 선호
고성능, 저리소스 마이크로서비스
학습곡선이 높을 수 있을 수도?

Feign Client를 선택해야 하는 경우

마이크로서비스 아키텍처 (MSA)
서비스 간 통신이 주 목적
Eureka 같은 서비스 디스커버리 사용
선언적인 코드 스타일 선호
재시도 로직이나 로드밸런싱 자동화 필요
여러 개의 내부 API 호출
모놀리식 구조보다는 분산 환경

7. 실전 예시: 상황별 선택

시나리오 1: 카카오 로그인 구현

// RestClient 사용
@Service
public class KakaoOAuthService {
    
    private final RestClient restClient = RestClient.create();
    
    public KakaoUserInfo getUserInfo(String token) {
        return restClient.get()
                .uri("https://api.kakao.com/v2/user/me")
                .header("Authorization", "Bearer " + token)
                .retrieve()
                .body(KakaoUserInfo.class);
    }
}

이유: 단순 외부 API 호출, MVC 환경, 코드 간결성 필요

시나리오 2: 주문 시 동시에 결제 + 재고 확인 + 배송 조회

// WebClient 사용
@Service
public class OrderService {
    
    private final WebClient webClient = WebClient.create();
    
    public Order createOrder(OrderRequest req) {
        Mono<Payment> paymentMono = webClient.post()
                .uri("http://payment-service/pay")
                .bodyValue(req.getPayment())
                .retrieve()
                .bodyToMono(Payment.class);
        
        Mono<Stock> stockMono = webClient.get()
                .uri("http://stock-service/check/{id}", req.getProductId())
                .retrieve()
                .bodyToMono(Stock.class);
        
        Mono<Shipping> shippingMono = webClient.get()
                .uri("http://shipping-service/quote")
                .retrieve()
                .bodyToMono(Shipping.class);
        
        // 세 개 API를 병렬로 호출하고 모두 완료 대기
        return Mono.zip(paymentMono, stockMono, shippingMono)
                .map(tuple -> new Order(tuple.getT1(), tuple.getT2(), tuple.getT3()))
                .block();  // MVC에서 동기 반환
    }
}

이유: 병렬 API 호출, 대기 시간 최소화, 높은 동시성

시나리오 3: 실시간 주문 알림 시스템 (고동시성)

// WebFlux + WebClient 사용
@RestController
@RequestMapping("/api/orders")
public class OrderController {
    
    @Autowired
    private OrderService orderService;
    
    // Server-Sent Events (SSE) - 실시간 스트림
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<Order> getOrderStream() {
        return orderService.getOrderStream();
    }
    
    // WebSocket도 가능
    @GetMapping("/subscribe")
    public Mono<Order> subscribeOrder(@PathVariable Long id) {
        return orderService.findById(id);
    }
}

@Service
public class OrderService {
    
    private final WebClient webClient = WebClient.create();
    
    // Flux로 계속 데이터 스트림
    public Flux<Order> getOrderStream() {
        return Flux.interval(Duration.ofSeconds(1))  // 1초마다 실행
                .flatMap(i -> webClient.get()
                        .uri("http://order-service/latest")
                        .retrieve()
                        .bodyToMono(Order.class)
                )
                .retry(3);  // 실패 시 3회 재시도
    }
}

이유: 완전한 논블로킹, 실시간 스트리밍, 매우 높은 동시성 (10,000+ 연결)

시나리오 4: MSA 환경에서 주문 서비스가 결제 서비스 호출

// Feign Client 사용
@FeignClient(
    name = "payment-service",
    url = "http://payment-service:8080",
    configuration = PaymentFeignConfig.class
)
public interface PaymentFeignClient {
    
    @PostMapping("/payments")
    PaymentResponse processPayment(@RequestBody PaymentRequest request);
    
    @GetMapping("/payments/{id}")
    PaymentResponse getPayment(@PathVariable Long id);
}

@Configuration
public class PaymentFeignConfig {
    
    // 재시도 로직: 3회 시도, 100ms ~ 1000ms 간격
    @Bean
    public Retryer retryer() {
        return new Retryer.Default(100, 1000, 3);
    }
    
    // 타임아웃
    @Bean
    public Request.Options options() {
        return new Request.Options(5, TimeUnit.SECONDS, 5, TimeUnit.SECONDS, true);
    }
    
    // 에러 디코딩
    @Bean
    public ErrorDecoder errorDecoder() {
        return new PaymentErrorDecoder();
    }
}

// 사용
@Service
public class OrderService {
    
    @Autowired
    private PaymentFeignClient paymentClient;
    
    public Order createOrder(OrderRequest req) {
        PaymentResponse payment = paymentClient.processPayment(
            new PaymentRequest(req.getAmount(), req.getOrderId())
        );
        
        if (payment.isSuccess()) {
            return new Order(req, payment);
        }
        throw new PaymentFailedException("결제 실패");
    }
}

이유:

서비스 간 통신
Eureka와 함께 사용하면 로드밸런싱 자동화
재시도/타임아웃/에러 처리 자동화
선언적이고 깔끔한 코드

8. 선택 플로우차트

HTTP 클라이언트가 필요한가?
│
├─ 웹 서버 자체를 리액티브하게 구성하고 싶은가?
│  └─ YES → WebFlux
│
├─ 외부 API 호출인가? (카카오, 구글, 네이버 등)
│  └─ YES → RestClient
│
├─ 마이크로서비스 간 통신인가?
│  └─ YES → Feign Client
│
└─ 동시에 여러 API를 병렬로 호출해야 하는가?
   └─ YES → WebClient
   └─ NO → RestClient 또는 Feign Client 중 선택

10. 성능 비교

시나리오처리량 (req/s)응답시간 (ms)메모리 (MB)

MVC + RestClient (1,000 동시)	5,000	200	500
MVC + WebClient (1,000 동시)	8,000	125	300
WebFlux + WebClient (10,000 동시)	50,000	50	200
MSA + Feign (1,000 동시)	6,000	167	400

주목: 동시 연결이 1,000을 넘어가면 WebFlux의 장점이 극대화

결론

일반 웹 애플리케이션 + 외부 API 호출	RestClient	간단하고 Spring MVC와 완벽 호환
고성능 필요 + 병렬 처리 많음	WebClient	논블로킹으로 동시성 극대화
완전한 리액티브 아키텍처 + 실시간 스트림	WebFlux	고동시성, 저리소스, 스트리밍 처리
MSA 환경 + 서비스 간 통신	Feign Client	선언적이고 자동화 기능 우수

Spring Boot 4 시대에는 더 이상 RestTemplate을 선택할 이유가 없음

왜 UUID v7을 선택했는가? (Snowflake와 비교까지)

kimfishes — Thu, 26 Feb 2026 17:07:28 +0900

대부분의 프로젝트는 기본 키로 다음 중 하나를 사용한다.

AUTO_INCREMENT (Long)
UUID v4 (랜덤)
Snowflake (시간 기반 64bit ID)

이번 프로젝트에서는 Postgres + Hibernate 환경에서 UUID v7을 선택했다.

왜 굳이 v7을 선택했는지, 그리고 Snowflake와는 무엇이 다른지 정리해본다.

기존 UUID v4의 문제점

UUID v4는 완전 랜덤이다.

550e8400-e29b-41d4-a716-446655440000

장점

충돌 확률 거의 없음
분산 환경에서 안전
중앙 서버 불필요

단점

완전 랜덤 → B-Tree 인덱스에 불리
insert 시 page split 빈번
인덱스 단편화 발생
대량 트래픽 환경에서 성능 저하

Postgres나 MySql 기본 인덱스는 B-Tree라 순차 증가 값에 최적화되어 있다.

그러나 랜덤 값(v4)은 매번 트리 중간에 삽입되기 때문에 성능상 불리하다.

UUID v7란?

UUID v7은 2024년 RFC 9562에서 공식화된 최신 UUID 버전

앞부분 = 시간 기반
뒷부분 = 랜덤

# UUID V7 구조
48bit Unix epoch milliseconds + 랜덤 비트

시간 순 정렬 가능
인덱스 친화적
충돌 확률 매우 낮음
Snowflake처럼 동작하지만 표준 UUID 형식 유지

Snowflake란

Snowflake ID는 Twitter에서 만든 분산 ID 생성 전략

# SnowFlake 구조
timestamp (41bit)
workerId (10bit)
sequence (12bit)

특징

시간 순 정렬 가능
분산 환경 지원
중앙 DB 없이 ID 생성
Long 타입 (64bit)

장점

인덱스 친화적
AUTO_INCREMENT처럼 정렬됨
높은 성능

단점

중앙 시계 의존 (Clock rollback 문제)
worker id 관리 필요
구현 복잡도 존재
DB 독립적이지만 시스템 설계 필요

왜 Snowflake 대신 UUID v7을 선택했는가?

1️⃣ 표준 기반

UUID v7은 RFC 공식 표준이지만 Snowflake는 구현 전략일 뿐 표준이 아니다.

2️⃣ 운영 복잡도 감소

Snowflake는 worker id 관리, 시계 동기화 문제, 인프라 고려 필요로 즉 ID 생성이 시스템 설계 일부가 된다.
그러나 UUID v7은 그냥 생성하면 끝

3️⃣ 만드려는 시스템이 Snowflake를 "관리할 가치가 있는가?"판단 필요

- Snowflake는 이런 경우에 빛난다

초고트래픽
수십~수백 노드
ID를 long으로 유지해야 함
Kafka key 등에서 8byte 이점 중요
글로벌 스케일

- 반면, 이런 경우라면?

모놀리식
혹은 소규모 MSA
운영 복잡도 최소화가 목표

4️⃣ Hibernate와 쉽게 통합 가능하여 구현의 간단함

- 의존성 주입

    implementation("com.github.f4b6a3:uuid-creator:5.3.3")

- 엔티티에 사용 코드

@Entity
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class User extends BaseEntity {

    @Id
    @Column(nullable = false, updatable = false)
    private UUID id;


    @PrePersist
    void init() {
        if (id == null) {
            id = UuidCreator.getTimeOrderedEpoch(); // = UUID v7
        }
    }
}

UUID v7의 단점은 없는가?

128bit라 Snowflake(64bit)보다 크다.
사람이 보기 어렵다.
로그 추적 시 가독성 낮음

항목	Snowflake	UUID v7
타입	bigint	uuid
길이	64bit	128bit
시간 정렬	O	O
분산 지원	O	O
worker 관리	필요	불필요
표준	비표준	RFC 표준
DB 독립성	O	O
인덱스 성능	좋음	좋음

크기 문제 해결 방법

128bit라는 크기를 해결하기 위해 MySQL에서는 UUID를 저장하기 위한 방식이 3가지 존재한다.
MySQL에는 PostgreSQL처럼 전용 UUID 타입이 없기 때문

방식	타입	크기	특징
문자열 저장	CHAR(36)	36 bytes	가독성 좋음, 느림
압축 저장	BINARY(16)	16 bytes	빠름, 공간 절약
함수 기반	UUID_TO_BIN()	16 bytes	정렬 최적화 가능

BINARY(16) 장점

16바이트로 저장
인덱스 작아짐
비교 빠름
캐시 효율 증가
이러한 이유들로 MySQL에선 BINARY(16)이 사실상 정석

id BINARY(16) NOT NULL PRIMARY KEY

그렇다면 PostgreSQL에서 크기 해결법은?

Postgres에는 전용 uuid 타입이 있어 내부적으로 16바이트로 저장함
인덱스 최적화
함수 내장
타입 안정성 보장

결론

Snowflake는 더 강력하지만, ID 생성 전략이 인프라 설계의 일부가 된다.
UUID v7은 Snowflake의 시간 정렬 장점을 유지하면서도, 표준 기반이며 운영 부담이 없기 때문에
이번 프로젝트는 운영 단순성과 표준 기반 설계를 우선했다.

Lettuce VS Redisson 분산 락

kimfishes — Fri, 13 Feb 2026 15:54:51 +0900

https://kimfishes.tistory.com/13

허브 간 최단 경로 탐색 캐시 스탬피드 (Cache Stampede) 발생+해결

이전 문제 상황출발지와 목적지 사이 허브 간 경로를 다익스트라 알고리즘으로 선정 후, Kakao Api를 호출해 허브 간 소요 시간 산출이때 Kakao Api 응답을 기다리는 방식의 경우 16 ~ 20 초의 많은 시

kimfishes.tistory.com

나의 상황

1명만 refresh lock → Kakao Api를 호출하여 값 갱신 시도
나머지는 Redis 재조회 2~3회 후 없으면 TTL 시간이 지난 값이라도 반환
성공 시 DB upsert + Redis set

- 허브 간 소요시간 저장 시 Redis에 분산락을 사용하여 하나의 요청만 Kakao에 요청하여 값이 갱신되도록 해야 함

- 동일 키에 대해 갱신자 1명만 선출하면 되고, 나머지는 락 대기 없이 값을 랜덤하게 2 ~ 3회 기다리다가 그래도 값을 받지 못하면 TTL 시간이 지난 값이라도 반환

Lettuce이란

Lettuce는 Redis와 비동기로 통신할 수 있는 자바 클라이언트
Redis 서버에 명령을 안전하고 효율적으로 전달
비동기 / 논블로킹 기반
Redis polling + jitter 구조에 안정적
분산락을 “자동으로” 제공하진 않음

단점

“락 자체”를 제공하지 않는다 → 직접 설계/검증 필요
재시도/폴링 설계를 잘못하면 결국 “스핀락”이 된다
TTL 만료 시간에 Lock 획득으로 동시 갱신자 가능성
- A가 갱신 중인데 TTL 만료 -> B가 락 획득 → Kakao API를 또 호출하여 결과적으로 “중복 호출” 발생

Redisson ( 고수준 라이브러리 분산락 ) 이란

Redis 위에 “분산 객체”를 제공하는 라이브러리
RLock, RMap, RSemaphore 같은 고수준 API 제공
내부적으로 Lua + watchdog + TTL 자동 연장

단점

락이 무거움 (watchdog 스레드)
“외부 API 1번만 호출” 같은 정밀 제어엔 과함

Lettuce 선택 이유

Redis의 Lettuce 락은 Lock를 얻지 못한 스레드가 Lock 획득 시도를 반복하는 스핀락(spin lock) 문제가 있으므로 무조건 사용하면 안된다라는 블로그들에 글이 꽤 있다.
하지만 지금의 경우 Lock 획득하기 위해 싸우는게 목적이 아닌 "갱신자 한 명을 선출하는 게 목적"
즉 락을 기다리지 않는 single-flight 캐시 갱신 정책을 사용하므로 최소 기능(SET NX PX + 토큰 기반 해제)만으로 투명하고 가볍게 구현 가능한 Lettuce 방식을 선택
혹여나 중복 호출이 발생하더라도 허브 간 소요 시간 결과에 악 영향을 끼치지 않음

Lettuce을 언제 사용하는지

락 보유 시간이 짧다 (수백 ms ~ 수 초)
“대기”가 아니라 선출이 목적
실패해도 치명적이지 않다 (503/캐시미스 허용, 재시도 가능)
구현을 투명하게 유지하고 싶다 (키/TTL/해제 조건 직접 제어)

언제 Redisson을 사용하는지

락을 잡고 하는 작업이 수십 초~분 단위인 경우
락이 중간에 풀리면 치명적인 중복 실행이 되는 경우 ( 금전/정산/재고 오류 )
동일 자원(좌석, 쿠폰, 포인트) 업데이트를 순서대로 처리가 필요한 경우
임계구역 작업이 꼭 성공해야 해서 대기 후 획득이 필요한 경우

예시 코드

@Component
@RequiredArgsConstructor
public class RedisHubEdgeCache {

    private final StringRedisTemplate redisTemplate;
    private final ObjectMapper om;

    public Optional<CacheHit<HubInfo>> get(String key){
        try {
            String value = redisTemplate.opsForValue().get(key);
            if(value == null) { return Optional.empty(); }

            long sec = redisTemplate.getExpire(key);
            Duration ttl = sec < 0 ? Duration.ZERO : Duration.ofSeconds(sec);

            return Optional.of(new CacheHit<>(om.readValue(value, HubInfo.class), ttl));

        } catch (Exception e) {
            // 역직렬화/redis 오류면 캐시 제거 후 miss 처리
            redisTemplate.delete(key);

            return Optional.empty();
        }
    }

    public void add(String key, HubInfo hubInfo, Duration ttl){
        try {
            redisTemplate.opsForValue().set(key, om.writeValueAsString(hubInfo), ttl);
        } catch (Exception ignored) {
            // 캐시 저장 실패는 복구 불가능 오류가 아니므로 실패를 시키지 않음
        }
    }

    // DB 조회/갱신은 1명만 가능하도록 Lock
    public boolean tryLock(String key, Duration ttl){
        Boolean result = redisTemplate.opsForValue().setIfAbsent(key, "1", ttl);
        return Boolean.TRUE.equals(result);
    }

    public void unlock(String key){
        try { redisTemplate.delete(key); } catch (Exception ignored) {}
    }
}

결론

- 이번 문제는 “분산락으로 모든 요청을 직렬화”하는 문제가 아니라,
캐시 갱신자 1명을 선출해 외부 API 호출을 1회로 제한하는 single-flight 문제다.

- 따라서 무거운 락 추상화보다 SET NX PX + 토큰 기반 해제로 충분하며,
운영 중 갱신 시간이 길어질 수 있는 경우에만 Redisson(Watchdog)로 확장하는 전략이 합리적이다.

허브 간 최단 경로 탐색 캐시 스탬피드 (Cache Stampede) 발생+해결

kimfishes — Mon, 19 Jan 2026 15:25:58 +0900

이전 문제 상황

출발지와 목적지 사이 허브 간 경로를 다익스트라 알고리즘으로 선정 후, Kakao Api를 호출해 허브 간 소요 시간 산출
이때 Kakao Api 응답을 기다리는 방식의 경우 16 ~ 20 초의 많은 시간이 걸림

첫 번째 해결

- Redis를 도입하여 TTL 5분이 지나지 않은 값은 Redis에 값을 꺼내 사용 (Redis TTL 5분, DB TTL 10분)

- Redis TTL 5분이 지난 경우 DB 조회 후 Redis에 값 갱신 (이때 우선 Redis에 갱신 후 Kakao Api를 호출하여 최신 값으로 갱신)

- Redis와 DB 모두 값이 없는 Cold Start의 경우 Kakao Api 호출 후 값 갱신

RedisHubEdgeCache

@Component
@RequiredArgsConstructor
public class RedisHubEdgeCache {

    private final StringRedisTemplate redisTemplate;
    private final ObjectMapper om;

    public Optional<HubInfo> get(String key){
        String value = redisTemplate.opsForValue().get(key);
        if(value == null){
            return Optional.empty();
        }
        try {
            return Optional.of(om.readValue(value, HubInfo.class));
        } catch (Exception e) {
            redisTemplate.delete(key);
            return Optional.empty();
        }
    }

    public void add(String key, HubInfo hubInfo, Duration ttl){
        try {
            redisTemplate.opsForValue().set(key, om.writeValueAsString(hubInfo), ttl);
        } catch (Exception ignored) {
            // 캐시 저장 실패는 복구 불가능 오류가 아니므로 실패를 시키지 않음
        }
    }

}

@Service
@Slf4j
@RequiredArgsConstructor
public class HubEdgeWeightService implements HubEdgeWeightProvider {

    private final Duration redisTtl = Duration.ofMinutes(5);

    private final HubInfoRepository hubInfoRepository;
    private final HubRepository hubRepository;
    private final KakaoMapClient kakaoMapClient;
    private final RedisHubEdgeCache redisHubEdgeCache;
    private final CacheStats cacheStats;

    @Override
    @Transactional
    public EdgeWeight getWeight(UUID startHubId, UUID endHubId) {

        // 1) redis 조회 (5분인 상태)
        String keys = HubEdgeCacheKeys.edgeKeys(String.valueOf(startHubId), String.valueOf(endHubId));
        Optional<HubInfo> optionalHubInfo = redisHubEdgeCache.get(keys);
        if (optionalHubInfo.isPresent()) {
            cacheStats.hit();
            log.info("redis Cache hit");
            HubInfo hubInfo = optionalHubInfo.get();
            return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
        }
        cacheStats.miss();

        // 2) DB TTL인 10분 이내의 캐시값이 있으면 기존 값 그대로 사용
        HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
            .orElseThrow(()-> new BusinessException(ErrorCode.HUB_INFO_NOT_FOUND));
        LocalDateTime now = LocalDateTime.now();

        if (hubInfo.getDeliveryDuration() != null && hubInfo.getDistance() != null && !hubInfo.checkUpdateTime(now)) {

            redisHubEdgeCache.add(keys, hubInfo, redisTtl);
            log.info("[HubEdgeWeight] cache hit: {} -> {} ({}h {}m, {} km)",
                startHubId, endHubId, hubInfo.getDeliveryDuration()/3600, hubInfo.getDeliveryDuration() % 3600 / 60, hubInfo.getDistance());

            return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
        }

        // 3) DB에도 없다면 Kakao API로 실제 거리/시간 계산
        // 허브 존재 여부 확인
        Hub startHub = hubRepository.findById(hubInfo.getStartHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));
        Hub endHub = hubRepository.findById(hubInfo.getEndHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

        // 해당 허브들에 위도, 경도값 추출
        String origin = startHub.getLongitude() + "," + startHub.getLatitude();
        String destination = endHub.getLongitude() + "," + endHub.getLatitude();

        DirectionInfoResponseV1 direction = kakaoMapClient.getDirection(
            origin,
            destination,
            2,          // carType
            "DIESEL",   // carFuel
            true        // carHipass
        );

        // Kakao 응답은 초 단위
        int durationSec = (int) direction.duration();
        BigDecimal distanceKm = BigDecimal
            .valueOf(direction.distance() / 1000.0)
            .setScale(3, RoundingMode.HALF_UP);

        hubInfo.updateDeliveryInfo(durationSec, distanceKm);
        // redis의 값은 after commit
        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
            @Override
            public void afterCommit() {
                redisHubEdgeCache.add(keys, hubInfo, redisTtl);
            }
        });

        log.info("[HubEdgeWeight] cache hit: {} -> {} ({}h {}m, {} km)",
            startHubId, endHubId, hubInfo.getDeliveryDuration() / 3600, hubInfo.getDeliveryDuration() % 3600 / 60, hubInfo.getDistance());

        return new EdgeWeight(startHubId, endHubId, durationSec, distanceKm);
    }
}

- 부하 테스트 걸기 전 캐시 miss와 hit 갯수를 알아보기 위해 CacheStats 작성

@Component
public class CacheStats {
    private final LongAdder hit = new LongAdder();
    private final LongAdder miss = new LongAdder();

    public void hit() { hit.increment(); }
    public void miss() { miss.increment(); }

    public long hits() { return hit.sum(); }
    public long misses() { return miss.sum(); }
}

CacheStatsEndPointConfig

- 캐시가 제대로 효율을 내고 있는지 운영 중에 확인하기 위해 사용

implementation 'org.springframework.boot:spring-boot-starter-actuator'

- 엔드포인트 설정

management:
  endpoints:
    web:
      exposure:
        include: cache-stats

@Component
@Endpoint(id = "cache-stats")
@RequiredArgsConstructor
public class CacheStatsEndPointConfig {

    private final CacheStats cacheStats;

    @ReadOperation
    public Map<String, Object> stats() {
        long hit = cacheStats.hits();
        long miss = cacheStats.misses();
        long total = hit+miss;

        double hitRate = (total == 0) ? 0.0 : (hit * 100.0 / total);

        return Map.of("hits", hit, "misses", miss, "total", total, "hitRate", hitRate);
    }
}

Jemeter 부하 테스트

- 동시 사용자 200명 × 사용자당 100회 요청 (총 20,000 requests)의 예시

- 결과 : p95: 850ms, p99: 13.4s, 평균 448ms

- 기존 16초 걸리던 상황보다 16,000ms → 488ms 약 32배 개선

그러나 Redis TTL 5분 만료 시점에 miss가 동시 다발적으로 발생하여 지연 시간이 스파이크 모양으로 튀는 모습

http://localhost:19093/actuator/cache-stats에 접속 시 miss와 hit 개수 & 퍼센트를 알 수 있다.

이 코드의 문제

Redis TTL 끝나는 타이밍에 트래픽이 몰리면, 들어온 모든 요청이 DB에 한번에 몰려
캐시 스탬피드(cache stampede) 발생

[ 캐시 스탬피드 (Cache Stampede) ]

여러 요청이 동시에 캐시 미스가 나면서, 원본 데이터(DB·외부 API)에 한꺼번에 몰려가는 현상
200명이 동시 요청으로 몰릴 시 Redis에 값이 있지만 TTL이 만료 된 경우 lock으로 한 명의 사용자만 DB에서 값을 가져오거나 DB 값도 TTL이 만료 되었다면 외부 Api(Kakao Api)를 호출해야 함
-> 나머지 199명에게는 만료된 값을 주거나 일정 시간 & 일정 횟수만큼 재시도 처리 후 실패 처리 등 처리 필요

목표

- 라즈베리파이나 프리티어 AWS로 서버를 돌릴 경우 낮은 서버 사양과 Kakao Api를 보내는 하루 & 월 사용 제한이 있으므로 스케줄링을 사용하여 항상 최신의 응답을 캐시에 넣을 시 많은 비용이 발생

- 비용 절감을 위해 스케줄링 사용 없이 사용자의 요청이 있을 때만 외부 Api를 전송하여 최신의 값을 제공해야 함

저장소의 TTL 분리

Redis TTL (10분)
DB TTL (15분)

응답 원칙

Redis가 있으면 무조건 Redis 먼저 사용
Redis hit이면 항상 즉시 응답
- 단, Redis TTL이 5분 이하로 남아있으면
  → 응답은 그대로 주되, refreshLock(single-flight) 성공한 1명만 외부 API로 백그라운드 갱신(refresh-ahead)
Redis miss이면 DB 확인
DB도 없거나 DB TTL 초과(15분 초과)면 외부 API 필요 (single-flight)
Redis 장애면 DB fallback + DB bulkhead(동시성 제한)로 “느리게라도” 응답, DB 보호

시나리오별 동작

1. Redis와 DB 모두 값이 없는 초기 상황 (Cord start)

Redis miss
DB miss
refreshLock(single-flight) : 200명 중 1명만 외부 API 호출
나머지 199명:
- jitter 재조회 2~3회로 Redis에 값이 생겼는지 확인
- 3회에도 Redis에 값이 없으면 → DB 조회 -> 그래도 없다면 503 에러 발생
외부 API 성공 시:
- DB upsert
- Redis set (TTL 10분)

핵심: Cold Start는 이전에 만료된 값이 없으니 Redis -> DB 순차적으로 조회
그래도 없다면 503 에러

2. Redis hit + TTL > 5분 (Redis Fresh)

Redis hit으로 즉시 응답 후 종료

3. Redis가 사망 후 복구되어 값이 없거나 값이 있어도 TTL이 만료된 상황이지만, DB에선 값도 있으며 TTL도 유효한 상황

(Redis가 죽었다가 복구했거나, Redis가 만료돼서 비어있는 상황)

Redis miss
DB hit + DB TTL 유효
warmupLock(single-flight) : 1명만 DB 조회
- DB 값을 Redis에 즉시 warm-up (TTL 10분) 하고 응답
- 동시에 refreshLock을 잡은 1명이 백그라운드 외부 API 갱신
나머지 199명:
- jitter 재조회 2~3회로 Redis가 채워졌는지 확인
- 채워지면 Redis로 응답
- 3회 재조회 실패 시 DB 값을 fallback으로 응답

핵심: Redis miss 시 DB로 한 명만 내려가서 Redis를 채우고, 나머지는 Redis에서 응답을 받음
( 나머지 199명 -> jitter 재조회 2~3회로 Redis 값 받아서 반환 )

4. Redis TTL 만료이고, DB에 값이 있지만 TTL이 초과인 상황

Redis miss
DB 값은 있으나 TTL 초과 → 신선하지 않음
refreshLock(single-flight) : 1명만 외부 API 호출
나머지 199명:
- jitter 재조회 2~3회로 Redis 값 생성 기다림
- 199명에게 DB에 만료된 값이라도 준다면 지연 시간을 줄일 수 있지만 너무 과거의 값을 주게 된다면 신뢰성을 잃음
- 그러나 3회 재시도에도 Redis에 값이 없으면 : DB stale 값으로 응답(Degraded) - 일단 신선하지 않은 결과라도 전달
외부 API 성공 시:
- DB upsert
- Redis set (TTL 10분)

핵심: 외부 API가 필요하지만, 실패 시에도 서비스 연속성을 위해 DB stale을 최후 fallback으로 둔다.

5. Redis나 Kakao Map Api에 문제가 생기면?

Redis 장애면 DB fallback + DB bulkhead
속도를 느리게라도 DB에 값을 응답으로 보내줘야 함
현재 로직에선 주문 후 배송이 이뤄지는 비동기 로직으로 구현되어 있어 사용자에게 따로 알림을 전송하진 않음

구현

- Redis에 분산락을 사용하여 하나의 요청만 Kakao에 갱신되도록 해야 함

- Lock는 2개로 나뉨

- Redis에 값이 없을 시 DB로 내려가 Redis를 채움

- Cold Start 상황, Redis TTL이 5분 이하이거나 DB값의 TTL도 만료인 경우 외부 Api(Kakao Api) 호출하는 용

1명만 refresh lock → Kakao 갱신 시도
Kakao에게 응답을 성공적으로 받을 시 DB upsert + Redis set
나머지 유저들은 리더가 응답을 받아올 때까지 Redis 3회 재조회 ->그래도 없으면 503

Redis 클라이언트 중 Lettuce 사용

Redis 서버에 명령을 안전하고 효율적으로 전달
비동기 / 논블로킹 기반
Redis polling + jitter 구조에 안정적
분산락을 “자동으로” 제공하진 않음

Lettuce 선택 이유

Redis의 Lettuce 락은 Lock를 얻지 못한 스레드가 Lock 획득 시도를 반복하는 스핀락(spin lock) 문제가 있으므로 무조건 사용하면 안 된다라는 블로그들 글이 있다.
하지만 지금의 경우 Lock 획득하기 위해 싸우는게 목적이 아닌 "갱신자 한 명을 선출 후 나머지는 Lock를 대기하지 않음"
즉 Lock을 기다리지 않는 single-flight 캐시 갱신 정책을 사용하므로 최소 기능(SET NX PX + 토큰 기반 해제)만으로 투명하고 가볍게 구현 가능한 Lettuce 방식을 선택

@Component
@RequiredArgsConstructor
public class RedisHubEdgeCache {

    private final StringRedisTemplate redisTemplate;
    private final ObjectMapper om;

    public Optional<CacheHit<HubInfo>> get(String key){
        try {
            String value = redisTemplate.opsForValue().get(key);
            if(value == null) { return Optional.empty(); }

            long sec = redisTemplate.getExpire(key);
            Duration ttl = sec < 0 ? Duration.ZERO : Duration.ofSeconds(sec);

            return Optional.of(new CacheHit<>(om.readValue(value, HubInfo.class), ttl));

        } catch (Exception e) {
            // 역직렬화/redis 오류면 캐시 제거 후 miss 처리
            redisTemplate.delete(key);

            return Optional.empty();
        }
    }

    public void add(String key, HubInfo hubInfo, Duration ttl){
        try {
            redisTemplate.opsForValue().set(key, om.writeValueAsString(hubInfo), ttl);
        } catch (Exception ignored) {
            // 캐시 저장 실패는 복구 불가능 오류가 아니므로 실패를 시키지 않음
        }
    }

    // DB 조회/갱신은 1명만 가능하도록 Lock
    public boolean tryLock(String key, Duration ttl){
        Boolean result = redisTemplate.opsForValue().setIfAbsent(key, "1", ttl);
        return Boolean.TRUE.equals(result);
    }

    public void unlock(String key){
        try { redisTemplate.delete(key); } catch (Exception ignored) {}
    }
}

HubEdgeWeightService

@Service
@Slf4j
@RequiredArgsConstructor
public class HubEdgeWeightService implements HubEdgeWeightProvider {

     private static final Duration REDIS_TTL = Duration.ofMinutes(6);

    // single-flight lock TTL (너무 길게 잡지 말고 “짧게”)
    private static final Duration LOCK_TTL = Duration.ofSeconds(10);

    // DB bulkhead: Redis 장애 시 DB 동시 접근 제한
    private final Semaphore dbBulkhead = new Semaphore(10);

    // jitter 재조회(50 -> 100 -> 200ms)
    private static final long[] JITTER_MS = {50, 150, 250};

    // Redis가 죽으면 Redis lock을 못 쓰니, JVM 내부 single-flight로 Kakao 폭주 방지 (같은 키에 대해 1명만 진입시키는 락 사용)
    private final ConcurrentHashMap<String, ReentrantLock> localLocks = new ConcurrentHashMap<>();

    private final HubInfoRepository hubInfoRepository;
    private final HubRepository hubRepository;
    private final KakaoMapClient kakaoMapClient;
    private final RedisHubEdgeCache redisHubEdgeCache;
    private final CacheStats cacheStats;
    private final TransactionTemplate transactionTemplate;

    @Override
    @Transactional
    public EdgeWeight getWeight(UUID startHubId, UUID endHubId) {

        String redisKey = HubEdgeCacheKeys.edgeKeys(String.valueOf(startHubId), String.valueOf(endHubId));
        final String refreshLockKey = redisKey + ":refreshLock";
        final String warmupLockKey = redisKey + ":warmupLock";
        boolean redisDown = false;

        LocalDateTime now = LocalDateTime.now();

        /** 1) Redis hit (항상 즉시 응답) */
        try {
            Optional<CacheHit<HubInfo>> redisHit = redisHubEdgeCache.get(redisKey);
            if (redisHit.isPresent()) {

                HubInfo hubInfo = redisHit.get().value();
                Duration ttlTime = redisHit.get().ttlTime();

                cacheStats.hit();
                log.info("redis Cache hit");

                // Redis TTL이 5분 이하면 값은 반환해서 주지만 Kakao API를 호출하여 시간 갱신
                if (ttlTime.compareTo(Duration.ofMinutes(5)) <= 0) {

                    // 동시에 refresh-ahead 트리거(1명만)
                    triggerRefreshAheadAsync(refreshLockKey, startHubId, endHubId, redisKey);
                }

                return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
            }
            cacheStats.miss();
        } catch (DataAccessException e) {

            // Redis 장애: 아래에서 DB fallback + bulkhead
            redisDown = true;
            log.warn("Redis down -> fallback to DB with bulkhead key={}", redisKey, e);
        }

        /** 2) Redis가 완전히 죽은 경우: DB로 "느리게라도 무조건" 반환 */
        if (redisDown) {
            return handleRedisDownMustReturnDb(startHubId, endHubId, redisKey, now);
        }

        /** 3) Redis miss (정상 Redis 동작) */
        return handleRedisMissNormal(startHubId, endHubId, warmupLockKey, refreshLockKey, redisKey, now);
    }

    /**
     * Redis가 완전히 죽었을 때 정책: - DB bulkhead는 "대기"해서라도 들어가는 방향으로 - DB에 시간/거리 값이 있으면 TTL 상관없이 무조건 반환
     * (단 리더는 무조건 최신값을 받게 구현 (DB TTL 만료 시 사용자가 한명만 접근하더라도 최신의 값을 주어야 되기 때문))

     * 예시 1 : Redis에 값이 없는 상황에서 DB에 값이 없는 상황 (cold start)
     * -> 로컬 single-flight로 1명만 Kakao Api 호출 -> bulkhead로 10명씩만 처리하기 때문에 많은 지연이 발생할 수 있음

     * 예시 2 : Redis가 없는 상황에서 DB에 값은 있지만 TTL이 만료된 상황 -> DB에서 값을 읽고 TTL이 만료된 값이라도 일단 반환 (bulkhead 적용) ->
     * 만료된 값을 받고 있다가 1명이 백그라운드 갱신 성공 시 최신의 값을 받게 됨 (여전히 bulkhead 적용)

     * - DB에 값이 없으면 cold-start처럼 외부 API 필요 (JVM single-flight로 Kakao api 폭주 방지)
     */
    private EdgeWeight handleRedisDownMustReturnDb(UUID startHubId, UUID endHubId, String redisKey, LocalDateTime now) {

        // 느리게라도 대기해서 bulkhead 진입
        dbBulkhead.acquireUninterruptibly();

        try {
            HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

            boolean hasValue = hubInfo.hasDeliveryInfo();

            // Redis 사망 + DB에 값도 없는 ColdStart 상황
            if (!hasValue) {
                return coldStartWithLocalSingleFlightSync(startHubId, endHubId, redisKey);
            }

            // DB에 값은 있지만 TTL이 만료 된 상황으로 우선 만료된 값을 주며 1명만 백그라운드 갱신
            if (hubInfo.checkUpdateTime(now)) {
                triggerRefreshWhenRedisDownAsync(startHubId, endHubId, redisKey);
            }

            return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
        } finally {
            dbBulkhead.release();
        }
    }

    /**
     * Redis down + DB TTL 만료(stale)여도 일단 반환하고, 1명만 백그라운드로 최신 갱신 시도
     * (중요: Thread에서 JPA 쓰려면 트랜잭션 필요 -> TransactionTemplate 사용)
     */
    private void triggerRefreshWhenRedisDownAsync(UUID startHubId, UUID endHubId, String redisKey) {

        ReentrantLock lock = localLocks.computeIfAbsent(redisKey, k -> new ReentrantLock());

        // reader가 아니라면 그냥 return
        if (!lock.tryLock()) {
            return;
        }

        new Thread(() -> {
            try {
                transactionTemplate.execute(status -> {
                HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                    .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

                // Redis는 죽었으니 DB만 갱신
                DirectionInfoResponseV1 directionInfoResponse = getKakaoMap(hubInfo);
                dbSet(directionInfoResponse.duration(), directionInfoResponse.distance(), hubInfo);

                // TransactionTemplate.execute()는 반드시 return 값이 필요하지만 지금은 필요가 없으므로 null 반환
                return null;
                });
            } catch (Exception e) {
                log.error("[RedisDownRefresh] failed {} -> {}", startHubId, endHubId, e);
            }finally {
                lock.unlock();
            }
        }).start();
    }

    /** Redis down + DB에도 값이 없는 cold-start
     * 리더 한명만 kakao Api를 호출하며 나머지는 DB 값이 채워질 때까지 짧게 재조회 시도
    */
    private EdgeWeight coldStartWithLocalSingleFlightSync(UUID startHubId, UUID endHubId, String redisKey) {

        ReentrantLock lock = localLocks.computeIfAbsent(redisKey, k -> new ReentrantLock());

        boolean tryLock = lock.tryLock();
        if (tryLock) {
            try {
                HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                    .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

                // 혹시 그 사이에 다른 트랜잭션에서 값이 채워졌으면 그대로 반환
                if (hubInfo.hasDeliveryInfo()){
                    return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
                }

                // DB만 갱신
                DirectionInfoResponseV1 directionInfoResponse = getKakaoMap(hubInfo);
                dbSet(directionInfoResponse.duration(), directionInfoResponse.distance(), hubInfo);

                return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
            }finally {
                lock.unlock();
            }
        }

        for(long ms : JITTER_MS){
            sleep(ms);
            HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

            // 값이 DB에 갱신이 되었으면 반환
            if (hubInfo.hasDeliveryInfo()){
                return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
            }
        }
        throw new BusinessException(ErrorCode.TEMPORARILY_UNAVAILABLE);
    }

    /**
     * Redis 서버는 정상인데 TTL 만료인 경우: warmupLeader 1명만 DB 내려가서 Redis 채움 -> 나머지는 jitter로 Redis 재조회
     * DB에 값도 TTL 만료 상태라면 refreshLock으로 1명만 Kakao 호출 (리더는 최신값으로 응답하도록 구성)
     * 예시 (Redis 만료 + DB도 TTL 만료 상황에서 200명 접근 시 리더 1명만 최신 값을 받고 나머지 199명은 redis에 재처리 3회를 하면서 리더가 갱신한 값을 받게 됨)
     * 3회 처리에도 받지 못한다면 에러를 띄움
     */
    private EdgeWeight handleRedisMissNormal(UUID startHubId, UUID endHubId, String warmupLockKey,
        String refreshLockKey, String redisKey, LocalDateTime now) {

        // DB에 값이 있다면 한명만 갱신 수행
        boolean warmupLeader = redisHubEdgeCache.tryLock(warmupLockKey, LOCK_TTL);

        if (warmupLeader) {
            try {
                HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                    .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

                //DB에도 값이 없으면 cold-start (1명만 Kakao 동기 호출해서 생성 후 응답)
                if (! hubInfo.hasDeliveryInfo()) {
                    return coldStartFetchWithRedisLock(startHubId, endHubId, refreshLockKey, redisKey, hubInfo);
                }
                // DB의 값이 존재하고 TTL도 살아 있으면 Redis에 warm-up 후 즉시 응답
                if (!hubInfo.checkUpdateTime(now)) { // false = fresh
                    redisHubEdgeCache.add(redisKey, hubInfo, REDIS_TTL);
                    return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
                }

                // Redis 서버는 살아 있고 DB에 값도 있지만 DB 값의 TTL이 만료 된 상황이라면 예전 값이라도 주는 동시에 1명은 값 갱신
                boolean leader = redisHubEdgeCache.tryLock(refreshLockKey, LOCK_TTL);
                if (leader) {
                    try {
                        // 리더는 항상 최신값을 받아서 응답
                        DirectionInfoResponseV1 directionInfoResponse = getKakaoMap(hubInfo);
                        RedisAndDbSet(directionInfoResponse.duration(), directionInfoResponse.distance(), hubInfo, redisKey);
                        return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
                    } finally {
                        redisHubEdgeCache.unlock(refreshLockKey);
                    }
                }
                // warmupLeader가 되지 못한 나머지 요청들은 우선 db에 값을 응답받고 jitter로 Redis에 값 생성을 기다리게 된다
            } finally {
                redisHubEdgeCache.unlock(warmupLockKey);
            }
        }

        return jitterWaitRedis(startHubId, endHubId, redisKey)
            .orElseThrow(() -> new BusinessException(ErrorCode.TEMPORARILY_UNAVAILABLE));
    }

    private EdgeWeight coldStartFetchWithRedisLock(UUID startHubId, UUID endHubId, String refreshLockKey, String redisKey, HubInfo hubInfo) {
        boolean leader = redisHubEdgeCache.tryLock(refreshLockKey, LOCK_TTL);

        if (leader) {
            try {
                DirectionInfoResponseV1 directionInfoResponse = getKakaoMap(hubInfo);
                RedisAndDbSet(directionInfoResponse.duration(), directionInfoResponse.distance(), hubInfo, redisKey);

                // 리더는 최신값으로 즉시 응답
                return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
            } finally {
                redisHubEdgeCache.unlock(refreshLockKey);
            }
        }

        return jitterWaitRedis(startHubId, endHubId, redisKey)
            .orElseThrow(() -> new BusinessException(ErrorCode.TEMPORARILY_UNAVAILABLE));
    }

    /**
     * Redis hit TTL 임박 시 한명만 값 갱신
     */
    private void triggerRefreshAheadAsync(String refreshLockKey, UUID startHubId, UUID endHubId, String redisKey) {
        boolean leader = redisHubEdgeCache.tryLock(refreshLockKey, LOCK_TTL);

        // 리더로 선정되지 못하면 반환
        if (!leader)
            return;

        // 선정된 리더만 비동기로 외부 API(Kakao Map)를 호출해 Redis + DB 갱신
        new Thread(() -> {
            try {
                transactionTemplate.execute(status -> {
                HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
                    .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

                // Kakao api 호출
                DirectionInfoResponseV1 directionInfoResponse = getKakaoMap(hubInfo);
                // 결과를 Redis와 DB에 갱신
                RedisAndDbSet(directionInfoResponse.duration(), directionInfoResponse.distance(), hubInfo, redisKey);
                return null;
                });
            } catch (Exception e) {
                log.error("[RefreshAhead] failed {} -> {}", startHubId, endHubId, e);
            } finally {
                redisHubEdgeCache.unlock(refreshLockKey); // 실패해도 락은 반드시 해제
            }
        }).start();
    }

    private DirectionInfoResponseV1 getKakaoMap(HubInfo hubInfo) {

        // 허브 존재 여부 확인
        Hub startHub = hubRepository.findById(hubInfo.getStartHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));
        Hub endHub = hubRepository.findById(hubInfo.getEndHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

        // 해당 허브들에 위도, 경도값 추출
        String origin = startHub.getLongitude() + "," + startHub.getLatitude();
        String destination = endHub.getLongitude() + "," + endHub.getLatitude();

        // Kakao Api 호출
        return kakaoMapClient.getDirection(
            origin,
            destination,
            2,          // carType
            "DIESEL",          // carFuel
            true               // carHipass
        );
    }

    private void RedisAndDbSet(long duration, long distance, HubInfo hubInfo, String redisKey) {
        // Kakao 응답은 초 단위
        int durationSec = (int) duration;

        BigDecimal distanceKm = BigDecimal
            .valueOf(distance / 1000.0)
            .setScale(3, RoundingMode.HALF_UP);

        hubInfo.updateDeliveryInfo(durationSec, distanceKm);

        // redis의 값은 after commit
        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
            @Override
            public void afterCommit() {
                redisHubEdgeCache.add(redisKey, hubInfo, REDIS_TTL);
            }
        });
    }

    private void dbSet(long duration, long distance, HubInfo hubInfo) {
        // Kakao 응답은 초 단위
        int durationSec = (int) duration;

        BigDecimal distanceKm = BigDecimal
            .valueOf(distance / 1000.0)
            .setScale(3, RoundingMode.HALF_UP);

        hubInfo.updateDeliveryInfo(durationSec, distanceKm);
    }

    /** reader로 선출되지 못하고 Redis에 값 갱신을 기다리는 애들을 위한 jitter 재조회 */
    private Optional<EdgeWeight> jitterWaitRedis(UUID startHubId, UUID endHubId, String redisKey){
        for (long ms : JITTER_MS) {
            sleep(ms);

            try {
                Optional<CacheHit<HubInfo>> hubInfoCacheHit = redisHubEdgeCache.get(redisKey);
                if (hubInfoCacheHit.isPresent()) {
                    HubInfo hubInfo = hubInfoCacheHit.get().value();
                    return Optional.of(new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance()));
                }
            } catch (DataAccessException e) {
                return Optional.empty();
            }
        }
            return Optional.empty();
    }

    /** 이 스레드를 잠깐 재우지만 다른 스레드가 interrupt(중단 신호)로 깨우면 신호를 받고 중지
     (대기중 상황에서 타임아웃 발생 & 클라이언트가 연결을 끊음 & 서버 종료 등) */
    private void sleep(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException ignored) {
            Thread.currentThread().interrupt();
        }
    }
}

중요 내용

- Redis에 값이 있을 경우 사용자에게 반환하고 Redis hit TTL 임박 시 한 명만 값 갱신

- Redis가 완전히 죽은 경우 세마포어에서 설정한 만큼씩만 DB에 접근하여 "느리게라도 무조건" 반환

- Redis 서버는 정상인데 TTL 만료인 경우: warmupLeader 1명만 DB 내려가서 Redis 채움 -> 나머지는 jitter로 Redis 재조회

        /** 1) Redis hit (항상 즉시 응답) */
        try {
            Optional<CacheHit<HubInfo>> redisHit = redisHubEdgeCache.get(redisKey);
            if (redisHit.isPresent()) {

                HubInfo hubInfo = redisHit.get().value();
                Duration ttlTime = redisHit.get().ttlTime();

                cacheStats.hit();
                log.info("redis Cache hit");

                // Redis TTL이 5분 이하면 값은 반환해서 주지만 Kakao API를 호출하여 시간 갱신
                if (ttlTime.compareTo(Duration.ofMinutes(5)) <= 0) {

                    // 동시에 refresh-ahead 트리거(1명만)
                    triggerRefreshAheadAsync(refreshLockKey, startHubId, endHubId, redisKey);
                }

                return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
            }
            cacheStats.miss();
        } catch (DataAccessException e) {

            // Redis 장애: 아래에서 DB fallback + bulkhead
            redisDown = true;
            log.warn("Redis down -> fallback to DB with bulkhead key={}", redisKey, e);
        }

        /** 2) Redis가 완전히 죽은 경우: DB로 "느리게라도 무조건" 반환 */
        if (redisDown) {
            return handleRedisDownMustReturnDb(startHubId, endHubId, redisKey, now);
        }

        /** 3) Redis miss (정상 Redis 동작) */
        return handleRedisMissNormal(startHubId, endHubId, warmupLockKey, refreshLockKey, redisKey, now);

Refactoring 후 Jemeter 부하 테스트

- 동시 사용자 200명 × 사용자당 100회 요청 (총 20,000 requests)의 예시

- 결과 : p95: 1.13s, p99: 2.57s, 평균 336ms

- 기존 16초 걸리던 상황보다 16,000ms → 366ms 약 48배 개선

- 리팩토링 전 488ms -> 366ms 약 1.45배 개선

- 캐시 miss가 특정 시점에 집중되어 p99 기준 10초 이상 튀던 지연 구간이 사라지고, 응답 시간이 전반적으로 고르게 분포

- Cache Hit Rate 100% 유지, TTL 만료 구간에서도 성능 저하 없음

라즈베리파이에 Loki + Grafana로 로그 수집 시스템 구축하기

kimfishes — Mon, 22 Dec 2025 16:16:18 +0900

문제

기존에는 EC2 환경에서 ELK 스택을 사용해 로그를 수집하고 있었다.
하지만 개인 프로젝트와 홈 서버 성격의 서비스까지 포함되면서 다음 문제가 발생했다.

ELK는 메모리 사용량이 너무 큼
라즈베리파이의 RAM 용량은 4~8GB이지만 ELK를 가볍게 띄워도 3~4GB가 소요됨
라즈베리파이의 디스크 IO 성능 제한

지금 환경에서 ELK는 기능은 충분하지만, 너무 무거우므로 “가벼운 로그 수집 시스템”이 필요하다.

서비스별 로그 흐름 파악
장애 발생 시 빠른 원인 추적
저사양 환경에서도 안정적으로 동작
운영 부담이 적을 것

Loki + Grafana + Promtail 조합

기존 로그 시스템과 달리 로그 본문을 인덱싱 하지 않고 로그에 붙은 라벨(Label)만 인덱싱하는 구조

메모리 사용량이 낮고
디스크 IO 부담이 적으며
라즈베리파이 같은 저사양 환경에 적합하다

각 구성요소 역할

Loki: Grafana Labs에서 만든 로그 수집·저장 시스템

Grafana: 시각화 & 검색 UI ( “관측성(Observability)을 시각화하는 플랫폼”으로 Grafana 자체는 데이터를 저장하지 않는다.)

Promtail : 로그 수집 Agent (로그 파일을 읽어, 라벨을 붙인 뒤 Loki로 전달)

기존 로그 시스템(ELK)의 방식

Full Text Index 방식으로 로그 내용 전체를 인덱싱 ( 모든 필드, 모든 텍스트를 검색 가능 )

[ERROR] OrderService - orderId=1234 timeout occurred

문제점

인덱스 용량 큼
메모리 사용량 큼
디스크 IO 부담

Loki의 접근 방식: 라벨(Label) 기반

❝ 로그의 내용을 인덱싱 하지 않으며, 대신 로그의 메타데이터(label)만 인덱싱 한다 ❞

라벨(Label)이란?

- 라벨은 로그 한 줄 한 줄에 붙는 검색용 메타데이터

이러한 예시 로그가 있다면

2025-12-19 11:36:29 ERROR OrderService orderId=1234 timeout

Loki에 넣을 때 이런 방식으로 로그를 넣게 된다.

즉 Loki는 오직 이 label만 인덱싱하여 로그 본문(message)은 인덱싱 되지 않는다.

labels:
  job: chill-logistics
  service: order-server
  level: ERROR
  instance: raspberrypi-01

라벨 기반의 장점

로그 본문은 사용하지 않으며 메타데이터(label)만 인덱싱 사용
인덱싱 비용 거의 없음
로그 쓰기 속도 빠름

“ ELK : 일단 다 넣고 나중에 검색하자”

“ Loki : 어떤 기준으로 검색할지를 미리 정하자”

항목	ELK	Loki
메모리 사용	높음	낮음
인덱싱 방식	Full Index	Label 기반

Code

1. Loki + Grafana의 Docker Compose 파일로 저장 후 실행 시켜준다.

예시 : docker compose -f docker-compose-logging.yml up -d

services:
  loki:
    image: grafana/loki:2.9.8
    container_name: loki
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    restart: always
    volumes:
      - loki_data:/loki

  grafana:
    image: grafana/grafana:10.4.5
    container_name: grafana
    ports:
      - "3000:3000"
    restart: always
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      # 필요하면 아래도 추가
      # - GF_SERVER_ROOT_URL=http://<GRAFANA_HOST>:3000
    depends_on:
      - loki
    volumes:
      - grafana_data:/var/lib/grafana

volumes:
  loki_data:
  grafana_data:

2. 로그 저장 형태인 logback.xml 파일은 기존 ELK 형태의 방식과 같다

spring에서 resources 폴더 -> logback.xml 파일로 넣어주면 됩니다

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <!-- 로그 경로 -->
  <property name="LOG_PATH" value="/app/logs"/>
  <property name="INFO_PATH" value="${LOG_PATH}/info" />
  <property name="WARN_PATH" value="${LOG_PATH}/warn" />
  <property name="ERROR_PATH" value="${LOG_PATH}/error" />

  <!-- =============== 콘솔 =============== -->
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- =============== INFO 전용 JSON 로그 파일 =============== -->
  <appender name="INFO_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${INFO_PATH}/application-info.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>${INFO_PATH}/application-info-%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>7</maxHistory> <!--  7일간 보관 -->
    </rollingPolicy>
    <filter class="ch.qos.logback.classic.filter.LevelFilter">
      <level>INFO</level>
      <onMatch>ACCEPT</onMatch>
      <onMismatch>DENY</onMismatch>
    </filter>
    <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
      <providers>
        <timestamp/>
        <logLevel/>
        <threadName/>
        <loggerName/>
        <message/>
        <arguments/>
        <stackTrace/>
          <mdc>
            <includeMdcKeyName>traceId</includeMdcKeyName>
          </mdc>
      </providers>
    </encoder>
  </appender>

  <!-- =============== WARN 전용 JSON 로그 =============== -->
  <appender name="WARN_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${WARN_PATH}/application-warn.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>${WARN_PATH}/application-warn-%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>7</maxHistory>
    </rollingPolicy>

    <!-- WARN만 -->
    <filter class="ch.qos.logback.classic.filter.LevelFilter">
      <level>WARN</level>
      <onMatch>ACCEPT</onMatch>
      <onMismatch>DENY</onMismatch>
    </filter>

    <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
      <providers>
        <timestamp/>
        <logLevel/>
        <threadName/>
        <loggerName/>
        <message/>
        <arguments/>
        <stackTrace/>
        <mdc>
          <includeMdcKeyName>traceId</includeMdcKeyName>
        </mdc>
      </providers>
    </encoder>
  </appender>


  <!-- =============== ERROR 전용 JSON 로그 파일 =============== -->
  <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${ERROR_PATH}/application-error.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>${ERROR_PATH}/application-error-%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>7</maxHistory> <!-- 7일간 보관  -->
    </rollingPolicy>
    <filter class="ch.qos.logback.classic.filter.LevelFilter">
      <level>ERROR</level>
      <onMatch>ACCEPT</onMatch>
      <onMismatch>DENY</onMismatch>
    </filter>
    <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
      <providers>
        <timestamp/>
        <logLevel/>
        <threadName/>
        <loggerName/>
        <message/>
        <arguments/>
        <stackTrace/>
        <mdc>
          <includeMdcKeyName>traceId</includeMdcKeyName>
        </mdc>
      </providers>
    </encoder>
  </appender>

  <!-- =============== 루트 로거 =============== -->
  <!--  root logger의 레벨을 설정으로 INFO 이상 레벨(INFO, WARN, ERROR) 만 출력한다 -->
  <root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="INFO_FILE"/>
    <appender-ref ref="WARN_FILE"/>
    <appender-ref ref="ERROR_FILE"/>
  </root>

</configuration>

3. Loki + Grafana가 있는 서버로 보내기 위해 Promtail 사용

주의 : 해당 경로에 config.yml 파일이 존재해야 합니다.

/c/app/promtail/config.yml

- config.yml 파일 (/*.log 부분 때문에 주석으로 인식 중이므로 무시해도 됩니다.)

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  # 로깅 서버(Loki) 주소
  - url: http://221.xxx.xxx.xxx:3100/loki/api/v1/push

scrape_configs:
  - job_name: chill-logistics-info
    static_configs:
      - targets: [localhost]
        labels:
          job: chill-logistics
          service: business  # 어떤 서비스인지 예로 user-server, firm-server처럼 구체적으로 사용이 좋지만 로컬 개발용으로 한번에 하므로
          level: INFO
          __path__: /app/logs/info/*.log
    pipeline_stages:
      - json:
          expressions:
            timestamp: timestamp
            logLevel: logLevel
            threadName: threadName
            loggerName: loggerName
            message: message
            traceId: traceId
      - timestamp:
          source: timestamp
          format: RFC3339Nano

  - job_name: chill-logistics-warn
    static_configs:
      - targets: [localhost]
        labels:
          job: chill-logistics
          service: business
          level: WARN
          __path__: /app/logs/warn/*.log
    pipeline_stages:
      - json:
          expressions:
            timestamp: timestamp
            logLevel: logLevel
            threadName: threadName
            loggerName: loggerName
            message: message
            traceId: traceId
      - timestamp:
          source: timestamp
          format: RFC3339Nano

  - job_name: chill-logistics-error
    static_configs:
      - targets: [localhost]
        labels:
          job: chill-logistics
          service: business
          level: ERROR
          __path__: /app/logs/error/*.log
    pipeline_stages:
      - json:
          expressions:
            timestamp: timestamp
            logLevel: logLevel
            threadName: threadName
            loggerName: loggerName
            message: message
            traceId: traceId
      - timestamp:
          source: timestamp
          format: RFC3339Nano

- config.yml 파일을 경로에 넣고, Promtail Docker Compose 파일 생성 (스프링 서버가 돌아가는 서버에서 실행 시켜준다.)

예시 : docker compose -f docker-compose-promtail.yml up -d

services:
  promtail:
    image: grafana/promtail:2.9.8
    container_name: promtail
    restart: always
    command: -config.file=/etc/promtail/config.yml
    volumes:
      - /c/app/promtail/config.yml:/etc/promtail/config.yml:ro
      - /c/app/logs:/app/logs:ro
      - promtail_positions:/tmp
    ports:
      - "${PROMTAIL_PORT}:${PROMTAIL_PORT}"

volumes:
  promtail_positions:

- 모든 서버를 실행 후 로그가 발생한다면 Loki + Grafana가 실행 중인 서버에 3000번 포트로 들어가면 Grafana에 들어갈 수 있습니다.

- 예시 : http://221.xxx.xxx.xxx:3000 (만약 로그인 창이 뜬다면 초기 값은 ID : admin PW : admin 을 넣어주면 됩니다.)

결론

1. 라즈베리파이와 같은 저사양 환경에서 ELK 스택은 기능적으로는 충분하지만, 운영 비용과 리소스 측면에서 과한 선택이었다.

2. Loki + Grafana + Promtail 조합은 로그 본문을 인덱싱 하지 않고 라벨 기반으로 접근하는 구조 덕분에 제한된 자원 환경에서도 안정적인 로그 수집과 조회를 가능하게 했다.

Cloudflare을 활용한 SSL 적용

kimfishes — Thu, 18 Dec 2025 23:57:41 +0900

Spring Boot 프로젝트 서버 배포 시 HTTPS 적용은 더 이상 선택이 아닌 필수가 되었다.

AWS나 GCP 같은 클라우드 환경이 아닌, 라즈베리파이에 직접 백엔드 서버를 배포 후 간단한 방법으로 SSL 인증서를 적용하는 방법을 작성하려 한다.

AWS를 사용하지 않고 라즈베리파이에서 운영 중인 서버에 Cloudflare를 활용해 SSL을 적용한 과정을 정리해본다.

Cloudflare를 선택한 이유
   - DNS + SSL + Proxy
   - 비용
   - 사용자는 HTTPS(443)로만 접근
- 라즈베리파이 서버는 기존 7777 포트 유지
- Nginx 및 인증서 관리 불필요
- 설정 단순 + 유지보수 용이

전체 구조

[ 사용자 브라우저 ]
|
HTTPS (443)
|

[ Cloudflare ]
HTTP (7777)
|
[ Raspberry Pi ]
Backend Server
(Port: 7777)

사용자는 항상 443 (HTTPS) 로 접근
실제 라즈베리파이 서버는 7777 포트 유지
포트 변환은 Cloudflare Origin Rule에서 처리

현재는 간단하게 클라우드 플레어에서 7777로 포트를 변환 후 전송하지만 다른 방법으론 Ngnix 방식도 존재한다.

그러나 이번 프로젝트에서는 설정을 최대한 단순하게 유지하기 위해 Nginx를 사용하지 않고, Cloudflare의 Origin Rule 기능을 사용하였다.

Nginx 방식

라즈베리파이에 Nginx 설치 필요
SSL 설정 필요

443 (Nginx)
↓
7777 (Backend)

1. 가비아에서 도메인 구매하기

https://www.gabia.com/

웹을 넘어 클라우드로. 가비아

그룹웨어부터 멀티클라우드까지 하나의 클라우드 허브

www.gabia.com

- 회원가입 후 원하는 도메인을 찾아 구매

2. Cloudflare에 도메인 등록하기

https://www.cloudflare.com/ko-kr/

모든 곳에서 연결하고, 보호하고, 구축하기

복잡성과 비용을 줄이면서 직원, 애플리케이션, 네트워크를 어디에서든 더 빠르고 안전하게 만듭니다.

www.cloudflare.com

- 클라우드 플레어에 회원가입 후 도메인 온보딩을 추가해준다

- 가비아에서 구매한 도메인 입력

- 요금제 선택

- 레코드를 설정해준다

A 레코드란?
- 도메인을 IPv4 주소(서버 IP) 로 연결해주는 레코드

- 배포 한 서버의 공인 IP를 넣어주면 된다

CNAME (www)이란?

- 구매한 DNS 이름 앞에 www. 이 붙어도, 붙지 않아도 같은 서버로 접근 가능

- 레코드 설정 후 네임서버 2개의 값을 복사한다

3. 네임서버를 Cloudflare로 변경하기

1. 가비아로 돌아가 도메인 관리 -> 본인이 구매한 도메인 설정을 들어간다

2. 복사한 클라우드플레어에 네임서버를 넣어준다.

4. Cloudflare SSL 설정

- SSL/TLS 개요로 진입

- 구성으로 들어가 준다

- Cloudflare에서 SSL을 설정할 때 Cloudflare와 원본 서버(Raspberry Pi) 사이를 어떻게 암호화할 것인가 설정 가능

현재 설정은

원본 서버에는 암호화 없이 HTTP로 요청
원본 서버에 SSL 설정이 전혀 없어도 동작

실제 서비스하는 서버라면 Full로 설정하여 전체(엄격)을 사용해야 한다. ( Cloudflare Origin Certificate 설치 필요)

즉 지금은 간단하게 설정 한 상황으로 Cloudflare와 원본 서버 간 통신은 HTTP로 이루어진다.

5. Origin Rule로 포트 변경 처리

- 규칙 -> 개요

- 규칙 생성 -> Origin Rule 클릭

- 규칙 이름 입력 후 모든 수신 요청 클릭

- 배포한 서버의 PORT 번호 입력 후 배포 클릭

- HTTPS 통신 성공

다시 작성하지만 현재 설정 방식은 실제 운영을 목적으로 하는 설정이 아니므로 설정의 주의가 필요합니다 !

Cloudflare의 Flexible SSL(가변) 모드는 구성은 간단하지만,
종단 간 암호화(End-to-End Encryption)를 제공하지 않기 때문에 보안 측면에서 주의가 필요합니다.

이 구조의 문제점

Cloudflare ↔ 서버 구간이 평문(HTTP)
중간에서 패킷 스니핑 가능
내부 네트워크가 아니라면 MITM 공격 가능성 존재
“자물쇠”는 있지만 종단 간 암호화 아님

즉 보안적으로는 반쪽짜리 HTTPS

언제 이런 설정을 사용할 수 있을까?

- 프론트엔드 개발팀과 협업하는 과정에서, 서로 다른 개발 서버 간 통신 시 HTTPS가 아니면 요청이 차단되는 문제가 발생하는 경우가 있다.

- 이러한 상황에서 운영 목적이 아닌 개발·테스트 환경이라면 간단한 해결책으로 Flexible SSL 방식을 가볍게 사용하는 것을 고려할 수 있다.

현제 설정의(Flexible(가변)) 이득은?
- 사용자 ↔ Cloudflare 구간 보호하여 공용 환경에서 쿠키 / 세션 / 요청 내용 탈취 방지 가능

공용 와이파이
회사 네트워크
카페 환경

요약

Flexible SSL은 HTTPS가 반드시 필요한 개발 환경’에서는 빠르게 적용할 수 있는 편의성 있는 선택지일 수 있다.
하지만 실제 운영 환경에서는 Cloudflare와 원본 서버 간 통신까지 암호화되는 Full 또는 Full (Strict) 모드를 사용하는 것이 바람직하다.

허브 간 최단 경로 탐색 알고리즘 구현 + Kakao Map Api 연동 (Spring Boot)

kimfishes — Sat, 6 Dec 2025 16:28:41 +0900

물류 관리 및 배송 시스템을 위한 MSA 기반 플랫폼 개발 프로젝트로 물류 관리 및 배송 시스템을 만들게 되었다.

그중 hub 파트를 맡게 되어 사용자가 주문을 완료하여 배송이 시작되면 특정 허브에서 도착 허브까지 가장 빠르고 효율적인 경로를 찾아 응답해 주는 코드를 구현해야 한다.

처음에는 거리만 기준으로 정렬하는 단순 탐색을 고려했지만, 실제 배송에서는 다음 요소들을 모두 고려해야 했다. 즉 가중치 기반 최단 경로 문제였고, 자연스럽게 다익스트라(Dijkstra) 알고리즘을 채택하게 되었다.

이동 거리 (distance)
소요 시간 (duration)

출발지의 위도 경도값, 도착지의 위도 경도값을 Kakao Map Api에 경로 탐색을 요청해 응답을 받아오며,

해당 결과가 있는 상태에서 동일 경로 탐색이 요청이 들어왔을 때 기존 결과와 시간차가 5분이 지나지 않은 상태이면 값을 재사용하여 응답 시간을 줄임

허브들의 정보 (p_hub)와 물류 허브 사이의 이동 데이터는 p_hub_info 테이블에 UUID로 연관 지어 저장해두고 있으며 연결 정보제약사항은 다음과 같다.

제약사항

“연결된” 허브간 배송만 가능합니다. 예를 들어, 서울-부산 배송 시 서울-경기남부-대구-부산 순으로 배송해야 합니다.
17개 센터는 아래와 같이 연결되어 있습니다.
- 경기남부: 경기북부, 서울, 인천, 강원도, 경상북도, 대전, 대구
- 대전: 충청남도, 충청북도, 세종, 전라북도, 광주, 전라남도, 경기남부, 대구
- 대구: 경상북도, 경상남도, 부산, 울산, 경상북도, 경기남부, 대전
- 경상북도: 경기남부, 대구

Code

엔티티 테이블은 총 4개 존재

Hub

public class Hub extends BaseEntity {

    @Id
    @GeneratedValue(generator = "uuidv7")
    @GenericGenerator(
            name = "uuidv7",
            strategy = "lib.id.UUIDv7Generator"
    )
    @Column(name = "id", columnDefinition = "BINARY(16)")
    private UUID id;

    @Column(name = "name", nullable = false, length = 20)
    private String name;

    @Column(name = "hub_manager_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID hubManagerId;

    @Column(name = "postal_code", nullable = false, length = 20)
    private String postalCode;

    @Column(name = "country", nullable = false, length = 50)
    private String country;

    @Column(name = "region", nullable = false, length = 50)
    private String region;

    @Column(name = "city", nullable = false, length = 50)
    private String city;

    @Column(name = "district", length = 50)
    private String district;

    @Column(name = "road_name", nullable = false, length = 100)
    private String roadName;

    @Column(name = "building_name", length = 50)
    private String buildingName;

    @Column(name = "detail_address", length = 100)
    private String detailAddress;

    @Column(name = "full_address", nullable = false, length = 100)
    private String fullAddress;

    @Column(name = "latitude", nullable = false, precision = 10, scale = 7)
    private BigDecimal latitude;

    @Column(name = "longitude", nullable = false, precision = 10, scale = 7)
    private BigDecimal longitude;
}

HubInfo

@Getter
@Entity
@Table(name = "p_hub_info")
public class HubInfo extends BaseEntity {

    @Id
    @GeneratedValue(generator = "uuidv7")
    @GenericGenerator(
            name = "uuidv7",
            strategy = "lib.id.UUIDv7Generator"
    )
    @Column(name = "id", columnDefinition = "BINARY(16)")
    private UUID id;

    @Column(name = "start_hub_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID startHubId;

    @Column(name = "end_hub_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID endHubId;

    @Column(name = "delivery_duration")
    private Integer deliveryDuration;
    // 배송 예측 소요 시간

    @Column(name = "distance", precision = 10, scale = 3)
    private BigDecimal distance;
    // 배송 거리 km 단위

    public static HubInfo create(UUID startHubId, UUID endHubId) {
        HubInfo hubInfo = new HubInfo();
        hubInfo.startHubId = startHubId;
        hubInfo.endHubId = endHubId;
        return hubInfo;
    }

    // 시간, 거리 넣기
    public void updateDeliveryInfo(Integer deliveryDuration, BigDecimal distance) {
        this.deliveryDuration = deliveryDuration;
        this.distance = distance;
    }


    // false면 기존 값 재사용
    public boolean checkUpdateTime(LocalDateTime updateTime) {
        LocalDateTime updatedAt = this.getUpdatedAt();
        if (updatedAt == null) {
            return true;
        }

        if (this.deliveryDuration == null || this.distance == null) {
           return true;
       }
        // 두 시간 차이를 분 단위로 계산
        long diffMinutes = Duration.between(updatedAt, updateTime).toMinutes();

        // 5분 이상 차이가 난다면 true
        return diffMinutes >= 5;
    }


    public void updateHubInfo(UUID startHubId, UUID endHubId) {
        if(startHubId != null) this.startHubId = startHubId;
        if(endHubId != null) this.endHubId = endHubId;
    }

}

HubRouteLog (출발지와 목적지)

@Getter
@Entity
@Table(name = "p_hub_route_log")
public class HubRouteLog extends BaseEntity {

    @Id
    @GeneratedValue(generator = "uuidv7")
    @GenericGenerator(
            name = "uuidv7",
            strategy = "lib.id.UUIDv7Generator"
    )
    @Column(name = "id", columnDefinition = "BINARY(16)")
    private UUID id;

    @Column(name = "start_hub_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID startHubId;

    @Column(name = "end_hub_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID endHubId;

    @Column(name = "total_duration")
    private Integer totalDuration;
    //총 소요 시간

    @Column(name = "total_distance", precision = 10, scale = 3)
    private BigDecimal totalDistance;
    // 총 거리 km

    public static HubRouteLog create(
        UUID startHubId,
        UUID endHubId,
        Integer totalDuration,
        BigDecimal totalDistance
    ){
        HubRouteLog log = new HubRouteLog();
        log.startHubId = startHubId;
        log.endHubId = endHubId;
        log.totalDuration = totalDuration;
        log.totalDistance = totalDistance;
        return log;
    }

}

HubRouteLogStop (허브 경로 정보)

@Getter
@Entity
@Table(name = "p_hub_route_log_stop")

public class HubRouteLogStop extends BaseEntity {

    @Id
    @GeneratedValue(generator = "uuidv7")
    @GenericGenerator(
            name = "uuidv7",
            strategy = "lib.id.UUIDv7Generator"
    )
    @Column(name = "id", columnDefinition = "BINARY(16)")
    private UUID id;

    @Column(name = "hub_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID hubId;
    // 경로 허브 id

    @Column(name = "hub_route_log_id", nullable = false, columnDefinition = "BINARY(16)")
    private UUID hubRouteLogId;
    // 출발허브 || 도착허브 정보

    @Column(name = "sequence_num", nullable = false)
    private Integer sequenceNum;

    public static HubRouteLogStop create(UUID hubRouteLogId, UUID hubId, int sequenceNum) {
        HubRouteLogStop stop = new HubRouteLogStop();
        stop.hubRouteLogId = hubRouteLogId;
        stop.hubId = hubId;
        stop.sequenceNum = sequenceNum;
        return stop;
    }

}

허브 간 Edge 가중치를 계산하는 서비스 – HubEdgeWeightService

p_hub_info 테이블에서 허브 간 연결 정보(HubInfo) 를 조회
최근 5분 이내에 계산된 캐시 된 거리/시간이 있으면 그대로 재사용
캐시가 없거나 오래되었으면 Kakao Map API를 호출해서 실제 거리/시간을 다시 계산
새로 계산한 값은 HubInfo 엔티티에 업데이트해서 DB 기반 캐시처럼 재사용
최종적으로 EdgeWeight VO로 (시작 허브, 도착 허브, 소요 시간, 거리)를 반환

@Service
@Slf4j
@RequiredArgsConstructor
public class HubEdgeWeightService implements HubEdgeWeightProvider {

    private final HubInfoRepository hubInfoRepository;
    private final HubRepository hubRepository;
    private final KakaoMapClient kakaoMapClient;

    @Override
    public EdgeWeight getWeight(UUID startHubId, UUID endHubId) {

        HubInfo hubInfo = hubInfoRepository.findByStartHubIdAndEndHubId(startHubId, endHubId)
            .orElseThrow(()-> new BusinessException(ErrorCode.HUB_INFO_NOT_FOUND));

        LocalDateTime now = LocalDateTime.now();

        // 1) 5분 이내의 캐시가 있으면 기존 값 그대로 사용
        if (hubInfo.getDeliveryDuration() != null && hubInfo.getDistance() != null && !hubInfo.checkUpdateTime(now)) {

            log.info("[HubEdgeWeight] cache hit: {} -> {} ({}h {}m, {} km)",
                startHubId, endHubId, hubInfo.getDeliveryDuration()/3600, hubInfo.getDeliveryDuration() % 3600 / 60, hubInfo.getDistance());

            return new EdgeWeight(startHubId, endHubId, hubInfo.getDeliveryDuration(), hubInfo.getDistance());
        }

        // 2) 아니면 Kakao API로 실제 거리/시간 계산
        // 허브 존재 여부 확인
        Hub startHub = hubRepository.findById(hubInfo.getStartHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));
        Hub endHub = hubRepository.findById(hubInfo.getEndHubId())
            .orElseThrow(() -> new BusinessException(ErrorCode.HUB_NOT_FOUND));

        // 해당 허브들에 위도, 경도값 추출
        String origin = startHub.getLongitude() + "," + startHub.getLatitude();
        String destination = endHub.getLongitude() + "," + endHub.getLatitude();

        DirectionInfoResponseV1 direction = kakaoMapClient.getDirection(
            origin,
            destination,
            2,          // carType
            "DIESEL",   // carFuel
            true        // carHipass
        );

        // Kakao 응답은 초 단위
        int durationSec = (int) direction.duration();
        BigDecimal distanceKm = BigDecimal
            .valueOf(direction.distance() / 1000.0)
            .setScale(3, RoundingMode.HALF_UP);

        hubInfo.updateDeliveryInfo(durationSec, distanceKm);

        log.info("[HubEdgeWeight] cache hit: {} -> {} ({}h {}m, {} km)",
            startHubId, endHubId, hubInfo.getDeliveryDuration() / 3600, hubInfo.getDeliveryDuration() % 3600 / 60, hubInfo.getDistance());

        return new EdgeWeight(startHubId, endHubId, durationSec, distanceKm);
    }
}

최단 경로 탐색 + 로그 저장 – findFastestRouteAndLog

경로 탐색(findFastestRoute)과 로그 저장(logRoute)을 하나의 트랜잭션 안에서 처리

    /**
     * 최단 시간 기준 경로 탐색 + 로그 저장
     */
    @Transactional
    public HubRouteResult findFastestRouteAndLog(UUID startHubId, UUID endHubId) {

        HubRouteResult result = findFastestRoute(startHubId, endHubId);
        logRoute(result);
        
        return result;
    }

최단 시간 기준 경로 탐색 – findFastestRoute

HubInfo에 잇는 모든 정보를 findAll하여 가져오고
Map <허브 ID, List <Edge>> 형태로 인접 리스트를 구성한다.
허브 간 시간/거리는 HubEdgeWeightProvider(= HubEdgeWeightService)를 통해 가져옴
다익스트라 알고리즘 호출

    /**
     * 최단 시간 기준 경로 탐색 (Dijkstra)
     */
    @Transactional(readOnly = true)
    public HubRouteResult findFastestRoute(UUID startHubId, UUID endHubId) {

        List<HubInfo> connections = hubInfoRepository.findAll();

        if (connections.isEmpty()) {
            log.warn("[HubRoute] no hub connections in DB");
            throw new BusinessException(ErrorCode.HUB_ROUTE_NOT_FOUND);
        }


        // 1. 인접 리스트 그래프 구성 (duration 기준 weight)
        Map<UUID, List<Edge>> graph = new HashMap<>();

        for (HubInfo info : connections) {
            UUID from = info.getStartHubId();
            UUID to = info.getEndHubId();

            // computeInfAbsent -> Map에서 key가 없을 때만 value를 생성해서 넣어주는 메서드
            graph.computeIfAbsent(from, k -> new ArrayList<>()).add(new Edge(to, info));

        }

        // 2. 다익스트라 실행
        return dijkstraByDuration(graph, startHubId, endHubId);
    }

다익스트라 구현 – dijkstraByDuration

가중치를 “시간(durationSec)”으로 고정해서 “최단 시간 경로”를 계산
dist: 시작 허브로부터 각 허브까지의 최소 소요 시간을 저장
prev: 나중에 실제 경로를 복원하기 위해 “이 허브로 오기 직전 허브”를 저장
PriorityQueue <Node>: 현재까지의 누적 시간이 가장 짧은 허브부터 탐색하기 위해 우선순위 큐를 사용

주석을 자세히 보시면 편합니다.

    private HubRouteResult dijkstraByDuration(Map<UUID, List<Edge>> graph, UUID startHubId, UUID endHubId) {

        Map<UUID, Integer> dist = new HashMap<>();  // 최소 시간
        Map<UUID, UUID> prev = new HashMap<>();     // 경로 복원용

        // 우선순위 큐로 Node 객체를 비교할 때 n.time (노드까지의 누적 시간)을 기준으로 정렬해서 넣음
        PriorityQueue<Node> pq = new PriorityQueue<>(Comparator.comparingInt(n -> n.time));


        // 시작 허브의 거리를 0으로 두고, 나머지는 모두 무한대(최대값)로 초기화
        for (UUID hubId : graph.keySet()) {
            dist.put(hubId, Integer.MAX_VALUE);
        }

        // dist는 지금까지 발견된 최소 누적 시간으로 기록 저장소
        // 출발 시점은 0으로
        dist.put(startHubId, 0);

        // pq는 앞으로 탐색할 후보 노드 목록
        // 시작 허브를 시간 0으로 큐에 넣어서 다익스트라 탐색 시작
        pq.offer(new Node(startHubId, 0));


        // 가장 누적 시간이 짧은 허브부터 꺼내서, 허브에서 갈 수 있는 모든 인접 허브의 거리를 갱신
        while (!pq.isEmpty()) {
            Node cur = pq.poll();
            UUID curId = cur.hubId;


            // 최단 거리 알고리즘의 특성상, 목적지 허브가 PQ에서 꺼내졌다는 것은 그 시간 값이 최종 최소 시간이라는 의미
            if (curId.equals(endHubId)) {
                break;
            }

            // cur.time > dist.get(curId) 이면, 이미 더 짧은 경로가 존재하는 상태라서 스킵
            // 예: 더 긴 경로로 먼저 들어갔다가, 나중에 더 짧은 경로가 발견된 경우로
            // “현재 꺼낸 값이 dist 테이블에 저장된 최소 시간보다 크면 버림
            if (cur.time > dist.get(curId)) {
                continue;
            }


            // 현재 허브(curId)가 연결된 허브들의 목록을 가져온다. 없으면 빈 리스트 반환 (NPE 방지)
            // key: 현재 허브 ID,  value: 그 허브에서 갈 수 있는 인접 허브들로의 간선 목록
            List<Edge> edges = graph.getOrDefault(curId, List.of());

            // 현재 허브에서 직접 갈 수 있는 허브들만 순회
            for (Edge e : edges) {

                //인접 허브들까지 얼마나 걸리는지 시간 계산
                EdgeWeight weight = hubEdgeWeightProvider.getWeight(curId, e.toHubId);

                // cur.time = 출발 → e. 현재 허브까지 걸린 누적 시간
                int nextTime = cur.time + weight.durationSec();

                // 아직 도달한 적 없는 허브라면 → 현재 값 = ∞ 이고 nextTime이 기존 값보다 더 빠르면 저장
                // 목적지에 처음 도달했다고 끝나는 게 아니라 더 빠른 경로가 발견될 때까지 반복문 동안 dist를 계속 비교·갱신
                if (nextTime < dist.getOrDefault(e.toHubId, Integer.MAX_VALUE)) {
                    dist.put(e.toHubId, nextTime);

                    //prev.put(e.toHubId, curId); 를 통해 경로 추적용 역방향 링크를 기록
                    prev.put(e.toHubId, curId);
                    pq.offer(new Node(e.toHubId, nextTime));
                }
            }
            // dist에는 반복적으로 더해진 시간 nextTime가 들어감
        }


        // 도착 허브가 여전히 무한대라면, 실제 경로가 없다고 판단하고 예외처리
        if (!dist.containsKey(endHubId) || dist.get(endHubId) == Integer.MAX_VALUE) {
            log.warn("[HubRoute] no path found: {} -> {}", startHubId, endHubId);
            throw new BusinessException(ErrorCode.HUB_ROUTE_NOT_FOUND);
        }


        // 3. 경로 복원
        // prev 맵을 이용해 endHubId → ... → startHubId 방향으로 역추적을 진행
        // 리스트에 담고 나서 Collections.reverse(path)로 순서를 뒤집어 최종적으로 start → ... → end 순서의 경로를 얻음
        List<UUID> path = new ArrayList<>();
        UUID cur = endHubId;
        while (cur != null) {
            path.add(cur);
            cur = prev.get(cur);
        }
        Collections.reverse(path);

        // 4. 총 거리 합산
        // path 리스트를 인접한 두 개씩 (from, to) 쌍으로 묶어서 순회
        BigDecimal totalDistance = BigDecimal.ZERO;

        for (int i = 0; i < path.size() - 1; i++) {
            UUID from = path.get(i);
            UUID to = path.get(i + 1);

            // 그래프에서 from 의 인접 간선 목록을 가져와 to 로 가는 간선을 찾음
            List<Edge> edges = graph.getOrDefault(from, List.of());
            Edge edge = edges.stream()
                .filter(e -> e.toHubId.equals(to))
                .findFirst()
                .orElseThrow(() -> new BusinessException(ErrorCode.HUB_EDGE_NOT_FOUND));


            // 거리 합산은 다시 weight를 조회해서 distanceKm만 사용했다.
            // hubEdgeWeightProvider 내부 캐시 덕분에 Kakao API는 필요 시에만 호출되었다.
            EdgeWeight weight = hubEdgeWeightProvider.getWeight(from, to);
            // 해당 간선의 distanceKm 를 모두 더해 총 이동 거리를 계산
            totalDistance = totalDistance.add(weight.distanceKm());
        }

        int totalDuration = dist.get(endHubId);

        return new HubRouteResult(
            startHubId,
            endHubId,
            path,
            totalDuration,
            totalDistance
        );
    }

경로 로그 저장 – logRoute

경로를 찾는 것에서 끝내지 않고, 실제로 어떤 경로가 선택되었는지 DB에 남김

1. 헤더 로그 – HubRouteLog

출발 허브, 도착 허브
총 소요 시간, 총 이동 거리

2. 스텝 로그 – HubRouteLogStop

경로 상의 각 허브 ID
seq 값을 통해 순서를 기록
이렇게 하면 나중에 조인해서 실제 경로를 그대로 재구성

    /**
     * 경로 로그 테이블에 저장
     */
    @Transactional
    public void logRoute(HubRouteResult result) {

        HubRouteLog logEntity = HubRouteLog.create(
            result.startHubId(),
            result.endHubId(),
            result.totalDurationSec(),
            result.totalDistanceKm()
        );
        hubRouteLogRepository.save(logEntity);

        int seq = 0;
        for (UUID hubId : result.pathHubIds()) {
            HubRouteLogStop stop = HubRouteLogStop.create(
                logEntity.getId(),
                hubId,
                seq++
            );
            hubRouteLogStopRepository.save(stop);
        }

        log.info("[HubRoute] Logged route {} -> {} : {} sec, {} km, {} hops",
            result.startHubId(), result.endHubId(),
            result.totalDurationSec(), result.totalDistanceKm(),
            result.pathHubIds().size());
    }

Edge - 그래프의 한 간선을 의미

어떤 허브(toHubId)로 가는지
그때 걸리는 시간(durationSec)
그때 이동 거리(distanceKm)

Node - 우선순위 큐에서 사용할 “현재 위치 + 지금까지 누적된 시간”을 표현

    private static class Edge {
        private final UUID toHubId;
        private final HubInfo hubInfo;

        public Edge(UUID toHubId, HubInfo hubInfo) {
            this.toHubId = toHubId;
            this.hubInfo = hubInfo;
        }
    }

    private static class Node {
        private final UUID hubId;
        private final int time;

        private Node(UUID hubId, int time) {
            this.hubId = hubId;
            this.time = time;
        }
    }

결과

요구사항에 맞춰 서울에서 부산 hub까지의 요청인 경우

서울 -> 경기남부 -> 대구 -> 부산 순서로 올바르게 경로를 찾아 응답을 주고 있다.

첫 요청의 경우 연관 경로에 허브들끼리의 시간을 api를 보내 가져와야 하니 시간이 오래 걸리지만, 한번 결과를 가져온 상태에서 5분이 지나지 않은 경우 DB에서 가져와 빠른 응답을 주고 있다.

서울 -> 부산으로 결과가 나온 이후 5분이 지나지 않은 상태에서 경기남부 -> 부산으로 조회 시 빠른 도착 시간 조회가 가능하다.

구현이 완료 되었지만 Redis 캐시를 사용하고 있지 않다는 문제가 존재하여 다음 게시물에서 이를 보완하려 한다.

https://kimfishes.tistory.com/13?category=1262695

허브 간 최단 경로 탐색 캐시 스탬피드 (Cache Stampede) 발생+해결

kimfishes.tistory.com

DDD의 페이징 로직 (Spring Boot)

kimfishes — Tue, 2 Dec 2025 17:06:57 +0900

문제 발생

- 헥사고날 아키텍처와 DDD 기반으로 허브 서버를 개발하면서, 페이징 로직을 어떻게 가져가야 할지에 대한 고민이 생겼다.

- Spring Data JPA가 제공하는 Pageable, PageRequest, Page 같은 페이징 타입들은 매우 강력하고 편리하지만, 도메인 계층에 노출시키기에는 기술 의존성이 크다는 문제가 있다.

- 도메인 계층에 그대로 사용하기에는 기술 의존성이 크다.

문제 예시

- 헥사고날 아키텍처에서 도메인은 비즈니스 규칙만 알고 있어야 하고, 프레임워크나 기술에 종속되면 안되지만 페이징을 구현하려다 보니 자연스럽게 아래와 같은 코드가 만들어졌다.

- Hub Repository 인터페이스에서 Page를 사용하게 된다면 도메인 부분이지만 Jpa에 의존하는 문제가 됨

- 도메인은 특정 프레임워크에 종속되지 않아야 한다는 점에서 구조가 무너지기 때문

최초로 작성했던 Hub Repository 인터페이스 ( 도메인이 JPA에 잠식)

public interface HubRepository {

    void save(Hub hub);

    Page<Hub> findAll(Pageable pageable);

    Page<Hub> findByNameOrFullAddressContaining(String nameOrFullAddress, Pageable pageable);
}

구분	문제점
DDD 관점	도메인 계층이 프레임워크에 의존하게 됨
확장성	JPA 기반 페이징 전략에 고정되어 버림

DDD 구조를 깨트리지 않기 위해 리팩토링

Pageable / Page 같은 JPA 타입을 제거
순수 타입(int page, int size)으로 대체

도메인은 페이징이 어떻게 구현되는지 모르며 페이징 전략이 무엇이든(Offset / Slice / Cursor 등) 도메인은 **그저 “몇 번째 페이지를 가져와라”**만 표현

    void save(Hub hub);

    List<Hub> findAll(int page, int size);

    List<Hub> findByNameOrFullAddressContaining(String nameOrFullAddress, int page, int size);

JpaRepsitory

public interface JpaHubRepository extends JpaRepository<Hub, UUID> {

    List<Hub> findByNameAndFullAddressContaining(String name, String address, Pageable pageable);

    List<Hub> findAllByDeletedAtIsNull(Pageable pageable);
}

Adapter (인프라스트럭처)

@RequiredArgsConstructor
public class HubRepositoryAdapter implements HubRepository {

    private final JpaHubRepository jpaHubRepository;


    @Override
    public void save(Hub hub) {
        jpaHubRepository.save(hub);
    }

    @Override
    public List<Hub> findAll(int page, int size) {
        Pageable pageable = PageRequest.of(page, size, Sort.by("name").ascending());
        return jpaHubRepository.findAllByDeletedAtIsNull(pageable);
    }



    @Override
    public List<Hub> findByNameOrFullAddressContaining(String nameOrFullAddress, int page, int size) {
        Pageable pageable = PageRequest.of(page, size);
        return jpaHubRepository.findByNameAndFullAddressContainingAndDeletedAtIsNotNull(nameOrFullAddress, nameOrFullAddress, pageable);
    }



}

여기서 한 가지 의문이 들었다.

“실제로 Repository에 넘어가는 객체는 PageRequest인데, 그냥 Repository에서 PageRequest를 받으면 더 낫지 않나?”

List<Hub> findAllByDeletedAtIsNull(PageRequest pageRequest);

하지만 이 구조는 더 큰 문제를 만들어냈다.

Repository가 PageRequest라는 특정 구현체에 고정됨
Slice, Keyset, Cursor 기반 페이징으로 변경될 경우 메서드 시그니처부터 수정해야 함
Controller에서 Pageable 자동 매핑을 사용할 경우 타입 불일치로 호출 불가

즉, PageRequest를 파라미터로 쓰는 순간 확장성이 완전히 사라지므로 Repository가 PageRequest에 “고정”되므로 구현체는 내부에서 생성해서 넘긴다.

1. find(PageRequest request)

2. find(Pageable pageable)

둘 다 지금은 똑같이 동작하지만 2번째 구조가 변화에 강한 구조다.

Pageable vs PageRequest 차이

개념	역할
Pageable	페이징 정보를 표현하는 인터페이스
PageRequest	가장 널리 쓰이는 Pageable의 구현체

Pageable은 추상 타입이고 PageRequest는 그 구현체이다.

List<Hub> findAllByDeletedAtIsNull(PageRequest pageRequest);

- 코드상에서는 문제가 없었고, 실제로 동작도 문제 없지만 PageRequest라는 특정 구현체에 종속됨으로써 확장성을 잃게된다.

- 이를 해결하기 위해 Repository는 Pageable, Adapter는 PageRequest.of(...)를 적용하는 방식 사용

결론

Repository가 PageRequest를 받는다고 해서 성능이 좋아지거나 기능이 늘어나지 않는다.
하지만 Repository가 Pageable을 받는 순간, PageRequest · unpaged · Slice · keyset · cursor · custom Pageable 등 어떤 페이징 전략을 적용하더라도 Repository는 변경되지 않는다.
즉 지금은 PageRequest가 넘어가더라도, 파라미터 타입을 Pageable로 두는 것이 미래의 변경 비용을 극적으로 줄이는 선택이 된다.

어? 만들어보니 프론트가 남은 갯수를 List로 주면 못 보는데??? 커스텀을 해야 한다...

도메인 계층에서는 JPA의 Page를 쓰지 않기 위해 List<Hub>만 반환하도록 깔끔하게 정리했는데, 막상 화면에서 필요한 정보는 단순히 “현재 페이지의 목록”뿐만 아니라 전체 허브 개수가 몇 개인지, 마지막 페이지가 어디까지인지 또는 다음 페이지가 있는지 정보를 제공해줘야 한다.

JPA의 Page를 그대로 노출하는 대신
도메인에 독립적인 커스텀 페이징 타입(예: PageResult<T> 같은)을 만들고
인프라 계층에서 Page → PageResult로 변환해 올려주는 구조

PageResult

import lombok.Getter;

import java.util.List;

@Getter
public class PageResult<T> {

    private final List<T> items;   // 현재 페이지의 데이터
    private final int page;        // 현재 페이지 번호 (0 기반)
    private final int size;        // 페이지 크기
    private final long totalCount; // 전체 데이터 개수 (Slice 기반일 경우 -1 허용)
    private final boolean hasNext; // 다음 페이지 존재 여부

    private PageResult(List<T> items, int page, int size, long totalCount, boolean hasNext) {
        this.items = items;
        this.page = page;
        this.size = size;
        this.totalCount = totalCount;
        this.hasNext = hasNext;
    }

    public static <T> PageResult<T> of(List<T> items, int page, int size, long totalCount) {
        boolean hasNext = (long) (page + 1) * size < totalCount;
        return new PageResult<>(items, page, size, totalCount, hasNext);
    }

    // slice 기반 페이징을 위한 팩토리 (totalCount 미알 수 있을 때)
    public static <T> PageResult<T> sliceOf(List<T> items, int page, int size, boolean hasNext) {
        return new PageResult<>(items, page, size, -1, hasNext);
    }
}

사용 예시

public PageResult<Hub> findAll(int page, int size) {
    Pageable pageable = PageRequest.of(page, size, Sort.by("name").ascending());
    Page<Hub> result = jpaHubRepository.findAllByDeletedAtIsNull(pageable);

    return PageResult.of(
        result.getContent(),
        result.getNumber(),
        result.getSize(),
        result.getTotalElements()
    );
}