-elastic

▶ 들어가며

이번 글에서는 Elasticsearch를 공부하면서 가장 먼저 익혀야 하는 기본 용어를 정리하고,
직접 코드를 쳐가며 CRUD(Create / Read / Update / Delete) 명령어에 익숙해지는 시간을 가져보려고 한다.

Elasticsearch는 처음 보면 생소한 용어가 많아서 막막할 수 있는데,
사실 구조적으로는 우리가 익숙한 MySQL과 닮은 부분이 굉장히 많다.

둘 다 데이터베이스라는 큰 틀 안에서

• 데이터를 삽입하고(Create)

• 조회하고(Read)

• 수정하고(Update)

• 삭제(Delete)

하는 흐름은 동일하다.

그래서 이번 글에서는
👉 MySQL과 비교하면서 Elasticsearch를 이해하는 방식으로 정리해보려고 한다!!

▶ Elasticsearch 기본 용어 정리

아래는 가장 기본적인 MySQL 과의 대응 관계이다.

-기본 용어 정리

MySQL:

table을 만들고 → column의 schema를 정의하고 → row(record)를 저장하고 → 데이터를 조회/수정/삭제한다

⭐Elasticsearch:

인덱스를 만들고 → field의 mapping을 정의하며 → document를 저장하고 → 데이터들을 검색/수정/삭제한다

라는 구조로 동작하는 것이다.

▶ CRUD 명령어 정리

이제부터는 Elasticsearch에서 실제로 사용하는 CRUD 명령어를 직접 쳐보면서 익혀보자!!
이번 글에서는 앞으로 계속 사용할 기본 인덱스명을 "users"로 고정해서 진행한다.

- Index 생성하기

MySQL에서 CREATE TABLE을 하듯이, Elasticsearch에서는 데이터를 저장하기 위한 Index를 생성한다.

아래 명령어로 users 인덱스를 생성해 보자.

PUT /users

- Index 조회하기

생성한 인덱스가 존재하는지 확인하는 명령어이다.

GET /users

- Index 삭제하기

이번에는 인덱스를 삭제해보자.

DELETE /users

이 상태에서 다시 인덱스를 조회해보면

"index_not_found_exception" 에러가 발생한다

👉 즉, 인덱스가 삭제되었기 때문에 더 이상 존재하지 않는 상태임을 확인할 수 있다!

- Mapping 정의하기

MySQL에서 테이블을 만들 때 schema를 정의하듯이, Elasticsearch에서도 index 내부에 어떤 타입의 데이터를 저장할지 정의할 수 있다. 이를 Elasticsearch에서는 Mapping이라고 부른다.

아래 명령어로 users 인덱스에 매핑을 정의해보자.

PUT /users/_mapping 
{    
    "properties": 
        { 
            "name": { "type": "keyword" }, 
            "age": { "type": "integer" }, 
            "is_active": { "type": "boolean" } 
        } 
}

여기서 핵심은 다음과 같다.

• properties 안에서 field들을 정의한다.

• 각 field는 type을 가진다.

• keyword는 MySQL에서 VARCHAR(문자열) 같은 느낌이라고 생각하면 된다.

• integer, boolean도 그대로 이해하면 된다.

👉 즉, Mapping은 MySQL에서 schema를 정의하는 과정과 거의 유사하다.

매핑이 잘 정의되었는지 확인하고 싶다면 조회 명령어로 확인할 수 있다.

- GET /users

- Document 삽입하기

이제 실제 데이터를 넣어보자!

MySQL에서 테이블에 record(row)를 삽입하는 과정과 동일하게, Elasticsearch에서는 index에 document를 삽입한다.

POST /users/_doc 
{
    "name": "Bo", 
    "age": 26, 
    "is_active": true 
}

이렇게 하면 Elasticsearch가 자동으로 랜덤한 _id 값을 생성해서 document를 저장한다.

- Document 조회하기

삽입된 document를 조회하려면 아래 명령어를 사용한다.

GET /users/_search

결과를 확인해보면 hits 안에 document가 들어가 있을 것이고,
각 document마다 Elasticsearch가 자동으로 생성한 랜덤 _id 값이 붙어있는 것도 확인할 수 있다.

- ID를 지정해서 Document 삽입하기

document를 저장할 때 자동 ID가 아니라, 내가 직접 ID를 지정해서 저장하는 것도 가능하다.

POST /users/_create/1
{
    "name": "Boo", 
    "age": 27, 
    "is_active": true 
}

이렇게 하면 _id = 1로 document가 저장된다.

여기서 중요한 포인트는,

👉 _create 방식은 같은 ID가 이미 존재하면 저장이 실패한다는 점이다.
즉, 중복 저장이 불가능하다. 고유 id를 알아서 처리하는..

- 특정 ID로 Document 조회하기

특정 document 하나만 조회하고 싶다면 아래처럼 조회할 수 있다.

GET /users/_doc/2

👉 여기서 마지막 숫자 2는 document의 "id" 값이다.

- 같은 ID여도 덮어씌우기(업데이트) 하고 싶다면?

위에서 확인한 것처럼 이미 존재하는 id값을 POST 하는 경우 ERROR가 발생했지만, MySQL에서 upsert처럼 동작하게 하려면 아래처럼 PUT을 사용하면 된다. 이미 존재하는 id=1 document에 새로운 값을 가지는 데이터를 PUT 하는 경우

PUT /users/_doc/1 
{ 
    "name": "Boo", 
    "age": 28, 
    "is_active": true 
}

데이터 삽입이 성공하는 모습을 확인할 수 있고, 이후 다시 조회해보면 기존 document가 덮어씌워진 것을 확인할 수 있다.

- Document 수정하기 (Update)

사실 위에서 사용했던 PUT /users/_doc/1 자체가
👉 특정 ID document를 수정하는 방식이라고 생각해도된다. 같은 의미지 사실상.

즉, Elasticsearch에서는 PUT 요청이

• 없으면 생성

• 있으면 덮어쓰기(update)

방식으로 동작한다.

- 특정 필드만 수정하기

특정 인물의 나이만 변경해야 하는 경우라면? 모든 필드가 아니라, 특정 필드만 수정하고 싶을 수도 있다.

이 경우에는 _update를 사용한다.

POST /users/_update/1 
{ 
    "doc": { "age": 29 } 
}

👉 doc 안에 수정할 필드만 넣어주면 된다.

이 방식은 MySQL의 UPDATE users SET age=29 WHERE id=1 같은 느낌이다.

- Document 삭제하기 (Delete)

마지막으로 특정 ID document를 삭제해보자.

DELETE /users/_doc/1

이후 index에서 해당 id의 document를 조회해보면 document가 삭제된 것을 확인할 수 있다.

▶ 마무리

이번 글에서는 Elasticsearch에서 가장 기본이 되는 용어와 CRUD 명령어를 정리해 봤다. 정리해보면 Elasticsearch는 처음엔 생소했지만, 동작 방식 자체는 MySQL과 굉장히 유사하다는 것을 알 수 있었다. 자주 사용하는 코드들을 자주 쳐보면서 채화시키는 것이 중요할 것 같다.

• 인덱스를 만들고

• document를 삽입하고

• 검색하고

• 수정하고

• 삭제한다

이 흐름만 익히면 막막했던 Elasticsearch와 조금 친해지는 느낌이 든다. 👍👍👍

코드 리뷰 한 줄에서 시작된 쿼리 최적화 여정

1. 시작 — "일단 돌아가게 만들자"

Finders 프로젝트에서 1:1 문의(Inquiry) API를 맡았다. 현상소에 문의를 남기고, 답변을 받고, 목록을 조회하는 — 평범한 CRUD다.

"JPA 쓰면 쿼리 안 짜도 되는 거 아니야?"

솔직히 처음엔 그렇게 생각했다. JpaRepository에 findAll, findById 쓰면 끝이니까.

// 첫 번째 버전의 목록 조회 (QueryDSL)
public List<Inquiry> findByMemberId(Long memberId, int page, int size) {
    return queryFactory
            .selectFrom(inquiry)
            .leftJoin(inquiry.photoLab).fetchJoin()
            .leftJoin(inquiry.replies, inquiryReply).fetchJoin()
            .where(inquiry.member.id.eq(memberId))
            .orderBy(inquiry.createdAt.desc())
            .offset((long) page * size)
            .limit(size)
            .fetch();
}

문의 목록을 가져올 때, 현상소 이름도 보여줘야 하고 답변이 있는지도 보여줘야 해서 fetchJoin을 걸었다. 잘 돌아갔다. 돌아가기는 했다.

