브랜치 전략 얘기다. 팀에서 실제로 부딪힌 딜레마 하나를 어떻게 풀었는지, Feature Flag를 왜 안 골랐는지, 대신 뭘 골랐는지의 기록. 결론부터 말하면 hotfix 브랜치를 stage 서버에 임시로 스왑하는 방식으로 갔다.

그날 아침 들어온 요청

기획쪽에서 카톡이 왔다.

"실서버 화면 하나가 잘못 나가고 있어요. 오늘 안에 반영해주세요."

익숙한 요청이다. 평소 흐름은 이렇다.

feat/* ──▶ develop ──▶ stage 검증 ──▶ main ──▶ prod

작은 수정이니 30분이면 끝나겠다 싶어 develop 상태를 확인했다. 여기서 브레이크가 걸렸다.

develop 위엔 아직 실서버에 나가면 안 되는 미공개 기능들이 잔뜩 머지돼 있었다. 공모전 어드민 같은, 기획팀이 아직 오픈 시점을 안 정한 페이지들. develop을 그대로 흘려보내면 stage에서 검증 중인 미공개 기능이 prod에 딸려 나간다.

문제를 한 줄로 다시 쓰면

곰곰이 정리하니 이렇게 되더라.

main 은 언제든 배포 가능해야 하는데, main 을 앞으로 끌고 갈 유일한 소스인 develop 이 배포 불가능한 코드를 담고 있어서 prod 반영 경로가 막혔다.

원인은 develop 브랜치가 두 역할을 겸용하고 있다는 것.

1. Stage 통합 테스트 무대 (WIP 검증 포함)
2. 다음 prod 릴리즈 후보 대기실

평소엔 이 둘이 문제없이 굴러갔다. 릴리즈 사이클이 짧아서 "WIP 있는 상태"가 오래 지속되지 않았기 때문이다. 이번엔 오래 붙어 있었다.

이런 상황이 앞으로도 반복될 수 있다는 걸 인정했다. 그러니 이번 한 번을 넘기는 것보다, 어떤 방식으로 이걸 상시 해결할지를 정하는 게 맞다.

첫 번째 후보: Feature Flag

가장 먼저 떠오른 건 Feature Flag였다. 미공개 기능을 코드에는 두되 flag로 꺼두는 방식.

• BE: @ConditionalOnProperty(name = "feature.contest.admin.enabled", havingValue = "true") 로 컨트롤러를 게이팅. Doppler로 환경별 flag 관리.
• FE: import.meta.env.VITE_FEATURE_CONTEST === 'true' + Amplify env.

이렇게 하면 develop은 언제나 배포 가능하다. 미공개 기능이 있어도 prod에선 flag가 꺼져 있으니 흔적이 없다. 구조적으로 예쁜 해결책이다.

그런데 팀 규모를 생각하니 손이 멈췄다.

• BE 1인 + FE 1인 규모다.
• Flag의 진짜 비용은 정리(cleanup) 다. 기능이 오픈된 뒤 flag를 제때 걷어내지 않으면 dead flag가 코드에 쌓인다. 두세 명 규모에서 이 규율을 지키는 건 현실적으로 어렵다.
• 매번 BE/FE 사이 flag 이름·타이밍을 조율해야 한다. 오버헤드.
• Flag가 늘어날수록 조합 테스트 부담이 2^N으로 커진다.
• 무엇보다 이번이 사실상 첫 사례다. 발생 빈도가 아직 낮은데 상시 인프라를 짜는 건 과잉.

Feature Flag는 팀이 3~5명을 넘어가고, 릴리즈 트레인이 상시 돌아가는 단계에서 쓰는 도구다. 지금은 아니다. 기각.

두 번째 후보: 3환경 브랜치 (dev / ready / prod)

이전 회사에서 이 방식을 썼다. 환경마다 브랜치를 두고 승인 게이트로 흘렸다. 대기업 SI에서 자주 보이는 그림이다.

이 팀에는 확실히 오버킬이다. 배포 절차만 무거워지고 얻는 안전마진이 지금 필요한 만큼보다 크다. 기각.

채택한 방식: Hotfix 브랜치 + Stage 스왑

정리하고 나서 남은 게 이거였다.

아이디어 한 줄:

급한 수정만 담은 hotfix/* 브랜치를 main에서 분기해서, stage 서버를 잠깐 이 브랜치로 갈아치우고 검증한다. 검증 끝나면 main으로 흘려 prod 반영, develop에 역머지, stage는 다시 develop로 복귀.

정통 git-flow의 hotfix 브랜치를 살짝 확장한 것에 가깝다. 새로 발명한 게 아니라 실무에서 이름만 안 붙어 있을 뿐 널리 쓰이는 방식이다.

핵심을 한 줄로 압축하면:

"마지막에 stage로 push된 브랜치가 stage 서버의 현재 상태를 이긴다."

이 규칙 하나가 전부다.

• 평소: develop을 push → stage가 develop 반영
• Hotfix 중: hotfix/* 를 push → stage가 hotfix 반영
• Hotfix 완료 후 develop을 다시 push → stage가 다시 develop 반영

그림으로

┌────────────┐   ┌────────────┐   ┌────────────┐
│  develop   │   │    main    │   │  hotfix/*  │  ← 필요할 때만 등장
└─────┬──────┘   └─────┬──────┘   └─────┬──────┘
      │                │                │
      │ 자동배포       │ 자동배포       │ 자동배포 (규칙 추가)
      ▼                ▼                ▼
┌────────────┐   ┌────────────┐   ┌────────────┐
│   stage    │   │   prod     │   │   stage    │ ← 같은 stage 서버
└────────────┘   └────────────┘   └────────────┘

하루가 어떻게 흘러가는지

10:00 — 요청 도착.

10:05 — main에서 hotfix 분기.

main    ────●────●
                 │
                 └── hotfix/20260915-poster-fix

⚠️ 반드시 main에서. develop에서 분기하면 WIP가 딸려오므로 목적이 파탄난다.

10:30 — 수정 커밋, push.

Push 순간 stage 자동배포가 도는데, 이때 stage가 hotfix/* 로 갈아치워진다. WIP는 stage에서 사라지고, hotfix만 반영된 깨끗한 상태가 된다.

이 순간 stage는 사실상 "prod 미리보기"다. WIP가 없는 상태니까.

10:45 — QA·프런트 검증.

방해 없이 hotfix만 검증할 수 있다. 이게 이 방식의 진짜 가치다. "검증 시점의 stage가 곧 prod가 될 코드" 라는 신뢰가 생긴다.

11:00 — main 머지.

main    ────●────●───────────────●   ← push 순간 prod 자동배포
                 │              ▲
                 └── hotfix ────┘

11:10 — develop에 역머지. (⚠️ 잊기 쉬움)

develop  ───●──WIP──WIP──────────────●
                                      ▲
             hotfix ────────────────┘

이걸 잊으면 다음번에 develop → main 릴리즈할 때 hotfix 수정이 사라져 회귀버그가 재발한다. 절대 잊으면 안 되는 스텝.

11:15 — develop을 다시 push해서 stage 복귀. 11:20 — hotfix 브랜치 삭제.

끝. 문제 요청부터 정리까지 1시간 20분.

여기서 진짜 무서운 것들

이 방식을 실제로 쓴다면 조심해야 할 지점이 몇 개 있다. 개념은 단순한데 규율이 흐트러지면 실수 여지가 크다.

첫째, hotfix 진행 중 다른 사람이 develop에 push하면 stage가 develop로 스왑된다. 검증 진행 중이던 QA는 갑자기 WIP가 나타나는 경험을 하게 된다. → 슬랙에 "hotfix 시작/종료" 공지가 필수. hotfix 활성 중 develop push 금지가 팀 규칙.

둘째, hotfix를 develop에 역머지하는 걸 잊는 건 진짜 흔한 실수다. prod에 반영되고 나면 다들 만족해서 브랜치를 지워버린다. 2주 뒤 릴리즈에서 회귀버그가 다시 튀어나온다. → PR 템플릿에 [ ] develop 역머지 완료 체크박스 필수, 역머지 전 브랜치 삭제 금지가 규칙.

셋째, stage 서버가 어떤 브랜치를 반영 중인지 밖에서 안 보인다. "왜 내 코드가 없지?" 삽질로 이어진다. → Swagger 상단, 어드민 footer에 배포 브랜치 + 커밋 SHA + 배포 시각을 노출. Spring Boot의 build-info + Actuator로 뽑을 수 있다.

넷째, hotfix 브랜치엔 DB 마이그레이션을 넣지 말자. hotfix는 main 기준이라 develop에서 새로 생긴 V29를 모른다. Stage DB는 이미 V29 적용됨. 대개 Flyway가 skip해서 문제없지만, 스키마 상태를 꼬이게 만들 여지가 있다. hotfix는 순수 코드 변경만.

다섯째, hotfix가 30분~1시간 넘게 걸리면 방식을 잘못 고른 거다. Stage 스왑 방식은 짧은 hotfix용 도구다. 길어지면 정식 feat 브랜치로 전환하는 게 맞다.

왜 이 방식이 지금 팀에 맞았나

세 가지가 딱 맞아떨어졌다.

1. 코드에 조건부 로직이 0이다. flag 지옥이 없다. dead flag가 쌓일 걱정 없음.

2. 학습곡선이 낮다. git-flow의 hotfix 개념을 아는 개발자면 5분 설명이면 이해한다.

3. 인프라 변경이 최소다. GitHub Actions workflow YAML에 hotfix/** 트리거 한 줄 추가로 끝. Terraform·Amplify 콘솔 조작 불필요.

on:
  push:
    branches:
      - develop
      - 'hotfix/**'    # ← 신규 추가

언제 이 결정을 재평가해야 하나

이 방식이 영원히 맞는 건 아니다. 아래 상황 중 하나라도 발생하면 재평가한다.

• Hotfix 케이스가 월 3회 이상 반복적으로 발생 → Feature Flag 정식 도입 검토
• 동시 hotfix 요청이 실제로 발생 → 병렬 stage 슬롯 신설 검토
• 팀 규모 3인 이상 으로 확대 → 자동화 강화 or Trunk-Based + Feature Flag 재검토
• 이 절차로 인한 회귀버그가 2회 이상 발생 → 자동화 우선순위 상향

배운 것 세 가지

1. "정답인 도구"보다 "지금 팀에 맞는 도구"가 우선이다. Feature Flag는 구조적으로 우수한 해결책이지만, 팀 규모 2인에서 flag 청소 규율을 유지할 수 있느냐가 진짜 질문이었다. 도구의 이론적 우수함이 아니라 운영 비용을 감당할 수 있는지로 판단해야 한다.

2. 브랜치 전략의 본질은 "환경과 브랜치의 매핑"이다. develop이 왜 안 됐는지 파고들었더니 결국 "develop이라는 브랜치 하나에 stage 무대 역할과 릴리즈 대기실 역할을 겹쳐 담았다"는 문제였다. Hotfix + Stage 스왑은 잠깐 이 매핑을 바꿔치기하는 방식이다. 매핑을 이해하면 왜 이 방식이 작동하는지가 자명하다.

3. 절차 문서엔 "왜"를 남겨야 한다. "어떻게"만 남긴 절차는 상황이 바뀌면 그냥 낡은 문서가 된다. "왜 Feature Flag가 아니라 이걸 골랐나"의 논리가 함께 남아 있어야, 팀 규모가 바뀌었을 때 이 결정을 재평가할 근거가 된다. 그래서 이 결정에 대해선 절차 문서(docs/guide/hotfix-workflow.md)와 회고 문서(이 글)를 따로 남겼다.

절차 자체는 프로젝트 안에 살아있는 문서로 정리해뒀다. 실제로 돌려보면서 또 배울 게 나올 것이다. 그때 이 글도 이어 붙일 예정이다.

백엔드 일지 마지막 편이다. 화려한 기능 대신 설정 파일을 꺼냈다. application.yml에 박힌 숫자들은 대부분 "기본값을 왜 바꿨는가"의 기록이기 때문이다.

기본값은 우리 사정을 모른다

프레임워크의 기본값은 "대부분의 상황에서 무난한" 값이지, "우리 상황에서 최적인" 값이 아니다. 운영하면서 기본값을 하나씩 의심했고, 바꾼 값에는 주석으로 이유를 박아뒀다. 그 이유들을 풀어본다.

3초의 철학: 빨리 실패하기

이 설정 파일에서 가장 자주 나오는 숫자는 3초다. 두 군데에 있다.

datasource:
  hikari:
    connection-timeout: 3000   # 기본 30s → 3s
data:
  redis:
    timeout: 3s                # Lettuce 기본 60s → 3s

HikariCP 30초의 문제. 커넥션 풀이 고갈됐다고 하자. 기본값이면 요청 스레드가 커넥션을 기다리며 30초씩 매달린다. 그동안 톰캣 스레드는 점유된 채고, 새 요청은 계속 쌓인다. DB가 아픈 게 앱 전체의 스레드 고갈로 번져나간다. 3초면 빨리 실패하고 스레드를 돌려준다. 사용자는 에러를 보지만, 서비스 전체가 마비되는 것보단 낫다.

Redis 60초는 더 심각했다. 우리 인증 필터는 요청마다 Redis에서 토큰 블랙리스트를 조회한다. Redis가 순단되면 기본값 기준 모든 인증 요청이 60초씩 행에 걸린다. 1편에서 "Redis 죽어도 서비스는 산다"를 설계해놨는데, 타임아웃이 60초면 그 설계가 무의미하다 — 죽진 않지만 60초 걸리는 서비스는 죽은 거나 다름없으니까.

두 값의 공통 철학: 의존성 장애는 "빨리 실패"로 격리한다. 느린 성공보다 빠른 실패가 시스템 전체엔 이롭다.

20초의 산수: graceful shutdown 예산

server:
  shutdown: graceful
lifecycle:
  timeout-per-shutdown-phase: 20s

배포하면 구버전 태스크는 SIGTERM을 받는다. graceful은 진행 중인 요청을 마저 처리하고 죽겠다는 선언인데, 문제는 얼마나 기다릴 거냐다.

이 20초는 임의의 숫자가 아니라 산수의 결과다.

ECS stop_timeout           = 30초   ← 이 안에 안 죽으면 SIGKILL (강제종료)
─────────────────────────────────
진행 중 HTTP 요청 마무리    ≈ 수 초
viewCountExecutor 큐 소진   ≤ 10초   (4편의 그 10초)
컨텍스트 정리 여유          = 나머지
─────────────────────────────────
합계                        = 20초  < 30초  ✓

20초를 30초보다 크게 잡으면? 앱이 "아직 정리 중"인데 ECS가 SIGKILL을 날린다. 진행 중이던 요청은 5xx, 큐에 있던 조회수는 유실. graceful shutdown은 앱 설정과 인프라 설정(stop_timeout)의 합의다. 한쪽만 보고 정하면 안 된다.

10의 근거: 커넥션 풀은 곱셈이다

hikari:
  maximum-pool-size: 10   # 기본값과 같지만 명시 고정

기본값이랑 같은데 왜 적어놨냐면, 이 10이 다른 계산의 입력이기 때문이다. 인프라 일지 5편의 그 계산이다.

태스크당 풀 10 × 최대 태스크 4 = 40 커넥션 ≪ RDS 한계 ≈ 85

누군가 "풀이 작네?" 하고 30으로 올리면, 오토스케일 max 4대 기준 120 커넥션 — RDS가 죽는다. 이 값은 앱 혼자 정하는 게 아니라 RDS 한계 ÷ 최대 태스크 수로 역산되는 값이라는 걸 주석으로 박아뒀다. 바꾸면 안 되는 값이 아니라, 바꿀 때 계산이 필요한 값이다.

나머지 한 줄짜리 결정들

open-in-view: false — 기본값 true는 HTTP 응답이 끝날 때까지 DB 커넥션을 물고 있는다. 뷰 렌더링에서 LAZY 로딩을 허용하기 위한 낡은 편의인데, API 서버엔 이득이 없고 커넥션 점유 시간만 는다. 10개뿐인 귀한 풀이라 더더욱. 대신 LAZY 접근은 서비스 레이어에서 fetch join과 batch size(3편)로 끝내야 한다 — false는 그 규율의 강제장치다.

default_batch_fetch_size: 100 — 3편에서 다뤘다. N+1의 안전망.

ddl-auto: validate — 스키마 변경은 Flyway만 한다(사건편 참고). Hibernate에겐 "만지지 말고 검증만 해라". 엔티티와 스키마가 어긋나면 런타임 어딘가에서 터지는 대신 부팅 시점에 죽는다. 빨리 실패의 또 다른 얼굴.

management.health.redis.enabled: false — 1편에서 다룬 헬스체크와 장애 설계의 정합. Redis는 "없어도 되는 의존성"으로 설계했으니 헬스체크도 그렇게 답해야 한다.

compression: min-response-size: 1024 — 1KB 미만 응답은 압축 안 한다. 압축에도 CPU가 들고, 작은 응답은 압축해봐야 몇 바이트라 배보다 배꼽이 크다.

배운 것

1. 설정값은 코드보다 감사(audit)받지 않는다. 코드 리뷰는 다들 열심히 하는데 yml의 숫자는 그냥 지나친다. 기본값 하나(Redis 60s)가 장애 시나리오 전체를 바꾸는데도.

2. 숫자엔 주석이 필요하다. "왜 3초인가"를 주석으로 남기지 않으면, 미래의 누군가(대부분 나)가 근거 없이 되돌린다. 계산으로 나온 값은 계산식을 함께 적는다.

3. 앱 설정은 인프라 설정과 짝이 있다. graceful 20s ↔ ECS stop_timeout 30s, 풀 10 ↔ RDS 85 ÷ 태스크 4, 헬스체크 ↔ ALB 판정. 한쪽만 고치면 짝이 깨진다. 설정 파일은 독립 문서가 아니라 인프라와의 계약서였다.

백엔드 일지는 여기까지. 인프라 8편 + 백엔드 5편, 돌아보면 결론은 하나로 수렴한다. 기본값과 초록불을 믿지 말고, 이유와 실측만 믿기. 다음 글은 또 사건이 터지면 돌아오겠다. (안 터지는 게 최선이지만.)

이번 편은 "조회수 +1"이라는, 요구사항 한 줄짜리 기능이다. 그런데 이 한 줄이 트랜잭션·비동기·백프레셔를 전부 소환했다. 그 과정을 남긴다.

순진한 버전에서 시작

첫 구현은 누구나 떠올리는 그대로였다. 상세 조회 트랜잭션 안에서 UPDATE.

상세 조회 트랜잭션 {
    콘텐츠 SELECT
    viewCount UPDATE +1   ← 여기
}

동작한다. 그런데 곱씹을수록 이상했다.

첫째, 조회 API에 쓰기가 섞인다. 읽기 트랜잭션이 쓰기 락을 잡는다. 같은 콘텐츠를 여럿이 동시에 열면 같은 행의 UPDATE 락을 두고 줄을 선다. 인기 콘텐츠일수록 상세 조회가 느려지는, 이상한 역설이 생긴다.

둘째, 주객이 전도된다. 조회수 UPDATE가 실패하면 상세 조회까지 실패한다. 사용자 입장에선 "화면이 안 뜨는" 대형 문제가, 고작 카운트 때문에 생기는 거다.

조회수의 본질을 정리하면 이렇다. 정확성보다 응답 속도가 중요하고, 하나쯤 유실돼도 아무도 안 죽는 데이터. 그렇다면 설계도 그 본질을 따라가야 한다.

분리 1단계: 이벤트로 떼어내기

메인 로직에서 카운트를 떼어내는 도구로 Spring의 이벤트를 썼다. 그냥 @EventListener가 아니라 @TransactionalEventListener다.

@Async("viewCountExecutor")
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void handle(ContentViewedEvent event) {
    viewCountService.increment(event.contentType(), event.contentId());
}

AFTER_COMMIT이 핵심이다. 메인 트랜잭션이 커밋된 뒤에만 리스너가 돈다.

• 메인이 롤백되면? → 이벤트도 안 돈다. 실패한 조회에 카운트가 오르는 정합성 깨짐 방지.
• 그냥 @EventListener였다면? → 메인 트랜잭션 안에서 동기 실행. 떼어낸 의미가 없다.

분리 2단계: 스레드까지 떼어내기

AFTER_COMMIT만으론 부족하다. 커밋 후라도 같은 스레드에서 돌면 카운트 UPDATE가 끝나야 응답이 나간다. 그래서 @Async를 얹었다.

여기서 결정 포인트 — 전용 Executor를 만들었다.

@Bean(name = "viewCountExecutor")
public Executor viewCountExecutor() {
    executor.setCorePoolSize(2);       // 카운트 작업은 짧고 가볍다
    executor.setMaxPoolSize(5);
    executor.setQueueCapacity(500);
    executor.setRejectedExecutionHandler(new CallerRunsPolicy());
    executor.setWaitForTasksToCompleteOnShutdown(true);
    executor.setAwaitTerminationSeconds(10);
}

숫자마다 이유를 붙이면:

core 2 / max 5 — 카운트는 UPDATE 한 방짜리 초경량 작업이다. 큰 풀은 낭비고, 무엇보다 이 스레드들도 결국 DB 커넥션을 쓴다. 인프라 일지 5편에서 계산한 태스크당 커넥션 10개 예산 안에서, 비동기 풀이 커넥션을 얼마나 점유할 수 있는지가 상한을 정한다. 비동기 풀 크기는 사실 DB 커넥션 계산의 연장선이다.

queue 500 + CallerRunsPolicy — 큐가 가득 차면 어떻게 할 것인가. 기본 정책(AbortPolicy)은 예외를 던진다 → 카운트 유실. 그 대신 CallerRunsPolicy는 요청 스레드가 직접 그 작업을 실행한다. 순간적으로 응답이 조금 느려지는 대가로, 유실 없이 밀린 속도를 따라잡는다. 생산 속도를 소비 속도에 맞춰 끌어내리는 자연스러운 백프레셔다.

shutdown 대기 10초 — 배포로 SIGTERM을 받았을 때 큐에 남은 카운트를 버리지 않고 최대 10초 기다린다. 이 10초는 다음 편에서 다룰 graceful shutdown 예산(20초) 안에 들어가도록 맞춘 숫자다.

조용히 죽는 예외 잡기

@Async + void 반환의 함정이 하나 있다. 예외가 조용히 사라진다. 호출자는 이미 응답하고 떠났으니 예외를 받을 사람이 없다.

이중 안전망을 깔았다.

// 1차: 리스너 안에서 직접 catch — 개별 실패는 로그만 남기고 흡수
catch (Exception e) {
    log.error("viewCount increment failed contentType={} contentId={}", ...);
}

// 2차: AsyncUncaughtExceptionHandler — 1차를 새는 예외의 최종 안전망

카운트 하나의 실패는 흡수하되, 로그는 반드시 남긴다. "유실돼도 되는 데이터"와 "유실을 몰라도 되는 데이터"는 다르다. 로그가 있으면 단발 유실인지, 뭔가 구조적으로 깨진 건지 구분할 수 있다.

남은 조각: 집계는 스케줄러로

원본 카운트가 쌓이면 일간 인기 목록 같은 집계가 필요해진다. 집계는 요청 시점이 아니라 스케줄러가 주기적으로 계산해 Redis에 얹는다.

여기서 인프라 일지 5편의 복선이 회수된다. 태스크가 2~4대로 늘어나는 환경에서 스케줄러가 대마다 돌면 집계가 중복 실행된다. ShedLock(Redis 분산락)으로 "한 시점에 한 대만"을 보장했다. 스케줄 코드에 애너테이션 하나지만, 이게 없으면 오토스케일링이 스케줄러의 버그 트리거가 된다.

그리고 집계 조회엔 DB fallback을 뒀다. Redis에 집계가 없으면(만료·장애) 그 자리에서 DB로 계산해 응답하고 다시 캐싱한다. 1편의 "캐시 실패는 miss로 강등" 원칙이 여기서도 반복된다.

배운 것

1. 데이터의 본질이 설계를 정한다. 조회수는 "빠르고 대충"이 맞는 데이터다. 본질이 그런데 구현이 "느리고 정확"하면 설계가 틀린 거다.

2. AFTER_COMMIT과 @Async는 분리의 축이 다르다. 전자는 트랜잭션 결과와의 분리(롤백 시 미실행), 후자는 응답 시간과의 분리. 하나만 쓰면 반쪽짜리 분리가 된다.

3. 비동기 풀의 거부 정책은 "실패 모드 선택"이다. Abort는 유실, CallerRuns는 지연. 어느 쪽이 덜 아픈지는 데이터마다 다르다. 조회수는 "잠깐 느려도 유실 없음"을 골랐다.

다음 편이 백엔드 일지 마지막이다. application.yml에 박힌 숫자들 — 3초, 20초, 100, 10 — 하나하나에 붙은 이유를 전부 푼다.

2편에서 검색 인덱스를 정리했다. 이번엔 그 검색 결과를 "어떻게 나눠 주느냐" — 페이징 이야기다. 교과서의 OFFSET 방식을 버리고 커서로 간 기록.

OFFSET의 조용한 비용

페이징의 기본형은 다들 이렇게 배운다.

SELECT * FROM content ORDER BY id DESC LIMIT 20 OFFSET 10000;

이 쿼리의 함정은 OFFSET의 동작 방식에 있다. DB는 10,020행을 읽어서 10,000행을 버린다. 건너뛰는 게 아니라 읽고 버린다.

• 1페이지: 20행 읽음
• 500페이지: 10,020행 읽고 10,000행 폐기

뒤 페이지로 갈수록 느려지는 구조적 비용이고, 무한 스크롤 UI에서는 사용자가 스크롤할수록 서버가 무거워진다는 뜻이 된다.

하나 더 있다. 행이 밀리는 문제. 사용자가 2페이지를 보는 사이 새 콘텐츠가 등록되면 전체 행이 한 칸씩 밀린다. 3페이지를 요청하면 2페이지 마지막 항목이 중복돼 나온다. 무한 스크롤에서 같은 카드가 두 번 보이는 버그의 고전적 원인이다.

커서: "몇 번째부터"가 아니라 "어디 다음부터"

커서(keyset) 방식은 질문을 바꾼다.

-- OFFSET: "10,000번째부터 20개 줘"
-- 커서:   "id 12345보다 작은 것부터 20개 줘"
WHERE (:cursor IS NULL OR id < :cursor)
ORDER BY id DESC
LIMIT :size

id < :cursor는 인덱스(PK)를 타고 시작점으로 점프한다. 읽고 버리는 게 없다. 1페이지든 500페이지든 비용이 같고, 중간에 행이 끼어들어도 "이 id 다음"이라는 기준은 안 밀리니 중복도 없다.

첫 요청은 커서 없이(:cursor IS NULL) 오고, 응답의 마지막 항목 id가 다음 요청의 커서가 된다. 클라이언트는 "마지막으로 본 것"만 기억하면 된다.

진짜 어려운 건 정렬 기준이 id가 아닐 때

최신순은 id 커서로 끝난다. 문제는 좋아요순 정렬이었다.

좋아요 수는 유일하지 않다. 좋아요 10개짜리가 서른 개면, likeCount < 10으로 끊는 순간 같은 10개짜리 나머지가 전부 건너뛰어진다.

해법은 복합 커서다. 정렬 기준 + 유일한 타이브레이커(id)를 쌍으로 쓴다.

WHERE (:lastLikeCount IS NULL
       OR likeCount < :lastLikeCount
       OR (likeCount = :lastLikeCount AND id < :lastId))
ORDER BY likeCount DESC, id DESC

풀어 읽으면: "좋아요가 더 적거나, 좋아요가 같다면 id가 더 작은 것부터". 정렬 순서(likeCount DESC, id DESC)와 커서 조건이 정확히 같은 순서를 표현해야 한다. 이 둘이 어긋나면 중복이나 누락이 조용히 생긴다.

커서 방식의 대가도 여기서 드러난다. "몇 페이지로 점프"가 안 된다. 항상 "다음"만 있다. 무한 스크롤에는 완벽하지만, 페이지 번호 UI가 필요했다면 OFFSET과의 하이브리드를 고민했을 거다. 우리는 스크롤 UI라 고민이 없었다.

페이징을 고쳐도 N+1이면 도루묵

커서로 20행을 가볍게 가져와도, 각 행의 연관 엔티티(작성자·장르)를 LAZY 로딩으로 하나씩 긁으면 쿼리가 1 + 20 + 20개가 된다. 악명 높은 N+1.

1차 방어는 fetch join이다. 리스트 쿼리에서 항상 쓰는 연관은 한 방에 가져온다.

SELECT c FROM Content c
LEFT JOIN FETCH c.member
LEFT JOIN FETCH c.genre
WHERE ...

2차 방어는 설정 한 줄이다.

hibernate:
  jdbc:
    default_batch_fetch_size: 100

fetch join이 못 덮는 경로(다른 서비스에서 재사용될 때, 컬렉션 연관 등)에서 LAZY 로딩이 발생하면, 프록시를 하나씩 조회하는 대신 IN (100개) 쿼리로 묶는다. N+1이 N/100+1이 되는 안전망이다.

역할을 나누면: fetch join은 "설계된 경로"의 최적화, batch size는 "설계 밖 경로"의 보험. 전자만 믿으면 언젠가 새 코드가 N+1을 다시 만들고, 후자만 믿으면 최적 경로도 쿼리가 2개가 된다. 둘 다 필요하다.

배운 것

1. OFFSET은 "읽고 버리는" 비용이다. 페이지가 뒤로 갈수록, 데이터가 쌓일수록 선형으로 느려진다. 무한 스크롤이면 커서가 구조적으로 맞다.

2. 커서는 정렬 기준의 유일성이 생명이다. 유일하지 않은 컬럼으로 정렬하면 반드시 타이브레이커(id)를 커서에 포함하고, WHERE 조건이 ORDER BY와 같은 순서를 표현하는지 검증해야 한다.

3. 페이징 최적화와 N+1 방어는 세트다. 행을 가져오는 비용을 줄여도 행당 추가 쿼리가 남으면 의미가 없다. fetch join(설계된 경로) + batch fetch size(안전망)의 이중 구조로 막았다.

다음 편은 조회수다. "카운트 1 올리기"라는 사소해 보이는 요구사항에 트랜잭션 이벤트, 비동기 풀, 백프레셔까지 동원하게 된 이유.

1편은 캐시였고, 이번엔 검색이다. 인프라 일지 5편의 부하 테스트에서 "가장 무거운 API = 검색"이었던 이유와, 그걸 어떻게 인덱스로 풀었는지.

문제의 쿼리

검색 기능의 핵심 조건은 이거다. 대소문자 무시 + 부분 일치.

WHERE LOWER(title) LIKE LOWER('%검색어%')

동작은 잘 한다. 문제는 실행 계획이다. sequential scan — 테이블 전체를 훑는다.

흔히 아는 규칙대로다. B-tree 인덱스는 정렬된 자료구조라서 LIKE '검색어%'(전방 일치)는 타지만, '%검색어%'(중간 일치)는 못 탄다. "어디서부터 찾을지"를 정할 수 없기 때문이다.

부하 테스트에서 검색이 CPU 바운드 1순위였던 이유가 여기 있다. 데이터가 적을 땐 풀스캔도 빠르다. 그런데 풀스캔의 비용은 데이터에 비례해서 자란다. 지금 안 터졌다고 두면, 언젠가 반드시 터지는 유형의 부채다.

반은 틀린 말: pg_trgm

"'%검색어%'는 인덱스 못 탄다"는 B-tree 한정의 이야기다. PostgreSQL에는 pg_trgm이라는 확장이 있다.

원리는 단순하다. 문자열을 3글자 단위 조각(trigram)으로 쪼개서 색인한다.

"backend" → "  b", " ba", "bac", "ack", "cke", "ken", "end", "nd "

검색어도 같은 방식으로 쪼갠 뒤, 조각이 겹치는 행만 후보로 추린다. 중간 일치라도 조각 단위로는 "어디서 찾을지"가 정의되는 거다. 이걸 GIN(역색인) 인덱스에 얹으면 LIKE '%검색어%'가 인덱스를 탄다.

CREATE EXTENSION IF NOT EXISTS pg_trgm;

참고로 RDS에서는 이 CREATE EXTENSION에 rds_superuser 권한이 필요해서, 마이그레이션이 실행되는 계정 권한을 미리 확인해야 한다. (여기서 한 번 막혔다.)

함정 하나: LOWER()가 인덱스를 무력화한다

그냥 컬럼에 GIN 인덱스를 걸면 될 것 같지만, 우리 쿼리는 LOWER(title)이다. 인덱스는 title에 걸려 있는데 쿼리는 LOWER(title)을 찾으니 매치가 안 된다.

인덱스는 컬럼이 아니라 표현식에도 걸 수 있다. 쿼리에 쓴 표현식 그대로.

CREATE INDEX idx_content_title_trgm
    ON content USING GIN (LOWER(title) gin_trgm_ops)
    WHERE deleted_at IS NULL;

쿼리의 LOWER(title)과 인덱스의 LOWER(title)이 글자 그대로 일치해야 플래너가 인덱스를 집어든다. 인덱스는 쿼리를 따라가야지, 그 반대가 아니다.

함정 둘: 지운 데이터까지 색인할 필요는 없다

위 DDL의 마지막 줄, WHERE deleted_at IS NULL — partial index다.

우리 서비스는 soft delete를 쓴다. 지워진 행도 테이블엔 남는다. 그런데 검색 쿼리는 항상 활성 행만 대상으로 한다. 그럼 인덱스도 활성 행만 색인하면 된다. 삭제된 행 몫의 인덱스 크기와 갱신 비용이 통째로 빠진다.

이 partial index는 다른 곳에서 더 재밌게 쓰였다. UNIQUE 제약이다.

-- 문제: 탈퇴(soft delete)한 회원의 소셜 ID·닉네임이 UNIQUE에 계속 잡혀서
--       같은 계정으로 재가입하면 UNIQUE violation → 500
CREATE UNIQUE INDEX uk_member_provider_active
    ON member (provider, provider_id) WHERE deleted_at IS NULL;

일반 UNIQUE 제약은 지워진 행까지 포함해 유일성을 강제한다. 탈퇴한 회원이 재가입을 못 하는 버그의 정체가 이거였다. partial unique index로 바꾸면 "활성 행끼리만 유일"이 된다. 탈퇴 행은 유일성 검사 대상에서 빠지니 재가입이 자연스럽게 풀린다.

soft delete를 쓰는 순간, 모든 UNIQUE 제약은 "전체 행 기준인가, 활성 행 기준인가"를 다시 물어야 한다.

적용 범위: 전부 걸지 않았다

trigram 인덱스를 검색 가능한 모든 컬럼에 걸진 않았다.

사용자 검색 (고빈도):  콘텐츠 3종의 title       → 즉시 적용
어드민 검색 (저빈도):  닉네임, 댓글 본문        → 풀스캔 회피 목적으로만

GIN 인덱스는 공짜가 아니다. 쓰기마다 trigram 분해·색인 갱신 비용이 붙는다. 고빈도 검색엔 확실한 이득이고, 저빈도 검색엔 "최악(풀스캔) 방지"만 노렸다.

배운 것

1. "인덱스 못 탄다"는 대부분 "B-tree로는"의 줄임말이다. 인덱스 종류(GIN, GiST, BRIN...)마다 잘하는 질문이 다르다. 쿼리 패턴에 맞는 인덱스를 고르는 게 튜닝의 시작이다.

2. 인덱스는 쿼리와 글자 단위로 맞아야 한다. LOWER() 하나로 인덱스가 무력화된다. 표현식 인덱스는 쿼리에 쓴 표현식을 그대로 복사해 만든다.

3. soft delete는 인덱스 전략을 바꾼다. 검색 인덱스는 partial로 작게, UNIQUE는 partial로 "활성 행만 유일"로. deleted_at IS NULL이 붙은 인덱스가 늘어나는 건 자연스러운 결과다.

다음 편은 페이징이다. OFFSET 10000이 왜 뒤로 갈수록 느려지는지, 그리고 커서 방식으로 갈아탄 이유.

인프라 구축 일지는 끝났고, 이번엔 그 위에서 돌아가는 애플리케이션 이야기다. 첫 주제는 캐시. Redis를 붙이는 건 쉬운데, "Redis가 아플 때"를 설계하는 게 진짜 일이었다.

캐시를 붙인 이유부터

메인 화면은 조회가 압도적으로 많고, 내용은 자주 안 바뀐다. 리스트 첫 페이지, 추천 목록, 배너 — 매 요청마다 DB를 때릴 이유가 없다. Spring Cache + Redis 조합으로 @Cacheable을 붙였다. 여기까진 교과서다.

문제는 그 다음부터였다.

TTL은 하나가 아니다

처음엔 전부 1시간 TTL이었다. 그런데 성격이 다른 데이터가 섞여 있었다.

기본 TTL:        1시간   (추천·배너 — 어드민이 바꿀 때만 변함)
리스트 캐시:     3분     (사용자가 등록하면 바로 보여야 함)

리스트에 1시간 TTL을 주면, 사용자가 콘텐츠를 등록하고 나서 "내 것이 목록에 없는데요?"가 최대 1시간 지속된다. 반대로 추천·배너에 3분을 주면 히트율만 떨어진다.

TTL은 "이 데이터가 얼마나 오래 틀려도 되는가"에 대한 답이다. 데이터마다 답이 다르면 TTL도 달라야 한다.

TTL만 믿을 수 없는 경우: 삭제

3분 TTL이라도 못 기다리는 경우가 있다. 콘텐츠 삭제·제재다. 내려간 콘텐츠가 리스트에 3분, 추천·배너에 1시간 떠 있는 건 곤란하다.

그래서 삭제 흐름에 캐시 무효화를 명시적으로 넣었다.

public void evict(ContentType type) {
    clear(cacheName(type));      // 해당 타입 리스트 캐시
    clear(RECOMMENDATIONS);      // 추천 (삭제 cascade에 걸릴 수 있음)
    clear(BANNERS);              // 배너 (동일)
}

포인트는 @CacheEvict 애너테이션이 아니라 프로그래매틱 방식을 쓴 것. 회원 탈퇴 cascade에선 삭제되는 콘텐츠 타입이 런타임에 결정되기 때문에 애너테이션으로는 못 박을 수가 없었다.

그리고 추천 캐시는 키별로 골라 지우지 않고 통째로 clear 한다. 키 매칭 로직을 정교하게 만드는 비용 대비, 재계산 비용이 무시할 수준이라서다. 무효화는 정밀함보다 확실함이 우선이다.

본론: Redis가 죽으면 어떻게 되나

여기서부터가 이 글을 쓴 이유다. 어느 날 자문해봤다. "Redis가 내려가면 우리 서비스는 어떻게 되지?"

기본 동작을 확인해보니 끔찍했다. @Cacheable은 메서드 실행 전에 캐시를 조회하는데, 이 조회가 예외를 던지면 그대로 500이 된다. 캐시는 최적화하려고 붙인 건데, 캐시 장애가 서비스 장애가 되는 구조였다.

더 음험한 경우도 겪었다. 응답 DTO에 등록일(LocalDateTime) 필드를 추가했는데, 직렬화기에 JavaTimeModule이 빠져 있어서 캐시 저장이 깨졌다. 코드를 고쳐 배포해도 — 깨진 엔트리가 Redis에 남아 있는 한, @Cacheable이 메서드 실행 전에 그 엔트리를 읽다가 계속 500을 냈다. 새 코드가 실행될 기회 자체가 없는 거다.

해법: 실패를 cache miss로 강등

Spring Cache에는 CacheErrorHandler라는 확장점이 있다. 여기에 원칙 하나를 심었다.

캐시는 어디까지나 최적화 레이어다. 캐시 실패가 응답을 막으면 안 된다.

public void handleCacheGetError(RuntimeException e, Cache cache, Object key) {
    log.warn("캐시 GET 실패 → miss 강등 + 깨진 엔트리 evict. ...");
    try {
        cache.evict(key);   // 깨진 엔트리 제거 → 다음 요청이 정상 값 재기록
    } catch (RuntimeException evictException) {
        log.warn("evict도 실패 (TTL 만료 대기). ...");
    }
}

동작을 풀면:

GET 실패  → miss 취급 + 깨진 키 evict → DB 조회 → 정상 값 재기록 (자가 치유)
PUT 실패  → 캐싱 없이 응답만 진행 (다음 요청이 재시도)
EVICT 실패 → 이건 error 로그 — stale 데이터가 TTL 동안 남는 실질 위험

GET/PUT 실패는 warn, EVICT 실패만 error로 로그 레벨을 갈랐다. GET 실패는 성능 저하일 뿐이지만, EVICT 실패는 틀린 데이터가 노출되는 문제라 사람이 봐야 할 수도 있기 때문이다. 같은 "캐시 실패"라도 결과의 무게가 다르다.

특히 GET 실패 시 evict를 같이 하는 게 핵심이다. 위의 LocalDateTime 사건처럼 깨진 엔트리가 박혀 있으면, miss 강등만으론 매 요청이 DB로 가는 상태가 TTL 내내 지속된다. 깨진 키를 지워버리면 다음 요청이 정상 값을 다시 써넣으면서 캐시가 스스로 낫는다.

마지막 퍼즐: 헬스체크

Redis 장애 대응이 앱 레벨에서 끝나도, 인프라가 배신할 수 있다.

기본 설정의 /actuator/health는 Redis 상태를 포함한다. Redis가 죽으면 헬스체크가 DOWN → ALB가 태스크를 비정상으로 판정 → 태스크 교체 → 새 태스크도 Redis에 못 붙으니 또 DOWN → 교체 무한 루프. 앱은 캐시 없이 버틸 수 있게 만들어놨는데, ALB가 멀쩡한 앱을 계속 죽이는 그림이다.

management:
  health:
    redis:
      enabled: false   # 헬스체크에서 Redis 제외

"Redis 없이도 응답할 수 있다"고 설계했으면, 헬스체크의 정의도 그 설계에 맞춰야 한다. 헬스체크는 "필수 의존성"만 물어야 한다.

배운 것

1. 캐시 설계의 절반은 "장애 시나리오"다. 붙이는 건 애너테이션 하나. 진짜 설계는 GET/PUT/EVICT 각각이 실패했을 때 서비스가 어떻게 되는지 정의하는 일이었다.

2. 깨진 캐시 엔트리는 배포로 안 고쳐진다. 코드를 고쳐도 캐시에 남은 과거의 산물이 계속 터진다. 자가 치유(evict on error)를 넣거나, 최소한 캐시 키에 버전을 태워야 한다.

3. 앱의 장애 설계와 인프라의 장애 판정을 맞춰야 한다. 앱은 "Redis 없이 버틴다"인데 헬스체크는 "Redis 없으면 죽음"이면, 더 정교한 쪽 설계가 무력화된다.

다음 편은 검색이다. LIKE '%검색어%'는 인덱스를 못 탄다는 말, 반은 맞고 반은 틀리다 — PostgreSQL pg_trgm 이야기.

구축 일지 마지막 편이다. 인프라는 다 만들어져 있었다. 문제는 "이대로 열어도 되나?"에 답하는 일이었다.

"다 됐다"와 "열어도 된다"의 간극

기능 개발이 끝나고 오픈 일정이 잡히면, 이상하게 그때부터 불안해진다. 개발 환경에선 편했던 것들이 운영에선 구멍이 되기 때문이다. 오픈 전 마지막 주에 한 것들을 영역별로 훑어보며 정리한다.

1. 문 잠그기: 운영 Swagger 차단

개발 내내 잘 쓰던 Swagger UI. API 명세를 브라우저로 보고 바로 호출해볼 수 있어 편하다. 그런데 그 "편함"이 운영에서는 그대로 공격자의 편함이 된다. 전체 API 목록, 파라미터 구조, 응답 스키마가 인증도 없이 공개되는 셈이니까.

방법이 고민이었다. 조건에 따라 코드를 바꾸는 건 싫었다. 같은 코드가 환경마다 다르게 동작하면 "스테이징에선 됐는데" 류의 문제가 생긴다.

결론은 환경변수 스위치였다. terraform이 운영 태스크에만 비활성 플래그를 주입한다.

코드:        모든 환경에서 동일 (springdoc enabled 여부만 env로)
스테이징:    Swagger 살아있음 (개발 편의 유지)
운영:        terraform이 SPRINGDOC_*_ENABLED=false 주입

적용하고 끝이 아니라 실측했다. Swagger 관련 4개 경로 (/swagger-ui.html, /swagger-ui/**, /v3/api-docs 등)를 운영 도메인에 직접 요청해서 전부 404인 걸 확인했다. "설정했으니 됐겠지"는 5편의 부하 테스트에서 이미 버린 습관이다.

2. 판 갈기: DB 리셋

베타 기간 동안 운영 DB엔 테스트 데이터가 쌓여 있었다. 실험 계정, 더미 데이터, 시행착오 흔적들. 정식 오픈은 깨끗한 판에서 시작하기로 했다.

① 스키마 전체 DROP
② 앱 재기동 → Flyway가 V1부터 순서대로 마이그레이션 재실행
③ 어드민 초기 계정은 시크릿 저장소 값으로 자동 재생성

포인트는 ②다. 백업을 복원하는 게 아니라 마이그레이션 이력으로 스키마를 처음부터 재구성했다. 이게 되려면 V1부터 최신까지의 마이그레이션이 빈 DB에서 한 번에 완주할 수 있어야 하는데, 실제로 완주했다. "우리 DB 스키마는 코드(마이그레이션 파일)만으로 재현 가능하다"는 게 증명된 순간이라 꽤 뿌듯했다.

③도 같은 맥락이다. 어드민 계정을 수동으로 만들지 않고, 앱이 기동하며 시크릿 저장소의 초기값으로 생성한다. 리셋 후 사람 손이 갈 일이 없었다.

그런데 — 시리즈 첫 글을 읽었다면 눈치챘겠지만, 이 리셋이 나중에 Flyway 사건의 복선이 된다. 운영은 리셋된 빈 DB, 스테이징은 리셋 안 한 DB. 이 상태 차이가 얼마 뒤 "운영은 통과하고 스테이징만 실패하는 마이그레이션"을 만들었다. 그때는 몰랐다. 환경 간 DB 상태를 갈라놓는 결정은 이렇게 시한부 부채가 되기도 한다.

3. 마지막 감사: 전 영역 훑기

오픈 결정 전에 영역별로 최종 점검을 돌았다. 요약하면 이런 체크리스트였다.

네트워크·접근 통제

• 외부 진입점이 ALB 하나뿐인가 (1편 구조 그대로인지 재확인)
• DB 서브넷에 인터넷 라우트가 없는가
• 어드민 API는 IP allowlist로 제한되는가

시크릿·노출면

• 코드·이미지·리포지토리에 평문 시크릿이 없는가 (3편)
• 운영 Swagger·API Docs 차단 (위 1번)
• 프런트 운영 빌드에서 소스맵 제외

확장·가용성

• 오토스케일링 실증 완료 — 포화점 실측 + 증설 동작 확인 (5편)
• 다중 인스턴스 안전성 — 스케줄러 분산락, JWT 무상태, DB 커넥션 계산
• 배포 실패 시 자동 롤백(서킷 브레이커) 동작

관측

• 알람 6종(CPU·메모리·5xx·RDS) + SNS 이메일 수신 확인 — 실제로 테스트 메일까지 받아봄
• ALB 액세스 로그 S3 90일 보존 (사고 시 포렌식용)

여기서도 원칙은 같았다. 항목마다 "설정돼 있다"가 아니라 "확인했다"로 체크했다. 알람은 SNS 구독 확인 메일을 실제로 받았고, Swagger는 404를 실제로 봤고, 오토스케일링은 증설 이벤트 로그를 실제로 읽었다.

4. 안 한 것들도 기록해뒀다

전부 다 하고 연 건 아니다. 의도적으로 미룬 것들이 있다.

• RDS Multi-AZ: 비용 대비 현재 트래픽 규모에선 과하다고 판단. 장애 시 복구 절차만 문서화
• NAT 게이트웨이 이중화: 같은 이유로 단일 구성 유지
• WAF 패턴 규칙 일괄 BLOCK: 오탐 관측을 거쳐 규칙별로 순차 승격하기로 (6편)

중요한 건 "몰라서 안 한 것"과 "알고 미룬 것"을 구분해 적어두는 거였다. 후자는 트래픽이 늘거나 요구사항이 바뀌면 꺼내 쓸 수 있는 대기 목록이 된다.

시리즈를 마치며

혼자 인프라를 구축하면서 가장 크게 남은 건 기술 지식보다 태도에 가깝다.

"설정했다"를 믿지 말고 "확인했다"만 믿기. 부하 테스트와 증설 이벤트 로그(5편), Swagger 404 실측과 알람 수신 확인(이번 편) — 전부 같은 원칙의 반복이었다. 그리고 이 원칙이 무너진 지점에서 정확히 사고가 났다. stage 배포가 5주간 조용히 롤백되던 Flyway 사건은 "초록불 = 반영됨"을 확인 없이 믿은 대가였다.

인프라는 만드는 것보다 의심하는 게 일이다. 이 시리즈가 누군가의 "이대로 열어도 되나?"에 체크리스트 하나라도 보태면 충분하다.

구축 일지는 여기까지. 운영하면서 생기는 사건들은 (첫 글의 Flyway 삽질기처럼) 사건이 생길 때마다 따로 남길 예정이다.

구축이 끝나면 운영이 시작된다. 오픈 이후 매일 아침 반복하는 4종 점검 루틴과, 로그를 "읽는 기준"을 정한 이야기다.

대시보드를 열지 않기로 했다

오픈 직후엔 불안해서 CloudWatch 콘솔을 하루에도 몇 번씩 열었다. 그런데 콘솔을 돌아다니는 건 시간도 걸리고, 볼 때마다 보는 범위가 달랐다. 어제는 알람을 봤는데 오늘은 로그만 봤다든가.

그래서 점검을 고정된 질문 4개로 정형화했다. 매일 같은 명령, 같은 범위, 같은 기준. CLI로 병렬 실행하면 5분 안에 끝난다.

4종 점검

① 발령 중인 알람이 있나

aws cloudwatch describe-alarms --state-value ALARM

CPU·메모리·5xx·RDS 커넥션 등 걸어둔 알람 중 지금 울리는 게 있는지. 정상이면 빈 배열. 뭐라도 나오면 그날 점검은 여기서 방향이 바뀐다.

② 지난 24시간 ERROR/WARN 로그

aws logs filter-log-events \
  --log-group-name "/ecs/<백엔드 로그그룹>" \
  --filter-pattern "?ERROR ?WARN" \
  --start-time <24시간 전 epoch>

전체 로그를 다 보는 게 아니라 ERROR와 WARN만 거른다. (해석 기준은 아래에서.)

③ ALB 5xx 카운트

aws cloudwatch get-metric-statistics \
  --namespace AWS/ApplicationELB \
  --metric-name HTTPCode_Target_5XX_Count ...

앱이 5xx를 뱉은 게 한 건이라도 있는지. 목표는 매일 0건, 지금까지 0건 유지 중이다.

④ ECS 서비스 상태

aws ecs describe-services --cluster <클러스터> --services <서비스>

running == desired인지, 이벤트에 재시작·롤백 흔적이 없는지.

진짜 어려운 건 "읽는 기준"

명령 4개는 금방 만든다. 어려운 건 결과를 보고 무엇을 무시할지 정하는 거였다.

②번의 WARN 로그를 예로 들면, 매일 이런 게 몇 건씩 나온다.

WARN ... BusinessException: INVALID_REFRESH_TOKEN
WARN ... BusinessException: ALREADY_REGISTERED
WARN ... BusinessException: INVALID_URL

처음엔 WARN이라는 글자만 보고 긴장했는데, 뜯어보면 이건 정상 동작이다. 만료된 토큰으로 갱신을 시도했다거나, 이미 등록된 콘텐츠를 또 등록하려 했다거나 — 전부 예상된 사용자 시나리오고, 전역 예외 핸들러가 잡아서 4xx로 응답한 흔적이다. 앱이 아프다는 신호가 아니라 앱이 일하고 있다는 신호다.

그래서 기준을 이렇게 세웠다.

무해한 로그가 알려준 것

마지막 줄의 "짧은 시간 반복"이 실제로 걸린 적이 있다. 어느 날 INVALID_URL이 21초 동안 7건 찍혔다.

서버 입장에선 전부 정상 처리된 무해 로그다. 그런데 상상해보면 — 한 사용자가 URL을 붙여넣고, 거부당하고, 다시 시도하고, 또 거부당하고... 를 21초간 7번 반복한 그림이다. 서버는 멀쩡한데 사용자는 고통받고 있었다.

이 관찰이 계기가 되어 파고들었더니, https://를 빼고 URL을 입력하면 무조건 거부되는 파싱 버그가 나왔다. (공교롭게도 오픈 전 준비 기간에 비슷한 URL 파싱 수정을 stage에서 확인하려다 더 큰 사건을 만난 적이 있다 — 시리즈 첫 글의 Flyway 삽질기다.)

에러 로그가 아니라 무해한 로그의 패턴이 버그를 찾아준 셈이다.

이 루틴이 못 잡는 것

정직하게 적어두면, 이 4종 점검엔 사각지대가 있다.

오픈 전에 겪은 Flyway 사건이 증명했듯 — stage 배포가 5주간 조용히 롤백되는 유형의 실패는 이런 점검으로 못 잡는다. 알람 없음, 5xx 없음, ECS 정상, 에러 로그 없음. 이 점검은 전부 "서비스가 살아있는가"를 묻는 질문이고, "새 버전이 반영됐는가"는 묻지 않기 때문이다.

그래서 지금은 배포 직후엔 별도로 확인한다: 배포 이벤트 이력과 실행 중인 태스크의 이미지가 방금 푸시한 커밋인지. 점검 루틴은 만능이 아니라, "무엇을 묻는 질문들의 집합인지"를 알고 써야 한다.

배운 것

1. 점검은 정형화해야 지속된다. "틈날 때 콘솔 보기"는 3일이면 무너진다. 같은 질문 4개를 매일 던지니 평소의 모습(baseline)이 몸에 익고, 이상이 눈에 띄기 시작했다.

2. 로그 읽기의 핵심은 무시할 것을 정하는 것이다. 모든 WARN에 반응하면 진짜 신호를 놓친다. "무해 목록"을 명시적으로 정해두니 나머지에 집중할 수 있었다.

3. 무해한 로그도 모이면 신호다. 개별로는 정상인 이벤트의 반복 패턴이 UX 버그를 찾아줬다. 서버 관점의 "정상"과 사용자 관점의 "정상"은 다르다.

4. 점검 루틴의 한계를 아는 것도 점검의 일부다. 초록불 4개가 "전부 정상"이 아니라 "이 4가지 질문에 한해 정상"이라는 걸 잊으면 안 된다.

다음 편이 구축 일지의 마지막이다. 서비스 오픈 직전에 했던 점검들 — Swagger 차단, DB 리셋, 그리고 런칭 체크리스트.

5편까지는 "만든" 이야기였다. 이번엔 서비스를 오픈하고 나서 실제로 들어온 공격과, 그걸 막은 기록이다.

오픈하면 스캐너부터 온다

서비스를 인터넷에 열면 사람보다 봇이 먼저 온다는 말이 있는데, 진짜였다. 오픈 직후부터 ALB 액세스 로그에 이런 요청들이 찍히기 시작했다.

GET /.env
GET /wp-login.php
GET /phpinfo.php
GET /config.json
...

우리는 Spring Boot 서비스다. 워드프레스도 아니고 PHP도 없다. 이건 특정 대상을 노린 게 아니라, 인터넷 전체를 훑으며 "아무 데나 걸려라" 식으로 알려진 취약점을 자동으로 찔러보는 스캐너다.

발신지를 추려보니 반복 소스가 둘로 좁혀졌다.

• 싱가포르의 VPS 한 대 (단일 IP)
• 프랑스 호스팅 업체의 대역 하나 (여러 IP를 바꿔가며 시도)

미리 깔아둔 그물: WAF 규칙 구성

다행히 WAF는 오픈 전에 ALB 앞에 걸어둔 상태였다. 규칙은 우선순위 순으로 이렇다.

BLOCK과 COUNT가 섞여 있는 게 포인트다. 기준은 오탐 위험이다.

• IP 기반 규칙(rate limit, 평판)은 오탐이 거의 없다 → 즉시 BLOCK
• 패턴 탐지형(SQLi, XSS)은 정상 요청을 오인할 수 있다 → 일단 COUNT로 관측만

COUNT 규칙은 지표만 쌓고 요청은 통과시킨다. 오탐이 없는 걸 확인한 규칙부터 순차적으로 BLOCK 승격하는 전략이다. 처음부터 다 막았다가 정상 사용자가 차단되면 그게 더 큰 사고다. (위 표는 도입 초기 구성이다. 승격은 관측 결과에 따라 계속 진행되므로, 글을 읽는 시점의 구성과는 다르다.)

"그럼 SQLi가 COUNT 동안은 뚫리는 거 아냐?"라는 질문엔 — 아니다. SQLi의 1차 방어는 WAF가 아니라 앱 코드다. JPA 파라미터 바인딩이라 쿼리와 데이터가 구조적으로 분리돼 있다. WAF는 그 위에 얹는 2차 그물이다. 심층 방어에서 각 겹의 역할을 알고 있으면 COUNT 기간이 무섭지 않다.

반복 스캐너는 수동 차단

스캐너 요청들은 어차피 존재하지 않는 경로라 404로 끝나긴 한다. 하지만 매일 로그에 소음을 만들고, 언젠가 진짜 취약점이 생겼을 때 걸릴 수도 있다. 반복 소스가 명확했기 때문에 IP set 규칙(BLOCK)을 추가해 영구 차단했다.

여기서 프랑스 쪽은 단일 IP가 아니라 /24 대역 전체를 막았다.

x.x.x.0/24  =  x.x.x.0 ~ x.x.x.255, 256개 IP

/24의 뜻: IP 32비트 중 앞 24비트가 네트워크 주소
→ 나머지 8비트가 호스트 = 2^8 = 256개

왜 대역으로 막았나? 로그를 보니 같은 대역 안에서 IP를 바꿔가며 들어오고 있었다. 한 IP를 막으면 옆 IP로 오는 패턴. 이럴 땐 개별 IP가 아니라 그 호스팅 대역 자체를 막는 게 맞다.

차단 후: 효과가 있긴 한 걸까?

차단하고 며칠 뒤 WAF 지표를 확인했는데, 재밌는 상황이 나왔다.

차단 규칙의 BlockedRequests가 0이었다.

처음엔 "규칙이 안 먹나?" 싶었다. 그런데 이 지표의 의미를 뜯어보면 반대다. BlockedRequests는 규칙이 요청을 막을 때마다 올라가는 카운터다. 이게 0이라는 건 = 그 IP들에서 요청 자체가 한 건도 안 왔다는 뜻이다.

솔직하게 결론 내리면: 차단이 공격을 "막아내는 중"인 게 아니라, 공격자가 떠났다. (차단 전에도 계속 404를 받으면서도 오던 애들이라, 시점이 겹친 건 우연에 가깝다.) 그럼 규칙이 무의미하냐면 아니고 — 같은 소스가 다시 오면 이번엔 로그에 닿기도 전에 차단되는 안전망으로 남는다. 효과 평가는 이렇게 지표의 의미까지 따져서 해야 "막았다"는 착각을 안 하게 된다.

진짜 물량전: 어느 밤의 플러딩

스캐너와 별개로, 어느 날 밤 자정 무렵 45분간 물량 공격이 들어왔다.

평상시 트래픽:    5분당 수십 건
공격 피크:       5분당 3,609건 차단 (평시의 수백 배)
공격 총량:       rate limit 차단 약 27,800건 + IP 평판 차단 약 6,000건

이때 일한 게 우선순위 0번(rate limit)과 1번(IP 평판)이다. 그리고 결과 지표가 이 구조의 존재 이유를 증명했다.

같은 시간대 ALB → 앱으로 넘어간 요청:  5분당 1~34건 (평소 수준)
앱 5xx 에러:                        0건

3만 건이 넘는 공격이 왔는데 앱은 공격이 있었는지도 모른다. 전부 ALB 앞 WAF 층에서 흡수됐다. 다음 날 아침 지표를 보고 나서야 공격이 있었음을 알았다. "장애 대응"이 아니라 "사후 확인"으로 끝난 것 — 방어가 잘 동작하면 이렇게 심심하다.

배운 것

1. 오픈 = 공격 개시다. 방어는 오픈 전에 깔려 있어야 한다. 스캐너는 서비스 인지도와 무관하게 온다. IP를 가진 모든 서버가 대상이다.

2. BLOCK/COUNT를 가르는 기준은 오탐 위험이다. 탐지 정확도가 높은 규칙만 즉시 차단, 나머지는 관측 후 승격. 보안 규칙도 배포처럼 점진적으로 켜는 거였다.

3. 지표는 "숫자"가 아니라 "의미"로 읽어야 한다. 차단 카운트 0 = 규칙 고장이 아니라 유입 자체가 없음. 효과를 과대평가하지 않는 해석이 다음 판단을 정확하게 만든다.

4. 계층 방어의 성공은 "안쪽 계층이 심심한 것"으로 측정된다. 3만 건 공격에 앱 계층 변화 0. 이게 WAF를 앞단에 두는 이유의 전부다.

다음 편은 운영 루틴이다. 매일 아침 서버 상태를 확인하는 4종 점검 루틴을 어떻게 정형화했는지.

5편까지는 "만든" 이야기였다. 이번엔 서비스를 오픈하고 나서 실제로 들어온 공격과, 그걸 막은 기록이다.

오픈하면 스캐너부터 온다

서비스를 인터넷에 열면 사람보다 봇이 먼저 온다는 말이 있는데, 진짜였다. 오픈 직후부터 ALB 액세스 로그에 이런 요청들이 찍히기 시작했다.

GET /.env
GET /wp-login.php
GET /phpinfo.php
GET /config.json
...

우리는 Spring Boot 서비스다. 워드프레스도 아니고 PHP도 없다. 이건 특정 대상을 노린 게 아니라, 인터넷 전체를 훑으며 "아무 데나 걸려라" 식으로 알려진 취약점을 자동으로 찔러보는 스캐너다.

발신지를 추려보니 반복 소스가 둘로 좁혀졌다.

• 싱가포르의 VPS 한 대 (단일 IP)
• 프랑스 호스팅 업체의 대역 하나 (여러 IP를 바꿔가며 시도)

미리 깔아둔 그물: WAF 규칙 구성

다행히 WAF는 오픈 전에 ALB 앞에 걸어둔 상태였다. 규칙은 우선순위 순으로 이렇다.

BLOCK과 COUNT가 섞여 있는 게 포인트다. 기준은 오탐 위험이다.

• IP 기반 규칙(rate limit, 평판)은 오탐이 거의 없다 → 즉시 BLOCK
• 패턴 탐지형(SQLi, XSS)은 정상 요청을 오인할 수 있다 → 일단 COUNT로 관측만

COUNT 규칙은 지표만 쌓고 요청은 통과시킨다. 오탐이 없는 걸 확인한 규칙부터 순차적으로 BLOCK 승격하는 전략이다. 처음부터 다 막았다가 정상 사용자가 차단되면 그게 더 큰 사고다. (위 표는 도입 초기 구성이다. 승격은 관측 결과에 따라 계속 진행되므로, 글을 읽는 시점의 구성과는 다르다.)

"그럼 SQLi가 COUNT 동안은 뚫리는 거 아냐?"라는 질문엔 — 아니다. SQLi의 1차 방어는 WAF가 아니라 앱 코드다. JPA 파라미터 바인딩이라 쿼리와 데이터가 구조적으로 분리돼 있다. WAF는 그 위에 얹는 2차 그물이다. 심층 방어에서 각 겹의 역할을 알고 있으면 COUNT 기간이 무섭지 않다.

반복 스캐너는 수동 차단

스캐너 요청들은 어차피 존재하지 않는 경로라 404로 끝나긴 한다. 하지만 매일 로그에 소음을 만들고, 언젠가 진짜 취약점이 생겼을 때 걸릴 수도 있다. 반복 소스가 명확했기 때문에 IP set 규칙(BLOCK)을 추가해 영구 차단했다.

여기서 프랑스 쪽은 단일 IP가 아니라 /24 대역 전체를 막았다.

x.x.x.0/24  =  x.x.x.0 ~ x.x.x.255, 256개 IP

/24의 뜻: IP 32비트 중 앞 24비트가 네트워크 주소
→ 나머지 8비트가 호스트 = 2^8 = 256개

왜 대역으로 막았나? 로그를 보니 같은 대역 안에서 IP를 바꿔가며 들어오고 있었다. 한 IP를 막으면 옆 IP로 오는 패턴. 이럴 땐 개별 IP가 아니라 그 호스팅 대역 자체를 막는 게 맞다.

차단 후: 효과가 있긴 한 걸까?

차단하고 며칠 뒤 WAF 지표를 확인했는데, 재밌는 상황이 나왔다.

차단 규칙의 BlockedRequests가 0이었다.

처음엔 "규칙이 안 먹나?" 싶었다. 그런데 이 지표의 의미를 뜯어보면 반대다. BlockedRequests는 규칙이 요청을 막을 때마다 올라가는 카운터다. 이게 0이라는 건 = 그 IP들에서 요청 자체가 한 건도 안 왔다는 뜻이다.

솔직하게 결론 내리면: 차단이 공격을 "막아내는 중"인 게 아니라, 공격자가 떠났다. (차단 전에도 계속 404를 받으면서도 오던 애들이라, 시점이 겹친 건 우연에 가깝다.) 그럼 규칙이 무의미하냐면 아니고 — 같은 소스가 다시 오면 이번엔 로그에 닿기도 전에 차단되는 안전망으로 남는다. 효과 평가는 이렇게 지표의 의미까지 따져서 해야 "막았다"는 착각을 안 하게 된다.

진짜 물량전: 어느 밤의 플러딩

스캐너와 별개로, 어느 날 밤 자정 무렵 45분간 물량 공격이 들어왔다.

평상시 트래픽:    5분당 수십 건
공격 피크:       5분당 3,609건 차단 (평시의 수백 배)
공격 총량:       rate limit 차단 약 27,800건 + IP 평판 차단 약 6,000건

이때 일한 게 우선순위 0번(rate limit)과 1번(IP 평판)이다. 그리고 결과 지표가 이 구조의 존재 이유를 증명했다.

같은 시간대 ALB → 앱으로 넘어간 요청:  5분당 1~34건 (평소 수준)
앱 5xx 에러:                        0건

3만 건이 넘는 공격이 왔는데 앱은 공격이 있었는지도 모른다. 전부 ALB 앞 WAF 층에서 흡수됐다. 다음 날 아침 지표를 보고 나서야 공격이 있었음을 알았다. "장애 대응"이 아니라 "사후 확인"으로 끝난 것 — 방어가 잘 동작하면 이렇게 심심하다.

배운 것

1. 오픈 = 공격 개시다. 방어는 오픈 전에 깔려 있어야 한다. 스캐너는 서비스 인지도와 무관하게 온다. IP를 가진 모든 서버가 대상이다.

2. BLOCK/COUNT를 가르는 기준은 오탐 위험이다. 탐지 정확도가 높은 규칙만 즉시 차단, 나머지는 관측 후 승격. 보안 규칙도 배포처럼 점진적으로 켜는 거였다.

3. 지표는 "숫자"가 아니라 "의미"로 읽어야 한다. 차단 카운트 0 = 규칙 고장이 아니라 유입 자체가 없음. 효과를 과대평가하지 않는 해석이 다음 판단을 정확하게 만든다.

4. 계층 방어의 성공은 "안쪽 계층이 심심한 것"으로 측정된다. 3만 건 공격에 앱 계층 변화 0. 이게 WAF를 앞단에 두는 이유의 전부다.

다음 편은 운영 루틴이다. 매일 아침 서버 상태를 확인하는 4종 점검 루틴을 어떻게 정형화했는지.

3·4편에서 비밀값과 배포 인증을 정리했다. 이번엔 트래픽이 몰리면 알아서 늘어나는 구조, 그리고 그게 진짜 동작하는지 부하를 걸어 실측한 이야기다.

설정 자체는 금방 끝난다

ECS 오토스케일링은 Target Tracking 방식으로 걸었다. terraform으로 몇 줄이면 된다.

대상:   ECS 서비스의 태스크 수 (min 2 ~ max 4)
지표:   서비스 평균 CPU 사용률
목표:   70% 유지

CPU가 70%를 넘게 유지되면 태스크를 늘리고, 내려가면 줄인다. CloudWatch 알람 생성·관리는 AWS가 자동으로 해준다. 설정만 보면 10분 컷.

그런데 이 숫자들 하나하나에 이유가 있어야 했다. 그냥 넣은 값은 없다.

숫자마다 이유 붙이기

왜 min 2인가 — 가용성 하한. AZ 2개에 하나씩은 있어야 한 쪽 데이터센터가 죽어도 산다.

왜 max 4인가 — 이게 제일 중요했다. 상한은 "돈 아끼려고" 정하는 게 아니라 DB 커넥션 한계로 정해진다.

태스크당 HikariCP 커넥션 풀 = 10
최대 4대 × 10 = 40 커넥션  ≪  db.t3.micro 한계 ≈ 85

max를 무턱대고 10으로 올리면? 10 × 10 = 100 커넥션. DB 한계를 넘어서 스케일아웃이 오히려 DB를 죽이는 역설이 생긴다. 앱을 늘릴 땐 뒤에 있는 DB가 받아줄 수 있는지부터 계산해야 한다.

왜 CPU만 추적하고 메모리는 안 하나 — JVM 때문이다. JVM은 한번 할당받은 힙을 OS에 잘 반환하지 않아서, 메모리 사용률이 항상 높게 유지된다. 메모리 기반 스케일링을 걸면 부하가 없는데도 증설되는 오탐이 난다. JVM 앱은 CPU가 정직하다.

쿨다운 두 개의 비대칭 —

scale_out_cooldown = 60초    (증설은 빠르게)
scale_in_cooldown  = 900초   (감축은 신중하게)

증설 쿨다운 60초엔 숨은 이유가 있다. 새로 뜬 태스크는 JVM 기동 때문에 CPU가 일시적으로 100%를 친다. 이걸 "부하"로 오인해 연쇄 증설되는 걸 막는 최소한의 대기다. 감축 15분은 트래픽 출렁임에 태스크가 들락날락하는 걸 막는다. 늘릴 땐 민감하게, 줄일 땐 둔감하게.

늘어나도 괜찮은가: 무상태 점검

태스크가 2대에서 4대가 되는 순간, "여러 대라서 생기는 문제"가 없는지 먼저 점검했다.

이게 되니까 "태스크 수 조절"이 안전한 확장 수단이 된다. 반대로 말하면, 앱이 무상태가 아니면 오토스케일링 설정은 시한폭탄이다.

"설정했다"와 "동작한다"는 다르다

여기서 멈출 수도 있었다. terraform apply 됐고, 콘솔에 정책 보이고. 끝?

찜찜했다. 알람이 진짜 발화하는지, 태스크가 진짜 늘어나는지 본 적이 없잖아. 장애 상황에서 처음 검증하고 싶지는 않았다. 그래서 부하 테스트를 했다.

도구는 autocannon. 가장 무거운 API(검색 — CPU 바운드)를 골라 때렸다.

1차: 한계 찾기. 동시성을 올려가며 처리량이 꺾이는 지점을 찾았다.

2대 기준 포화점 ≈ 460 req/s

포화점 근처에서 병목을 확인해보니 CPU보다 먼저 태스크당 DB 커넥션 풀(10개)에서 대기가 걸렸다. 즉 이 병목은 태스크를 늘리면(=풀이 늘어나면) 풀리는 구조다. 스케일아웃이 유효한 처방이라는 게 확인됐다.

2차: 증설 실증. CPU를 90% 이상으로 3분간 몰아붙였다.

① CloudWatch 알람(AlarmHigh) 발화
② Application Auto Scaling이 desired 2 → 3 변경
③ 새 태스크 기동 → 헬스체크 통과 → ALB 타겟 등록
④ 서비스 평균 CPU 하락

부하 감지부터 새 태스크가 트래픽을 받기까지 약 5분. 이벤트 로그로 전 과정을 눈으로 확인했다. 이제 "오토스케일링 됩니다"를 설정 화면이 아니라 실측 로그로 말할 수 있다.

알람과 스케일링의 역할 분담

스케일링용 임계값(70%)과 별개로 사람 호출용 알람은 80%에 걸어놨다.

CPU 70% → 기계가 대응 (자동 증설)
CPU 80% → 사람을 부름 (증설로도 못 버티는 상황 = max 도달 등)

80% 알람이 울린다는 건 "스케일링이 일하는 중"이 아니라 "스케일링으로도 안 되는 중"이라는 뜻이 되도록 설계했다. 알람은 사람이 행동해야 할 때만 울려야 한다.

배운 것

1. 오토스케일링의 진짜 설계는 max 값에 있다. min은 가용성, max는 뒷단(DB)의 수용량 계산. 상한 없는 확장은 병목을 뒤로 전가할 뿐이다.

2. "설정했다"는 검증이 아니다. 부하 테스트 전까지 오토스케일링은 가설이었다. 포화점(460 req/s)과 증설 실증(2→3)을 얻고 나서야 용량 계획을 숫자로 말할 수 있게 됐다.

3. 병목의 위치가 처방을 결정한다. 병목이 커넥션 풀(태스크당 자원)이라 스케일아웃이 답이 됐다. 병목이 DB 자체였다면 태스크를 아무리 늘려도 소용없었을 거다.

다음 편은 보안 실전편이다. 오픈하고 나니 진짜로 공격이 들어왔다 — 취약점 스캐너와 트래픽 플러딩을 WAF로 막은 기록.

3편에서 "비밀은 한 군데에만 산다"를 만들었다. 그런데 정리하고 보니 아직 한 군데가 남아 있었다. GitHub Secrets에 들어 있는 배포용 AWS 액세스 키.

남아 있던 마지막 장기 키

우리 배포는 GitHub Actions가 한다. develop에 push하면 스테이징, main이면 운영. 그러려면 Actions가 AWS에 접근해야 하고, 처음엔 정석대로(?) 했다.

1. 배포용 IAM 사용자 생성
2. 액세스 키 발급
3. GitHub Secrets에 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 등록

동작엔 문제가 없다. 문제는 이 키의 성질이다.

• 만료가 없다. 한 번 유출되면 폐기 전까지 영원히 유효하다.
• 어디서 쓰든 통한다. GitHub에서 쓰라고 만든 키지만, 훔친 사람의 노트북에서도 똑같이 동작한다.
• 정기 로테이션은 사람이 해야 한다. 그리고 사람은 까먹는다.

3편에서 내 로컬 키를 aws-vault로 치웠는데, CI에는 장기 키가 그대로 있는 셈이었다. 이걸 없애는 방법이 OIDC다.

OIDC 방식: 키 대신 신원 증명

발상의 전환은 이거다. 키를 잘 보관하는 게 아니라, 키 자체를 안 만든다.

[기존] GitHub Secrets에 영구 키 저장 → 워크플로가 키로 인증

[OIDC] 워크플로 실행 → GitHub이 "이 워크플로는 이 repo의 이 브랜치다"라고
       서명한 토큰 발급 → AWS가 서명 진위 확인 → 조건 맞으면
       1시간짜리 임시 자격증명 발급 → 배포 → 자동 소멸

GitHub Secrets에 저장되는 영구 키: 0개.

인증의 근거가 "키를 알고 있다"에서 "GitHub이 서명으로 보증하는 신원"으로 바뀐다. 훔칠 키가 없고, 임시 자격증명은 1시간이면 죽는다.

핵심은 신뢰 정책의 sub 조건

AWS 쪽엔 배포용 IAM Role을 하나 만들고, 신뢰 정책에 이렇게 건다.

{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::<계정>:oidc-provider/token.actions.githubusercontent.com" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
    "StringLike": {
      "token.actions.githubusercontent.com:sub": [
        "repo:<org>/<repo>:ref:refs/heads/main",
        "repo:<org>/<repo>:ref:refs/heads/develop"
      ]
    }
  }
}

이 sub 조건이 OIDC 보안의 전부라고 해도 된다.

• 우리 repo의 main·develop 브랜치에서 실행된 워크플로만 이 Role을 쓸 수 있다
• 다른 repo? 차단. 포크? 차단. PR 워크플로? 차단. feature 브랜치? 차단.

키 방식에선 "키를 가진 자 = 아무나"였는데, OIDC에선 "허용된 repo의 허용된 브랜치"로 주체가 좁혀진다.

권한도 최소로

Role에 붙인 권한은 워크플로가 실제로 호출하는 액션만 골랐다.

배포 Role이 탈취돼도 할 수 있는 건 "이미지 올리고 재배포" 정도다. 인프라를 바꾸거나 시크릿을 읽는 권한은 없다.

백엔드(ECR/ECS)와 프런트(Amplify) 워크플로 4개가 이 Role 하나를 같이 쓴다. sub 조건이 브랜치 기준이라 4개를 전부 커버하고, Role이 하나면 감사도 한 곳만 보면 된다.

워크플로 쪽 변경은 의외로 작다

permissions:
  id-token: write   # OIDC 토큰 발급 허용 — 이거 빼먹으면 안 됨
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::<계정>:role/<배포롤>
      aws-region: ap-northeast-2

aws-access-key-id/aws-secret-access-key 줄이 사라지고 role-to-assume 한 줄로 바뀐다. permissions.id-token: write가 OIDC 토큰을 요청할 수 있게 하는 스위치다.

전환은 한 번에 하지 않았다

기존 키를 바로 지우고 싶은 유혹이 있었지만, 순서를 지켰다.

1. OIDC Role 생성 + 스테이징 워크플로부터 전환
2. 스테이징 배포가 OIDC로 정상 동작하는 것 확인
3. 운영 워크플로 전환 → 운영 배포 정상 확인
4. 그 다음에야 기존 액세스 키 폐기

새 인증이 초록불인 걸 확인하기 전에 옛 인증을 지우면, 배포가 막힌 상태에서 되돌릴 수단도 없는 최악의 상황이 나온다. 탈출구는 마지막에 닫는다.

배운 것

1. 최고의 키 관리는 키를 안 만드는 것이다. 로테이션 자동화, 유출 탐지, 금고 암호화... 전부 "키가 존재한다"는 전제의 비용이다. OIDC는 그 전제를 지운다.

2. 신원 기반 인증은 조건을 정밀하게 걸 수 있다. 키는 all-or-nothing인데, OIDC sub 조건은 repo·브랜치 단위로 좁힌다. 1편의 SG 체이닝("IP가 아니라 신분")과 같은 철학이 인증에도 적용된 셈이다.

3. 마이그레이션은 병행 기간을 두고, 옛길은 새 길 검증 후에 닫는다.

다음 편은 오토스케일링이다. "설정했다"로 끝내지 않고 부하 테스트로 실제 증설이 일어나는 것까지 실측한 이야기.

1편은 네트워크, 2편은 컴퓨팅이었다. 이번엔 눈에 안 보이는 것 — 비밀값 이야기다. DB 비밀번호, JWT 키, OAuth 시크릿, 그리고 AWS 액세스 키 자체까지.

시작은 찜찜함이었다

인프라를 구축하다 보면 비밀값이 계속 늘어난다. DB 비밀번호, JWT 서명 키, 소셜 로그인 클라이언트 시크릿, 어드민 초기 계정...

처음엔 다들 하듯이 .env 파일과 ~/.aws/credentials에 넣고 시작했다. 동작은 한다. 그런데 어느 날 문득 세어보니, 내 노트북 디스크에 평문으로 굴러다니는 비밀이 열 개가 넘었다.

• ~/.aws/credentials — AWS 액세스 키가 평문 텍스트로
• .env, *.tfvars — 실수로 커밋하면 그대로 유출
• terraform.tfstate — 여기엔 비밀값이 평문으로 박힌다 (이건 나중에 알고 식겁했다)

하나씩 정리하기로 했다. 목표는 한 문장이었다. "비밀은 한 군데에만 산다."

역할 분담: Doppler / AWS / Git

비밀값을 다루는 시스템이 셋인데, 셋이 같은 비밀을 나눠 갖는 게 아니라 역할이 다르다.

값이 흐르는 방향은 한 방향이다.

Doppler (평문 값의 유일한 거처)
   │  terraform apply 시 주입
   ▼
AWS Secrets Manager (KMS 암호화 저장)
   │  ECS task definition: valueFrom = secret의 ARN   ← 값이 아니라 주소
   ▼
Spring Boot 컨테이너 (기동 시점에만 읽어서 ${ENV}에 바인딩)

포인트 몇 개.

앱은 Doppler를 모른다. 컨테이너는 시작할 때 AWS에서만 값을 읽는다. 그래서 Doppler에서 값만 바꾸고 apply를 안 하면 아무 일도 안 일어난다. (한 번 당해보고 배웠다.)

task definition엔 값이 없다. valueFrom에 들어가는 건 Secrets Manager ARN, 즉 "값이 어디 있는지"다. task definition이 노출돼도 값은 안 나온다.

db/url 같은 건 사람이 안 적는다. RDS 엔드포인트는 인프라를 깔아야 정해지는 값이라, Doppler가 아니라 terraform이 직접 조합해서 넣는다. "사람이 아는 비밀"과 "인프라가 만드는 값"을 구분하니 관리가 명확해졌다.

Git이 절대 못 보는 것

.gitignore로 원천 차단한 것들.

그리고 tfstate. terraform state 파일엔 시크릿 값이 평문으로 들어간다. 이걸 로컬에 두면 그동안의 노력이 무의미해진다. 그래서 state는 S3 backend(암호화 + 잠금)로 옮겼다. 로컬 디스크엔 state가 없다.

이 구조의 결론이 마음에 든다.

리포지토리가 통째로 유출돼도, 꺼낼 비밀이 애초에 없다.

마지막 남은 평문: 내 AWS 키

앱 비밀은 정리됐는데, 정작 그걸 관리하는 내 AWS 액세스 키가 ~/.aws/credentials에 평문으로 남아 있었다. 등잔 밑이 어둡다.

이건 aws-vault로 해결했다. 키를 OS 자격증명 저장소(Windows Credential Manager)에 암호화해서 넣고, 평문 credentials 파일은 삭제했다.

# 저장 (이후 평문 파일 삭제)
aws-vault add <profile>

# 사용 — 임시 자격증명을 발급받아 명령 하나에만 주입
aws-vault exec <profile> -- aws s3 ls

aws-vault의 좋은 점은 단순 암호화 저장이 아니라, 실행할 때마다 STS로 수명이 있는 임시 자격증명을 만들어 그 프로세스에만 넘긴다는 것. 장기 키가 환경변수로 셸에 떠다니지 않는다.

전부 합치면: terraform 실행 한 줄

이 모든 게 합쳐진 결과물이 이 명령이다. 인프라를 변경할 때 항상 이렇게 실행한다.

aws-vault exec <profile> -- \
  doppler run -p backend -c prd --name-transformer tf-var -- \
  terraform apply

풀어보면:

1. aws-vault exec — 암호화 저장소에서 AWS 임시 자격증명 발급
2. doppler run ... --name-transformer tf-var — Doppler의 시크릿을 TF_VAR_* 환경변수로 변환해 주입
3. terraform apply — 그 값들로 Secrets Manager 갱신

이 한 줄이 실행되는 순간에만, 이 프로세스 안에서만 비밀이 존재한다. 끝나면 사라진다. 디스크 어디에도 평문이 안 남는다.

환경 격리도 이 구조에 얹혀 있다. prod는 Doppler prd config + state key prod/, 스테이징은 stg + stg/. 운영과 스테이징 값이 섞일 구조적 여지가 없다.

배운 것

1. 비밀 관리의 핵심은 암호화가 아니라 "사본 줄이기"다. 비밀이 다섯 군데 있으면 다섯 군데를 다 지켜야 한다. 단일 원천 + 한 방향 흐름으로 만들면 지킬 곳이 하나로 준다.

2. tfstate를 조심하라. .tfvars는 다들 gitignore하는데, state에 값이 평문으로 남는 건 놓치기 쉽다. remote backend + 암호화는 선택이 아니라 필수다.

3. 앱 비밀보다 "관리자인 나의 키"가 더 위험할 수 있다. 내 AWS 키는 인프라 전체를 만질 수 있는 키다. 앱 시크릿을 금고에 넣어놓고 금고 열쇠를 책상 위에 두면 의미가 없다.

다음 편은 이 흐름의 연장선이다. GitHub Actions에 저장돼 있던 배포용 AWS 키를 아예 없애버린 이야기 — OIDC 전환기.

1편에서 네트워크를 3층으로 나눴다. 이번엔 그 2층(앱 층)에 뭘 올릴지 정하는 이야기다.

EC2냐 Fargate냐

Spring Boot 앱을 AWS에서 돌리는 방법은 여러 가지다. 후보를 두 개로 좁혔다.

• EC2: 가상 서버를 직접 빌려서 그 위에 도커/앱을 올린다
• ECS Fargate: 컨테이너 이미지만 주면 AWS가 알아서 굴려준다

EC2가 더 익숙한 길이다. 자료도 많고, SSH로 들어가서 뭐든 만질 수 있다. 그런데 그 "뭐든 만질 수 있다"가 바로 문제라고 생각했다.

EC2를 고르면 관리해야 하는 것들:

• 호스트 OS 보안 패치 (안 하면 그대로 취약점)
• SSH 키 관리, 접속 통제
• 오토스케일링 하려면 AMI + Launch Template + ASG 직접 배선
• 서버 안에 쌓이는 상태 (로그, 임시 파일, 언젠가 누가 손대서 바뀐 설정...)

Fargate를 고르면:

• 관리할 호스트 OS 자체가 없다
• SSH 접속 경로 자체가 없다
• 스케일링은 "태스크 수" 숫자만 조절
• 컨테이너는 배포 때마다 이미지에서 새로 뜬다

혼자 백엔드와 인프라를 다 맡는 상황에서, 운영 부담이 적은 쪽이 답이었다. Fargate로 갔다.

불변 인프라라는 사고방식

Fargate를 쓰면서 자연스럽게 따라온 개념이 불변(immutable) 인프라다.

전통적 서버 운영은 "고쳐 쓰기"다. 서버에 들어가서 패치하고, 설정을 바꾸고, 재시작한다. 그러다 보면 서버마다 상태가 조금씩 달라지고, "그 서버에서만 되는" 미스터리가 생긴다.

불변 인프라는 "갈아 끼우기"다. 컨테이너를 수정하지 않는다. 바꿀 게 있으면 새 이미지를 구워서 통째로 교체한다.

전통 방식:  서버 접속 → 수정 → 재시작   (서버마다 상태가 갈라짐)
불변 방식:  새 이미지 빌드 → 교체       (모든 컨테이너가 항상 이미지와 동일)

배포마다 깨끗한 상태에서 새로 뜨니까, 설령 뭔가 이상한 게 침투해도 다음 배포에서 사라진다. 감염이 지속될 곳이 없다.

"서버에 백신 안 깔았어요?"

보안 점검 과정에서 실제로 받은 질문이다. 온프레미스 서버 기준으론 당연한 질문이다. 그런데 Fargate에선 대답이 좀 다르다. 정리하면 이렇다.

1. 사람이 악성코드를 심을 경로가 없다. SSH가 없다. 접속 자체가 안 되니 누가 들어가서 뭘 깔 수가 없다.

2. 호스트 OS 보안은 AWS 책임이다. 책임 공유 모델. 하이퍼바이저와 호스트 OS 패치는 AWS가 하고, 우리는 앱과 데이터를 책임진다. 백신을 깔 호스트에 우리는 접근조차 못 한다.

3. 그 대신 다른 방어를 쓴다.

• ECR 이미지 스캔: 이미지를 push할 때마다 알려진 취약점(CVE) 검사
• WAF: 앱으로 들어오는 요청 내용(L7)을 검사 — 이건 별도 편에서
• 최소권한 IAM: 컨테이너가 가진 권한 자체를 최소화

전통적 호스트 백신은 "서버가 오래 살고, 사람이 드나드는" 환경의 도구다. 불변·단명 컨테이너 환경에선 실행 모델이 달라서, 방어 수단도 달라진다.

"OS가 없다"면서 이미지엔 리눅스가 있는데요?

이것도 헷갈렸던 지점이다. Fargate는 "서버리스"라며? 근데 Dockerfile엔 이렇게 쓰여 있다.

FROM eclipse-temurin:21-jre-alpine

Alpine Linux다. OS가 없다더니 리눅스가 들어있다. 모순 아닌가?

모순이 아니다. 층을 나눠서 보면 된다.

[이미지 안]  Alpine 유저스페이스 (libc, 셸, 패키지) + JRE + 우리 jar
[이미지 밖]  리눅스 커널 — 호스트와 공유, AWS가 관리

컨테이너 이미지엔 커널이 없다. 유저스페이스만 있다. 커널은 호스트 것을 빌려 쓴다. 그게 컨테이너가 VM보다 가벼운 이유이기도 하다.

"OS가 없다"의 진짜 뜻은 "리눅스가 없다"가 아니라 "패치하고 SSH로 들어가서 관리하는 전통적 관리 대상 OS가 없다"는 거다.

Alpine을 고른 이유도 같은 맥락이다. 5MB짜리 초경량 배포판이라 이미지에 들어가는 게 적을수록 공격 표면도 작아진다. 없는 건 뚫릴 수도 없다.

Dockerfile에서 챙긴 두 가지

# 멀티스테이지: 빌드 도구는 최종 이미지에 안 들어간다
FROM gradle:... AS build
...
FROM eclipse-temurin:21-jre-alpine
COPY --from=build /app/build/libs/*.jar app.jar

# 루트로 돌리지 않는다
USER spring

• 멀티스테이지 빌드: Gradle, JDK 같은 빌드 도구는 빌드 단계에서만 쓰고 버린다. 최종 이미지엔 JRE와 jar만. 이미지도 작아지고 공격 표면도 준다.
• non-root 실행: 컨테이너가 뚫려도 컨테이너 안에서 루트가 아니다. 피해 범위를 한 겹 더 줄인다.

배운 것

1. 기술 선택의 기준은 "내가 감당할 수 있는 운영 부담"이었다. EC2가 나쁜 게 아니다. 호스트를 직접 통제해야 하는 요구사항이 있으면 EC2가 맞다. 우리는 그 요구가 없었고, 관리 표면을 줄이는 게 이득이었다.

2. 보안 질문에는 그 환경의 언어로 다시 답해야 한다. "백신 깔았냐"는 질문의 본질은 "악성코드 대책이 있냐"다. 도구(백신)가 아니라 목적(악성코드 방어)에 답하면, 불변 인프라 + 이미지 스캔이라는 다른 형태의 답이 성립한다.

3. "서버리스"라는 말은 마케팅 용어라서, 실제 구조로 한 번 번역해봐야 한다. 커널 공유 구조를 이해하고 나니 컨테이너, VM, Fargate의 차이가 명확해졌다.

다음 편은 비밀값 이야기다. DB 비밀번호와 API 키를 코드에 넣지 않기 위해 Doppler와 aws-vault로 만든 "비밀이 한 군데만 사는" 구조.

백엔드 개발자가 AWS 인프라를 처음부터 직접 구축한 기록이다. 지난 글(Flyway 삽질기)에서 예고했던 구축 일지, 그 첫 번째. 네트워크부터 시작한다.

집을 짓기 전에 땅부터

인프라를 구축하면서 가장 먼저 한 일은 서버를 띄우는 게 아니었다. 네트워크 도면 그리기였다.

AWS에서 네트워크의 시작은 VPC다. 우리만 쓰는 격리된 사설 네트워크. 여기에 10.1.0.0/16이라는 대역을 잡았다. IP로 치면 6.5만 개짜리 땅이다.

문제는 이 땅을 어떻게 나누느냐였다. 다 한 방에 몰아넣을 수도 있다. ALB도, 앱 서버도, DB도 전부 같은 서브넷에. 동작은 한다. 하지만 그렇게 안 했다.

3개의 층으로 나눴다

1층 퍼블릭   → ALB(입구) · NAT(출구)     ← 인터넷이 닿는 유일한 층
2층 앱       → ECS Fargate 컨테이너      ← 나가는 것만 가능 (NAT 경유)
3층 데이터   → RDS(PostgreSQL) · Redis   ← 인터넷으로 가는 길 자체가 없음

각 층은 가용영역(AZ) 2개에 걸쳐 있어서 실제 서브넷은 6개다.

한 문장으로 요약하면: 안으로 갈수록 인터넷에서 멀어진다.

"퍼블릭 서브넷"이라는 건 사실 없다

여기서 처음 제대로 이해하게 된 것. 퍼블릭 서브넷과 프라이빗 서브넷은 서브넷 자체의 속성이 아니다.

차이는 오직 라우팅 테이블 한 줄이다.

• 라우팅 테이블에 0.0.0.0/0 → IGW(인터넷 게이트웨이) 경로가 있으면 → 퍼블릭
• 없으면 → 프라이빗

그래서 우리 구조는 이렇게 된다.

퍼블릭 층 라우팅:  0.0.0.0/0 → IGW        (인터넷 양방향)
앱 층 라우팅:     0.0.0.0/0 → NAT GW     (나가기만 가능)
데이터 층 라우팅:  0.0.0.0/0 경로 없음     (인터넷과 단절)

앱 층의 NAT 게이트웨이는 "나가기만 하는 출구"다. 컨테이너가 외부 API를 호출하거나 이미지를 pull할 땐 나갈 수 있지만, 외부에서 컨테이너로 직접 들어오는 건 불가능하다.

그리고 데이터 층. 여기가 이 설계의 핵심인데, 0.0.0.0/0 라우트를 일부러 안 만들었다.

DB 비밀번호가 통째로 유출돼도, 인터넷에서 DB에 접근할 물리적 경로 자체가 없다. 방화벽이 막는 게 아니라, 길이 없는 거다.

방화벽은 IP가 아니라 "신분"으로

층을 나눴으면 층 사이의 문도 통제해야 한다. AWS에선 보안 그룹(SG)이 그 역할인데, 여기서 한 가지 결정을 했다. IP 기반이 아니라 SG 체이닝으로 연결한다.

인터넷 → [ALB SG] → :8080 → [ECS SG] → :5432 → [RDS SG]
                                     → :6379 → [Redis SG]

각 화살표의 규칙이 "특정 IP를 허용"이 아니라 "앞 단계 SG를 가진 리소스만 허용"이다.

• ECS SG의 8080 인바운드: ALB SG를 가진 것만
• RDS SG의 5432 인바운드: ECS SG를 가진 것만

왜 IP가 아니라 신분인가? 컨테이너 IP는 계속 바뀌기 때문이다. 오토스케일링으로 2대가 4대가 되면 새 컨테이너는 새 IP를 받는다. IP로 규칙을 짰다면 스케일아웃할 때마다 방화벽이 깨진다. "ECS SG 멤버"라는 신분으로 열어두면 몇 대로 늘든 규칙이 자동으로 맞는다.

요청 하나가 흐르는 길

사용자가 API를 호출하면 이렇게 흐른다.

① 사용자 → https://api.도메인 (DNS가 ALB로 안내)
② ALB(1층)가 TLS 종료 — HTTPS를 풀고
③ ALB → ECS 컨테이너(2층)로 8080 평문 전달   ← 사설망 내부라 평문 OK
④ 앱 → RDS/Redis(3층) 조회
⑤ 응답이 역순으로 나감

외부에서 들어오는 문은 ALB 하나뿐이다. TLS 암호화 부하는 ALB가 흡수하고, 내부 통신은 사설망이라 평문으로 빠르게 처리한다.

배운 것

1. 네트워크 격리는 "설정"이 아니라 "구조"다. 방화벽 규칙은 실수로 열 수 있다. 하지만 라우트가 없는 서브넷은 실수로도 못 연다. 가장 강한 방어는 규칙이 아니라 경로의 부재였다.

2. 퍼블릭/프라이빗은 라우팅 테이블 한 줄 차이다. 이걸 이해하고 나니 AWS 네트워크 문서들이 갑자기 읽히기 시작했다.

3. 방화벽 규칙은 변하는 것(IP)이 아니라 변하지 않는 것(신분)에 걸어야 한다. 오토스케일링 시대에 IP 기반 규칙은 유지보수 폭탄이다.

다음 편은 컴퓨팅 이야기다. EC2 대신 Fargate를 고른 이유, 그리고 "서버에 백신 안 깔았어요?"라는 질문에 어떻게 답했는지.

시리즈 예고: 지금 운영 중인 서비스의 백엔드 인프라(AWS ECS Fargate + Terraform)를 직접 구축했다. 구축 과정은 따로 연재로 풀 예정이고, 오늘은 정식 오픈 전 준비 기간에 겪은 사건 하나를 먼저 꺼낸다. 실사용자가 없던 시기라 피해는 없었지만, 개인적으로 올해 겪은 삽질 중 가장 교훈이 많았던 건이다.

버그 하나 고쳤을 뿐인데

시작은 사소했다. URL 파싱 버그를 고쳤다. https:// 없이 www.도메인/...처럼 스킴을 빼고 입력하면 등록이 거부되는 문제였다.

수정하고, 테스트 통과 확인하고, develop에 머지했다. CI가 돌고 stage 배포 워크플로가 초록불로 끝났다. 여기까진 평화로웠다.

그런데 stage에서 확인해보니 —

• https://www.도메인/... → 등록됨
• www.도메인/... → 여전히 실패

고친 코드가 반영이 안 된 거다. 방금 배포 성공했다고 초록불 떴는데?

파이프라인은 초록불

처음엔 당연히 코드나 브랜치를 의심했다.

• 머지가 제대로 됐나? → develop에 커밋 있음
• 워크플로가 안 돌았나? → 트리거 정상, 테스트 통과, 이미지 빌드·푸시 정상
• ECR에 새 이미지가 올라갔나? → 최신 커밋 SHA 태그로 올라가 있음

전부 정상이다. 빌드도 됐고 이미지도 있고 배포 명령도 나갔다. 그런데 서버는 옛날 코드로 응답하고 있다. 증상이 앞뒤가 안 맞았다.

ECS 이벤트에서 찾은 단서

파이프라인이 아니라면 그 다음 단계, ECS를 봐야 한다. 서비스 이벤트 로그를 열었더니 이런 문장이 있었다.

(service ...-stg-back) deployment failed: tasks failed to start.
(service ...-stg-back) rolling back to deployment ...

새 태스크가 부팅에 실패해서, ECS가 알아서 구버전으로 롤백하고 있었다.

ECS에는 deployment circuit breaker라는 기능이 있다. 새 버전 컨테이너가 계속 뜨지 못하면 배포를 실패로 판정하고 마지막으로 성공했던 버전으로 자동 롤백한다. 서비스가 죽는 것보단 훨씬 낫다.

문제는 이게 너무 조용하다는 거다. 롤백된 구버전이 멀쩡히 트래픽을 받으니까 서비스는 초록불이고, 알람도 안 울리고, 5xx도 없다. 겉으로 보면 "배포 성공 + 서비스 정상"인데 실제로는 "배포 실패 + 구버전 유지"다.

진짜 범인: Flyway 마이그레이션

그럼 새 태스크는 왜 부팅에 실패했을까. 컨테이너 로그를 열어보니 답이 바로 나왔다.

Migration V28__remove_placeholder_master_seed.sql failed
ERROR: update or delete on table "genre" violates
foreign key constraint "..._fkey" on table "content"

Spring Boot는 부팅 시점에 Flyway로 DB 마이그레이션을 돌린다. V28이라는 마이그레이션이 FK 제약 위반으로 실패했고, 마이그레이션이 실패하면 앱이 안 뜬다. 앱이 안 뜨니 태스크 실패, 태스크 실패니 circuit breaker 롤백. 인과가 전부 연결됐다.

V28의 내용은 단순하다. 초기 세팅 때 넣어둔 placeholder 시드 데이터(장르 목록 등)를 지우는 거다.

DELETE FROM genre;      -- 마스터 시드 3종 (테이블명은 일반화했다)
DELETE FROM tag;
DELETE FROM category;

파일 주석에는 이렇게 적혀 있었다. "DB 초기화 직후라 콘텐츠가 아직 이 시드를 참조하지 않는 시점. FK 충돌 없음."

이 가정이 문제였다.

왜 prod는 되고 stage만 안 되나

여기가 이 사건의 핵심이다. 같은 코드, 같은 V28인데 prod는 멀쩡했다.

이유는 두 환경의 DB가 걸어온 역사가 달랐기 때문이다.

• prod: 오픈 준비 과정에서 DB를 전체 리셋했다. V28이 돌 때 테이블이 비어 있었고, 시드를 참조하는 데이터가 없으니 DELETE가 그냥 통과했다. Flyway 이력에 V28 = success가 기록됐다.
• stage: 리셋한 적이 없다. 테스트하면서 등록한 콘텐츠들이 시드 데이터를 FK로 참조하고 있었다. 그 상태에서 시드를 지우려니 FK 위반. V28 = success 기록이 영영 안 생긴다.

Flyway는 어떤 마이그레이션을 적용했는지를 DB마다 flyway_schema_history 테이블에 기록한다. 그래서 prod는 부팅 때마다 "V28? 이미 했네" 하고 넘어가고, stage는 부팅 때마다 "V28 해야지" → FK 위반 → 실패를 반복한 거다.

코드는 하나인데 DB 상태가 갈라져 있으면, 같은 마이그레이션이 환경마다 다르게 동작한다. Flyway는 스키마 버전만 추적하지, 그 안에 어떤 데이터가 쌓였는지는 모른다.

더 소름: 5주 전부터였다

"근데 왜 갑자기 안 되지?"라고 생각하며 배포 이력을 거슬러 올라갔다.

갑자기가 아니었다. V28이 들어간 이후 5주 동안, stage 배포는 전부 실패하고 있었다.

stage에서 돌고 있는 이미지를 확인해보니 5주 전 커밋이었다. V28이 생기기 직전 버전. 그 사이에 있었던 배포들 전부 — V28 FK 실패 → circuit breaker 롤백 → 5주 전 이미지로 복귀.

그동안 아무도 몰랐다. stage 서비스는 계속 초록불이었으니까. 이번에 버그 수정을 stage에서 확인하려다가 우연히 수면 위로 올라온 거다.

그나마 다행인 건 시점이었다. 아직 정식 오픈 전이라 실사용자에게 간 영향은 없었다. 오픈 준비 중의 stage에서 미리 밟은 지뢰인 셈인데, 이 함정 자체는 오픈 후에도 언제든 똑같이 터질 수 있는 구조였다. 그래서 기록해둔다.

돌이켜보면 무서운 지점이다. 모니터링은 "서비스가 살아있는가"를 본다. 그런데 이 사건의 실패 신호는 "서비스가 죽었다"가 아니라 "새 버전이 반영되지 않았다"였다. 살아있는지만 보는 모니터링에는 절대 안 잡힌다.

파일을 고치면 되는 거 아냐?

가장 먼저 드는 생각: V28에서 DELETE 앞에 참조 데이터 정리를 추가하면 되지 않나?

안 된다. Flyway는 마이그레이션 파일의 체크섬을 이력에 함께 저장하고, 부팅 때마다 "적용된 파일이 그대로인지" 검증한다(validate).

V28은 이미 prod에 적용됐고 체크섬이 박제됐다. 지금 파일을 수정하면 다음 prod 배포에서 체크섬 불일치로 validate가 깨진다. stage 고치려다 prod를 망가뜨리는 그림이다.

한번 적용된 마이그레이션 파일은 불변(immutable)이다. 고치고 싶으면 파일이 아니라 다른 곳을 손대야 한다.

해결: 파일이 아니라 이력을 만졌다

선택지는 두 개였다.

• A. stage 이력에 V28을 "적용됨"으로 수동 마킹 — 시드 데이터는 남지만, stage에선 실제로 쓰이는 데이터라 남아도 무해. 데이터 무손실.
• B. 시드를 참조하는 stage 데이터를 정리하고 V28을 정상 실행 — 스키마 상태는 prod와 완전히 일치하지만 테스트 데이터가 날아간다.

A를 택했다. stage의 테스트 데이터를 지킬 수 있고, 조치가 DB 이력 한 줄로 끝난다.

flyway_schema_history에 V28 행을 직접 INSERT 했다. 주의할 건 체크섬 — Flyway가 다음 부팅 때 파일과 대조하므로 실제 파일의 체크섬 값과 일치해야 한다. (Flyway의 체크섬은 파일을 줄 단위로 읽어 CRC32를 누적한 값이다. 줄바꿈 문자는 계산에서 빠지기 때문에 CRLF/LF가 달라도 같은 값이 나온다.)

INSERT INTO flyway_schema_history
  (installed_rank, version, description, type, script, checksum,
   installed_by, installed_on, execution_time, success)
VALUES
  ((SELECT COALESCE(MAX(installed_rank),0)+1 FROM flyway_schema_history),
   '28', 'remove placeholder master seed', 'SQL',
   'V28__remove_placeholder_master_seed.sql', <파일_체크섬>,
   'manual-skip', now(), 0, true);

그리고 재배포. 이번엔 부팅 로그가 달랐다.

Successfully validated 28 migrations
Current version of schema "public": 28
Schema "public" is up to date. No migration necessary.
...
Started Application in 49.6 seconds

V28을 "이미 적용됨"으로 스킵하고 앱이 떴다. 새 태스크가 헬스체크를 통과하고, 이번엔 구버전 쪽이 드레이닝됐다. 5주 만에 처음으로 롤백이 반대로 일어난 순간이었다.

밀려 있던 5주치 변경사항이 한 번에 반영됐고, 처음 고치려던 URL 파싱 버그도 stage에서 정상 동작했다.

배운 것 세 가지

1. 데이터에 의존하는 마이그레이션은 환경마다 다르게 터진다. Flyway가 보장하는 건 "스키마 버전의 순서"뿐이다. DELETE처럼 데이터 상태를 가정하는 마이그레이션은 "모든 환경에서 그 가정이 참인가"를 물어야 한다. "지금 이 DB에서 되니까"는 다른 환경에서의 성공을 보장하지 않는다.

2. 자동 롤백은 서비스를 지키지만, 실패를 숨긴다. circuit breaker 덕분에 장애는 없었다. 대신 실패가 5주간 은폐됐다. 초록불은 "서비스가 살아있다"는 뜻이지 "최신 버전이 떠 있다"는 뜻이 아니다. 배포가 반영 안 되는 것 같으면 에러 로그가 아니라 배포 이벤트와 실행 중인 이미지 버전을 먼저 봐야 한다.

3. 적용된 마이그레이션은 불변이다. 고칠 땐 파일이 아니라 이력을. 체크섬이 박제된 파일을 수정하면 그 파일이 적용된 모든 환경이 깨진다. 환경 하나의 이력이 꼬였다면 그 환경의 flyway_schema_history를 수술하는 게 정석이다. (Flyway에 repair 명령이 있는 것도 같은 맥락이다.)

다음 글부터는 이 인프라를 어떻게 구축했는지 처음부터 풀어볼 예정이다. VPC를 왜 3층으로 나눴는지, EC2 대신 Fargate를 왜 골랐는지 — 구축 일지로 이어진다.

이제 Qwen-Image-Edit-2511 모델을 실제로 올려보자.

생각보다 순탄하지 않았다.

모델 다운로드

작업 폴더를 만들고 모델을 내려받는다.

모델 크기가 약 40GB라 시간이 좀 걸린다.

mkdir -p ~/qwen-project
cd ~/qwen-project

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="Qwen/Qwen-Image-Edit-2511",
    local_dir="./model",
    local_dir_use_symlinks=False,
    resume_download=True
)

resume_download=True 덕분에 중간에 끊겨도 이어받을 수 있다 !

1차 시도 — device_map="cuda"

모델을 GPU에 전부 올리는 방식으로 시작했다.

pipeline = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2511",
    torch_dtype=torch.float16,
    device_map="cuda",
    low_cpu_mem_usage=True
)

바로 에러가 떴다.

torch.OutOfMemoryError: CUDA out of memory.
Tried to allocate 72.00 MiB.
GPU 0 has a total capacity of 21.99 GiB of which 69.38 MiB is free.
Of the allocated memory 21.48 GiB is allocated by PyTorch

VRAM 상태를 보면 이렇다.

Total VRAM : 21.99 GiB
사용 중    : 21.91 GiB (99.6%)
 ├─ PyTorch : 21.48 GiB
 └─ 기타    : 0.43 GiB
남은 공간  : 0.069 GiB (69MB)

72MB가 필요한데 69MB밖에 없었다.

모델이 VRAM을 꽉 채워버린 것이다.

2차 시도 — device_map="balanced"

GPU 메모리가 부족하면 자동으로 CPU로 offload하는 방식으로 바꿨다.

pipeline = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2511",
    torch_dtype=torch.float16,
    device_map="balanced",
    low_cpu_mem_usage=True
)

실행은 됐다.

근데 문제가 생겼다.

40%|████████| 12/30 [4:09:33<6:09:14, 1230.82s/it]

30 스텝 중 12번째(40%)에 4시간 9분이 걸렸다.

스텝당 약 20분, 총 예상 시간이 10시간이 넘었다.

GPU와 CPU를 계속 왔다갔다하면서 속도가 처참하게 느려진 것이다.

결국 KeyboardInterrupt 로 중단했다.

3차 시도 — FP 조절

VRAM 사용량을 줄이려면 데이터 타입을 낮추면 된다.

# 기존
torch_dtype=torch.float16

# 변경 시도
torch_dtype=torch.float8

바로 막혔다.

PyTorch에는 torch.float8 이 없다 !

AttributeError: module 'torch' has no attribute 'float8'

float16보다 더 낮은 타입을 쓰려면 다른 방법이 필요했다.

해결 — 서버 교체 + sequential offload + bfloat16 조합

원래 쓰던 서버는 VRAM 8GB였다.

모델 자체가 너무 커서 8GB로는 아예 올라가지도 않았다.

서버를 교체했지만 모델 전체를 다 올릴 수 있는 사양으로 바꾼 건 아니었다.

그래서 두 가지를 함께 적용했다.

sequential CPU offload — 레이어 단위로 필요할 때만 GPU에 올리고 나머지는 CPU에 둔다.

model 방식보다 느리지만 메모리를 훨씬 적게 쓴다.

pipeline.enable_sequential_cpu_offload()

bfloat16으로 타입 변경 — float16 대비 수치 안정성이 높고 메모리 사용량은 동일하다.

torch_dtype=torch.bfloat16

이 두 가지 조합으로 정상적으로 동작했다 !

결과

서버를 바꾼 뒤 정상적으로 동작했다.

GPU 상태도 안정적이었다.

GPU 사용률 : 89%
온도       : 73°C
전력       : 58W / 72W
메모리 사용 : 890 MiB / 23034 MiB (약 3.9%)
여유 메모리 : 약 21.6 GB

강아지 사진 테스트

원본 사진에 다양한 각도와 스타일 변환을 적용해봤다.

• 원본 강아지 사진

• right side view high-angle shot close-up

• back side view high-angle shot close-up

• left side view high-angle shot close-up

• 지브리 스타일 변환 결과

지브리 스타일 변환에 사용한 프롬프트다.

Transform the actual photo provided into an anime-style landscape scene.
Keep the core composition and elements from the original photo,
but render everything in vibrant anime aesthetics with exaggerated colors,
dynamic lighting, soft gradients, and cel-shaded outlines typical of
Studio Ghibli-inspired landscapes.

사람 사진 테스트

• 원본 사람 사진

• right side view high-angle shot close-up 결과

LoRA + Gradio 서버

LoRA까지 붙이고 외부에서 접근할 수 있는 Gradio 서버를 구축했다. 단일 편집과 배치 편집(다중 각도 한 번에 생성) 두 가지 탭으로 구성했다.

import gradio as gr
import torch
from PIL import Image
from diffusers import QwenImageEditPlusPipeline
import gc
import os

os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'

pipeline = QwenImageEditPlusPipeline.from_pretrained(
    "./model",
    torch_dtype=torch.bfloat16
)
pipeline.enable_sequential_cpu_offload()

pipeline.load_lora_weights(
    "fal/Qwen-Image-Edit-2511-Multiple-Angles-LoRA",
    adapter_name="multi_angle"
)
pipeline.set_adapters(["multi_angle"], adapter_weights=[0.9])

서버는 0.0.0.0:7860 으로 띄운다.

demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    share=False,
    debug=True
)

• 결과화면

Qwen 모델 핵심 파라미터

일반적인 Diffusion 모델과 파라미터가 다르다.

공식 문서 기준으로 아래 값을 써야 제대로 동작한다.

output = pipeline(
    image=[img],           # 리스트로 전달
    prompt=prompt,
    negative_prompt=" ",   # 빈 문자열이 아닌 공백 하나
    true_cfg_scale=4.0,    # Qwen 필수 파라미터
    guidance_scale=1.0,    # Qwen 기본값
    num_inference_steps=20,
)

negative_prompt=" " 에서 "" 이 아니라 " " (공백 하나)를 써야 한다.

처음엔 이걸 몰라서 한참 헤맸다 !

메모리 최적화 정리

T4에서 삽질하면서 배운 최적화 포인트 4가지다.

1024x1024 → 512x512로 줄이는 것만으로 메모리 사용량이 1/4로 줄어든다 !

처음엔 단순히 모델을 올리는 거라 쉽게 생각했는데, VRAM 용량과 속도 사이에서 꽤 고생했다.

이번에 배운 건 하나다.

VRAM이 모델 크기를 전부 수용할 수 있으면 제일 좋다.

하지만 그렇지 않더라도 방법이 있다.

• sequential CPU offload — 레이어 단위로 쪼개서 필요한 부분만 GPU에 올린다
• bfloat16 / float16 — 데이터 타입을 낮춰서 메모리 사용량을 줄인다
• 이미지 크기 축소 — 입력 해상도를 낮추면 메모리가 확 줄어든다

서버 사양이 부족하다고 바로 포기할 필요가 없다는 걸 직접 경험했다.

물론 속도 트레이드오프는 있다. 하지만 테스트 목적이라면 충분히 쓸 만하다 !

이제 직접 모델을 구축해서 테스트해볼 차례다.

왜 AWS인가

회사에서 실제로 사용 중인 GPU 서버에 바로 올리기엔 부담이 있었다.

검증되지 않은 모델을 프로덕션 서버에 올리는 건 리스크가 크니까.

AWS에서 먼저 테스트하고, 결과가 괜찮으면 실 서버에 올리는 방식으로 접근했다.

인스턴스 선택

테스트 목적이니 비용 대비 효율을 따졌다.

T4는 추론 최적화 GPU라 딥러닝 모델 테스트 용도로 충분하다.

환경 세팅

모델을 올리기 전에 환경부터 제대로 잡아야 한다.

GPU 인스턴스 세팅부터 Python 환경 구축까지 순서대로 정리한다.

AMI 선택

AWS에서 인스턴스를 생성할 때 AMI 선택이 중요하다.

직접 드라이버, CUDA, PyTorch를 하나씩 설치하면 버전 충돌로 삽질할 가능성이 크다.

아래 AMI를 선택하면 전부 세팅된 상태로 시작할 수 있다.

Deep Learning OSS Nvidia Driver AMI GPU PyTorch 2.9 (Ubuntu 24.04)

이 AMI 하나로 끝난다.

• NVIDIA 드라이버 ✅
• CUDA Toolkit ✅
• cuDNN ✅
• PyTorch 2.9 ✅
• 기타 딥러닝 라이브러리들 ✅

1. 시스템 확인 및 업데이트

인스턴스에 접속하면 가장 먼저 시스템 상태와 GPU를 확인한다.

# 시스템 정보
cat /etc/os-release | grep PRETTY_NAME
uname -r

# GPU 확인
nvidia-smi

# 업데이트
sudo apt update && sudo apt upgrade -y

# 기본 도구 설치
sudo apt install -y build-essential wget curl git vim htop

nvidia-smi 에서 GPU 정보가 정상적으로 출력되면 드라이버는 잡힌 거다.

2. NVIDIA 드라이버 설치 (AMI 미사용 시)

딥러닝 AMI를 쓰지 않는 경우라면 드라이버를 직접 설치해야 한다.

sudo apt update && sudo apt upgrade -y

# ubuntu-drivers 설치
sudo apt install -y ubuntu-drivers-common

# 추천 드라이버 확인
sudo ubuntu-drivers devices

# 자동 설치
sudo ubuntu-drivers autoinstall

# 재부팅
sudo reboot

3. Conda 설치

패키지 버전 관리를 위해 Miniconda를 설치한다.

# Miniconda 다운로드
cd ~
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 설치
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3

# Conda 초기화
$HOME/miniconda3/bin/conda init bash

# 설정 적용
source ~/.bashrc

# 확인 — (base) 표시가 나와야 함
conda --version

4. Python 환경 생성

모델별로 환경을 분리해두는 게 좋다.

# Python 3.10 환경 생성
conda create -n qwen python=3.10 -y -c conda-forge

# 환경 활성화
conda activate qwen

# 확인 — (qwen) 표시가 나와야 함
python --version

에러가 발생하면 conda update -n base -c defaults conda 로 먼저 conda 자체를 업데이트해보자.

5. PyTorch 설치

환경 안에서 CUDA 호환 PyTorch를 설치한다.

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

설치 후 GPU 연결 여부를 확인한다.

import torch

print(f"PyTorch 버전: {torch.__version__}")
print(f"CUDA 사용 가능: {torch.cuda.is_available()}")
print(f"CUDA 버전: {torch.version.cuda}")
print(f"GPU 이름: {torch.cuda.get_device_name(0)}")
print(f"GPU 메모리: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB")

CUDA 사용 가능: True 가 나오면 성공이다 !

6. Diffusers 및 의존성 설치

Qwen 모델을 쓰려면 HuggingFace 생태계 라이브러리들이 필요하다.

pip install diffusers transformers accelerate safetensors pillow huggingface_hub

7. HuggingFace 로그인

모델을 다운로드하려면 HuggingFace 계정 인증이 필요하다.

huggingface-cli login

토큰을 입력하면 인증이 완료된다.

GPU 실행 옵션 정리

모델 로드 시 device_map 옵션에 따라 동작 방식이 달라진다.

VRAM이 충분하다면 "cuda" 로 전체 로드하는 게 속도 면에서 가장 좋다.

이제 환경이 다 갖춰졌다.

다음 편에서는 Qwen 모델을 실제로 내려받고 Gradio 서버까지 구축한 과정을 정리한다.

이미지를 잘라내거나 비율을 바꿔야 할 때 배경을 AI가 자연스럽게 채워준다는 거니까.

직접 써보기 전에 개념부터 잡고, 상용 서비스들을 하나씩 테스트해봤다.

Out Painting이란

원본 이미지의 사이즈를 변경해야 할 때, 없는 배경을 자연스럽게 생성해주는 기술이다.

예를 들어 16:9 이미지를 9:16으로 바꿔야 할 때, 원본 바깥 영역을 AI가 추론해서 채워준다.

직접 테스트해봤다

원본 사진에서 일부를 잘라낸 뒤, 잘린 이미지로 원본을 복원할 수 있는지 여러 서비스에서 테스트했다.

• 원본 사진

• 원본 사진 일부 추출 (캡처)

PromeAI

PromeAI 바로가기

• PromeAI 결과 화면

Pixelcut

Pixelcut 바로가기

• Pixelcut 결과 화면

CapCut

CapCut 바로가기

• CapCut 프롬프트 화면

• CapCut 프롬프트 입력 후 결과 화면

세 서비스 모두 사진이 완벽하게 복구되진 않았고, 퀄리티가 조금씩 아쉬웠다.

그 중 CapCut은 프롬프트를 함께 입력할 수 있어서 다른 서비스보다 조금 더 나은 결과를 받을 수 있었다.

Gemini

• Gemini Out Painting 프롬프트 화면

• Gemini 생성 이미지

Stable Diffusion으로도 해봤다

상용 서비스 외에 Stable Diffusion으로도 직접 돌려봤다.

• 원본 산 풍경 사진

• Stable Diffusion Out Painting 설정 화면

• Stable Diffusion Out Painting 결과

완벽하게 모방하진 못하지만 어느 정도의 자연스러움은 유지하면서 확장됐다.

문제는 속도였다

이미지 한 장 확장에 CPU 기준으로 약 3분이 걸렸다.

영상으로 확장하면 어떻게 될까 계산해봤다.

24fps 1분짜리 클립을 Out Painting 한다고 하면:

1,440 프레임 × 3분 = 4,320분

72시간이 넘는다 !

GPU로 시도해봐야 한다는 결론이 나왔다.

과연 영상으로 이 과정을 처리할 수 있을까 ?

다음 편에서는 Video Out Painting을 다룬 논문을 분석한다.

세로 영상을 가로로 변환하는 문제를 어떻게 접근했는지, 핵심 아이디어가 뭔지 정리해볼 예정이다.

choi.openai 님 Threads 포스트 (2025-12-24)

4개월 만에 상용 모델을 따라잡는 오픈소스라니, 직접 돌려보고 싶다는 생각이 바로 들었다.

그냥 API 쓰는 게 아니라, 모델이 내부적으로 어떻게 돌아가는지 직접 부딪혀보기로 했다.

시작하기 전에 GPU 관련 개념부터 제대로 정리해두기로 했다.

레이어 구조

GPU로 AI를 돌리려면 세 가지 계층이 맞춰져 있어야 한다.

PyTorch
   ↑
CUDA
   ↑
NVIDIA 드라이버
   ↑
GPU 하드웨어

위로 올라갈수록 추상화가 높아진다.

아래부터 하나씩 보자.

NVIDIA 드라이버

"운영체제 ↔ GPU 하드웨어를 이어주는 필수 소프트웨어"

OS와 애플리케이션이 GPU에 명령을 보내고 결과를 받게 해주는 가장 낮은 레벨의 소프트웨어 계층이다.

OS 입장에서 이게 없으면 GPU라는 하드웨어 자체를 인식하지 못한다.

드라이버 = GPU 장치 드라이버 (Device Driver)

CUDA

드라이버 위에서 돌아가는 개발용 플랫폼이다.

"GPU를 써서 연산을 짜고 돌리게 해주는 것"

CUDA = GPU 프로그래밍용 SDK + 런타임

개발자 입장에서 이게 없으면 C/Python 코드로 행렬연산이나 딥러닝 같은 걸 GPU에 던질 수 없다.

PyTorch

CUDA 위에서 돌아가는 고수준 프레임워크다.

CPU/GPU에서 텐서 연산, 자동 미분, 딥러닝 모델 구현과 학습을 담당한다.

GPU 가속이 필요할 때 내부적으로 CUDA를 사용한다.

개발자는 torch.cuda 모듈을 통해 CUDA를 직접 다루지 않고도 GPU를 쓸 수 있다.

레이어 순서 정리

서버 AMI 설정

이번에 AWS에서 아래 AMI를 선택했다.

Deep Learning OSS Nvidia Driver AMI GPU PyTorch 2.9 (Ubuntu 24.04)

이 AMI 하나로 아래가 전부 세팅된 상태로 시작한다.

• NVIDIA 드라이버 ✅
• CUDA Toolkit ✅
• cuDNN ✅
• PyTorch 2.9 ✅
• 기타 딥러닝 라이브러리들 ✅

직접 하나씩 설치하면 버전 충돌로 삽질할 가능성이 크다.

딥러닝 AMI를 쓰면 이 과정을 통째로 건너뛸 수 있다 !

다음 편에서는 Out Painting이 뭔지, 상용 서비스들을 직접 써보면서 비교한 과정을 정리한다.