(#137, PR #138)

2. 잠깐, N+1이 뭔데?

블로그를 쓰는 김에, N+1 문제가 뭔지 한번 쉽게 설명해보겠다.

상황 설정

문의 10개를 목록 조회한다고 하자. 각 문의에는 현상소(PhotoLab) 정보가 필요하다.

😱 N+1이 터지면

[쿼리 1] SELECT * FROM inquiry WHERE member_id = 1 LIMIT 10    ← 문의 10개 가져옴
[쿼리 2] SELECT * FROM photo_lab WHERE id = 3                   ← 1번 문의의 현상소
[쿼리 3] SELECT * FROM photo_lab WHERE id = 7                   ← 2번 문의의 현상소
[쿼리 4] SELECT * FROM photo_lab WHERE id = 3                   ← 3번 문의의 현상소 (중복!)
  ...
[쿼리 11] SELECT * FROM photo_lab WHERE id = 12                 ← 10번 문의의 현상소

1번의 쿼리로 문의 목록을 가져오고, 각 문의마다 현상소를 N번 추가 조회한다. 그래서 1 + N = N+1 문제다.

문의가 10개면 11번, 100개면 101번, 1000개면 1001번. 데이터가 늘수록 쿼리가 선형으로 증가한다.

sequenceDiagram
    participant App as Spring 서버
    participant DB as MySQL

    Note over App,DB: 😱 N+1 발생 시

    App->>DB: SELECT * FROM inquiry LIMIT 10
    DB-->>App: 문의 10건

    loop 문의 1건마다
        App->>DB: SELECT * FROM photo_lab WHERE id = ?
        DB-->>App: 현상소 1건
    end

    Note over App,DB: 총 11번 쿼리 실행!

😎 fetchJoin으로 해결하면

[쿼리 1] SELECT i.*, pl.*
         FROM inquiry i
         LEFT JOIN photo_lab pl ON i.photo_lab_id = pl.id
         WHERE i.member_id = 1
         LIMIT 10

딱 1번. 끝.

sequenceDiagram
    participant App as Spring 서버
    participant DB as MySQL

    Note over App,DB: 😎 fetchJoin 적용 후

    App->>DB: SELECT i.*, pl.* FROM inquiry i LEFT JOIN photo_lab pl ...
    DB-->>App: 문의 10건 + 현상소 정보 한 번에!

    Note over App,DB: 총 1번 쿼리 실행!

왜 이렇게 되는 걸까?

JPA는 기본적으로 지연 로딩(Lazy Loading)을 쓴다.

@ManyToOne(fetch = FetchType.LAZY)  // ← 이게 기본
@JoinColumn(name = "photo_lab_id")
private PhotoLab photoLab;

LAZY는 inquiry.getPhotoLab().getName()처럼 실제로 접근하는 순간에 쿼리를 날린다. 문의 1건만 볼 때는 괜찮지만, 목록으로 10건을 루프 돌면 10번 추가 쿼리가 나간다.

LAZY 자체가 나쁜 게 아니다. 목록 조회에서 연관 엔티티에 접근할 때 문제가 된다.

3. 첫 번째 발견: fetchJoin + 페이징 = 💥

돌아가는 코드를 올렸더니, 코드 리뷰에서 이런 피드백이 왔다.

"fetchJoin이랑 offset/limit 같이 쓰면 Hibernate가 메모리에서 페이징해요. 데이터 많아지면 터집니다."

무슨 소리지? 싶었는데, 실제로 로그를 보니:

WARN  HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory

⚠️ Hibernate가 경고를 보내고 있었다.

왜 이런 일이?

fetchJoin은 SQL의 JOIN으로 바뀌는데, 컬렉션(replies 같은 @OneToMany)을 fetchJoin하면 한 문의에 답변이 3개일 때 결과 행이 3배로 뻥튀기된다.

문의1 - 답변A
문의1 - 답변B
문의1 - 답변C  ← 같은 문의인데 행이 3개!
문의2 - 답변D

이 상태에서 LIMIT 10을 걸면? 문의 10개가 아니라 행 10개를 자른다. 그래서 Hibernate는 전체 데이터를 메모리에 올린 다음 애플리케이션에서 페이징한다.

flowchart LR
    A["fetchJoin + 페이징"] --> B{"컬렉션 JOIN?"}
    B -->|YES| C["❌ Hibernate가\n전체 데이터 메모리 로드\n→ OOM 위험"]
    B -->|NO| D["✅ 정상 작동\n(단건 연관관계는 OK)"]

    style C fill:#fee,stroke:#c33
    style D fill:#efe,stroke:#3a3

해결: 2단계 쿼리 패턴

코드 리뷰 피드백을 반영해서 ID를 먼저 뽑고, 그 ID로 데이터를 가져오는 2단계 구조로 바꿨다.

// ✅ 개선된 버전 — 2단계 쿼리
public List<Inquiry> findByMemberId(Long memberId, int page, int size) {

    // 1단계: ID만 페이징해서 가져온다 (가볍다)
    List<Long> ids = queryFactory
            .select(inquiry.id)
            .from(inquiry)
            .where(inquiry.member.id.eq(memberId))
            .orderBy(inquiry.createdAt.desc())
            .offset((long) page * size)
            .limit(size)
            .fetch();

    if (ids.isEmpty()) {
        return Collections.emptyList();
    }

    // 2단계: ID 목록으로 fetchJoin (페이징 없이!)
    return queryFactory
            .selectFrom(inquiry)
            .leftJoin(inquiry.photoLab).fetchJoin()
            .leftJoin(inquiry.replies, inquiryReply).fetchJoin()
            .where(inquiry.id.in(ids))
            .orderBy(inquiry.createdAt.desc())
            .fetch();
}

왜 이게 되는 걸까?

• 1단계에서 LIMIT으로 정확히 10개의 문의 ID를 가져온다

• 2단계에서는 WHERE id IN (1, 2, 3, ...) 으로 딱 그 문의들만 fetchJoin한다

• 페이징은 1단계에서 끝났으니, 2단계에서 Hibernate 경고 안 뜬다 ✅

(커밋 82b42c7)

4. 두 번째 발견: "그 데이터, 진짜 필요해?"

2단계 쿼리로 바꾸고 나서 다시 코드를 봤다.

// 2단계에서 replies를 fetchJoin하고 있었다
.leftJoin(inquiry.replies, inquiryReply).fetchJoin()

문의 목록 화면에서 답변 전체 내용이 필요할까?

사실 목록에서는 "답변이 있는지 없는지"만 보여주면 됐다.

그런데 기존 코드는 이렇게 하고 있었다:

// ❌ Before: replies를 전부 로드해서 비었는지 체크
.hasReply(!inquiry.getReplies().isEmpty())
.latestReply(latestReply != null ? ReplyPreviewDTO.from(latestReply) : null)

getReplies()를 호출하는 순간, JPA는 replies 전체를 DB에서 가져온다. 문의 1건에 답변이 20개면? 20건의 데이터가 메모리에 올라간다. 목록에서 문의 10개를 보여줄 때, 답변 200개가 같이 딸려온다.

해결: status로 판단하기

문의 엔티티에는 이미 status 필드가 있었다.

public enum InquiryStatus {
    PENDING,    // 답변 대기
    ANSWERED,   // 답변 완료
    CLOSED      // 종료
}

답변이 등록되면 ANSWERED로 바뀌니까, replies를 안 가져와도 답변 여부를 알 수 있다!

// ✅ After: status만으로 판단, replies 전혀 안 건드림
.hasReply(inquiry.getStatus() != InquiryStatus.PENDING)

QueryDSL 쿼리에서도 replies fetchJoin을 통째로 삭제했다:

// ✅ After: replies JOIN 자체를 제거
return queryFactory
        .selectFrom(inquiry)
        .leftJoin(inquiry.photoLab).fetchJoin()  // 현상소 이름은 필요하니까 유지
        // .leftJoin(inquiry.replies, inquiryReply).fetchJoin()  ← 삭제!
        .where(inquiry.id.in(ids))
        .orderBy(inquiry.createdAt.desc())
        .fetch();

DTO에서도 latestReply 필드를 아예 제거했다:

// ❌ Before
public record InquiryItemDTO(
    Long id, String title, InquiryStatus status,
    String photoLabName, LocalDateTime createdAt,
    boolean hasReply,
    ReplyPreviewDTO latestReply  // ← 이것 때문에 replies 전체를 로드
) { }

// ✅ After
public record InquiryItemDTO(
    Long id, String title, String content, InquiryStatus status,
    String photoLabName, LocalDateTime createdAt,
    boolean hasReply              // ← status로 판단, latestReply 삭제
) { }

불필요한 데이터를 안 가져오는 것이 최고의 최적화다.

(커밋 a996e61)

5. 세 번째 발견: 상세 조회도 N+1이었다

문의 상세 조회에서는 답변 내용, 작성자 이름, 현상소 정보가 전부 필요하다.

처음에 이렇게 짰다:

// ❌ Before: member를 안 가져옴
@Query("SELECT i FROM Inquiry i " +
       "LEFT JOIN FETCH i.photoLab " +
       "LEFT JOIN FETCH i.replies r " +
       "LEFT JOIN FETCH r.replier " +
       "WHERE i.id = :id")
Optional<Inquiry> findByIdWithDetails(@Param("id") Long id);

근데 DTO 변환할 때 inquiry.getMember().getName()을 호출하고 있었다. member를 fetchJoin하지 않았으니, 여기서 추가 쿼리 1개가 나간다.

[쿼리 1] SELECT i.*, pl.*, r.*, rp.*     ← 문의 + 현상소 + 답변 + 답변자
         FROM inquiry i
         LEFT JOIN photo_lab pl ...
         LEFT JOIN inquiry_reply r ...
         LEFT JOIN member rp ...
         WHERE i.id = 1

[쿼리 2] SELECT * FROM member WHERE id = 5  ← 😱 문의 작성자 (N+1!)

해결: member도 fetchJoin에 추가

// ✅ After: member 추가
@Query("SELECT i FROM Inquiry i " +
       "LEFT JOIN FETCH i.member " +       // ← 추가!
       "LEFT JOIN FETCH i.photoLab " +
       "LEFT JOIN FETCH i.replies r " +
       "LEFT JOIN FETCH r.replier " +
       "WHERE i.id = :id")
Optional<Inquiry> findByIdWithDetails(@Param("id") Long id);

이제 상세 조회도 딱 1번 쿼리로 전부 가져온다. ✅

(커밋 25c991b)

6. 방어선 만들기 — 놓쳐도 터지지 않게

모든 쿼리를 완벽하게 최적화할 수는 없다. 그래서 안전망을 깔아뒀다.

default_batch_fetch_size

# application.yml
spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 100

이 설정 하나면, fetchJoin을 깜빡 잊어도 N+1이 N/100+1로 줄어든다.

예를 들어 문의 100개를 조회하는데 현상소를 fetchJoin하지 않았다면:

• 설정 없이: 100번 추가 쿼리 (N+1)

• batch_size: 100: 1번 추가 쿼리 (WHERE id IN (1,2,3,...100))

@BatchSize — 특정 컬렉션만 배치 로딩

@OneToMany(mappedBy = "inquiry", cascade = CascadeType.ALL, orphanRemoval = true)
@OrderBy("displayOrder ASC")
@BatchSize(size = 10)  // ← 이미지는 한 번에 10개씩 배치 로딩
private List<InquiryImage> images = new ArrayList<>();

목록 vs 상세: DTO 분리

flowchart TB
    subgraph 목록 조회
        A["InquiryItemDTO"] --> B["id, title, status\nphotoLabName, hasReply"]
        A --> C["❌ replies 안 가져옴\n❌ images 안 가져옴\n❌ member 안 가져옴"]
    end

    subgraph 상세 조회
        D["InquiryDetailDTO"] --> E["id, title, content, status\nphotoLab, member\nimages, replies"]
        D --> F["✅ fetchJoin 한 방 쿼리\n✅ 모든 연관 데이터 포함"]
    end

    style C fill:#fee,stroke:#c33
    style F fill:#efe,stroke:#3a3

같은 엔티티라도 화면마다 필요한 데이터가 다르다. 목록에서는 가볍게, 상세에서는 한 방에.

7. Before vs After

문의 목록 10건 조회 시

문의 상세 1건 조회 시

안전망

8. 정리 — 우리가 배운 것들

timeline
    title Inquiry 쿼리 최적화 타임라인
    1월 16일 : 1:1 문의 API 첫 구현
            : fetchJoin + 페이징 조합
    1월 17일 : 코드 리뷰에서 문제 발견
            : 2단계 쿼리 패턴 도입
    1월 17일 : 목록 조회 replies 제거
            : status 기반 hasReply 판단
    1월 17일 : 상세 조회 member N+1 수정
            : 보안 어노테이션 추가
    1월 28일 : 중복 로직 헬퍼 메서드 추출
            : 코드 정리 완료

4가지 교훈:

1. fetchJoin + 페이징 = 위험

컬렉션(@OneToMany)을 fetchJoin하면서 페이징하면 메모리 페이징이 발생한다. 2단계 쿼리(ID 먼저 → fetchJoin 나중)로 해결.

2. 안 가져오는 게 최고의 최적화

목록에서 replies를 fetchJoin하던 걸 통째로 삭제했다. 이미 있는 status 필드로 대체.

3. N+1은 한 곳만 있지 않다

목록 조회를 고쳤더니, 상세 조회에서 또 N+1이 있었다. 모든 조회 경로를 의심해야 한다.

4. 안전망을 깔아두자

default_batch_fetch_size와 @BatchSize는 fetchJoin을 깜빡해도 N+1을 N/100+1로 줄여준다. 보험이다.

참고

• Finders 1:1 문의 API 구현 — Issue #137

• fetchJoin + 페이징 수정 — 커밋 82b42c7

• replies 로딩 최적화 — 커밋 a996e61

• 상세 조회 N+1 수정 — 커밋 25c991b

• Hibernate ORM User Guide — Fetching

• Spring Data JPA Reference — Query Methods

"서버 죽었는데 아무도 몰랐다"에서 "에러나면 1분 안에 안다"까지

1. 모니터링을 시작한 계기

프론트엔드: "API 안 되는데요?"
백엔드: "엥? 언제부터요?"
프론트엔드: "...2시간 전부터요?"
백엔드: 😱

어느 날 서버가 죽어있었는데 아무도 몰랐다. 그날 이후, 모니터링 시스템 구축을 결심했다. (Issue #102)

2. 모니터링 도구 비교: 뭘 쓸까?

처음에는 여러 도구를 비교했다.

우리의 선택

앱 에러 추적    → Sentry (무료 Developer 플랜)
인프라 지표     → GCP Cloud Monitoring (무료)
실시간 알림     → Discord Webhook (직접 구현, 무료)
로그 중앙화     → GCP Cloud Logging (Docker gcplogs 드라이버)

핵심 전략: "무료로 최대한 커버하고, 부족한 건 직접 만들자"

3. Sentry 도입하기

왜 Sentry인가?

Spring Boot에서 에러 모니터링을 시작하기 가장 쉬운 도구였다.

의존성 하나 추가:

// build.gradle
implementation 'io.sentry:sentry-spring-boot-starter-jakarta:8.28.0'

설정 추가:

# application.yml
sentry:
  dsn: ${SENTRY_DSN}              # Sentry 프로젝트 DSN
  environment: ${SPRING_PROFILES_ACTIVE:local}
  traces-sample-rate: 1.0          # 성능 추적 비율
  send-default-pii: false          # 개인정보 전송 안 함
  in-app-includes: com.finders     # 우리 코드만 하이라이트
  logging:
    minimum-event-level: warn      # WARN 이상만 Sentry로
    minimum-breadcrumb-level: info # Breadcrumb은 INFO부터

이것만으로 서버에서 발생하는 모든 Exception이 자동으로 Sentry에 기록된다.

Sentry 대시보드에서 에러 목록과 발생 빈도를 한눈에 볼 수 있다

환경별 샘플링 차이

무료 플랜은 월 5,000 에러까지라서, prod에서 100% 캡처하면 한도를 금방 넘긴다.

Sentry 초기 삽질: @ExceptionHandler와의 충돌

처음에 Sentry를 붙이고 나서, 에러가 캡처가 안 되는 문제가 있었다.

원인: Spring의 @ExceptionHandler가 에러를 처리해버리면, Sentry 입장에서는 "에러가 아닌 정상 응답"으로 보이는 것이었다!

# 해결: exception-resolver-order를 최우선으로 설정
sentry:
  exception-resolver-order: -2147483648  # HIGHEST_PRECEDENCE
  # → @ExceptionHandler보다 먼저 예외를 캡처!

이 설정 하나로 해결되었지만, 찾는 데 한참 걸렸다... (Issue #177)

4. Sentry Discord 알림 — 왜 포기했나

Sentry에서 에러가 기록되는 건 좋은데, 대시보드를 열어봐야 알 수 있다는 게 문제였다.

"에러 났을 때 바로 알림 받고 싶은데..."

Sentry의 알림 옵션

Discord 연동을 하려면 Team 플랜($26/월)이 필요했다! 대학생 팀에게 매달 $26은... 🥲

그래서 결론:

• Sentry는 Email 알림만 사용 (무료)

• Discord 알림은 직접 구현하기로!

5. Discord Webhook 직접 만들기

Discord 설정: 이게 제일 헷갈렸다

Discord에서 Webhook URL을 만드는 과정이 의외로 복잡했다.

💡 Discord 웹후크 설정 경로: 서버 설정(⚙️) → 앱 → 연동 → 웹후크 → "새 웹후크" → URL 복사

자주 헷갈리는 것들 정리:

주의! "채널 ID"와 "Webhook URL"은 완전히 다른 것이다.
Sentry 같은 서비스는 채널 ID를 요구하고, 직접 구현할 때는 Webhook URL을 쓴다.

Webhook URL 만드는 법

1. Discord 서버 설정 (⚙️) 클릭
2. 앱 > 연동 > 웹후크 클릭
3. "새 웹후크" 클릭
4. 이름 설정 (예: "Finders 에러 알림")
5. 채널 선택 (에러 알림을 받을 채널)
6. "웹후크 URL 복사" 클릭

⚠️ 개발자 모드가 필요할 수 있다! Discord 사용자 설정 → 고급 → 개발자 모드 켜기 이게 꺼져있으면 "ID 복사" 메뉴가 안 보인다. 찾기 어려워서 한참 헤맸다...

💡 개발자 모드 경로: Discord 사용자 설정(⚙️) → 앱 설정 → 고급 → 개발자 모드 토글 ON

6. 코드 구조: 어떻게 만들었나

전체 구조

src/main/java/com/finders/api/
├── infra/discord/
│   ├── DiscordProperties.java       # 설정 (webhook-url, enabled)
│   ├── DiscordWebhookService.java   # 알림 전송 로직
│   └── dto/
│       └── DiscordMessage.java      # Discord Embed 메시지 포맷
└── global/exception/
    └── GlobalExceptionHandler.java  # 여기서 Discord 호출!

동작 흐름

graph TD
    A["🚨 서버 500 에러"] --> B["GlobalExceptionHandler"]
    B --> C["DiscordWebhookService"]
    C --> D["💬 Discord 채널 알림"]
    B --> E["📊 Sentry 자동 기록"]
    B --> F["👤 사용자에게 에러 응답"]

1. 사용자 요청 → 서버에서 에러 발생 (500)
2. GlobalExceptionHandler가 catch
3. DiscordWebhookService.sendErrorNotification() 호출
4. Discord 채널에 Embed 메시지 전송 🔔
5. (동시에) Sentry에도 자동 기록
6. (동시에) 사용자에게는 깔끔한 에러 응답 반환

핵심 코드 1: GlobalExceptionHandler

@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Void>> handleException(
        Exception e, HttpServletRequest request) {

    log.error("[UnhandledException] {} - {}", 
              request.getRequestURI(), e.getMessage(), e);

    try {
        // 💡 에러 발생 즉시 Discord로 알림!
        discordWebhookService.sendErrorNotification(
            e, request.getMethod(), request.getRequestURI()
        );
    } catch (Exception ignored) {
        // 알림 실패가 사용자 응답에 영향 주면 안 됨
    }

    return ResponseEntity.status(500)
        .body(ApiResponse.error(ErrorCode.INTERNAL_SERVER_ERROR));
}

핵심 설계:

• Discord 알림이 실패해도 사용자 응답에 영향 없음 (try-catch로 감쌈)

• 500 에러만 알림 (400대 에러는 클라이언트 실수이니 알림 불필요)

핵심 코드 2: 중복 알림 방지

같은 에러가 1초에 100번 나면 Discord도 100번 울릴까? 아니다!

private static final long DEDUPE_WINDOW_MS = 60_000; // 60초

private boolean isDuplicate(String errorKey) {
    long now = System.currentTimeMillis();
    Long lastSeen = recentErrors.putIfAbsent(errorKey, now);

    if (lastSeen != null && now - lastSeen < DEDUPE_WINDOW_MS) {
        return true;  // 60초 내 같은 에러 → 스킵!
    }
    return false;
}

• 60초 내 같은 에러 (같은 Exception + 같은 URL)는 한 번만 알림

• Discord Webhook Rate Limit(30요청/분)도 넘기지 않음

핵심 코드 3: 민감정보 마스킹

스택트레이스에 비밀번호나 토큰이 포함될 수 있다. 자동으로 걸러낸다:

private String filterSensitiveInfo(String stackTrace) {
    return stackTrace
        .replaceAll("(?i)password[=:]\\s*\\S+", "password=***")
        .replaceAll("(?i)token[=:]\\s*\\S+", "token=***")
        .replaceAll("(?i)secret[=:]\\s*\\S+", "secret=***")
        .replaceAll("(?i)api[_-]?key[=:]\\s*\\S+", "api_key=***");
}

핵심 코드 4: Discord Embed 메시지

Discord에는 단순 텍스트보다 Embed 메시지가 훨씬 보기 좋다:

public record DiscordMessage(List<Embed> embeds) {
    public record Embed(
        String title,       // "Server Error"
        String description,
        int color,          // 0xE74C3C (빨간색)
        List<Field> fields, // Exception, Method, URL, Message, Stack Trace
        Instant timestamp
    ) {}
}

실제로 받는 알림은 이런 느낌이다:

🚨 Server Error
━━━━━━━━━━━━━━━━━━━
Exception    NullPointerException
Method       POST
URL          /api/v1/reservations
Message      Cannot invoke method on null
Stack Trace  (첫 5줄만)
━━━━━━━━━━━━━━━━━━━

환경별 설정

# application.yml (공통 - 기본 비활성화)
discord:
  webhook-url: ${DISCORD_WEBHOOK_URL:}
  enabled: false

# application-prod.yml (운영에서만 활성화)
discord:
  enabled: true
  webhook-url: ${DISCORD_WEBHOOK_URL}

local이나 dev에서 에러 날 때마다 디코에 알림이 오면 스팸이 되니까, prod에서만 활성화했다.

7. 기술 선택 이유: 왜 직접 만들었나?

Issue #211에서 여러 방안을 검토했다:

직접 구현 시 고려한 것들:

8. 최종 모니터링 구조

[Spring Boot 서버]
│
├── 에러 발생 시
│   ├── Sentry ──→ 대시보드에서 상세 분석 📊
│   │              (스택트레이스, 빈도, 환경 정보)
│   │              이메일 알림 (무료)
│   │
│   └── Discord Webhook ──→ 실시간 알림 🔔
│                            (에러 요약 Embed 메시지)
│
├── 인프라 지표
│   └── GCP Cloud Monitoring ──→ 대시보드 📈
│       (CPU, 메모리, 디스크, 네트워크, 에러 로그 수)
│       Terraform으로 대시보드 코드 관리
│
└── 로그
    └── Docker gcplogs ──→ GCP Cloud Logging 📝
        (컨테이너 로그 자동 수집, 라벨로 필터링)

9. 마치며

비용 정리

$26/월짜리 Sentry Team 플랜 대신, 직접 구현해서 동일한 효과를 무료로 얻었다.

배운 것들

1. Discord Webhook URL 만들기가 의외로 어렵다 — 개발자 모드, 채널 ID vs 서버 ID vs Webhook URL 구분이 처음엔 많이 헷갈린다

2. Sentry의 무료 플랜은 생각보다 쓸 만하다 — 에러 추적 자체는 무료로 충분. 알림 연동만 유료

3. 직접 만들면 우리 상황에 딱 맞출 수 있다 — 중복 제거, 민감정보 필터링, 환경별 분리 등 세밀한 제어 가능

4. 모니터링은 빨리 도입할수록 좋다 — "나중에 하자"가 아니라, 서버가 죽은 걸 모르는 것보다 빨리 하는 게 낫다

에러가 나면:

1. Discord로 즉시 알림 → 1분 내 인지

2. Sentry에서 상세 분석 → 원인 파악

3. GCP Cloud Logging에서 로그 추적 → 재현 & 디버깅

"서버 죽었는데 몰랐다"는 이제 옛날 얘기가 되었다. 😄

📎 참고 이슈

• #102 Sentry 모니터링 시스템 구축

• #177 Sentry가 @ExceptionHandler 예외를 캡처하도록 설정

• #211 Discord Webhook을 통한 서버 에러 알림 구현

• Sentry 공식 가격표

• Discord Webhook 가이드

🚀 우리 auto-release.yml 바로 보러가기 →

이 글에서 설명하는 워크플로우의 전체 코드를 바로 확인할 수 있다!

main에 머지만 하면 버전 태그부터 릴리즈 노트까지 알아서 생긴다

1. 우리의 Git 전략: Git Flow (경량 버전)

Finders 프로젝트는 Git Flow 전략을 사용하고 있다. 다만 hotfix나 release 브랜치 없이, 조금 가볍게 운영한다.

main        ← 운영 서버 (prod) 배포 브랜치
develop     ← 개발 서버 (dev) 배포 브랜치
feature/*   ← 기능 개발 브랜치 (이슈 기반)
fix/*       ← 버그 수정 브랜치

출처: A successful Git branching model — Vincent Driessen

흐름

1. 이슈 생성 → 브랜치 생성 (feat/signup-api-#14)

2. 개발 완료 → develop으로 PR → CI 통과 + 코드 리뷰 → 머지

3. develop 머지 → Dev 서버 자동 배포 (프론트와 연동 테스트)

4. 테스트 완료 → develop → main PR → 승인 → 머지

5. main 머지 → Prod 서버 자동 배포 + 릴리즈 자동 생성 ← 여기!

2. 처음에는 수동이었다

처음에는 릴리즈를 전부 수동으로 만들었다.

# 1. main으로 이동
git checkout main
git pull origin main

# 2. 태그 생성
git tag v0.7.0

# 3. 태그 푸시
git push origin v0.7.0

그러면 .github/release.yml 설정에 의해 GitHub Release가 생성되었다.

뭐가 문제였을까?

• 매번 수동으로 해야 함 → 까먹기 쉬움

• 버전 번호를 직접 정해야 함 → "이번에 뭐였지... v0.7? v0.8?"

• 릴리즈 노트를 직접 작성해야 함 → 귀찮아서 대충 쓰게 됨

• main 머지 후 태그 푸시를 깜빡하면 릴리즈가 안 생김

결국 issue #344를 만들었다:

"main 머지만 하면 태그 + 릴리즈가 자동 생성되도록 워크플로우를 개선합니다."

3. Auto Release 워크플로우 만들기

전체 흐름

graph TD
    A["main에 PR 머지"] --> B["auto-release.yml 실행"]
    B --> C{"PR 제목에 버전이 있나?"}
    C -->|"[RELEASE] v0.9.2 배포"| D["v0.9.2 사용"]
    C -->|"버전 없음"| E["PATCH 자동 증가<br/>v0.9.1 → v0.9.2"]
    D --> F["태그 생성 & 푸시"]
    E --> F
    F --> G["커밋 로그 기반<br/>릴리즈 노트 생성"]
    G --> H["GitHub Release 발행"]

핵심 코드

1단계: 버전 결정

# PR 제목에서 버전 추출 시도
if [[ "$COMMIT_MSG" =~ v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
  VERSION="v${BASH_REMATCH[1]}"
  # → PR 제목이 "[RELEASE] v0.9.2 배포" 이면 v0.9.2 사용
else
  # 버전 없으면 PATCH 자동 증가
  IFS='.' read -ra PARTS <<< "${LAST_TAG//v/}"
  PATCH=$((PARTS[2] + 1))
  VERSION="v${PARTS[0]}.${PARTS[1]}.${PATCH}"
  # → v0.9.1 이 마지막이면 v0.9.2 자동 생성
fi

2단계: 릴리즈 노트 자동 생성

커밋 메시지의 prefix(feat, fix, docs...)를 분석해서 자동 분류한다:

# feat 커밋만 모아서 Features 섹션
FEATS=$(git log "${LAST_TAG}..HEAD" --pretty=format:"- %s (%h)" --grep="^feat")

# fix 커밋만 모아서 Bug Fixes 섹션
FIXES=$(git log "${LAST_TAG}..HEAD" --pretty=format:"- %s (%h)" --grep="^fix")

# docs, refactor, test도 각각 분류

3단계: GitHub Release 생성

gh release create "$VERSION" \
  --title "Release ${VERSION}" \
  --notes-file RELEASE_NOTES.md \
  --latest

4. 실제 릴리즈는 이렇게 생긴다

📎 실제 릴리즈 목록: Finders BE Releases →

예를 들어 Release v0.9.5의 릴리즈 노트는 이렇게 자동 생성되었다:

# Release v0.9.5

## Changes since v0.9.4

### ✨ Features
- feat: 전용 terraform-ci SA 추가 및 Compute SA 역할 분리 (#396)
- feat: 공지 api 수정

### 🐛 Bug Fixes
- fix: swagger 문서 수정
- fix: 위치 미 동의시 현상소 조회의 경우 distanceKm가 반환되지 않게 수정
- fix: 배포 스크립트 서버 경로 통일 (#391)

### 📚 Documentation
- docs: 아키텍처 문서 업데이트 (#385)

### ♻️ Refactoring
- refactor: outputs.tf를 단일 jsonencode deploy_config로 통합 (#393)

사람이 한 일: PR 머지 버튼 클릭. 끝.

5. 두 가지 배포 시나리오

시나리오 A: 일반 배포 (PATCH 자동 증가)

develop → main PR
제목: "[FIX] 이미지 업로드 버그 수정 (#123)"

→ 마지막 태그 v0.9.4에서 자동으로 v0.9.5 생성

시나리오 B: 메이저/마이너 릴리즈 (버전 명시)

develop → main PR
제목: "[RELEASE] v1.0.0 배포"

→ PR 제목에서 v1.0.0 추출해서 그 버전으로 태그 생성

포인트: 특별한 릴리즈(메이저, 마이너 버전 업)일 때만 PR 제목에 버전을 적으면 되고, 일반적인 패치는 알아서 버전이 올라간다!

6. 버전 관리 규칙 (Semantic Versioning)

v MAJOR . MINOR . PATCH
  ↓       ↓       ↓
  1   .   2   .   3

현재 Finders는 아직 v0.x.x 대로, 빠르게 기능을 추가하는 단계다. v1.0.0은 정식 서비스 출시 시점에 찍을 예정!

7. Before vs After

graph LR
    subgraph Before["❌ Before — 수동"]
        B1["main 머지"] --> B2["git tag 직접"] --> B3["git push 태그"] --> B4["릴리즈 수동 작성"]
    end
    subgraph After["✅ After — 자동"]
        A1["main 머지"] --> A2["전부 자동! 🎉"]
    end

8. 마치며

릴리즈 자동화는 "편해지자"가 아니라 "실수를 없애자"에 가깝다.

수동으로 하면:

• 까먹는다 (태그 안 찍는 건 일상)

• 대충 한다 (릴리즈 노트 "잡다한 수정" 한 줄)

• 틀린다 (중복 태그, 잘못된 버전)

자동으로 하면:

• 머지만 하면 끝 → 깜빡할 수가 없음

• 커밋 메시지가 곧 릴리즈 노트 → feat/fix 잘 쓰는 습관이 중요해짐

• 중복 체크 내장 → 같은 태그 두 번 생성 불가

결국 좋은 커밋 메시지 컨벤션 + Auto Release = 자동으로 정리되는 프로젝트 히스토리라는 걸 깨달았다. 커밋 메시지를 대충 쓰면 릴리즈 노트도 대충 나오니까, 팀원들의 커밋 습관도 자연스럽게 좋아졌다. 👍

📎 참고

• 🚀 auto-release.yml 전체 코드 보기

• Issue #344: main 머지 시 GitHub Release 자동 생성 워크플로우 추가

• Semantic Versioning 공식 사이트

• GitHub Actions - gh release create 문서

PR 하나면 끝나는 무중단 배포까지, 삽질의 기록

1. 시작은 단순했다

"서버에 올려야 하는데... 어떻게 하지?"

Finders 프로젝트를 시작했을 때, 배포라는 걸 해본 적이 없었다. 그래서 처음에는 이렇게 했다.

1. SSH로 서버 접속
2. git pull
3. ./gradlew build
4. java -jar app.jar

당연히 문제가 생겼다.

• 빌드하는 동안 서버가 꺼져있음 (프론트: "API 왜 안 돼요?" 🔥)

• 빌드가 실패하면 이전 버전도 날아감

• 누가 마지막에 배포했는지 아무도 모름

그래서 GitHub Actions로 자동화를 시작했다. (Issue #3)

2. 1단계: CI + CD 기본기 만들기

CI — "최소한 빌드는 되는 코드만 머지하자"

가장 먼저 만든 건 CI(Continuous Integration) 워크플로우였다.

# .github/workflows/ci.yml
name: Finders CI (Build & Test)

on:
  pull_request:
    branches: [ "develop", "main" ]

steps:
  - name: Checkout Code
    uses: actions/checkout@v4

  - name: Set up JDK 21
    uses: actions/setup-java@v4
    with:
      java-version: '21'

  - name: Cache Gradle packages  # ⭐ 빌드 속도 최적화
    uses: actions/cache@v4
    with:
      path: |
        ~/.gradle/caches
        ~/.gradle/wrapper
      key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}

  - name: Test & Build
    run: ./gradlew clean build

핵심 포인트:

• PR을 올리면 자동으로 빌드 + 테스트 실행

• 실패하면 머지 불가 (Branch Protection Rule)

• Gradle 캐시로 의존성 다운로드 시간 절약 (체감 40~50% 단축)

GitHub Actions가 PR마다 자동으로 빌드/테스트를 실행한다

CD — "머지하면 알아서 배포되게"

CI가 돌아가니, 이제 배포도 자동화하고 싶었다. 처음에는 deploy.yml 하나와 docker-compose.prod.yml 하나만 있었다.

main에 push → Docker 이미지 빌드 → GCE 서버에 배포

이때의 구조는 아주 단순했다:

.github/workflows/
├── ci.yml          ← PR 빌드/테스트
└── deploy.yml      ← main push 시 배포

docker-compose.prod.yml  ← 서버에서 Docker로 실행
Dockerfile               ← 멀티스테이지 빌드

graph LR
    A["🧑‍💻 코드 Push"] --> B["⚙️ GitHub Actions"]
    B --> C["🐳 Docker 이미지 빌드"]
    C --> D["🚀 서버 배포"]

Docker 멀티스테이지 빌드

Dockerfile도 2단계로 나눠서 최적화했다:

# Stage 1: 빌드 (JDK 포함 — 무거움)
FROM eclipse-temurin:21-jdk AS builder
COPY . .
RUN ./gradlew build -x test --no-daemon

# Stage 2: 실행 (JRE만 — 가벼움)
FROM eclipse-temurin:21-jre
COPY --from=builder /app/build/libs/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

왜 이렇게 할까?

• 빌드에 필요한 JDK, Gradle, 소스코드는 런타임에 필요 없음

• 최종 이미지 크기가 확 줄어듦 → 배포 속도 향상

3. 2단계: "prod랑 dev를 분리해야겠다"

처음엔 main 브랜치 하나에 prod 환경만 있었다. 그런데 프론트엔드 팀과 API 연동을 시작하면서 문제가 터졌다.

프론트엔드: "이 API 아직도 안 돼요...?"
백엔드: "아직요... main에 머지가 안 됐어서..."
프론트엔드: "그게 언제 될까요?"
백엔드: "승인 받아야 하는데..." 😰

main 브랜치에 머지하려면 팀원 최소 1명의 approve가 필요했다. 코드 리뷰는 꼭 필요한 과정이지만, API 연동 초기에는 매번 작은 수정마다 main PR → 승인 대기 → 머지 → 배포 사이클을 돌려야 했고, 프론트엔드 팀은 계속 기다려야 했다.

이게 반복되면서 결국 깨달았다: 개발용 서버가 따로 있어야 한다.

• develop 브랜치에 머지하면 → dev 서버에 바로 배포 (연동 테스트용)

• main 브랜치에 머지하면 → prod 서버에 배포 (코드 리뷰 후)

이렇게 하면 프론트엔드 팀은 dev 서버에서 자유롭게 연동 테스트를 하고, prod에는 검증된 코드만 올라가게 된다.

application.yml 분리

src/main/resources/
├── application.yml        ← 공통 설정
├── application-local.yml  ← 로컬 개발 (Docker MySQL)
├── application-dev.yml    ← 개발 서버 (GCE)
└── application-prod.yml   ← 운영 서버 (GCE)

환경별로 뭐가 다를까?

Docker Compose & CD 워크플로우 분리

.github/workflows/
├── ci.yml
├── deploy.yml      ← main → prod 배포
└── deploy-dev.yml  ← develop → dev 배포  🆕

docker-compose.infra.yml  ← 공통 인프라 (Traefik, Cloudflared)
docker-compose.prod.yml   ← prod 앱 설정
docker-compose.dev.yml    ← dev 앱 설정  🆕

이제 develop 브랜치에 머지하면 dev 서버, main 브랜치에 머지하면 prod 서버에 자동 배포된다!

graph TB
    F["feature/*"] -->|"PR + 코드리뷰"| D["develop"]
    D -->|"자동 배포"| DEV["🖥️ Dev 서버"]
    D -->|"PR + approve"| M["main"]
    M -->|"자동 배포"| PROD["🖥️ Prod 서버"]

4. 3단계: "배포할 때 서버가 죽어요" → 무중단 배포

환경 분리까지는 좋았다. 그런데 배포할 때마다 서버가 죽는 문제가 있었다.

배포 과정이 이랬다:

1. docker compose down  ← 여기서 서버 사망 💀
2. 새 이미지 Pull
3. docker compose up
4. Spring Boot 기동 대기...

docker compose down을 하는 순간부터 서버가 내려간다. 새 컨테이너가 뜨고 Spring Boot가 완전히 기동될 때까지 짧으면 3분, 길면 5분. 그 사이에 들어오는 모든 요청은 503 에러.

팀원들이 API를 테스트하다가 갑자기 503이 뜨기 시작하면...

"서버 왜 안 돼요?"
"아 배포 중이에요... 5분만 기다려주세요..."
"..." 😐

특히 데모 준비할 때 배포하면 대참사였다. 🤦

Nginx vs Traefik, 뭘 쓸까?

무중단 배포를 위해 리버스 프록시가 필요했다. 두 가지를 비교했다:

Traefik을 선택한 이유: Docker Compose의 labels만으로 라우팅이 설정되니까, Blue-Green 배포가 훨씬 간단했다!

Blue-Green 배포란?

출처: BlueGreenDeployment — Martin Fowler

서버를 2개 슬롯(Blue, Green)으로 운영하는 방식이다:

[사용자] → [Traefik] → [🔵 Blue 슬롯] ← 현재 트래픽 처리 중
                        [🟢 Green 슬롯] ← 대기 중 (비어있음)

배포할 때:

1. Green에 새 버전 올리기 (같은 Traefik 라벨 등록)

2. Green 헬스체크 통과 확인

3. Traefik이 새로 뜬 Green 컨테이너를 자동 감지해서 라우팅

4. Blue 컨테이너 제거 → Green만 남음

핵심: 항상 1대만 트래픽을 받되, 전환 사이에 다운타임이 0!

참고: 로드밸런서처럼 2대가 동시에 트래픽을 나누는 게 아니다. Traefik은 리버스 프록시로, Docker 컨테이너가 뜨고 내려가는 것을 감지해서 라우팅 대상을 자동 전환해주는 역할이다.

Docker Compose로 구현한 Blue-Green

# docker-compose.prod.yml (핵심만)
services:
  prod-blue:
    image: ${DOCKER_IMAGE}:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.prod.rule=Host(`api.finders.it.kr`)"
    profiles: [blue]  # ← 프로필로 선택적 실행

  prod-green:
    image: ${DOCKER_IMAGE}:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.prod.rule=Host(`api.finders.it.kr`)"
    profiles: [green]  # ← 프로필로 선택적 실행

Traefik의 핵심: Docker 컨테이너에 같은 라우팅 라벨(Host)이 붙어있으면, Traefik이 자동으로 감지한다. Green이 올라오면 Traefik이 Green을 인식하고, Blue를 내리면 자연스럽게 Green만 남아서 라우팅된다. 별도의 설정 변경이나 reload 없이!

Health Check: "진짜 살아있어?"

Green 컨테이너가 올라왔다고 바로 Blue를 내리면 안 된다. Spring Boot가 완전히 기동될 때까지 기다려야 한다.

# docker-compose.prod.yml
healthcheck:
  test: ["CMD", "wget", "--spider", "-q",
         "http://localhost:8080/api/actuator/health"]
  interval: 20s
  timeout: 5s
  retries: 5
  start_period: 60s  # 기동 대기 시간

배포 스크립트에서 최대 180초 동안 체크하고, 실패하면 자동 롤백:

for i in {1..36}; do
  STATUS=$(docker inspect --format='{{.State.Health.Status}}' $GREEN)

  if [[ "$STATUS" == 'healthy' ]]; then
    echo "✅ 정상! 기존 슬롯 제거"
    break
  fi

  if [[ "$STATUS" == 'unhealthy' ]]; then
    echo "❌ 비정상! 롤백"
    docker stop $GREEN && docker rm -f $GREEN
    exit 1  # GitHub Actions 실패 → 팀에게 알림
  fi

  sleep 5
done

5. 보너스: GCP 인증은 비밀번호 없이

GitHub Actions에서 GCP에 접근하려면 인증이 필요하다. 보통은 서비스 계정 키(JSON 파일)를 쓰는데, 이건 유출 위험이 있다.

우리는 Workload Identity Federation(WIF)을 사용했다:

# 키 파일 없이 인증!
- uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
    service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

graph LR
    GH["GitHub Actions"] -->|"OIDC 토큰 발급"| STS["GCP STS"]
    STS -->|"임시 토큰 교환"| SA["Service Account"]
    SA -->|"GCP 리소스 접근"| GCE["GCE / Artifact Registry"]

키 파일 없이 GitHub → GCP 인증이 가능한 원리 (GCP 공식 문서)

원리 (한 줄 요약):

GitHub Actions가 "나 이 리포에서 온 워크플로우야"라고 증명하면, GCP가 임시 권한을 줌. 키 파일 불필요!

6. 최종 모습: 전체 파이프라인

graph LR
    A["🧑‍💻 코드 작성"] --> B["📋 PR 생성"]
    B --> C["✅ CI: 빌드+테스트"]
    C --> D{"코드 리뷰 & 승인"}
    D -->|develop merge| E["🚀 Dev Blue-Green 배포"]
    D -->|main merge| F["🚀 Prod Blue-Green 배포"]
    F --> G["🏷️ 자동 릴리즈"]

7. 마치며: 삽질의 연대기

graph LR
    S0["🔧 수동 배포"] --> S1["⚡ CI + CD"]
    S1 --> S2["🔀 환경 분리"]
    S2 --> S3["🔄 Blue-Green"]

돌아보면 이런 순서로 진화했다:

매번 "이 정도면 됐지" 싶었는데, 실제로 운영하다 보면 다음 문제가 찾아왔다. 결국 CI/CD는 한 번에 완성되는 게 아니라, 필요에 따라 점진적으로 발전시키는 거라는 걸 배웠다.

지금은 개발자가 PR만 올리면 나머지는 전부 자동이다. "서버 배포해주세요"라는 말이 사라졌다. 😄

📎 참고 이슈

• #3 CI/CD 파이프라인 구축

• #101 CI/CD 무중단 배포 구현

• #194 Cloudflare Tunnel 도입 및 WIF 기반 CI/CD 고도화

ReservationSlot 단위 비관적 락을 통한 정원 초과 및 중복 생성 방지

1. 예약 시스템에서 실제로 어떤 동시성 문제가 발생했는가?

이 예약 시스템은 다음 조건을 가진다.

• 같은 사진관

• 같은 날짜

• 같은 시간대

에 대해 여러 사용자가 동시에 예약 요청을 보낼 수 있다.

이때 락이 없다면 다음 문제가 발생할 수 있다.

1️⃣ 정원 초과 문제

정원 5명
A 요청: 현재 예약 4명 → OK
B 요청: 현재 예약 4명 → OK
→ 결과: 예약 6명 (초과)

2️⃣ 슬롯 중복 생성 문제

슬롯이 아직 생성되지 않은 상태에서:

A 요청: 슬롯 없음 → 생성
B 요청: 슬롯 없음 → 생성
→ 동일한 (photoLab, date, time) 슬롯 2개 생성 시도

3️⃣ 취소 시 카운트 불일치

동시에 취소 요청이 들어오면:

• reservedCount가 중복 감소

• 음수로 떨어질 가능성

👉 결론
이 시스템의 동시성 문제는

“같은 시간 슬롯을 기준으로 한 경쟁 조건”
에서 발생한다.

2. 왜 이 문제는 애플리케이션 락이나 낙관적 락으로 해결하기 어려웠는가?

❌ 애플리케이션 락의 한계

• 서버가 여러 대면 보장되지 않음

• 트랜잭션과 결합이 어려움

❌ 낙관적 락의 한계

• 충돌 시 예외 발생

• 사용자에게 재시도 요구

• 예약 도메인 특성상 UX가 나빠짐

예약은:

• 정확성 > 성능

• “다시 시도하세요”가 허용되기 어려움

  → 그래서 비관적 락을 선택했다.

3. 해결 전략: ReservationSlot 단위 비관적 락

이 시스템에서 핵심 리소스는 ReservationSlot이다.

같은 슬롯에 대한 요청은
항상 직렬로 처리되어야 한다

그래서 전략은 다음과 같다.

• 슬롯 row를 SELECT … FOR UPDATE로 잠근다

• 락을 잡은 상태에서만 정원 증가/감소를 수행한다

• 슬롯이 없을 경우에도 중복 생성이 발생하지 않도록 처리한다

4. 예약 생성 시 동시성 해결 흐름

4-1. 슬롯 조회 + 락 획득

reservationSlotRepository
    .findByPhotoLabIdAndReservationDateAndReservationTimeForUpdate(
        photoLab.getId(), date, time
    )

이 쿼리는 내부적으로 다음과 같다.

SELECT *
FROM reservation_slot
WHERE photo_lab_id = ?
  AND reservation_date = ?
  AND reservation_time = ?
FOR UPDATE;

👉 이 순간, 같은 슬롯에 대한 다른 트랜잭션은 대기 상태가 된다.

4-2. 슬롯이 없는 경우: 중복 생성 방지

동시 요청이 들어오면 슬롯 생성도 경쟁 상태가 된다.
이를 위해 DB에 다음 전제를 둔다.

• (photo_lab_id, reservation_date, reservation_time) 유니크 제약

그리고 코드에서는:

try {
    reservationSlotRepository.save(slot);
} catch (DataIntegrityViolationException ignored) {
    // 다른 트랜잭션이 먼저 생성한 경우
}

이후 반드시 다시 FOR UPDATE로 조회한다.

return reservationSlotRepository
    .findByPhotoLabIdAndReservationDateAndReservationTimeForUpdate(...)

👉 결과적으로:

• 슬롯은 하나만 생성되고

• 모든 요청은 동일 슬롯 row에 대해 직렬화된다

4-3. 정원 초과 방지

slot.increaseReservedCountOrThrow();

이 로직은:

• 슬롯 row가 락 잡힌 상태에서 실행됨

• 동시에 두 요청이 “자리 있음”이라고 판단할 수 없음

따라서 정원 초과는 구조적으로 발생하지 않는다.

5. 예약 취소 시 동시성 해결 흐름

취소도 동일한 문제가 발생할 수 있기 때문에 락을 사용한다.

5-1. 예약 자체를 잠금

reservationRepository
    .findByIdAndPhotoLabIdAndUserIdForUpdate(...)

• 중복 취소 방지

• 상태 변경 경쟁 방지

5-2. 슬롯 잠금 후 카운트 감소

ReservationSlot lockedSlot =
    reservationSlotRepository.findByIdForUpdate(slotId);

lockedSlot.decreaseReservedCountSafely();

👉 취소 역시 슬롯 기준으로 직렬 처리된다.

6. 이 구조가 안전한 이유 요약

• 슬롯 단위로 경쟁 범위를 최소화

• DB 트랜잭션 + 비관적 락으로 서버 수와 무관하게 일관성 보장

• 재시도 로직 없이도 정합성 유지

• 예약/취소 흐름 모두 동일한 락 기준 사용

7. 정리

이 예약 시스템의 동시성 문제는
“같은 시간 슬롯을 동시에 수정하는 경쟁 조건”에서 발생했다.

이를 해결하기 위해:

• ReservationSlot을 동시성의 기준 단위로 삼고

• 비관적 락을 통해 요청을 직렬화했다

그 결과:

• 정원 초과

• 슬롯 중복 생성

• 취소 시 카운트 불일치

를 모두 구조적으로 방지할 수 있었다.

한 줄 결론

이 예약 시스템에서는 성능보다 정합성이 중요했기 때문에, 슬롯 단위 비관적 락을 선택해 동시성 문제를 해결했다.

단위 테스트란?

단위 테스트(Unit Test)는
하나의 모듈을 기준으로 독립적으로 수행되는 가장 작은 단위의 테스트이다.

여기서 말하는 모듈이란,
애플리케이션에서 동작하는 하나의 기능 또는 하나의 메서드를 의미한다.

단위 테스트의 어려움

일반적인 애플리케이션에서는
하나의 기능을 처리하기 위해 여러 객체와 메시지를 주고받는다.

하지만 단위 테스트는 특정 모듈을 독립적으로 검증하는 것이 목적이기 때문에,
다른 객체와의 협력이 포함되면 테스트가 어려워진다.

이 문제를 해결하기 위해,
단위 테스트에서는 실제 객체 대신 가짜 객체(Mock Object)를 주입하고
“어떤 상황에서 어떤 결과를 반환할지”를 미리 정의한다.

이렇게 미리 정해진 응답을 준비하는 과정을 Stub이라고 한다.

좋은 단위 테스트의 특징

좋은 단위 테스트는 다음 원칙을 따른다.

• 하나의 테스트 함수는 하나의 개념만 검증한다

• 테스트 함수 내에서 assert는 최소화한다

또한, 좋은 테스트 코드는 흔히 FIRST 원칙을 만족해야 한다.

• Fast
  테스트는 빠르게 실행되어 자주 돌릴 수 있어야 한다.

• Independent
  각 테스트는 서로 의존하지 않고 독립적으로 실행되어야 한다.

• Repeatable
  어떤 환경에서도 동일한 결과를 보장해야 한다.

• Self-Validating
  성공 또는 실패가 명확해야 하며, 추가 해석이 필요 없어야 한다.

• Timely
  실제 코드를 작성하기 직전 또는 동시에 작성되어야 한다.

Given / When / Then 패턴

단위 테스트에서는
테스트의 의도를 코드만 보고도 이해할 수 있도록 만드는 것이 중요하다.

이를 위해 가장 널리 사용되는 구조가
Given / When / Then 패턴이다.

• Given: 테스트를 위한 사전 조건을 준비한다.

• When: 테스트 대상의 동작을 실행한다.

• Then: 실행 결과를 검증한다.

이 패턴의 목적은

“이 테스트가 무엇을 검증하는지”
를 코드 구조만으로 드러내는 데 있다.

외부 의존성이 없는 경우: 순수 객체 기반 테스트

로또 번호 생성기 예제처럼
외부 의존성이 전혀 없는 경우에는 매우 단순한 테스트 구조를 유지할 수 있다.

// given
final LottoNumberGenerator lottoNumberGenerator = new LottoNumberGenerator();
final int price = 1000;

// when
final List<Integer> lotto = lottoNumberGenerator.generate(price);

// then
assertThat(lotto).hasSize(6);

이 경우 테스트 대상은 오직 하나의 객체이며,
new 키워드만으로 충분히 단위 테스트를 구성할 수 있다.

왜 예약 도메인에서는 같은 방식이 어려울까?

예약 도메인의 서비스 로직은
로또 예제와 구조적으로 다르다.

하나의 기능을 수행하기 위해
여러 협력 객체와 메시지를 주고받기 때문이다.

photoLabRepository.findById(...)
memberUserRepository.findById(...)
reservationSlotRepository.findByPhotoLabIdAndReservationDateAndReservationTimeForUpdate(...)
reservationRepository.save(...)

이 서비스는 다음과 같은 특징을 가진다.

• Repository를 통해 DB에 접근한다.

• 트랜잭션과 락 조회가 포함된다.

• 여러 협력 객체의 상태에 따라 분기 로직이 달라진다.

이런 구조에서는 단순히 객체를 new 해서 테스트를 실행할 수 없다.
테스트가 DB 상태, 트랜잭션 환경, 외부 설정에 영향을 받게 되기 때문이다.

즉, Mock 없이 실제 협력 객체만으로는
순수 객체 기반 단위 테스트를 구성하기 어렵다.

그래서 단위 테스트에서는 Mock을 사용한다

이러한 문제를 해결하기 위해,
단위 테스트에서는 실제 객체 대신 행동이 고정된 가짜 객체(Mock)를 주입한다.

중요한 점은,
Mock을 사용하더라도 테스트의 초점은 여전히 Service에 있다는 것이다.

Mock을 사용했지만, 테스트의 초점은 Service에 있다

아래 테스트는
ReservationCommandService 하나의 개념만을 검증한다.

@ExtendWith(MockitoExtension.class)
class ReservationCommandServiceImplTest {

    @Mock PhotoLabRepository photoLabRepository;
    @Mock MemberUserRepository memberUserRepository;
    @Mock ReservationRepository reservationRepository;
    @Mock ReservationSlotRepository reservationSlotRepository;

    @InjectMocks
    ReservationCommandServiceImpl service;
}

모든 Repository는 Mock으로 대체되었고,
각각의 반환 값은 Given 단계에서 명확하게 정의된다.

given(photoLabRepository.findById(labId))
        .willReturn(Optional.of(lab));

given(memberUserRepository.findById(memberId))
        .willReturn(Optional.of(user));

이를 통해 이 테스트는

• DB 동작을 검증하지 않고

• 트랜잭션 구현을 신경 쓰지 않으며

• 오직
  **“이 서비스가 주어진 상황에서 올바른 결정을 내리는지”**만 확인한다.

Given 지옥을 피하기 위해 적용한 방법

협력 객체가 많은 서비스 테스트에서는
Given 코드가 길어지기 쉽다.

이를 방치하면 테스트의 의도가 흐려진다.

1. Fixture로 객체 생성 책임을 분리했다

var lab = ReservationDomainFixture.photoLab(labId);
var user = ReservationDomainFixture.memberUser(memberId);
var slot = ReservationDomainFixture.slot(lab, 100L, date, time);

테스트에서는
무엇을 검증하는지만 드러나야 한다.

객체 생성 방식은 Fixture로 숨긴다.

2. 결과 중심으로 검증했다

assertThat(response.reservationId()).isEqualTo(777L);

내부 구현이 아니라
최종 결과와 핵심 부작용만 검증한다.

3. 한 테스트는 하나의 개념만 검증했다

void createReservation_정상_슬롯없으면_생성후_예약저장()

• 메서드 이름 자체가 시나리오

• 실패 원인이 즉시 드러남

• 불필요한 assert 제거

Spring Context를 띄우지 않은 이유

이 테스트는 @SpringBootTest를 사용하지 않는다.
즉, Spring Application Context를 띄우지 않는다.

그 결과 다음과 같은 장점이 있다.

• 테스트 실행 속도가 빠르다 (Fast)

• 테스트 간 상태 공유가 없다 (Independent)

• 환경에 관계없이 반복 가능하다 (Repeatable)

이는 FIRST 원칙을 충족하는
단위 테스트에 가까운 구조이다.

정리

• 단위 테스트는 “Mock이 없는 테스트”가 아니다.

• 단위 테스트의 핵심은
  하나의 개념을 외부 영향 없이 검증하는 것이다.

• 외부 환경에 의해 결과가 달라질 수 있는 의존성만 Mock으로 대체한다.

• Given / When / Then 구조를 통해 테스트의 의도를 드러낸다.

• Fixture와 명확한 네이밍으로 Given 지옥을 줄인다.

이러한 기준을 지키면,
협력 객체가 많은 서비스 로직에서도
읽기 쉽고 신뢰할 수 있는 단위 테스트를 작성할 수 있다.

1. 조회 캐시 vs 인증/토큰

먼저, Redis가 다운되는 것뿐만 아니라 지연되는 것도 생각해야 된다. 그래서 redis가 다운/지연된다면 DB로 fallback 하는 로직을 추가하게 되었다. 하지만 지금 redis를 사용하는 부분은 인기글 조회, 인기 현상소 조회와 인증/토큰 부분이었다.

Redis -> 실패/타임아웃 -> DB 조회

조회 캐시는 이런 흐름으로 방어 로직을 넣었다.

하지만 인증/토큰 부분은 얘기가 다르다. Redis가 안 된다고 DB로 넘겨 버리면 인증 번호 재사용 위험, 만료 처리 꼬임 등 여러 문제가 생긴다고 생각되었다. 그래서 인증 실패 응답을 띄우는 게 더 나을 것 같다고 생각했다. 그래서 조회 캐시 부분만 방어 로직을 적용했다.

2. Upstash 연결

기존에는 Redis를 도커에 붙여서 사용했는데 Upstash로 연결하면 관리하기 더 편하다는 얘기를 들었다. 그래서 무료 플랜이 있길래 사용해 보기로 했다.

사진처럼 설정해서 사용했다. 지역에는 한국이 없어서 일본으로 설정하고 넘어갔다. 무료 플랜으로 설정하면 카드 입력도 안 해도 돼서 혹시 모를 불안감이 안 생기고 좋은 것 같다.

첫 번째 사진에 있는 Read Regions는 유료 플랜만 가능한 기능이다. 읽기 전용 복제본을 다른 지역에 두는 기능으로 쓰기(write)를 한국에서 하면, 읽기(read)를 미국으로 설정할 수 있다. 그러면 전 세계 유저가 빠르게 조회 가능하다고 한다. 하지만 쓰기 성능에는 영향이 없고 읽기 트래픽이 많을 때 의미가 있다고 한다.

그리고 Eviction은 저장 공간이 꽉 찼을 때, 기존 데이터를 자동으로 지울지 말지를 정하는 옵션이다. 우리 프로젝트는 인증/토큰뿐만 아니라 조회 캐시에서도 Redis를 사용하고 있어, 초기에는 예상치 못한 에러를 피하기 위해 일단 off로 설정하고 시작했다.

Upstash를 연결하면 사진처럼 commands가 늘어나는 걸 볼 수 있다. 그리고 사이트 내 CLI를 이용해서 캐시 초기화도 한 번에 가능하다. 원래라면 도커로 들어가고, 날리고, 다시 나오고... 번거로움이 있었지만 편하게 날릴 수 있다.

Upstash를 연결하고 connect-timeout과 timeout을 각각 1s, 2s로 수정했다. 원래는 10ms, 20ms였는데 그러면 네트워크가 왕복하기에 너무 촉박하기 때문이다. Upstash는 인터넷 너머에 있는 Redis이기 때문에 원래 설정했던 값들이랑은 문제가 있었다. 그리고 docker-compose-dev에서도 Redis 관련 설정을 제거했다. 다른 docker 파일은 추후 인증/토큰 부분도 방어 로직이 추가된다면 제거할 예정이다.

오늘의 요약

• Redis는 타임아웃 설정이 핵심이다.

• 조회 캐시와 인증/토큰은 성격이 다르다.

1. DefaultTyping.EVERYTHING의 문제점

처음 설계는 Redis용 ObjectMapper에 DefaultTyping.EVERYTHING를 써서 모든 캐시 데이터에 강제로 자바 클래스 정보(@class)를 다 넣는 구조였다. 하지만 이러면 몇 가지 문제가 생기게 된다. 첫 번째, 내 설정 하나 때문에 다른 팀원이 만든 캐시 데이터 포맷까지 강제로 바뀔 수 있다. 두 번째, 모든 클래스를 다 받아 주는 구조라 외부에서 이상한 클래스 정보가 섞여 들어오면 역직렬화 과정에서 RCE 공격 위험이 생길 수 있다. 그래서 보안적으로도, 팀 단위 코드 기준으로도 사용하지 않는 게 좋다.

2. 해결 과정

수정 전 구조에서는 Redis에 Java 객체를 그대로 저장한 게 아니었다. 나는 그냥 객체로 들어갔다가 객체로 나오는 줄 알고 쓴 거고,

PostCacheDTO -> JSON -> Redis -> LinkedHashMap

실제로는 이 흐름인 것이다.

그래서 생각한 해결 방법은 캐시에서 꺼낸 Map을 우리가 직접 DTO로 변환해 주자였고,

LinkedHashMap -> PostCacheDTO

그 결과 이렇게 바꿔 주는 코드가 추가되었다.

그리고 인기글 캐시는 단순한 목록 캐시가 아니라 로그인/비로그인, 좋아요 여부, 이미지 URL 가공 로직까지 섞이기 때문에 결과를 무조건 캐시하게 되면 안 된다. 어디까지 캐시할지 결정하는 로직이 필요하다고 생각되어서

1. DB에서 가져온 공통 데이터만 캐시

2. 좋아요 여부, 이미지 URL 같은 건 요청 시점에 조립

이 구조를 만들기 위해 PopularPostCacheService 파일을 따로 생성하였다. 그리고 @Cacheable을 기존 Service나 Repository에 붙이지 않고 PopularPostCacheService로 분리했다. 이렇게 하니 캐시 정책이 한곳에 모이고, 요청자 기준 분기 로직도 훨씬 관리하기 쉬워졌다.

objectMapper 함수는 JacksonConfig 파일에 존재하기 때문에 중복 코드는 지우고 끌어와서 쓰게 되었다.

3. 해결 결과

Redis에서 캐시를 꺼낸다고 해서 항상 PostCacheDTO가 그대로 나오는 것은 아니었다. 스프링 캐시의 내부 동작 때문에 최초로 DB에서 조회하여 캐시에 저장하는 시점에는 메서드가 반환한 PostCacheDTO가 메모리에 남아 있어 그대로 반환한다. 하지만 캐시가 이미 존재하여 Redis에서 데이터를 읽어오는 시점에는 타입 정보(@class)가 없으므로 Jackson이 이를 LinkedHashMap으로 읽어오게 된다.

• 첫 번째 호출 (DB 조회) -> PostCacheDTO

• 두 번째 이후 호출 (캐시 히트) -> LinkedHashMap

최종적으로는 이런 흐름으로 진행하게 된다.

+. @Cacheable에 관하여

@Cacheable을 남발하면 좋지 않다는 얘기를 들었다. 그래서 조사해 보았더니 이 부분은 상황마다 다른 것 같다. 데이터가 자주 바뀌지 않거나, 조회가 매우 잦거나, DB 조인 쿼리가 무거울 때 쓰면 효과가 좋다고 한다. 내가 맡은 인기글도 조회가 잦은 홈페이지에서 사용되니 어노테이션을 사용해도 괜찮은 것이다. 반대로 주식처럼 실시간으로 계속 바뀌는 데이터나 어쩌다 한 번만 조회되는 데이터, DB 조회가 아주 단순하고 빠른 경우엔 오히려 손해라 안 쓰는 게 좋다고 한다.

오늘의 요약

• Redis에 대해 제대로 이해하지 않고 진행하다 보니 역직렬화에서 계속 부딪히게 됐다. 꼭 이해하고 넘어가자.

인기 게시물은 좋아요 수 기준으로 상위 10개를 불러온다. 실시간으로 데이터가 급격히 변하지 않지만 메인 페이지의 특성상 호출 빈도가 매우 높다. 매번 DB를 조회하는 대신 Redis 캐시를 사용해 성능을 개선했다.

1. RedisConfig 설정

@Configuration
@EnableCaching
public class RedisConfig {

    ...
    public static final String POPULAR_POSTS_CACHE = "popularPosts"; // 홈페이지 사진 수다 미리 보기

    ...
    private static final long POPULAR_POSTS_TTL_MINUTES = 10L;

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new GenericJackson2JsonRedisSerializer(redisObjectMapper()));
        return template;
    }

    @Bean
    public CacheManager cacheManager(RedisConnectionFactory connectionFactory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                .entryTtl(Duration.ofMinutes(DEFAULT_CACHE_TTL_MINUTES))
                .disableCachingNullValues()
                .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer(redisObjectMapper())));

        return RedisCacheManager.builder(connectionFactory)
                .cacheDefaults(config)
                ...
                .withCacheConfiguration(POPULAR_POSTS_CACHE, config.entryTtl(Duration.ofMinutes(POPULAR_POSTS_TTL_MINUTES)))
                .build();
    }

    private ObjectMapper redisObjectMapper() {
        ObjectMapper objectMapper = new ObjectMapper();
        objectMapper.registerModule(new JavaTimeModule());
        objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

        BasicPolymorphicTypeValidator ptv = BasicPolymorphicTypeValidator.builder()
                .allowIfBaseType(Object.class)
                .allowIfSubType("com.finders.api")
                .build();
        objectMapper.activateDefaultTyping(ptv, ObjectMapper.DefaultTyping.EVERYTHING);
        return objectMapper;
    }
}

• 인기 게시물 전용 캐시 이름과 TTL 10분 설정을 추가했다.

• EVERYTHING 설정을 사용하되, allowIfSubType("com.finders.api")를 통해 우리 패키지 하위 클래스만 타입 정보를 유지하도록 화이트리스트를 적용했다.

• 코드 리뷰 중에 EVERYTHING 대신 NON_FINAL을 사용해 구성을 더 단순하게 유지하는 것을 고려해 보라는 의견이 있었지만, 아래 트러블 슈팅에서 언급할 record 이슈로 인해 현재 설정을 유지하기로 했다.

2. PostCacheDTO

@Builder
public record PostCacheDTO(
        Long id,
        String title,
        Integer likeCount,
        Integer commentCount,
        String objectPath
) implements Serializable {
}

• Post 엔티티가 PostImage를 참조하고, PostImage가 다시 Post를 참조하는 등 순환 참조 문제가 발생할 수 있고, 캐시에 불필요한 정보까지 저장되는 것을 방지하기 위해 전용 DTO를 생성했다.

• Entity를 직접 캐싱하지 않고, 필요한 데이터만 담은 PostCacheDTO를 생성했다.

3. PostResponse

 // PostResponse
 public static PostPreviewDTO fromCache(PostCacheDTO cache, boolean isLiked, String fullImageUrl) {
            return PostPreviewDTO.builder()
                    .postId(cache.id())
                    .title(cache.title())
                    .likeCount(cache.likeCount())
                    .commentCount(cache.commentCount())
                    .isLiked(isLiked)
                    .image(new PostImageResDTO(fullImageUrl, null, null))
                    .build();
        }

• 캐시 DTO를 응답 DTO로 변환했다.

4. PostRepository

// PostRepository
@Cacheable(value = "popularPosts", key = "'home_top10'")
    public List<PostCacheDTO> findTop10PopularPosts() {
        List<Long> ids = queryFactory
                .select(post.id)
                .from(post)
                .where(post.status.eq(CommunityStatus.ACTIVE))
                .orderBy(post.likeCount.desc(), post.createdAt.desc()) // 좋아요 순, 같으면 최신순
                .limit(POPULAR_POSTS_LIMIT)
                .fetch();

        if (ids.isEmpty()) return List.of();

        List<Post> posts = queryFactory
                .selectFrom(post)
                .leftJoin(post.postImageList).fetchJoin()
                .where(post.id.in(ids))
                .orderBy(post.likeCount.desc(), post.createdAt.desc())
                .fetch();

        return posts.stream()
                .map(p -> PostCacheDTO.builder()
                        .id(p.getId())
                        .title(p.getTitle())
                        .likeCount(p.getLikeCount())
                        .commentCount(p.getCommentCount())
                        .objectPath(p.getPostImageList().isEmpty() ? null : p.getPostImageList().get(0).getObjectPath())
                        .build())
                .toList();
    }

• @Cacheable을 적용하여 Redis에 데이터가 있으면 메서드 로직을 타지 않고 바로 반환한다.

• 쿼리 튜닝을 위해 ID 목록을 먼저 뽑고 IN 절로 데이터를 갖고 오는 방식을 사용했다.

• 조회 성능 개선이 목적이므로, 서비스가 아닌 조회 전용 Repository 메서드에 캐시를 적용했다. 해당 메서드는 상태 변경 로직이 없고, 캐시 무효화 시점도 명확해 안전하다고 판단했다.

• 인기 게시물은 모든 사용자에게 동일한 결과를 반환하므로 사용자 ID를 포함하지 않은 고정 캐시 키(home_top10)를 사용했다.

5. PostQueryServiceImpl

// PostQueryServiceImpl
@Override
    public PostResponse.PostPreviewListDTO getPopularPosts(Long memberId) {
        List<PostCacheDTO> cachedPosts = postQueryRepository.findTop10PopularPosts();

        Set<Long> likedPostIds;
        if (memberId != null && !cachedPosts.isEmpty()) {
            List<Long> postIds = cachedPosts.stream().map(PostCacheDTO::id).toList();
            likedPostIds = postLikeRepository.findLikedPostIdsByMemberAndPostIds(memberId, postIds);
        } else {
            likedPostIds = java.util.Collections.emptySet();
        }

        List<PostResponse.PostPreviewDTO> previews = cachedPosts.stream()
                .map(dto -> {
                    boolean isLiked = likedPostIds.contains(dto.id());

                    String fullImageUrl = (dto.objectPath() != null)
                            ? storageService.getPublicUrl(dto.objectPath())
                            : null;

                    return PostResponse.PostPreviewDTO.fromCache(dto, isLiked, fullImageUrl);
                })
                .toList();
        return PostResponse.PostPreviewListDTO.from(previews);
    }

• 전체 리스트는 캐시에서 가져오되, 내가 이 글에 좋아요를 눌렀는가와 같은 개인화된 정보는 서비스 레이어에서 동적으로 결합하도록 설계했다. 캐시의 효율성과 개인화 정보를 동시에 잡은 방식이다.

6. 트러블 슈팅

오늘 가장 시간을 많이 썼던 부분은 record 타입의 직렬화 충돌 문제였다.

Could not read JSON:Unexpected token (START_ARRAY) // 에러 발생

• 코드 리뷰 과정에서 EVERYTHING 대신 NON_FINAL을 사용해 구성을 단순화하자는 의견이 있었다. 그러나 Java의 record 타입은 모든 필드가 final이기 때문에 NON_FINAL 설정에서는 타입 정보가 누락되어 역직렬화 오류가 발생했다. 해당 오류로 인해 EVERYTHING은 유지하되, allowIfSubType("com.finders.api")를 통해 패키지 화이트리스트를 적용했다.

• 설정을 변경한 후에는 반드시 docker exec -it [컨테이너명] redis-cli flushall 을 통해 기존에 잘못된 데이터를 날려 줘야 한다. 설정 변경 후 기존에 잘못 직렬화된 데이터가 남아 있어 로컬 환경에서만 flushall로 캐시를 초기화했다.

오늘의 요약

• 캐시용 DTO를 별도로 설계하여 필요한 정보만 효율적으로 저장했다.

• 설정 변경 후에는 기존 캐시 데이터를 꼭 날리자.

외부에서 접근만 되면 되잖아?

프로젝트를 진행하면서 외부에서 접근 가능한 API 엔드포인트가 필요했다. 하지만 서버 환경은 꽤 제한적이었다.

• 내부 네트워크 또는 로컬 환경

• 인바운드 포트 개방 불가

• 공인 IP 사용 지양

• VPN은 과한 해결책

이 조건들을 모두 만족시키면서 서버를 외부에 노출할 방법이 필요했고, 이때 선택한 것이 Cloudflare Tunnel이었다.

포트 포워딩 없이도 로컬 서버를 외부로 노출할 수 있다는 점이 좋아 보였다.
하지만 이 편리함이 첫 번째 오해였다..

2. 처음엔 Cloud Tunnel을 너무 쉽게 봤다

Cloud Tunnel을 처음 접했을 때의 인식은 이랬다.

로컬 서버를 외부에 잠깐 열어주는 도구겠지

그래서 구조에 대한 깊은 이해 없이 바로 설정부터 시작했다. 처음 Cloud Tunnel을 도입했을 때의 전제는 단순했다.

• 하나의 인스턴스에 올라와 있는 dev, prod 서버

• 둘 다 외부에서 접근 가능해야 함

• Cloud Tunnel은 어차피 연결만 해주는 역할

그래서 자연스럽게 “인스턴스는 하나니깐 Tunnel도 하나 만들어서 dev 도메인, prod 도메인 둘 다 연결하면 되는 거 아닌가?”

이 판단은 틀리지는 않았지만, 불완전했다… 🥹

3. 최초 구조: 하나의 Tunnel + 두 개의 Hostman

초기 구성은 대략 이런 형태였다.

tunnel: finders-tunnel
ingress:
    - hostname: dev-api.finders.it.kr
      service: http://localhost:8081
    - hostname: api.finders.it.kr
      service: http://localhost:8080

DNS 역시 다음처럼 설정했다.

• dev-api.finders.it.kr → Cloud Tunnel

• api.finders.it.kr → Cloud Tunnel

이론적으로는 완벽해 보였다.

• hostname으로 환경 구분

• 포트로 서비스 구분

• Tunnel은 공통

hostname으로 환경을 구분하고 포트로 서비스를 나누니, 이론적으로는 완벽해 보였다.
실제로 dev 환경 배포 직후에는 모든 것이 잘 동작했다!! 새로운 기술을 적용했기에 기뻐했는데,,

진짜 문제는 prod 서버를 올리면서 시작되었다..

4. 첫 번째 이상 징후: 200 → 502 → CORS 에러?

main 브랜치를 배포하고 나서 갑자기 API 응답이 요동치기 시작했다. 어떨 때는 200 OK가 뜨다가, 갑자기 502 Bad Gateway와 함께 CORS 에러가 터져 나왔다!!!!!

CORS 설정은 완벽했기에 대체 왜 이런 일이 발생했는지 의문이었다.
대체 뭐가 문제인가 싶어서 확인했더니 Cloud Tunnel 문제였다.👿

내가 했던 착각

hostname이 다르면 Cloudflare가 알아서 완벽하게 분리해 주겠지?

하지만 정말 착각이었따..

터널의 기준은 hostname이 아니라 Tunnel Demon(Cloudflared) 그 자체였다. 하나의 터널 프로세스가 여러 호스트네임의 트래픽을 동시에 처리하다 보니, Connection Pool의 혼선이나 라우팅 우선순위 문제가 발생했던 것이다.
Cloudflare Edge 서버 입장에서는 같은 터널로 들어오는 요청이 꼬이면서 응답을 제대로 받지 못해 502를 던졌고, 이 과정에서 필수 헤더가 누락되어 브라우저가 이를 CORS 에러로 오인한 것이었다.

5. 해결책 1: 터널 분리

hostname 기준으로 다 나뉠 줄 알았다.. (그렇게 해도 된다며..!!!)

결국 터널을 물리적으로 두 개로 분리하기로 했다. prod용 터널과 dev용 터널을 각각 생성하여 각자의 설정 파일과 프로세스를 가지게 했다.

이렇게 하면 장애 전파 범위를 완벽히 격리할 수 있었다. dev 터널에 과부하가 걸리거나 설정 오류가 나더라도 prod 터널은 물리적으로 분리된 통로를 사용하므로 영향을 받지 않게 되는 것이다!

→ 이것이 바로 격리(Isolation)이었다.

6. 두 번째 문제: 사라지지 않는 유령(Zombie) 설정

dev를 고쳐놨더니 prod가 말썽이네?

dev가 너무 정상적으로 실행되었고, 에러가 하나도 나지 않았기 때문에 prod도 문제 없을 거라 생각했다.

하지만 prod 환경이 여전히 불안정했다. 설정은 완벽한데 왜일까?

Tunnel을 분리함으로써 각각의 역할을 명시해주었고, 그에 따라 동일한 설정을 가지고 있음에도 dev는 멀쩡했는데 prod만 문제가 발생하니 어떻게 해야할지가 막막했다..

답은 라우팅 전파(Propagation)의 지연에 있었다..

찾아보니 기존 터널 정보를 지우고 새 터널을 연결해도, 퍼져 있는 Cloudflare의 Edge 노드들에는 이전의 라우팅 캐시나 ‘좀비 커넥션’이 남아있을 수도 있다고 했다.

그래서 바로 완전히 새로 터널을 생성하여서 ID 자체를 갱신하였다.

두근.. 두근..!!!

결론적으로는 그 이후로는 아주 안정화되었다!!! 아마도 이전 설정 기록들이 어딘가에 남아있었고, 그게 계속 문제를 일으키고 있었던 것 같다.

7. 마치며

이제는 왜 두 개의 Tunnel을 쓰는지 설명할 수 있다

이번 경험을 통해 단순한 네트워크 도구라도 운영 환경에서는 책임과 경계를 명확히 해야 함을 배웠다.

1. 터널은 단순한 통로가 아니다: 터널은 하나의 리소스 단위이며 장애 전파의 단위였다.

2. 논리적 분리보다 물리적 분리: hostname(논리적) 구분보다 Tunnel Process(물리적) 분리가 훨씬 안전하다.

3. 인프라 설정은 때로 재생성이 답이다: 때로는 수정보다 ‘재생성’이 더 빠르고 확실한 해결책이 될 수 있다.

처음엔 Tunnel 하나로 dev / prod를 동시에 운영하려 했다. 그리고 실제로 한동안은 잘 되는 것처럼 보였다. 하지만 dev와 prod의 분리는 필요하였고, 이는 편의가 아니라 안정성과 책임의 문제였다.

바이요

-elastic

▶ 들어가며

이번에는 ELK Stack에 관해서 찍먹을 해보자.
전체적인 플로우를 먼저 잡아두면, 이 기술을 왜 사용하는지, 어떤 구조로 동작하는지 이해하기가 훨씬 쉬워진다.

그래서 이번 글에서는 ELK Stack을 구성하는 요소들이 각각 어떤 역할을 하는지,
그리고 전체 흐름이 어떻게 연결되는지를 가볍게 정리해보려고 한다.

▶ ELK Stack 전체 구조

-ELK stack

위 사진은 ELK Stack의 전체적인 구조를 보여주는 대표적인 그림이다. ELK Stack의 핵심 요소는 이름 그대로 아래 3가지이다.

로고가 아주 찰떡이야

• Elasticsearch

• Logstash

• Kibana

그리고 가장 왼쪽에 있는 data 구간은 Beats라는 별도의 구성요소로 구분된다.

그럼 이제 각 단계가 어떤 역할을 하는지 하나씩 살펴보자.

▶ Beats

-Beats

사진에서 가장 왼쪽에 있는 요소들이 Beats이다.
Beats는 “가벼운 수집 프로그램”들이고, 서버에 설치해서 데이터를 긁어 Elasticsearch 또는 Logstash로 보내는 데이터 수집기 역할을 한다.

즉 Beats는 서버에 설치해서 백그라운드에서 동작하는
👉 경량 수집 agent 프로그램이라고 이해하면 된다.

Beats는 종류가 여러 가지가 있는데 대표적으로 아래와 같다.

• Filebeat : 서버의 로그 파일(log file)을 수집

• Metricbeat : CPU, RAM, Disk 사용량 같은 서버 metric 정보를 수집

• Packetbeat : 네트워크 패킷(wire data)을 분석하여 트래픽 정보를 수집

• Winlogbeat : Windows 이벤트 로그를 수집

!! Beats가 하는 일을 정리하면 이런 느낌이다!!

• 웹서버, 백엔드 서버, DB 서버, 운영 서버 등에 설치

• 로그 파일을 읽거나, metric을 수집하거나, 네트워크 패킷을 분석해서

• Elasticsearch 또는 Logstash로 전송

즉, 빅데이터 관점에서 보면 Beats는
👉 Ingestion(수집) 단계에 해당한다고 보면 된다.

▶ Logstash

-logstash

Logstash는 ELK에서 Beats로부터 로그를 받아서
👉 가공한 뒤 목적지로 보내는 중간 처리 서버 역할을 한다.

Logstash는 단순 전달이 아니라, 로그 데이터를 검색 가능한 형태로 바꿔주는 파이프라인 엔진이라고 볼 수 있다.

Logstash는 크게 아래 3단계 구조로 동작한다.

• Input : 데이터를 입력받음

• Filter : 데이터를 파싱하고 변환함

• Output : 데이터를 Elasticsearch 등 목적지로 보냄

예를 들어 앱 서버가 아래처럼 단순 텍스트 로그를 보낸다고 해보자.

user=kim age=26

Logstash는 이를 입력으로 받은 뒤, filter 단계에서 파싱 해서 아래처럼 JSON 형태로 구조화할 수 있다.

{ "user": "kim", "age": 26 }

이렇게 구조화된 데이터는 Elasticsearch에서 검색하기 훨씬 쉬워진다.
즉 Logstash는
👉 로그를 분석 가능한 형태로 바꾸는 전처리(ETL) 단계라고 볼 수 있다.

-Logstash 설정 예시

Logstash는 logstash.conf 같은 설정 파일을 코드처럼 작성해두고, 이 설정대로 파싱 및 변환 작업을 수행한다.

예시 설정은 다음과 같다.

input {
  http {
    port => 8080
  }
}

filter {
  json {
    source => "message"
  }

  mutate {
    convert => { "age" => "integer" }
  }
}

output {
  elasticsearch {
    hosts => ["http://localhost:9200"]
    index => "users"
  }

  stdout { codec => rubydebug }
}

위 설정을 보면,

• HTTP로 들어오는 요청을 받아서

• JSON 파싱 후

• age를 integer로 변환하고

• Elasticsearch에 저장하는 구조이다.

그리고 중요한 점은 Logstash는 필수는 아니다.

Beats가 바로 Elasticsearch로 보내는 구조도 가능하지만,
로그가 너무 지저분하거나 여러 시스템의 로그를 하나의 형태로 통합해야 하는 경우 Logstash가 필요해진다.

즉 Logstash는 빅데이터 관점에서 보면
👉 Streaming ETL / Transform 단계라고 이해하면 된다.

▶ Elasticsearch

-elasticsearch

Elasticsearch는 전처리된 로그/데이터를 저장하면서 동시에
👉 검색 가능한 구조(index)로 만들어주는 단계이다.

즉, 단순 저장소(DB)가 아니라 검색/분석이 가능하도록 인덱스를 만들어서 저장하는 저장소 검색엔진이라고 이해하면 된다.

Elasticsearch는 데이터를 SQL 테이블 row 형태로 저장하는 것이 아니라,
JSON 형태의 Document로 저장한다.

예를 들어 아래 데이터는 Elasticsearch에서 document 한 개가 된다.

{ "user": "kim", "name": "bo", "age": 26 }

이 document는 특정 index(예: users)에 저장된다.

그리고 Elasticsearch가 단순 DB가 아니라 검색엔진이라고 불리는 이유는, 저장 과정에서 검색을 위한 구조를 만들어두기 때문이다. 대표적으로 Elasticsearch는
👉 Inverted Index(역색인) 구조를 사용한다.

이 덕분에 특정 단어가 포함된 document를 빠르게 찾을 수 있고, 검색 성능이 매우 뛰어나다.

자세한 내용은 다음 포스팅에서...

-Aggregation(집계) 기능

Elasticsearch는 단순히 검색만 하는 것이 아니라, Aggregation(집계) 기능도 제공한다.

예를 들어 다음과 같은 분석이 가능하다.

• 특정 시간대별 로그 개수

• status code 별 요청 수

• 가장 많이 등장한 user top 10

• 특정 키워드 검색 결과 집계

즉, Elasticsearch는 빅데이터 관점에서 보면
👉 저장 + 검색 + 집계 분석을 동시에 수행할 수 있는 핵심 저장소 역할을 한다.

▶ Kibana

-kibana

이전에도 설명했지만, Kibana는 Elasticsearch에 저장된 데이터를 시각화해 주는 GUI 단계이다. 즉 Kibana는 ELK Stack에서
👉 프론트엔드 역할을 한다고 보면 된다.

Kibana를 사용하면 아래와 같은 작업이 가능하다.

• Elasticsearch index에 저장된 로그 검색

• 필터 조건을 걸어 원하는 로그만 확인

• 시간대별 트래픽 변화 그래프 확인

• 대시보드(Dashboard)를 구성하여 모니터링 화면 제작

즉 Kibana는 단순히 데이터를 보여주는 툴이 아니라,
운영 환경에서 로그 분석과 모니터링을 할 수 있도록 도와주는 도구이다.

▶ ELK Stack 전체 과정 정리

전체 흐름을 정리하면 다음과 같다.

1. 서버에서 로그/metric 데이터가 생성됨

2. Beats가 해당 데이터를 수집해서 전송함

3. Logstash가 있다면 데이터를 파싱/변환/정제함

4. Elasticsearch가 데이터를 저장하고 검색 가능한 구조로 인덱싱함

5. Kibana가 Elasticsearch 데이터를 시각화하여 보여줌

EndFragment

-elastic

▶ 들어가며

이번 글에서는 이전 포스팅에 이어서, Elasticsearch를 MySQL과 비교하며 아키텍처 관점에서 어떻게 다른지 살펴보고,
직접 Kibana를 사용한 개발 환경 세팅까지 진행해보려고 한다.

단순히 개념으로만 이해하는 것이 아니라,

• 요청이 어떤 방식으로 전달되는지

• 실제로 Elasticsearch가 잘 동작하는지

까지 확인하는 것을 목표로 한다.

▶ Elasticsearch 아키텍처

Elasticsearch의 기본적인 동작 흐름은 다음과 같다.

-MySQL의 요청 흐름

-Elasticsearch의 요청 흐름

여기서 가장 중요한 점은
👉 REST API 기반으로 동작한다는 점이다.

자체 문법을 실행하는 방식이 아니라 우리에게 익숙한 HTTP 요청을 통해 데이터를 삽입하고 조회한다.

예를 들어 데이터를 삽입한다고 가정하면,

• MySQL

INSERT INTO user (name, age)
VALUES ('bo', 26);

• Elasticsearch

curl -X POST "http://localhost:9200/user/_doc" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bo",
    "age": 26
  }'

조회 역시 마찬가지로, SQL 대신 HTTP 기반 요청으로 처리된다.

이 점 덕분에 Elasticsearch는 웹 서비스와의 연동, 검색 기능 구현에 특히 잘 어울린다.

▶ Elasticsearch의 GUI, Kibana

위에서 본 것처럼 cli를 매번 사용하여 요청을 보내고 테이블을 일일이 확인하는것은 여간 번거러운 일이 아님을 알고있을 것이다. MySQL을 공부하면서 이러한 번거로음을 줄이기 위해서

• MySQL Workbench

• DataGrip

같은 GUI 도구를 사용하듯이,
Elasticsearch 역시 매번 Postman이나 curl로 요청을 보내는 것은 번거롭다.

그래서 Elasticsearch에서는
👉 Kibana라는 GUI 도구를 함께 사용한다.

Kibana를 사용하면 데이터 조회, 인덱스 관리, 쿼리 테스트 를 훨씬 직관적으로 할 수 있다.

-Kibana 세팅 구조

전체 흐름을 정리하면 다음과 같다.

• 5601 포트: Kibana

• 9200 포트: Elasticsearch REST API

▶ 개발 환경 세팅

서로 다른 개발환경을 통일시킬 수 있는 Docker를 사용하여 Docker위헤 Elastic과 Kibana를 띄우는 방식으로 세팅을 해볼 것이다.

도커 관련 지식이나 막혔을때는 인터넷을 찾아서 하는것이 훨씬 빠를것이다.

• docker-compose.yml 파일을 작성/수정

• Elasticsearch + Kibana를 동시에 실행

version: "3.8"

services:
  elastic:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.2.4
    ports:
      - "9200:9200"
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - xpack.security.http.ssl.enabled=false

  kibana:
    image: docker.elastic.co/kibana/kibana:9.2.4
    ports:
      - "5601:5601"
    environment:
      - ELASTICSEARCH_HOSTS=http://elastic:9200
    depends_on:
      - elastic

- elastic과 kibana 버전이 반드시 맞아야 함. 다르니까 안됐음.

이후 postman으로 localhost:9200의 GET요청과 브라우저에서 http://localhost:5601 주소로 접속했을때 응답이 200OK로 오거나 접속창이 로딩되면 성공!.

-postman 응답 화면

-localhost:5601 Kibana화면

• 모두 정상적으로 뜬다면
  👉 Elasticsearch와 Kibana가 잘 실행 중이라는 의미다.

햄버거 바에서 "Dev Tools"를 찾아서 GUI로 편하게 요청을 보낼 수있게 된 나. 기존에 Postman이나 curl로 직접 보내던 REST API 요청을

GET /

과 같은 요청으로 Kibana 내부에서 바로 실행하며 결과를 확인할 수 있다.

👉 훨씬 간편하게 실행할 수 있다. 따봉!

-elastic

▶ 들어가며

이번 프로젝트에서 조회 및 검색 기능 구현을 맡아 개발을 진행했다.
Elasticsearch 없이 검색어 자동완성과 검색/조회 기능을 직접 구현하면서, 전체 검색 흐름과 동작 방식에 대해 많이 고민해볼 수 있었다. 이 과정에서 Elasticsearch라는 도구를 접하게 되었는데, 살펴보니 검색, 정렬, 필터링, 자동완성 등
주요 기능들이 내가 구현해야 했던 기능들과 거의 정확히 일치했다.

단순히 “검색 엔진이다”라는 인상을 넘어서,
이를 도입하면 검색 기능 개선 측면에서도 충분히 이야기해볼 만한 포인트가 많겠다는 생각이 들었고,
자연스럽게 Elasticsearch를 제대로 공부해보고 싶어졌다.

이번 카테고리는
👉 Elasticsearch를 처음 접하는 입장에서 개념을 최대한 쉽게 정리하고,
👉 이후에는 실제로 어떻게 활용할 수 있는지까지 딥다이브하는 것을 목표로 한다.

▶ Elasticsearch가 할 수 있는 일들

Elasticsearch가 제공하는 대표적인 기능들을 정리해보면 다음과 같다.

• 조회 기능 향상

• 정렬 기능 향상

• 필터링 서비스에 최적화

• 검색어 자동완성

• 동의어 기반 검색

• 위치(Geo) 검색에 최적화

• 데이터 양이 많아도 빠른 검색 성능

• 로그 및 기록 관리에 유용

정리해보니,
👉 내가 구현해야 했던 기능들과 거의 정확히 겹친다.

많은 우리나라 대기업에서 (쿠팡이나 배민과 같은) 실제로 Elasticsearch를 사용하여 대규모 데이터들을 관리하고 있기때문에 이번 기회에 제대로 공부하면 좋을듯..

▶ Elasticsearch가 뭔데 그래서?

처음 감을 잡기 위해 아주 단순하게 한 줄로 정리하면,

Elasticsearch는 검색과 데이터 분석을 아주 잘하는 데이터베이스다.

물론 엄밀하게 말하면 전통적인 의미의 DB(RDBMS)와는 다르다!!

그래도 처음 접근할 때는 DB라고 생각하는 게 가장 편하다고 느꼈다. (기능이 아주 많은 도구??)

우리가 많이 사용하는 RDBMS인 MySQL과 비슷한 점도 많고, 차이점도 명확하다.

핵심만 정리하면

• Elasticsearch는

  • 검색(Search), 조회(Query)

  • 데이터 분석(Analytics)

이 2가지에 특화되어 기능을 구현시켜주는 도구이다.

▶ Elasticsearch는 어떻게 다루나?

MySQL을 사용할 때를 떠올려보면,

• DataGrip

• MySQL Workbench

같은 GUI 툴을 사용해서 직접 데이터 삽입, 삭제, 조회를 보다 가독성있게 관리한다.

Elasticsearch도 마찬가지다.

-kibana

Elasticsearch는 Kibana라는 GUI 도구를 함께 사용한다.

• Elasticsearch 데이터 조회

• 쿼리 테스트

• 로그 시각화

• 인덱스 관리

등을 훨씬 편하게 할 수 있다. 나는 Kibana 기준으로 명령어와 쿼리를 공부할 예정이다.

(MySQL에서 터미널을 사용하듯이 curl 같은 명령어를 사용해서 직접 요청을 보내는 것이 기본.)

단순히 서버를 띄우는 것을 넘어, 외부 노출을 최소화하고 권한을 체계적으로 관리하는 법을 고민했습니다..

1. 왜 VPC와 Subnet을 설계해야 하는가?

인프라의 가장 밑단인 VPC(Virtual Private Cloud)는 구글 클라우드에서 만드는 우리만의 사유지입니다. 이는 외부와 완전히 격리되어 있으며, 우리는 이 내부를 보안 등급에 따라 Subnet이라는 논리적 구역으로 쪼개 관리합니다.

• App Subnet (Private): 백엔드 서버(GCE)가 있는 공간입니다. 외부 IP가 없어 인터넷에서 직접 접근할 수 없습니다.

• DB Subnet (Private/Logical): 데이터 관련 자원을 위해 비워둔 예비 공간입니다.

💡 외부 IP(Public IP)를 모두 제거함으로써, 외부의 Brute-force 공격이나 포트 스캐닝 가능성을 물리적으로 차단했습니다!

2. 서버와 DB의 통신: 비공개 서비스 액세스(PSA)의 원리

설계 과정에서 깨달은 점은 Cloud SQL은우리 VPC 안에 직접 설치되는 것이 아니라, 구글이 관리하는 별도의 ‘구글 서비스 VPC’에 존재한다는 점이었습니다. 그런데 어떻게 우리는 내부 IP로 DB에 접속할 수 있는 걸까요?

VPC 피어링과 PSA (Private Service Access)

격리된 두 동네(우리 VPC와 구글 VPC)가 통신하기 위해 비공개 서비스 엑세스(PSA)라는 전용 통로를 구축했습니다.

1. VPC 피어링(Peering): 우리 VPC와 구글 SQL VPC 사이에 거대한 전용 고속도로를 뚫습니다.

2. 내부 IP 할당: 우리 VPC의 남는 IP 대역을 DB용으로 정해두면, 구글 DB가 그 주소를 달고 우리 내부망인 것처럼 행동합니다

3. 결과: 우리 서버는 인터넷을 거치지 않고, 구글 클라우드 내부 망을 통해 DB 주소로 직접 패킷을 보냅니다.

3. 외부와의 소통은 어떻게 할까?

외부 IP가 없는데 사용자는 어떻게 접속하고, 서버는 어떻게 외부 API를 호출할까요? 여기서 입구(Inbound)와 출구(Outbound)의 분리가 일어납니다.

📥 입구: Cloudflare Tunnel (Inbound)
사용자의 요청은 서버로 직접 오지 않습니다. Cloudflare Tunnel이라는 가상의 보안 터널을 통해 들어옵니다. 서버는 밖으로 문을 열어두지 않아도, 이 터널을 통해 안전하게 요청만 전달받습니다.

📥 출구: Cloud NAT (Outbound)
서버가 샌드온(Sendon) 같은 외부 API에 요청을 보내야 할 때, Cloud NAT이 신분증 역할을 해줍니다.

• IP Masquerading: 서버의 비공개 IP를 감추고, Cloud NAT의 고정된 외부 IP를 달고 밖으로 나갑니다.

• Whitelisting: 서버가 10대든 100대든, 샌드온에는 Cloud NAT의 IP만 등록하면 모든 서버가 통신할 수 있습니다.

4. 마치며: 비어있는 서브넷과 Redis

결과적으로 제가 직접 만든 DB Subnet은 현재 비어있는 상태입니다. 향후 Redis 캐시 서버를 구축하거나 별도의 Proxy 서버를 둘 때, 이 구역을 이용할 수 있습니다.

현재 Redis 캐시 서버는 앱 서버 내에서 Docker 컨테이너로 운영 중이며, 논리적으로는 App Subnet에 위치합니다. 이를 별도 인스턴스로 분리한다면, DB Subnet으로 넣을 수 있겠죠?☺️

저를 소개하자면,

Log8 - 김덕환 개인 블로그

이런 사람입니다.

저희끼리 블로그를 작성해보기 위해서 hashnode를 만들게 되었습니다!

다들 인사 한번씩 해주세요!!

조만간 hashnode 만드는 법부터 시작해서 블로그 글을 올려보겠습니다!