Spring Boot + Thymeleaf 모놀리식 구조에서 React(Vercel) + Spring Boot(Docker) 분리 배포까지, 실전에서 마주한 삽질과 해결 과정을 공유합니다.

왜 프론트를 분리했는가?

기존 마이니치 니홍고 프로젝트는 Spring Boot + Thymeleaf로 프론트와 백엔드가 하나의 서버에서 동작하는 모놀리식 구조였습니다.

[사용자] → [Ubuntu 서버 (Spring Boot + Thymeleaf)]
                    ↕
              [MySQL DB]

여기에 소셜 로그인(Google, Kakao), JWT 인증, 학습 콘텐츠 리스트 등 프론트 기능이 점점 복잡해지면서 React로 전환하게 되었고, 자연스럽게 프론트/백엔드 분리 배포를 결정했습니다.

목표 아키텍처

[사용자] → [Vercel (React)] ←→ [Ubuntu 서버 (Spring Boot API)]
     mainichi-nihongo.com          api.mainichi-nihongo.com
                                          ↕
                                    [MySQL DB]
                                    [Redis]

• 프론트엔드: Vercel에 배포 (자동 CI/CD, CDN)
• 백엔드: Ubuntu 인스턴스에 Docker로 배포 (nginx-proxy + Let's Encrypt)
• 도메인 분리: mainichi-nihongo.com (프론트) / api.mainichi-nihongo.com (백엔드)

1. 프론트엔드 : 환경변수로 API 주소 관리하기

문제

개발 시에는 Vite의 proxy 설정으로 /api 요청을 localhost:8080으로 프록시했지만, 프로덕션에서는 백엔드 서버 주소가 다릅니다.

// ❌ 하드코딩된 API 주소
const API_BASE_URL = 'http://localhost:8080';

해결

Vite의 환경변수 시스템을 활용했습니다.

// ✅ 환경변수로 관리
export const API_BASE_URL =
  import.meta.env.VITE_API_BASE_URL || 'http://localhost:8080';

const api = axios.create({
  baseURL: API_BASE_URL,
  timeout: 10000,
});

Vercel 대시보드에서 VITE_API_BASE_URL을 https://api.mainichi-nihongo.com 으로 설정하면 프로덕션에서 자동으로 올바른 주소를 사용합니다.

⚠️ 주의: OAuth2 로그인 URL도 같은 방식으로 처리해야 합니다. authApi.ts에서 API_BASE_URL을 import해서 사용하세요.

2. 백엔드 : CORS와 도메인 설정

CORS 허용 출처 추가

프론트가 다른 도메인에서 API를 호출하므로 CORS 설정이 필수입니다.

# application.yml
cors:
  allowed-origins:
    - http://localhost:3000          # 로컬 개발
    - https://mainichi-nihongo.com    # 프로덕션
    - https://www.mainichi-nihongo.com
    - https://api.mainichi-nihongo.com

Docker Compose에서 API 서브도메인 설정

nginx-proxy + Let's Encrypt로 SSL 인증서 자동 발급

# docker-compose.yml
services:
  app:
    environment:
      VIRTUAL_HOST: api.mainichi-nihongo.com
      LETSENCRYPT_HOST: api.mainichi-nihongo.com
      FRONTEND_URL: ${FRONTEND_URL}

3. CI/CD : Github Actions로 자동 배포

환경변수 전달 구조

개발 중 OAuth2, JWT, Redis 등의 기능이 추가되면서 환경변수가 많아졌습니다. Github Secrets -> SSH -> .env 파일로 안전하게 전달합니다.

# .github/workflows/application-deploy-oracle.yml
- name: Deploy via SSH with environment variables
  env:
    DB_URL: ${{ secrets.DB_URL }}
    JWT_SECRET: ${{ secrets.JWT_SECRET }}
    GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
    KAKAO_CLIENT_ID: ${{ secrets.KAKAO_CLIENT_ID }}
    REDIS_HOST: ${{ secrets.REDIS_HOST }}
    REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD }}
    # ... 기타 변수들
  run: |
    ssh ubuntu@${{ secrets.ORACLE_HOST }} << EOF
      echo "DB_URL=${DB_URL}" > .env
      echo "JWT_SECRET=${JWT_SECRET}" >> .env
      # ... 나머지 변수들
      sudo docker compose pull
      sudo docker compose up -d --force-recreate
    EOF

4. 삽질 모음 : 프로덕션에서만 터지는 것들

삽질 1: Docker 이미지가 없다고?

ERROR: pull access denied, repository does not exist or may require authentication

openjdk:17-jdk-slim 이미지가 Docker Hub에서 deprecated 되어 더 이상 pull이 안 됩니다.

# ❌ deprecated
FROM openjdk:17-jdk-slim

# ✅ Eclipse Temurin으로 교체 (multi-platform 지원)
FROM eclipse-temurin:17-jre-jammy

삽질 2: OAuth2 로그인하면 redirect_uri가 http://?

카카오 로그인 시 이런 에러가 발생했습니다

등록하지 않은 리다이렉트 URI를 사용해 인가 코드를 요청했습니다. 사용한 리다이렉트 URI: http://api.mainichi-nihongo.com/login/oauth2/code/kakao

분명 https://로 등록했는데 http://로 요청이 갔습니다.

원인: Spring Boot는 nginx-proxy 뒤에서 8080 포트로 동작하기 때문에, 자신이 http://로 접근되고 있다고 인식합니다. nginx가 HTTPS를 처리하고 내부적으로는 HTTP로 전달하기 때문이죠.

# application.yml - 한 줄 추가로 해결
server:
  port: 8080
  forward-headers-strategy: native  # ← 이거!

이 설정으로 nginx-proxy가 보내는 X-Forwarded-Proto: https 헤더를 Spring Boot가 인식하게 됩니다.

Google OAuth2는 프로덕션에서 https:// redirect URI만 허용합니다. http://로 등록하면 작동하지 않아요.

삽질 3: 컨테이너 이름 충돌

Error: Conflict. The container name "/mainichi-nihongo" is already in use
by container "334f3290c63f..."

docker compose down은 현재 compose 프로젝트의 컨테이너만 제거합니다. 이전에 별도로 실행했던 같은 이름의 컨테이너가 남아있으면 충돌이 발생합니다.

# 수동으로 제거
sudo docker rm 334f3290c63f
sudo docker compose up -d

삽질 4: 로그인하면 /login 페이지로?

OAuth2 로그인이 api.mainichi-nihongo.com/login으로 리다이렉트되는 현상. 로그를 확인해보니

Table 'mainichi_nihongo.users' doesn't exist

application.yml에서 ddl-auto: none으로 설정해놓고 프로덕션 DB에 users 테이블을 생성하지 않았던 것이 원인이었습니다. 로컬에서는 이미 만들어둬서 잘 되었는데, 배포 환경에서는 빠뜨린 거죠.

CREATE TABLE users (
    id BIGINT NOT NULL AUTO_INCREMENT,
    email VARCHAR(255) NOT NULL,
    name VARCHAR(100),
    profile_image VARCHAR(500),
    provider VARCHAR(255) NOT NULL,
    provider_id VARCHAR(255) NOT NULL,
    tier VARCHAR(255) NOT NULL,
    created_at DATETIME(6) NOT NULL,
    last_login_at DATETIME(6),
    subscriber_id BIGINT,
    PRIMARY KEY (id),
    UNIQUE KEY uk_users_email (email)
);

ddl-auto: none 환경에서는 엔티티를 추가할 때마다 프로덕션 DB 마이그레이션을 잊지 말 것! Flyway나 Liquibase 같은 마이그레이션 도구 도입을 고려해보세요.

삽질 5: Vercel에서 직접 URL 접속하면 404

https://mainichi-nihongo.com/contents/20260223을 직접 주소창에 입력하면

404: NOT_FOUND

React는 SPA(Single Page Application)이기 때문에 모든 라우팅은 클라이언트(React Router)에서 처리합니다. Vercel에 해당 경로의 실제 파일이 없으므로 404를 반환합니다.

// vercel.json
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

이 설정으로 모든 경로를 index.html로 리라이트하면 React Router가 라우팅을 처리할 수 있습니다.

삽질 6: 파비콘이 Vercel에서 안 보인다?

public/favicon.ico를 넣었는데 Vercel에서 404. .gitignore를 열어보니

# Gatsby files
.cache/
public        # ← 이 놈!!!!

프로젝트 초기에 범용 .gitignore 템플릿을 사용했더니 Gatsby용 설정이 포함되어 있었고, Vite 프로젝트에서 정적 파일을 두는 public/ 폴더 전체가 Git에서 무시되고 있었습니다.

# ✅ 해당 라인 삭제 후
git add public/favicon.ico

.gitignore 템플릿을 그대로 쓰지 말고, 프로젝트에 맞게 검토하세요.

최종 체크리스트

프론트/백엔드 분리 배포 시 확인해야 할 사항들

• 프론트 API 주소가 환경변수로 관리되는가 ?
• 백엔드 CORS에 프론트 도메인이 허용되는가?
• OAuth2 rediret URI가 HTTPS인가?
• forward-headers-strategy가 설정되었는가?
• Vercel에 SPA 라우팅 설정 (vercel.json)이 있는가?
• .gitignore가 정적 파일을 무시하고 있지 않은가?
• 프로덕션 DB에 새 테이블이 생성되었는가?
• Github Secrets에 모든 환경변수가 등록되었는가?
• Docker 이미지가 최신 & multi-platform 지원인가?

마무리

모놀리식에서 프론트/백엔드 분리는 단순히 "코드를 나누는 것"이 아니라, 인프라, 네트워크, 보안, CI/CD 전반을 재설계하는 작업이었습니다.

특히 forward-headers-strategy나 .gitignore의 public 같은 문제는 로컬에서는 절대 발견할 수 없는, 프로덕션에서만 터지는 이슈들이어서 더 고생했습니다.

이 글이 비슷한 구조를 도입하려는 분들에게 도움이 되길 바랍니다 !

마이니치 니홍고 이용해보기

https://mainichi-nihongo.com

기술 스택: React + TypeScript + Vite (Vercel) / Spring Boot 3.4.5 + JPA + Security + OAuth2 (Docker) / MySQL 8.0 / Redis 7 / nginx-proxy + Let's Encrypt / GitHub Actions

개발하다 보면 누구나 겪는 딜레마. 모놀리스(Monolith)로 빠르게 시작하긴 했는데, 기능이 늘어날수록 의존성이 뒤엉켜서 '거대한 진흙 덩어리(Big Ball of Mud)'가 되어버린다. 그렇다고 당장 MSA로 넘어가자니 인프라 비용이랑 관리 포인트가 너무 부담스럽고.

그래서 찾아본 현실적인 대안, Spring Modulith. 스프링 공식 프로젝트라 믿을만하고, '모듈러 모놀리스(Modular Monolith)'를 강제해 주는 도구다. 핵심만 빠르게 정리해 둔다.

Spring Modulith가 뭔데?

쉽게 말해 "패키지 구조가 곧 아키텍처가 되게 만드는" 프레임워크다.

패키지 = 모듈: 최상위 패키지 바로 아래 있는 패키지들을 하나의 '논리적 모듈'로 본다.

경계 강제: 내 모듈의 public 클래스만 남이 쓸 수 있게 하고, 내부는 철저히 숨긴다.

느슨한 결합: 모듈끼리는 웬만하면 이벤트를 던져서 소통한다.

왜 써야 할까? (핵심 기능 3가지)

직접 써보니 좋았던 점은 구조 검증, 이벤트 처리, 문서화 딱 3가지다.

첫째, 아키텍처 구조 검증 (Verification)

보통 개발하다 보면 Order에서 Inventory 부르고, Inventory가 다시 Payment 부르고 난리가 난다. Spring Modulith는 테스트 코드 한 줄로 순환 참조나 허용되지 않은 의존성을 잡아낸다.

Java

class ApplicationModulesTest {

    @Test
    void verifyModularity() {
        // 전체 모듈 구조가 규칙을 잘 지키는지 검증
        // 순환 참조 있으면 바로 테스트 실패 뜸
        ApplicationModules.of(Application.class).verify();
    }
}

빌드 타임에 아키텍처 깨지는 걸 막을 수 있다는 게 엄청난 장점.

둘째, 이벤트 기반의 느슨한 결합 (Event Externalization)

서비스끼리 메서드 직접 호출(의존)하지 말고, 이벤트(Event)를 던지라는 거다. 특히 Transactional Outbox Pattern 구현이 진짜 편하다.

상황: 주문 완료되면 -> 재고 줄이기

주문 모듈: 주문 끝나면 OrderPlacedEvent 발행

재고 모듈: 이벤트 리스닝해서 처리

Java

// 재고 모듈 (Inventory)
@Component
@RequiredArgsConstructor
class InventoryEventListener {

    private final InventoryService inventoryService;

    // @EventListener 말고 이거 씀
    // 트랜잭션 커밋 된 후에 실행됨을 보장해 줌
    @ApplicationModuleListener 
    void on(OrderPlacedEvent event) {
        inventoryService.decreaseStock(event.orderId());
    }
}

@ApplicationModuleListener: 트랜잭션 성공했을 때만 실행되고, 실패하면 재시도 처리까지 지원함. 비동기 처리가 세상 편해짐.

셋째, 살아있는 문서화 (Documentation)

코드 짜기도 바쁜데 문서 업데이트는 언제 함? 얘는 코드를 분석해서 모듈 간 관계도(C4 Model)를 PlantUML로 그려준다.

Java

@Test
void writeDocumentationSnippets() {
    new Documenter(ApplicationModules.of(Application.class))
            .writeDocumentation() // build 폴더에 puml 파일 생성됨
            .writeIndividualModulesAsPlantUml();
}

코드가 바뀌면 문서도 알아서 바뀐다. 이게 진짜 문서화지.

디렉토리 구조는 이렇게

패키지 구조가 곧 모듈 정의다.

src/main/java
└── com.example.shop
    ├── ShopApplication.java
    ├── inventory            // [Inventory 모듈]
    │   ├── Inventory.java
    │   ├── InventoryService.java (public - 공개 API)
    │   └── internal          // (숨김 - 외부에서 접근 불가!)
    │       └── InventoryRepository.java 
    ├── order                // [Order 모듈]
    │   └── OrderService.java
    └── payment              // [Payment 모듈]

internal 같은 패키지에 넣어둔 건 외부 모듈에서 import 하려고 하면 컴파일러가(혹은 테스트가) 혼낸다. 강제로 캡슐화가 됨.

결론: 언제 도입할까?

"지금 당장 MSA 하긴 오버인데, 나중에 쪼갤 준비는 하고 싶을 때"

배포는 하나로 퉁쳐서 운영 편의성은 챙기고, 코드 내부는 MSA처럼 깔끔하게 유지할 수 있다. 나중에 트래픽 터져서 떼어내야 할 때도, 이미 모듈 경계가 확실해서 찢어내기 쉽다.

레거시가 엉망이거나, 신규 프로젝트 깔끔하게 시작하고 싶다면 Spring Modulith, 무조건 찍먹해볼 만하다.

📚 Reference Spring Modulith Reference Documentation

최근에 Mini PC를 구매해서 직접 Ubuntu를 설치하고, 기존에 Railway에서 운영하던 서비스를 Mini PC로 마이그레이션하는 작업을 진행했다. 처음엔 단순히 “클라우드 비용을 아껴보자”는 생각이었는데, 실제로 직접 서버를 구성해보니 예상보다 훨씬 많은 걸 배우고 느낄 수 있었다.

1. 실제 서버 환경 구성 — 클라우드가 자동으로 해주던 것들

Railway 같은 클라우드 서비스에서는 배포 버튼 몇 번만 누르면 모든 게 자동으로 된다. 하지만 Mini PC 환경에서는 기본적인 네트워크와 서버 설정을 모두 직접 해야 한다.

포트포워딩 설정

라우터에서 외부 요청이 Mini PC까지 올 수 있도록 포트포워딩을 수동으로 설정했다. 예를 들어, HTTP(80), HTTPS(443), API용 8080 포트를 열어서 내 내부 IP로 포워딩:

# 예시 (라우터 설정 화면에서)
외부포트: 80  → 내부 IP: 192.168.0.20  내부포트: 80  (TCP)
외부포트: 443 → 내부 IP: 192.168.0.20  내부포트: 443 (TCP)
외부포트: 8080 → 내부 IP: 192.168.0.20 내부포트: 8080 (TCP)

라우터마다 UI가 조금씩 다르긴 하지만, 원리는 동일하다.

UFW 방화벽 설정

Ubuntu 기본 방화벽인 UFW(Uncomplicated Firewall)를 활용해서 불필요한 포트는 차단하고, 필요한 포트만 열었다.

# 방화벽 활성화
sudo ufw enable

# 기본 정책: 모든 외부 접근 차단
sudo ufw default deny incoming
sudo ufw default allow outgoing

# 필요한 포트만 열기
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 8080/tcp  # API 서버

이 과정을 거치니, “클라우드에서 왜 기본적으로 보안 설정이 잘 돼 있는지” 체감할 수 있었다. 직접 하면 생각보다 귀찮고, 설정 실수 하나로 바로 접속이 막히거나 공격 대상이 되기도 한다.

도메인 & SSL 인증서 적용

무료 SSL 인증서를 발급해주는 Let’s Encrypt와 Nginx를 활용해서 HTTPS를 적용했다.

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

# Nginx 서버블록 설정 (예: /etc/nginx/sites-available/myservice)
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
    }
}

# 심볼릭 링크로 활성화
sudo ln -s /etc/nginx/sites-available/myservice /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# SSL 인증서 발급
sudo certbot --nginx -d example.com

이제 브라우저에서 https://example.com으로 접속하면 인증서가 적용된 안전한 서비스에 접근할 수 있게 됐다.

서비스 자동 실행 설정 (systemd)

서버가 재부팅되거나 장애가 발생했을 때 자동으로 백엔드 애플리케이션이 재시작되도록 systemd 설정도 추가했다.

sudo nano /etc/systemd/system/myservice.service

[Unit]
Description=My Spring Boot Service
After=network.target

[Service]
User=ubuntu
ExecStart=/usr/bin/java -jar /home/ubuntu/app/myservice.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable myservice
sudo systemctl start myservice

이제 서버가 꺼졌다 켜져도 자동으로 애플리케이션이 실행된다.

2. 클라우드가 “그만큼의 비용”을 받는 이유를 실감하다

Railway, Vercel, AWS, GCP 등은 단순히 서버만 빌려주는 게 아니다. 실제로 해보면, 그들이 인프라를 얼마나 자동화하고 안정적으로 제공하는지가 피부로 느껴진다. • 자동 백업 / 복구 • 장애 대비 고가용성 구성 (HA) • 로드밸런싱 및 트래픽 분산 • 모니터링, 로그 수집, 알림 시스템

이런 걸 혼자서 Mini PC 환경에 구성하려면 생각보다 훨씬 많은 시간, 경험, 그리고 리소스가 필요하다. 그래서 규모가 커지면 결국 클라우드 서비스로 이전하는 게 정답이라는 걸 깨달았다.

3. Mini PC의 역할 — 학습용, 소규모 서비스에 딱이다

그렇다고 Mini PC가 의미 없는 건 아니다. 오히려 공부용, 실험용으로는 정말 훌륭하다. • 개인 블로그나 소규모 API 서버 운영 가능 • Docker, Nginx, CI/CD 등 실습에 최적 • 인프라 전반을 스스로 설정해보며 실력을 끌어올릴 수 있음 • 비용 부담 없이 자유롭게 테스트 가능

실제로 이번 마이그레이션 경험은 단순히 서버 이전이 아니라, 인프라의 기본 원리를 체득하는 값진 시간이었다.

마무리

👉 정리하자면, • 공부/소규모 서비스에는 Mini PC로도 충분하다. • 실서비스/대규모 트래픽은 클라우드의 안정성과 자동화가 필요하다. • 무엇보다, 실제로 직접 설정해보는 경험이 개발자로서의 역량을 크게 키운다.

이번 경험을 통해 클라우드의 편리함이 단순한 “편의” 수준이 아니라는 걸 확실히 느꼈고, 동시에 Mini PC 환경에서 자유롭게 실험해볼 수 있는 즐거움도 컸다. 앞으로도 이런 식의 실험을 계속해 나갈 생각이다. 💪

정보처리기사 실기 준비 중 서브넷 개념과 문제 풀이 방법을 정리했습니다.

🔍 서브넷(Subnet)이란?

서브넷은 하나의 큰 네트워크를 여러 개의 작은 네트워크로 나누는 기술입니다. 이를 통해 네트워크를 효율적으로 관리하고 보안을 강화할 수 있습니다.

서브넷 마스크는 IP 주소에서 네트워크 영역과 호스트 영역을 구분하는 데 사용됩니다.

📊 기본 서브넷 마스크

💡 핵심 공식

1. 서브넷 개수 계산

서브넷 개수 = 2^n
(n = 서브넷 비트 수)

2. 호스트 개수 계산

호스트 개수 = 2^h - 2
(h = 호스트 비트 수)

-2를 하는 이유: 네트워크 주소와 브로드캐스트 주소는 사용할 수 없기 때문

3. CIDR 표기법 이해

• /24 → 255.255.255.0 (호스트 비트 8개)
• /26 → 255.255.255.192 (호스트 비트 6개)
• /27 → 255.255.255.224 (호스트 비트 5개)

변환 방법: 8비트씩 순서대로 1로 채우고, 나머지는 0으로 채웁니다.

📝 자주 나오는 문제 유형

유형 1: 서브넷 범위 구하기

예제: 192.168.10.0/25의 서브넷 범위는?

- 네트워크 주소: 192.168.10.0
- 브로드캐스트 주소: 192.168.10.127
- 사용 가능한 IP: 192.168.10.1 ~ 192.168.10.126
- 사용 가능한 호스트 수: 126개

계산 과정:

• /25는 호스트 비트가 7개
• 2^7 - 2 = 126개의 호스트

유형 2: 네트워크 분할

예제: 192.168.1.0/24를 4개의 서브넷으로 나누기

필요한 서브넷 비트: 2^2 = 4개 → 2비트 필요
새로운 서브넷 마스크: /26 (255.255.255.192)

각 서브넷:
1번: 192.168.1.0   ~ 192.168.1.63
2번: 192.168.1.64  ~ 192.168.1.127
3번: 192.168.1.128 ~ 192.168.1.191
4번: 192.168.1.192 ~ 192.168.1.255

유형 3: 서로 다른 서브넷으로 분리

예제: 192.168.0.1과 192.168.0.65를 서로 다른 서브넷에 배치하려면?

풀이:

1. 두 IP의 차이를 확인 (64)
2. 64는 2^6이므로, 호스트 비트가 6개 이하면 분리 가능
3. 답: 255.255.255.192 (/26) 사용

🎯 문제 풀이 팁

1. 2의 제곱수를 외워두기: 2, 4, 8, 16, 32, 64, 128, 256
2. 비트 계산에 익숙해지기: 8비트 단위로 생각하기
3. 네트워크/브로드캐스트 주소 제외하기: 항상 -2 기억
4. CIDR 표기법 변환 연습: /24, /25, /26 등을 즉시 변환할 수 있도록

🔥 실전 연습 문제

Q1. 255.255.255.192의 호스트 개수는?

255.255.255.192는 /26
호스트 비트: 6개
2^6 - 2 = 62개

Q2. 10.0.0.0/8 네트워크를 16개의 서브넷으로 나누려면?

16 = 2^4 → 4비트 필요
/8 + 4 = /12
서브넷 마스크: 255.240.0.0

📌 마무리

서브넷 문제는 공식과 계산 방법만 숙지하면 빠르게 풀 수 있는 유형입니다. 특히 실기에서는 직접 계산해야 하므로 2의 제곱수와 CIDR 변환을 확실히 익혀두는 것이 중요합니다!

참고: 이 내용은 정보처리기사 실기 시험 준비를 위해 학습한 내용을 정리한 것입니다.

들어가며

최근 사이드 프로젝트로 Spring Boot 기반의 RESTful API 서버를 개발하고 있었습니다. 로컬 환경에서는 Docker Compose를 활용해 Redis, MongoDB, MySQL을 함께 운영하며 개발을 진행했는데, 배포 단계에서 고민이 많았습니다.

AWS EC2나 GCP Compute Engine을 사용하자니 설정할 것이 너무 많고, Heroku는 2022년 11월부터 무료 플랜이 사라져서 대안을 찾고 있었죠. 그러던 중 개발자 커뮤니티에서 Railway라는 서비스를 알게 되었고, 직접 마이그레이션해본 경험을 상세히 공유하고자 합니다.

기존 환경 분석

로컬 개발 환경

• Framework: Spring Boot 3.1.5
• Java Version: OpenJDK 17
• Build Tool: Gradle 8.4
• Database: MySQL 8.0 (주 데이터), MongoDB 6.0 (로그 데이터)
• Cache: Redis 7.0
• Container: Docker Compose

Docker Compose 구성

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - MYSQL_HOST=mysql
      - MYSQL_PORT=3306
      - MYSQL_DATABASE=myapp
      - MYSQL_USERNAME=app_user
      - MYSQL_PASSWORD=secure_password
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - MONGO_HOST=mongo
      - MONGO_PORT=27017
      - MONGO_DATABASE=myapp_logs
    depends_on:
      - mysql
      - redis
      - mongo
    networks:
      - app-network

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_DATABASE=myapp
      - MYSQL_USER=app_user
      - MYSQL_PASSWORD=secure_password
      - MYSQL_ROOT_PASSWORD=root_password
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - app-network

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --requirepass redis_password
    volumes:
      - redis_data:/data
    networks:
      - app-network

  mongo:
    image: mongo:6
    environment:
      - MONGO_INITDB_ROOT_USERNAME=mongo_user
      - MONGO_INITDB_ROOT_PASSWORD=mongo_password
      - MONGO_INITDB_DATABASE=myapp_logs
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    networks:
      - app-network

volumes:
  mysql_data:
  redis_data:
  mongo_data:

networks:
  app-network:
    driver: bridge

Dockerfile 구성

FROM openjdk:17-jdk-slim

WORKDIR /app

COPY build/libs/*.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app/app.jar"]

주요 기능

• 인증/인가: JWT 기반 인증 시스템
• 파일 업로드: MultipartFile 처리 (이미지, 문서)
• 실시간 알림: WebSocket 연결
• API 문서화: Swagger/OpenAPI 3.0
• 로깅: 구조화된 로그를 MongoDB에 저장
• 캐싱: Redis를 활용한 세션 관리 및 데이터 캐싱

Railway 마이그레이션 과정

1단계: Railway 프로젝트 초기화

Railway 대시보드에서 새 프로젝트를 생성하는 과정은 놀라울 정도로 간단했습니다.

1. GitHub 연동: Railway에서 "Deploy from GitHub repo" 선택
2. Repository 선택: 배포할 레포지토리를 선택하면 자동으로 Dockerfile을 인식
3. 자동 빌드: 첫 번째 배포가 자동으로 시작됨

# Railway CLI 설치 (선택사항)
npm install -g @railway/cli

# 로컬에서 Railway 프로젝트 연결
railway login
railway link [프로젝트-ID]

2단계: 데이터베이스 서비스 추가

Railway의 가장 큰 장점 중 하나는 데이터베이스를 별도로 관리할 필요가 없다는 것입니다.

2-1. MySQL 서비스 추가

Railway Dashboard → Add Service → Database → MySQL

Railway에서 제공하는 MySQL 인스턴스 정보:

• Host: containers-us-west-xxx.railway.app
• Port: 6543
• Database: railway
• Username: root
• Password: 자동 생성된 32자리 패스워드

2-2. Redis 서비스 추가

Railway Dashboard → Add Service → Database → Redis

Redis 연결 정보:

• Host: redis-xxx.railway.app
• Port: 6379
• Password: 자동 생성

2-3. MongoDB 서비스 추가

Railway Dashboard → Add Service → Database → MongoDB

MongoDB 연결 정보:

• Connection URI: mongodb://mongo:xxx@containers-us-west-xxx.railway.app:6034/railway

3단계: 환경변수 구성

Railway는 각 데이터베이스 서비스마다 연결 정보를 환경변수로 자동 제공합니다. 이를 Spring Boot의 application.yml에 맞게 매핑해야 합니다.

Railway 제공 환경변수

# MySQL
MYSQL_URL=mysql://root:xxx@containers-us-west-xxx.railway.app:6543/railway
MYSQLHOST=containers-us-west-xxx.railway.app
MYSQLPORT=6543
MYSQLDATABASE=railway
MYSQLUSER=root
MYSQLPASSWORD=xxx

# Redis
REDIS_URL=redis://:xxx@redis-xxx.railway.app:6379
REDISHOST=redis-xxx.railway.app
REDISPORT=6379
REDISPASSWORD=xxx

# MongoDB  
MONGO_URL=mongodb://mongo:xxx@containers-us-west-xxx.railway.app:6034/railway
MONGOHOST=containers-us-west-xxx.railway.app
MONGOPORT=6034
MONGOUSER=mongo
MONGOPASSWORD=xxx
MONGODATABASE=railway

application.yml 수정

spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:prod}

  # MySQL 설정
  datasource:
    url: jdbc:mysql://${MYSQLHOST:localhost}:${MYSQLPORT:3306}/${MYSQLDATABASE:myapp}?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
    username: ${MYSQLUSER:root}
    password: ${MYSQLPASSWORD:password}
    driver-class-name: com.mysql.cj.jdbc.Driver

  # JPA 설정
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true

  # MongoDB 설정
  data:
    mongodb:
      host: ${MONGOHOST:localhost}
      port: ${MONGOPORT:27017}
      database: ${MONGODATABASE:myapp_logs}
      username: ${MONGOUSER:}
      password: ${MONGOPASSWORD:}
      authentication-database: admin

  # Redis 설정
  data:
    redis:
      host: ${REDISHOST:localhost}
      port: ${REDISPORT:6379}
      password: ${REDISPASSWORD:}
      timeout: 60000
      jedis:
        pool:
          max-active: 8
          max-wait: -1
          max-idle: 8
          min-idle: 0

# 서버 설정
server:
  port: ${PORT:8080}

# JWT 설정
jwt:
  secret: ${JWT_SECRET:your-secret-key}
  expiration: ${JWT_EXPIRATION:3600000}

# 파일 업로드 설정
file:
  upload:
    path: ${FILE_UPLOAD_PATH:/tmp/uploads}
    max-size: ${FILE_MAX_SIZE:10485760}

4단계: Railway Variables 설정

Railway 대시보드에서 Variables 탭으로 이동해 다음 환경변수들을 추가했습니다.

# Spring 프로파일
SPRING_PROFILES_ACTIVE=prod

# JWT 설정
JWT_SECRET=your-super-secure-jwt-secret-key-here
JWT_EXPIRATION=3600000

# 파일 업로드 설정
FILE_UPLOAD_PATH=/app/uploads
FILE_MAX_SIZE=10485760

# 로깅 레벨
LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_COM_MYAPP=DEBUG

# Railway 포트 (자동 설정됨)
PORT=${{PORT}}

5단계: 배포 및 테스트

코드를 GitHub에 push하면 Railway가 자동으로 배포를 시작합니다.

git add .
git commit -m "Configure Railway deployment"
git push origin main

배포 과정은 Railway 대시보드의 Deployments 탭에서 실시간으로 확인할 수 있습니다.

1. Build Phase: Dockerfile 기반 이미지 빌드
2. Deploy Phase: 컨테이너 실행 및 health check
3. Live: 서비스 활성화 완료

배포가 완료되면 Railway에서 제공하는 도메인 (예: https://myapp-production-xxxx.up.railway.app)으로 접근할 수 있습니다.

성능 및 모니터링

Railway 제공 메트릭

Railway 대시보드에서 다음과 같은 메트릭을 실시간으로 확인할 수 있습니다.

• CPU 사용량: 평균 15-20% (유휴 상태 기준)
• 메모리 사용량: 약 300MB (Spring Boot JVM 기본 설정)
• 네트워크 I/O: 인바운드/아웃바운드 트래픽
• 응답 시간: 평균 200ms 이하

로그 모니터링

Railway는 실시간 로그 스트리밍을 제공합니다.

# Railway CLI로 로그 확인
railway logs --follow

# 특정 서비스 로그만 확인
railway logs --service mysql --follow

Health Check 구성

Spring Boot Actuator를 활용해 health check 엔드포인트를 구성했습니다.

@RestController
@RequestMapping("/actuator")
public class HealthController {

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    @Autowired
    private DataSource dataSource;

    @GetMapping("/health")
    public ResponseEntity<Map<String, String>> health() {
        Map<String, String> status = new HashMap<>();

        try {
            // MySQL 연결 확인
            try (Connection connection = dataSource.getConnection()) {
                status.put("mysql", "UP");
            }

            // Redis 연결 확인
            redisTemplate.opsForValue().set("health-check", "OK");
            status.put("redis", "UP");

            status.put("status", "UP");
            return ResponseEntity.ok(status);

        } catch (Exception e) {
            status.put("status", "DOWN");
            status.put("error", e.getMessage());
            return ResponseEntity.status(503).body(status);
        }
    }
}

비용 분석

Railway 요금 체계

Railway는 사용량 기반 과금 모델을 사용합니다.

• Compute: $0.000463/vCPU/minute
• Memory: $0.000231/GB/minute
• Egress: $0.10/GB
• Storage: 데이터베이스별 별도 과금

실제 사용 비용 (월간)

• Spring Boot App: CPU 0.5, Memory 512MB → 약 $8/월
• MySQL: 약 $5/월
• Redis: 약 $3/월
• MongoDB: 약 $4/월
• Total: 약 $20/월

$20 무료 크레딧으로 약 1개월간 무료 사용이 가능합니다.

기존 솔루션과 비교

• AWS EC2 t3.micro: $8.5/월 + RDS $15/월 + ElastiCache $13/월 = $36.5/월
• Heroku: Dyno $7/월 + PostgreSQL $9/월 + Redis $15/월 = $31/월
• Railway: 약 $20/월 (올인원)

최적화 및 팁

1. 빌드 시간 최적화

# Multi-stage build로 빌드 시간 단축
FROM gradle:7.6-jdk17 AS build
COPY --chown=gradle:gradle . /home/gradle/src
WORKDIR /home/gradle/src
RUN gradle build --no-daemon

FROM openjdk:17-jdk-slim
COPY --from=build /home/gradle/src/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

2. 환경별 배포 설정

Railway에서는 브랜치별로 다른 환경을 구성할 수 있습니다.

• main 브랜치 → Production 환경
• develop 브랜치 → Staging 환경

3. 자동 SSL 및 도메인

Railway는 자동으로 HTTPS를 적용하고, 커스텀 도메인도 쉽게 연결할 수 있습니다.

Settings → Environment → Custom Domain → Add Domain

4. 백업 설정

각 데이터베이스는 자동 백업이 활성화되어 있지만, 중요한 데이터는 별도 백업 전략을 수립하는 것이 좋습니다.

🚨 주의사항 및 한계점

장점

• 간편한 배포: Dockerfile만 있으면 즉시 배포 가능
• 통합 관리: DB까지 한 곳에서 관리
• 자동 스케일링: 트래픽에 따른 자동 확장
• 실시간 모니터링: 로그, 메트릭 실시간 확인
• 합리적인 가격: 소규모 프로젝트에 적합

한계점

• 지역 제한: 아직 아시아 리전 없음 (레이턴시 약 150-200ms)
• 커스터마이징 제약: 고도의 인프라 커스터마이징이 어려움
• 대용량 트래픽: 대규모 서비스에는 부적합할 수 있음
• 한국어 지원: 공식 한국어 문서 부재

추천 대상

• 사이드 프로젝트 및 MVP 개발
• 스타트업 초기 단계
• 개인 포트폴리오 프로젝트
• 프로토타입 개발 및 테스트

향후 계획

1. CI/CD 파이프라인 구성

GitHub Actions와 Railway를 연동한 자동 배포 파이프라인을 구축할 예정입니다.

# .github/workflows/deploy.yml
name: Deploy to Railway

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Railway CLI
        run: npm install -g @railway/cli
      - name: Deploy to Railway
        run: railway deploy
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

2. 모니터링 강화

Prometheus + Grafana를 통한 커스텀 메트릭 수집과 New Relic 연동을 검토하고 있습니다.

3. 로드 테스트

Apache JMeter를 활용해 Railway 환경에서의 성능 한계를 측정하고, 최적화 포인트를 찾을 계획입니다.

결론

Docker Compose에서 Railway로의 마이그레이션은 예상보다 훨씬 수월했습니다. 특히 데이터베이스 관리의 복잡성이 크게 줄어들었고, 배포 과정도 자동화되어 개발에만 집중할 수 있게 되었습니다.

Railway는 다음과 같은 경우에 특히 추천합니다.

1. 빠른 MVP 배포가 필요한 경우
2. 인프라 관리보다 개발에 집중하고 싶은 경우
3. 합리적인 비용으로 풀스택 환경을 구축하고 싶은 경우

물론 대규모 트래픽을 처리해야 하거나, 특수한 인프라 요구사항이 있다면 AWS나 GCP를 고려하는 것이 좋습니다. 하지만 개인 프로젝트나 스타트업 초기 단계라면 Railway가 매우 실용적인 선택지라고 생각합니다.

참고 자료

• Railway 공식 문서
• Spring Boot 공식 문서
• Docker Compose 공식 문서

💡 Railway $20 크레딧 받기: 여기서 가입

최근에 Ninety라는 습관 트래킹 앱에 간단한 게임 요소를 추가하는 작업을 했다. 방 꾸미기와 펫 수집/육성 기능을 넣어서 사용자들이 습관을 달성할 때마다 재미를 느낄 수 있도록 만들었다.

처음에는 단순하게 시작했지만, 게임 요소가 들어가면서 여러 가지 기술적 고민이 생겼다. 특히 게임 리소스를 어떻게 관리할지에 대한 부분이 가장 고민스러웠다.

백오피스 분리에 대한 고민

현재 상점 관련 API들(방 꾸미기 아이템, 캐릭터 관련)이 모두 Ninety 메인 프로젝트에 포함되어 있다. 개발 초기에는 빠르게 구현하기 위해 이렇게 했지만, 점점 불편함을 느끼기 시작했다.

상점 아이템을 추가하거나 수정할 때마다 메인 앱의 코드를 건드려야 하는 상황이 발생했다. 예를 들어 새로운 가구 아이템을 추가하려면 API 코드를 수정하고, 배포까지 해야 하는 번거로움이 있었다.

그래서 백오피스 기능을 별도 프로젝트로 분리하는 것을 고려하게 되었다. 전용 웹사이트나 관리 툴을 만들어서 게임 컨텐츠를 관리할 수 있도록 말이다 !

분리했을 때의 장점들

• 책임 분리 : 게임 컨텐츠 관리와 메인 앱 로직을 완전히 분리할 수 있다
• 개발 효율성 : 컨텐츠 업데이트를 위해 메인 앱을 건드릴 필요가 없다
• 확장성 : 나중에 더 복잡한 게임 요소가 추가되어도 유연하게 대응할 수 있다
• 협업 : 기획자나 다른 팀원들이 직접 컨텐츠를 관리할 수 있다

결국 별도 관리 시스템을 구축하는 것이 장기적으로 더 좋겠다는 결론을 내렸다.

게임 리소스 저장 방식 고민

다음으로 고민한 것은 게임 리소스(이미지 파일들)를 어떻게 관리할지였다.

프론트엔드 번들링 vs 외부 저장소

처음에는 픽셀 아트로 만든 이미지들이 용량이 크지 않아서 그냥 프론트엔드 프로젝트에 포함시키면 어떨까 생각했다. 이렇게 하면 ?

• 별도 서버 없이도 이미지를 표시할 수 있다
• 네트워크 요청 없이 즉시 로딩된다
• 관리가 단순해진다

하지만 곰곰히 생각해보니 여러 문제점들이 보였다.

• 새로운 아이템이 추가될 때마다 앱을 새로 배포해야 한다
• 앱 용량이 계속 늘어날 수 있다
• 이미지 최적화나 버전 관리가 어렵다
• 백오피스에서 동적으로 컨텐츠를 관리하기 힘들다

AWS S3 + 백오피스 조합

결국 AWS S3에 리소스를 저장하고, 백오피스 툴에서 API를 통해 상점 아이템들을 생성 / 관리하는 방식을 선택했다.

이 방식의 장점은 ?

• 동적 관리 : 앱 배포 없이도 새로운 아이템을 추가할 수 있다
• 성능 : CDN을 통한 빠른 이미지 로딩
• 확장성 : 나중에 더 많은 리소스가 생겨도 대응 가능
• 관리 편의성 : 백오피스에서 이미지 업로드부터 상품 등록까지 한 번에 처리

배운 점들

초기 편의성 vs 장기 확장성 처음에는 간단하게 구현하는 것이 좋지만, 어느 정도 규모가 커지면 구조를 제대로 잡는 것이 중요하다. 당장은 번거로워 보여도 나중을 생각하면 투자할 가치가 있다.

컨텐츠 관리의 중요성 게임 요소가 들어가면 컨텐츠 업데이트가 빈번해진다. 이를 위한 시스템을 미리 준비해두지 않으면 나중에 발목을 잡힌다..

단계적 접근 처음부터 완벽한 시스템을 만들려고 하지 말고, 문제가 생겼을 때 하나씩 개선해나가는 것도 좋은 방법이다. 다만 너무 늦기 전에 리팩토링을 시작해야 한다.

작은 프로젝트지만 이런 고민들을 통해 시스템 설계에 대해 더 깊이 생각해볼 수 있었다. 무엇보다 사용자가 재미있게 습관을 만들어갈 수 있는 서비스를 만들어가는 과정이 즐겁다.

Spring Boot 프로젝트에서 날짜별 콘텐츠를 조회하는 기능을 구현하던 중, 다음과 같은 오류가 발생했다.

Query did not return a unique result: 2 results were returned

처음에는 동일한 날짜에 여러 개의 레코드가 존재하는 것으로 생각했다. 하지만 MySQL에서 직접 쿼리를 실행해보니 예상과 달랐다.

문제가 된 코드

Repository

@Query("SELECT e FROM EmailContent e JOIN FETCH e.theme WHERE e.createdAt BETWEEN ?1 AND ?2")
Optional<EmailContent> findByCreatedDateBetween(LocalDateTime startDate, LocalDateTime endDate);

Controller

LocalDate targetDate = LocalDate.parse(date, DateTimeFormatter.ofPattern("yyyyMMdd"));
LocalDateTime startOfDay = targetDate.atStartOfDay();        // 2025-07-05T00:00:00
LocalDateTime endOfDay = targetDate.atTime(23, 59, 59);     // 2025-07-05T23:59:59

Optional<EmailContent> content = emailContentRepository.findByCreatedDateBetween(startOfDay, endOfDay);

MySQL 직접 확인 결과

-- 날짜별 레코드 수 확인
SELECT DATE(created_at) as date, COUNT(*) as count 
FROM email_content 
GROUP BY DATE(created_at) 
HAVING count > 1;
-- 결과: Empty set

-- 해당 날짜의 데이터 확인
SELECT count(1) 
FROM email_content e 
JOIN content_theme t ON t.id = e.theme_id 
WHERE e.created_at BETWEEN '2025-07-05 00:00:00' AND '2025-07-05 23:59:59';
-- 결과: 1 (정상)

MySQL에서는 1개의 결과만 나오는데, 왜 JPA에서는 2개 결과가 반환된다고 하지?

원인 분석

JPA JOIN FETCH의 특성

문제는 JPA의 JOIN FETCH와 Optional 조합에서 발생했다.

• JOIN FETCH는 연관된 엔티티를 즉시 로딩하기 위한 JPA 최적화 기법
• 하지만 Optional과 함께 사용할 때, JPA 구현체 (Hibernate)의 내부 처리 과정에서 중복 결과로 인식하는 경우가 있음
• 실제 DB에서는 1개 행 이지만, JPA 레벨에서는 2개로 인식하는 상황

Hibernate 로그 분석

Hibernate: 
    select
        ec1_0.id,
        ec1_0.created_at,
        ec1_0.detailed_content,
        ec1_0.html_content,
        ec1_0.sent,
        ec1_0.sent_at,
        t1_0.id,
        t1_0.jlptlevel,
        t1_0.topic,
        t1_0.used,
        t1_0.used_at 
    from
        email_content ec1_0 
    join
        content_theme t1_0 
            on t1_0.id=ec1_0.theme_id 
    where
        ec1_0.created_at between ? and ?

SQL 자체는 정상적이지만, JPA가 결과를 Optional로 변환하는 과정에서 문제가 발생한다.

해결 방법

1. DISTINCT 추가

@Query("SELECT DISTINCT e FROM EmailContent e JOIN FETCH e.theme WHERE e.createdAt BETWEEN ?1 AND ?2")
Optional<EmailContent> findByCreatedDateBetween(LocalDateTime startDate, LocalDateTime endDate);

왜 DISTINCT가 해결책?

• JPA에서 JOIN FETCH를 사용할 때 권장되는 패턴
• 중복 결과 제거로 Optional 안전하게 동작

2. 반환 타입 변경

@Query("SELECT e FROM EmailContent e JOIN FETCH e.theme WHERE e.createdAt BETWEEN ?1 AND ?2")
List<EmailContent> findByCreatedDateBetween(LocalDateTime startDate, LocalDateTime endDate);

// Controller에서 사용
List<EmailContent> contents = emailContentRepository.findByCreatedDateBetween(startOfDay, endOfDay);
Optional<EmailContent> content = contents.isEmpty() ? Optional.empty() : Optional.of(contents.get(0));

3. JOIN FETCH 제거

Optional<EmailContent> findByCreatedAtBetween(LocalDateTime startDate, LocalDateTime endDate);

연관된 엔티티는 지연 로딩으로 처리하고, 필요시 별도 조회

TIL

1. JPA와 실제 DB 동작의 차이 : MySQL에서 정상 동작하는 쿼리라도 JPA 레벨에서는 다른 결과가 나올 수 있다.
2. JOIN FETCH + Optional 조합 주의 : 이 조합은 NonUniqueResult 오류를 발생시킬 수 있으므로 DISTINCT를 함께 사용하는 것이 안전하다.
3. 디버깅 접근법 :
   • 먼저 DB에서 직접 쿼리 실행
   • Hibernate 로그 확인
   • JPA 내부 동작 원리 이해
4. Best Practice : JPA에서 JOIN FETCH를 사용할 때는 항상 DISTINCT를 고려하자.

단순해 보이는 조회 기능이지만, JPA의 내부 동작을 이해하지 못하면 예상치 못한 오류에 직면할 수 있다. 이번 경험을 통해 ORM의 추상화 뒤에 숨겨진 복잡성을 다시 한번 깨달았다.

• 참고 자료
  • Hibernate Documemtation - JOIN FETCH
  • JPA Query 최적화 가이드

Spring Boot로 운영 중인 프로젝트에서 대규모 이메일 발송 성능 테스트를 수행하다가, 두 가지 문제를 겪고 원인 분석 및 해결까지 진행한 경험을 공유합니다.

배경

프로젝트에 구독자에게 일본어 학습 이메일을 매일 발송하는 기능이 있습니다. 실제로 수천 명의 유저에게 동시에 이메일을 보낼 수 있도록 하기 위해, 단일 스레드 기반으로 성능 테스트 코드를 작성했습니다.

public PerformanceResult testSingleThreadPerformance(int targetCount) {
    List<Subscriber> testSubscribers = createTestSubscribers(targetCount);
    String subject = "마이니치 니홍고 - 성능 테스트";
    String content = contentService.generateDailyContent(); // 매일 학습 콘텐츠 생성

    for (Subscriber subscriber : testSubscribers) {
        emailService.sendEmail(subscriber.getEmail(), subject, content);
        ...
    }
}

generateDailyContent()는 오늘 날짜 기준의 콘텐츠를 생성하고 저장하며, emailService.sendEmail()은 JavaMailSender를 통해 실제 메일을 발송합니다.

하지만 1만명 단위의 구독자 테스트를 수행하던 중, 아래와 같은 경고 로그가 계속 출력되었습니다.

문제 1 : 커넥션 누수 (Connection Leak) 경고 발생

문제 발생

HikariPool-1 - Connection leak detection triggered for ... 

테스트 중 일정 수 이상의 구독자에게 메일을 발송하면 위와 같은 커넥션 누수 경고가 반복적으로 출력되고, 전체 테스트 속도도 현저히 느려졌습니다.

원인 추론

generateDailyContent() 내부 코드를 살펴본 결과, 문제의 원인을 찾을 수 있었습니다.

@Transactional
public String generateDailyContent() {
    Optional<EmailContent> todayContent = emailContentRepository.findByCreatedDate(...);
    ...
    String htmlContent = geminiService.generateContent(...); // 외부 API 호출
    ...
    emailContentRepository.save(...);
    ...
}

이 메서드는 @Transactional이 붙어 있기 때문에, 전체 블록이 하나의 트랜잭션으로 묶입니다. 즉, 내부에서 사용하는 DB 커넥션은 트랜잭션이 끝날 때까지 반환되지 않습니다.

그런데 문제는 geminiService.generateContent()가 외부 AI API 호출이기 때문에 지연이 수 초 이상 발생하는 경우가 잦았습니다. 그 시간 동안 커넥션이 반환되지 않기 때문에, 수천 명에게 메일을 보내면 커넥션 풀을 모두 소진하게 됩니다.

결과적으로 커넥션 누수 경고가 발생한 것입니다.

해결 방법

핵심은 외부 API 호출을 트랜잭션 밖으로 분리하여, DB 커넥션을 점유하지 않도록 하는 것입니다.

public String generateDailyContent() {
    Optional<EmailContent> todayContent = emailContentRepository.findByCreatedDate(...);
    if (todayContent.isPresent()) {
        return applyEmailTemplate(todayContent.get().getHtmlContent());
    }

    ContentTheme theme = getOrCreateTheme();
    String htmlContent = geminiService.generateContent(theme.getJLPTLevel(), theme.getTopic());

    return saveContentWithTransaction(theme, htmlContent); // 트랜잭션은 여기서 시작
}

@Transactional
public String saveContentWithTransaction(ContentTheme theme, String htmlContent) {
    EmailContent emailContent = new EmailContent(theme, htmlContent);
    emailContentRepository.save(emailContent);

    theme.markAsUsed();
    contentThemeRepository.save(theme);

    return applyEmailTemplate(htmlContent);
}

이렇게 분리하면 트랜잭션이 필요한 DB 작업만 최소 범위로 분리되어, 커넥션 점유 시간이 줄어듭니다.

문제 2 : Gmail SMTP 일일 발송량 초과로 인한 전송 실패

문제 발생

성능 테스트 중 갑자기 콘솔에 다음과 같은 오류가 발생했습니다.

org.eclipse.angus.mail.smtp.SMTPSendFailedException: 
550-5.4.5 Daily user sending limit exceeded. 
For more information on Gmail 550-5.4.5 sending limits go to ...

이메일 전송 실패: Failed messages: org.eclipse.angus.mail.smtp.SMTPSendFailedException: 550-5.4.5 Daily user sending limit exceeded.

원인 분석

이는 JavaMailSender나 SMTP 설정의 문제가 아니라, *Gmail SMTP *서버가 제공하는 일일 발송량 한도를 초과했기 때문입니다.

• Gmail SMTP는 일반 계정 기준으로 하루에 최대 500명에게만 메일 전송 가능
• 테스트 중 1만명 이상의 구독자에게 메일을 전송하려 했기 때문에, Gmail 서버 측에서 이를 차단한 것

Gmail 공식 가이드에 따르면, SMTP를 통한 대량 발송은 제한되며, 비즈니스용 Google Workspace에서도 하루 2,000건 내외로 제한됩니다.

해결 방법

이번 테스트는 개발 환경에서 Gmail SMTP로 메일 발송을 설정한 상태였기 때문에, 실제 대량 발송에 적합한 메일 서비스로 전환이 필요했습니다.

다음과 같은 방법을 고려하고 있습니다.

1. Amazon SES, Mailgun, Sendgrid 등 외부 이메일 서비스 사용

   • Amazon SES : 저렴하고 AWS 기반이라 확장성도 우수
   • Mailgun/SendGrid : REST API 또는 SMTP를 통해 대량 발송 지원
   • 대부분 SPF, DKIM 설정을 통해 발송 신뢰도도 높일 수 있음

2. 메일 발송 큐 구성

   • 실제 서비스에서는 Kafka나 RabbitMQ 기반의 비동기 메일 큐 구성을 통해 메일 발송 속도를 제어
   • 일정 시간당 발송량을 제한하여 발송 실패율을 줄일 수 있음

   ---

   마무리

• Gmail SMTP 제한을 인지하고.. 메일을 500개 정도로 줄여서 테스트 진행
• 이후 메일 발송 성공률이 100%로 회복되었고, 장기적으로는 Amazon SES로 전환을 계획 중

동시성 문제는 실제 서비스에서 생각보다 흔하게 발생한다. 특히 재고 감소, 결제, 좋아요 등의 기능은 수많은 요청이 동시에 들어올 수 있기 때문에 신중한 동시성 제어가 필요하다.

동시성 문제란?

동시에 여러 사용자가 같은 자원에 접근할 때, 예상치 못한 상태 충돌이나 데이터 불일치가 발생하는 문제이다. 예를 들어 A와 B가 동시에 같은 상품의 재고를 감소시키면, 잘못된 재고 값이 저장될 수 있다.

주요 동시성 제어 방법

왜 한 가지 방식으로 통일하지 않을까?

"Redisson이 분산 락도 되는데 이걸로 다 하면 되지 않을까?" 라는 생각이 들 수 있지만, 실제로는 성능, 안정성, 구현 난이도를 고려해 상황에 맞는 전략을 선택하는 것이 훨씬 중요하다.

Redisson만으로는 부족하거나 과한 경우

• 단순한 동기화인데 Redis 락을 사용하면 오히려 성능 낭비
• 충돌이 거의 없는데 굳이 락을 걸 필요는 없다
• 외부 장애 (예 : Redis 다운)로 전체 시스템이 영향을 받을 수 있다

결론

모든 락은 비용이 따르고, 트레이드오프가 존재한다. 따라서 서비스의 특성과 요구 사항에 따라 가장 효율적인 전략을 선택해야 한다.

로컬에서는 정상 작동하던 크론잡이 EC2 서버에서는 정상적으로 실행되지 않았다.

원인 분석

크론잡(@Scheduled)은 서버 시간대(Timezone)를 기준으로 작동한다. 로컬은 'Asia/Seoul', EC2는 'UTC' 시간대를 사용하고 있었다. 즉, 크론 표현식 기준 시간이 달라져 실행되지 않은 것처럼 보인 것이다.

해결 방법

1. EC2 인스턴스의 시간대 설정 EC2 인스턴스에 접속하여 시간대 설정이 어떻게 되어있는지 확인해본다. ('timedatectl' 명령어로 가능) 현재 'UTC' 시간대로 설정되어있는 모습을 확인할 수 있었다. 'sudo timedatectl set-timezone Asia/Seoul' 명령어로 시간대를 현지 지역과 시간에 맞게 변경해주었다.

2. Docker 컨테이너의 시간대를 호스트와 동기화 docker-compose.yml 스크립트를 수정하여 컨테이너가 EC2의 시간대와 동일하게 작동하도록 설정하였다.

   services:
   app:
    ...
    volumes:
      - /etc/localtime:/etc/localtime:ro

3. 크론잡에 시간대 명시 코드상에 명시적으로 타임존을 지정하므로서 코드만 봐도 유지보수 시 혼란을 줄일 수 있다.

@Scheduled(cron = "0 0 8 * * ?", zone = "Asia/Seoul")
    public void sendDailyEmailToSubscribers() {
        log.info("일일 이메일 발송 작업 시작: {}", LocalDateTime.now());

        List<Subscriber> subscribers = subscribeService.getAllSubscribers();

        if (subscribers.isEmpty()) {
            log.info("구독자가 없습니다. 이메일 발송을 건너뜁니다.");
            return;
        }

        String subject = "마이니치 니홍고 - 오늘의 일본어 학습";
        String content = contentService.generateDailyContent();

        int successCount = 0;
        int failCount = 0;

        for (Subscriber subscriber : subscribers) {
            boolean sent = emailService.sendEmail(subscriber.getEmail(), subject, content);

            if (sent) {
                successCount++;
            } else {
                failCount++;
            }
        }

        log.info("일일 이메일 발송 완료 - 성공: {}, 실패: {}", successCount, failCount);
    }

결국 이번 문제는 코드상에 문제가 있다기 보다는 배포 환경의 시간대 설정이 문제였다. 크론잡을 사용할 때는 항상 시간대를 명시하거나 서버의 시간대를 확인하자

현재 GigSync라는 인디밴드 커뮤니티 웹 어플리케이션을 개발하고 있다.

• 프론트엔드 : Vite + React (localhost:5173)
• 백엔드 : Spring Boot (localhost:8080)
• 인증 방식 : JWT + Refresh Token (HttpOnly Cookie)

로컬 환경에서는 아무 문제 없이 RefreshToken이 쿠키로 잘 전달되고 인증이 매끄럽게 동작했다. 그러나 EC2에 프론트와 백엔드를 각각 배포하면서 문제가 발생했다.

발생한 문제 : 로그인 직후 로그아웃됨

프론트 EC2에서는 로그인 요청을 정상적으로 보내고, 백엔드 EC2에서는 RefreshToken을 Set-Cookie 헤더에 담아 응답했음에도 불구하고, 쿠키가 클라이언트에 저장되지 않았다. 결과적으로 인증 상태가 유지되지 않아 로그인 직후 자동 로그아웃되는 현상이 발생했다.

원인분석 : 크로스 도메인 + 보안 정책

1. Same-Origin Policy와 크로스 도메인 브라우저는 보안상 출처(origin)가 다른 경우 쿠키를 자동으로 저장하거나 전송하지 않는다.

   항목	프론트	백엔드	Same-Origin인가?
   로컬	http://localhost:5173	http://localhost:8080	X (포트 다름)
   EC2 배포	http://FRONT_IP	http://BACK_IP	X (도메인 다름)

   • 포트가 다르거나 도메인이 다르면 Same-Origin이 아니다.

2. Set-Cookie의 보안 속성 백엔드가 보낸 쿠키가 브라우저에 저장되려면 아래 조건을 만족해야 한다.

   속성	설명	테스트 환경에서 주의할 점
   HttpOnly	자바스크립트로 접근 불가	로그인 보안 향상
   Secure	HTTPS에서만 동작	로컬이나 HTTP EC2에서는 작동 안 함
   SameSite=None	크로스 사이트 요청 허용	Secure가 반드시 같이 설정되어야 함

   즉, SameSite=None; Secure 조합은 HTTPS가 아니면 무효하다.

해결 방법

테스트 환경에서의 임시 해결(프론트 + 백엔드를 단일 EC2에 배포)

• NGINX 또는 Caddy 등으로 Reverse Proxy를 구성하여 하나의 도메인 또는 포트로 동작하게 한다.
• 로컬처럼 동일 Origin이 되므로 쿠키가 정상 동작함

실제 서비스 운영 시 해결 방안

1. 도메인 구입 및 HTTPS 적용
   • SSL 인증서로 HTTPS 적용
   • Secure 속성이 붙은 쿠키도 정상 작동
2. 백엔드 응답 헤더 설정

ResponseCookie.from("refreshToken", token)
    .httpOnly(true)
    .secure(true) // HTTPS 환경에서만 작동
    .sameSite("None") // 크로스 도메인 허용
    .path("/")
    .build();

3. 프론트엔드 요청 시 설정

axios.post('https://api.gigsync.com/login', data, {
  withCredentials: true // 반드시 설정
});

쿠키 전달 문제 점검 체크리스트

끝으로..

테스트 환경에서는 동일 EC2에 프론트와 백엔드를 배치하여 문제를 해결했지만, 서비스 확장성과 보안성을 고려하면 도메인을 이용한 HTTPS 기반의 분리 배포가 필수이다. HttpOnly Cookie 기반 인증은 보안상 유리하지만, 크로스 도메인 환경에서의 제약을 반드시 이해하고 맞춰줘야 한다는 걸 알 수 있었다.

Apache Kafka는 분산 스트리밍 플랫폼으로 대용량의 데이터를 빠르고 안정적으로 처리할 수 있는 메시지 브로커 시스템이다. 기본적인 구성 요소는 다음과 같다.

• Producer : 메시지를 발행하는 주체
• Broker : 메시지를 저장하고 관리하는 Kafka 서버
• Topic : 메시지를 분류하는 단위
• Consumer : 메시지를 구독하고 처리하는 주체

Kafka는 일반적인 메시지 큐 시스템보다 높은 처리량, 내구성, 확정성을 제공하여 마이크로서비스 간의 통신이나 실시간 데이터 처리에 매우 유용하다.

왜 Kafka를 채팅 시스템에 도입?

기존의 WebSocket 기반 채팅 시스템에서는 WebSocket 세션 간 직접 메시지를 전달하는 방식으로 구성하는 경우가 많다. 이 경우 다음과 같은 문제점이 발생할 수 있다.

• 다중 서버 환경에서 세션 공유의 어려움
• 실시간 처리 외의 기능(메시지 저장, 분석, 알림 발송 등) 확장이 어려움

Kafka를 도입하면 메시지를 중간에 Kafka로 보내고 Consumer에서 받아 WebSocket을 통해 다시 전달하는 방식으로 아키텍처가 바뀐다. 이를 통해 다음과 같은 이점을 얻을 수 있다.

• 메시지 발행과 소비를 분리하여 확장성 향상
• 다양한 서비스가 동일 메시지를 구독 가능 (알림, 저장, 분석)
• 서버 간 세션 공유가 불필요 (stateless)

구현 구조 요약

• 클라이언트는 WebSocket으로 연결하며 token과 receiverId를 쿼리 파라미터로 보낸다.
• 서버는 JWT로 인증된 후 세션을 관리하며 과거 메시지를 불러온다.
• 클라이언트에서 메시지를 보내면 서버를 이를 Kafka Producer를 통해 전송한다.
• Kafka Consumer가 메시지를 수신하고 수신자에게 해당 메시지를 WebSocket으로 전송한다.

WebSocket Handler 예제 코드

@Override
protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception {
    String senderId = (String) session.getAttributes().get("userId");
    String receiverId = (String) session.getAttributes().get("receiverId");

    ChatMessageRequestDto requestDto = new ChatMessageRequestDto(message.getPayload());
    ChatMessageResponseDto savedMessage = chatMessageService.saveMessage(
        Long.parseLong(receiverId),
        Long.parseLong(senderId),
        requestDto
    );

    String messageJson = objectMapper.writeValueAsString(savedMessage);
    kafkaProducerService.sendMessage(messageJson); // Kafka로 메시지 전송
}

문제 상황과 해결

문제 1 : 채팅방에 관계없는 메시지가 전달됨

• 유저 1과 채팅 중인데 유저 2가 보낸 메시지가 실시간으로 나타남
• 원인 : 메시지를 수신할 때 receiverId만 비교하고 roomId에 대한 필터링이 없음
• 해결 : WebSocketSession에 roomId를 저장하고, Kafka Consumer에서 메시지의 roomId와 세션의 roomId를 비교해 일치할 때만 전송하도록 수정

문제 2 : 메시지가 중복 전송됨

• Kafka에서 메시지를 수신할 때 같은 메시지가 2번 표시되는 현상 발생
• 원인 : 메시지를 전송하는 로직이 이중으로 실행되거나, WebSocket 세션이 여러 개 생성된 경우
• 해결 : SessionManager를 통해 중복 세션을 방지하고, 메시지 전송 전에 중복 여부 확인

Spring Boot + JWT 인증 구조에서 로그인 시 refreshToken을 HttpOnly 쿠키에 담아 응답하도록 설정했다.

ResponseCookie refreshTokenCookie = ResponseCookie.from("refreshToken", refreshToken)
    .httpOnly(true)
    .secure(true)
    .path("/api/auth/refresh")
    .maxAge(Duration.ofDays(14))
    .sameSite("None")
    .build();

return ResponseEntity.ok()
    .header(HttpHeaders.SET_COOKIE, refreshTokenCookie.toString())
    .body(...);

그러나 로컬에서 http://localhost로 서버를 실행했을 때, 브라우저에 쿠키가 저장되지 않았다.

원인 분석

쿠키 설정에서 아래 두 옵션이 문제였다.

• secure=true : HTTPS에서만 쿠키 전송을 허용
• sameSite="None" : 크로스 도메인 요청에서 쿠키 전송 허용. 단, secure=true 조건 필수

따라서 로컬에서는 쿠키 자체가 전송되지 않는다. -> 브라우저 개발자 도구에서도 보이지 않음

해결 방법

환경에 따라 쿠키 설정을 분기 처리하도록 수정하였다.

boolean isLocal = true; // 개발/운영 환경에 따라 설정

ResponseCookie refreshTokenCookie = ResponseCookie.from("refreshToken", refreshToken)
    .httpOnly(true)
    .secure(!isLocal)                          // 운영에서는 secure=true
    .path("/api/auth/refresh")
    .sameSite(isLocal ? "Lax" : "None")        // 로컬에서는 Lax로 설정
    .maxAge(Duration.ofDays(14))
    .build();

• 로컬(localhost)
  • secure=false, sameSite=Lax
  • 쿠키 정상 전송됨 (브라우저 Application > Cookies 탭에서 확인 가능)
• 운영(https)
  • secure=true, sameSite=None
  • 크로스 사이트에서도 쿠키 전송 가능 (보안 유지)

보안상 중요한 포인트

• httpOnly=true 덕분에 JS에서는 document.cookie로 접근이 불가하다. -> XSS 방어
• 브라우저 콘솔에서 쿠키가 안 보이는 건 정상 동작이다.

왜 Redis를 사용하는가?

JWT는 서버에 세션을 저장하지 않는 Stateless 방식이라 로그아웃 시 토큰을 무효화시키는 것이 쉽지 않다. 이를 해결하기 위해 Redis를 블랙리스트 저장소로 활용한다.

• AccessToken 블랙리스트 저장 : 로그아웃 시 해당 토큰을 Redis에 저장하여 재사용 방지
• Refresh Token 저장 및 검증 : 클라이언트가 갱신 요청 시 Redis에 저장된 Refresh Token을 기준으로 검증

Redis 설정

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

JwtAuthFilter 내부 블랙리스트 검증 코드

private void authenticate(HttpServletRequest request) {
    String token = this.getTokenFromHeader(request);
    if (!StringUtils.hasText(token) || !jwtUtil.validateToken(token)) return;

    // 블랙리스트 여부 확인
    String isLogout = (String) redisTemplate.opsForValue().get(token);
    if ("logout".equals(isLogout)) return;

    String email = jwtUtil.getUserEmail(token);
    UserDetails userDetails = userDetailsService.loadUserByUsername(email);

    UsernamePasswordAuthenticationToken authenticationToken =
        new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities());

    authenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
    SecurityContextHolder.getContext().setAuthentication(authenticationToken);
}

로그아웃 서비스 구현

@Override
public void logout(String accessToken, Long expirationTime) {
    // 블랙리스트 등록
    redisTemplate.opsForValue().set(accessToken, "logout", Duration.ofMillis(expirationTime));

    // Refresh Token 삭제
    redisTemplate.delete("RT:" + getEmailFromToken(accessToken));
}

Refresh Token 저장 예시

@Override
public void saveRefreshToken(String email, String refreshToken, Long ttl) {
    redisTemplate.opsForValue().set("RT:" + email, refreshToken, Duration.ofMillis(ttl));
}

Refresh Token 검증 및 재발급 로직 예시

public String reissueAccessToken(String email, String providedRefreshToken) {
    String savedRefreshToken = (String) redisTemplate.opsForValue().get("RT:" + email);
    if (!providedRefreshToken.equals(savedRefreshToken)) {
        throw new CustomException(TokenErrorCode.INVALID_REFRESH_TOKEN);
    }

    return jwtUtil.generateAccessToken(userRepository.findByEmail(email).get());
}

유의할 점

• 토큰 만료 시간과 Redis TTL을 맞춰줘야 불필요한 메모리 낭비를 줄일 수 있다
• Filter, JwtUtil, RedisConfig 사이 의존성도 잘 분리해둬야 유지보수가 쉬움
• RedisTemplate를 여러 서비스에서 사용할 경우, 유틸 클래스로 추출해 사용하는 것도 고려할 수 있다
• Refresh Token의 경우도 Redis에 저장되므로 탈취에 유의하고 HTTPS 등 보안 대책 필수

느낀 점

처음에는 Stateless 인증 구조에서 로그아웃 구현이 어렵게 느껴졌지만, Redis를 활용한 블랙리스트 패턴과 Refresh Token 저장 방식으로 충분히 실용적인 방법이 가능하다는 걸 깨달았다. Spring Security와 잘 연동되도록 설계하는 것이 핵심이었다.

Spring Boot에서 게시글 생성 시 파일(이미지, 동영상)을 첨부해 AWS S3에 업로드하도록 구현했다. 하지만 Postman으로 테스트하던 중 다음과 같은 에러가 발생했다.

2025-04-12T01:19:02.529+09:00  WARN 47568 --- [gigsync] [nio-8080-exec-7] 
.w.s.m.s.DefaultHandlerExceptionResolver : 
Resolved [org.springframework.web.HttpMediaTypeNotSupportedException: 
Content-Type 'application/octet-stream' is not supported]

파일 업로드 자체가 실패했고, 이후 S3 버킷을 확인해도 업로드된 파일은 application/octet-stream 타입으로 설정되어 있었으며 브라우저에서 바로 열 수 없고 다운로드만 되는 문제가 발생했다.

원인 분석

이 문제는 크게 두 가지 원인으로 나눌 수 있었다.

1. Spring이 application/octet-stream 요청을 처리하지 못함

• @RequestPart로 JSON (BoardRequestDto)과 파일(List<MultipartFile>)을 동시에 받는 구조였는데, Postman에서 JSON을 잘못 설정하거나 Content-Type을 생략하면 Spring이 인식하지 못해 위 에러가 발생함

2. S3에 잘못된 Content-Type으로 업로드됨

• Multipart 업로드 요청 시 Content-Type이 지정되지 않으면 S3에서 자동으로 application/octet-stream으로 처리됨 -> 이 경우, 이미지도 파일처럼 다운로드되며 웹에서 미리보기가 되지 않음

해결 방안

Postman에서 요청을 multipart/form-data로 정확히 설정하고 @RequestPart에는 application/json 형태의 문자열을 전달하였다. 업로드 파일의 Content-Type을 MultipartFile.getContentType()으로 명시하고, 이미지 업로드 시 허용된 확장자만 가능하도록 설정했다.

Postma API 요청

수정된 FileService.java

@Service
@RequiredArgsConstructor
public class FileService {

    private static final List<String> ALLOWED_IMAGE_EXTENSIONS = List.of("jpg", "jpeg", "png", "gif");

    private final S3Client s3Client;

    @Value("${cloud.aws.s3.bucketName}")
    private String bucketName;

    public List<BoardFile> uploadFiles(List<MultipartFile> files, Board board) {
        List<BoardFile> result = new ArrayList<>();

        for (MultipartFile file : files) {
            String originalFilename = file.getOriginalFilename();
            String extension = getExtension(originalFilename);

            if (isImage(file) && !ALLOWED_IMAGE_EXTENSIONS.contains(extension.toLowerCase())) {
                throw new IllegalArgumentException("지원하지 않는 이미지 형식입니다: " + extension);
            }

            String fileName = UUID.randomUUID() + "_" + originalFilename;
            String url = uploadToS3(file, fileName);

            result.add(BoardFile.builder()
                    .fileName(fileName)
                    .fileUrl(url)
                    .board(board)
                    .build()
            );
        }

        return result;
    }

    private String uploadToS3(MultipartFile file, String fileName) {
        try {
            PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(fileName)
                    .acl("public-read")
                    .contentType(file.getContentType())
                    .build();

            s3Client.putObject(putObjectRequest, RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
            return "https://" + bucketName + ".s3.amazonaws.com/" + fileName;
        } catch (IOException e) {
            throw new RuntimeException("파일 업로드 중 오류 발생", e);
        }
    }

    private boolean isImage(MultipartFile file) {
        String contentType = file.getContentType();
        return contentType != null && contentType.startsWith("image");
    }

    private String getExtension(String filename) {
        if (filename == null || !filename.contains(".")) {
            throw new IllegalArgumentException("파일 이름에 확장자가 없습니다.");
        }
        return filename.substring(filename.lastIndexOf('.') + 1);
    }
}

결과 확인

브라우저에서 바로 이미지 미리보기 가능

동영상도 별도 설정 없이 S3 주소에서 재생 가능

확장자 검증으로 잘못된 파일 업로드를 방지하고 S3 URL을 게시판 조회 시 바로 사용할 수 있게 되었다.

이번 이슈는 흔하지만 초반에 놓치기 쉬운 Content-Type과 multipart/form-data 처리에 대한 실수였다. Spring Boot와 S3 연동 시에는 아래 항목들을 꼭 챙기자 !

• @RequestPart를 사용할 때는 multipart/form-data 필수
• 파일은 적절한 Content-Type으로 업로드해야 브러우저에서 랜더링됨
• 이미지 확장자 검증은 보안/UX 차원에서 중요
• Postman에서도 요청 설정을 정확히 해야 Spring이 인식함

HPA는 애플리케이션의 리소스 사용량(CPU, 메모리 등)을 기준으로 Pod 수를 자동으로 조절하는 오브젝트이다. 일반적으로 Deployment, ReplicaSet, StatefulSet에 적용 가능하다. 리소스 사용량을 기반으로, 정의된 임계치를 넘기면 Pod의 수를 늘리고, 사용량이 줄어들면 다시 줄인다.

HPA 예제 코드

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

• kubectl top pod으로 리소스 사용량 확인 가능
• metrics-server 설치가 필요하다 (클러스터에 리소스 사용량 데이터를 제공)

다양한 배포 전략

• Rolling Update
  • 쿠버네티스의 기본 배포 전략
  • 점진적으로 새로운 Pod를 생성하고, 이전 버전을 하나씩 종료함
  • 다운타임 없이 배포 가능
• Blue/Green Deployment
  • 기존 버전(Blue)과 새로운 버전(Green)을 동시에 유지하다가, 트래픽을 전환하는 방식
  • 트래픽 전환이 완전히 이뤄진 후, 기존 버전을 제거
  • 롤백이 쉽고 안정성이 높다
  • 쿠버네티스에서는 서비스 객체를 이용해 label selector를 변경하여 트래픽을 전환
• Canary Deployment
  • 새로운 버전을 일부 사용자에게만 점진적으로 배포한 뒤, 이상이 없으면 전체 배포한다
  • ex) 전체 트래픽의 10%만 Canary 버전에 전달 -> 이상이 없다면 점차 확대한다
  • Deployment를 복수로 관리하거나, Service 객체를 통해 레이블 조정 + 트래픽 분산을 조절함

쿠버네티스에서 Persistent Volume(PV)는 클러스터에서 관리하는 스토리지 리소스이고, Persistent Volume Claim(PVC)는 사용자가 해당 스토리지를 요청하는 방식이다.

• Persistent Volume(PV)
  • 관리자가 설정한 정적인 스토리지 리소스
  • 다양한 스토리지 백엔드(NFS, AWS EBS, GCE Persistent Disk 등) 지원
  • 수명 주기가 노드의 독립적
• Persistent Volume Claim(PVC)
  • 개발자가 필요한 스토리지를 요청하는 오브젝트
  • PV가 클레임에 매칭되면 바인딩되어 사용 가능
  • 요청한 용량, 접근 모드(ReadWriteOnce, ReadOnlyMany 등)에 따라 적절한 PV가 할당됨

StatefulSet과 Stateless 차이

Stateful vs Stateless

• Stateless(무상태 애플리케이션)
  • 특정 요청에 대한 상태를 저장하지 않음
  • 여러 인스턴스를 동일한 방식으로 생성/삭제 가능 (ex: 웹서버, API 서버)
  • 확장이 용이하며 로드 밸런서를 통해 부하 분산 가능
• Stateful(상태 저장 애플리케이션)
  • 특정 요청에 대한 상태를 유지해야 하는 애플리케이션 (ex: 데이터베이스, 메시지 큐)
  • 각 인스턴스가 고유한 식별자와 데이터를 가지며, 특정 순서로 생성/삭제됨

StatefulSet 이란?

StatefulSet은 상태를 가지는 (Stateful) 애플리케이션을 관리하는 쿠버네티스 컨트롤러이다.

• 각 Pod에 고유한 네트워크 ID(Stable Network Identity) 부여
• Pod 재시작 또는 재배포 시에도 일관된 시토리지 유지 (PVC와 함께 사용)
• Pod 번호 순서 보장 (ex: my-sql-0, my-sql-1)
• 주로 데이터베이스 (MySQL, PostgreSQL), Kafka, Redis 같은 상태 기반 서비스에서 사용

StatefulSet 기본 구성 예제

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: my-db
spec:
  serviceName: "my-db"
  replicas: 3
  selector:
    matchLabels:
      app: my-db
  template:
    metadata:
      labels:
        app: my-db
    spec:
      containers:
      - name: my-db
        image: mysql:latest
        volumeMounts:
        - name: data
          mountPath: /var/lib/mysql
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi

Batch 프로그램과 쿠버네티스 Job

Batch 프로그램이란?

• 일정한 작업을 한 번 또는 주기적으로 실행하는 프로그램
• 사용자 입력 없이 실행되며 대량의 데이터 처리에 적합
• ex: 로그 분석, 백업, 데이터 변환, 배치 처리

쿠버네티스 Job

Job은 일회성 또는 특정 횟수만큼 실행되는 작업을 관리하는 오브젝트이다.

• Pod가 성공적으로 완료될 때까지 실행됨
• 실패한 경우 재시도 가능
• completions 및 parallelism 설정을 통해 여러 개의 작업을 병렬로 실행 가능

Job 예제

apiVersion: batch/v1
kind: Job
metadata:
  name: example-job
spec:
  template:
    spec:
      containers:
      - name: batch-job
        image: busybox
        command: ["echo", "Hello, Kubernetes Batch Job!"]
      restartPolicy: Never
  backoffLimit: 4  # 실패 시 최대 4번 재시도

CronJob (스케줄링 Job)

• Job을 일정한 주기로 실행하는 오브젝트
• Cron 표현식(* * * * *)을 사용하여 실행 시간 설정 가능
• ex: 매일 자정에 백업 실행, 5분마다 로그 분석 실행

CronJob 예제

apiVersion: batch/v1
kind: CronJob
metadata:
  name: daily-backup
spec:
  schedule: "0 0 * * *"  # 매일 자정
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: busybox
            command: ["echo", "Backing up data..."]
          restartPolicy: OnFailure

정리

• PV/PVC : 쿠버네티스에서 상태를 저장하는 방법 (스토리지)
• StatefulSet : 상태를 유지하는 애플리케이션을 위한 관리 방식
• Stateless vs Stateful : 상태 저장 여부에 따른 애플리케이션의 특성
• Job : 일회성 작업을 수행하는 쿠버네티스 오브젝트
• CronJob : 일정 주기로 실행되는 Job

kubernetes에서 Pod는 동적으로 생성되고 사라지므로, 특정 Pod의 IP 주소는 고정되지 않는다. 따라서 안정적인 네트워크 통신을 위해 Service가 필요하다.

Service의 주요 타입

1. ClusterIP (기본값)
   • 클러스터 내부에서만 접근 가능한 서비스
   • kubectl expose deployment my-app --type=ClusterIP --port=80
2. NodePort
   • 각 Node의 고정된 포트를 개방하여 외부에서 접근 가능
   • kubectl expose deployment my-app --type=NodePort --port=80
3. LoadBalancer
   • 클라우드 제공자의 로드밸런서를 사용하여 외부 접근을 지원
   • kubectl expose deployment my-app --type=LoadBalancer --port=80
4. ExternalName
   • 외부 서비스 도메인과 연결
   • kubectl apply -f external-service.yaml

Ingress : 외부 트래픽을 클러스터 내부로 라우팅

Ingress는 kubernetes에서 HTTP(S) 트래픽을 관리하는 리소스로, 로드밸런서보다 유연한 라우팅 기능을 제공한다.

Ingress 주요 개념

• Path-based Routing : 도메인 + 경로 기반으로 트래픽을 특정 서비스로 전달
• Host-based Routing : 여러 도메인을 하나의 Ingress에서 처리 가능
• TLS 지원 : HTTPS 트래픽 관리 가능

Ingress 예제 yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - host: my-app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

Ingress Controller 필요

기본적으로 kubernetes에는 Ingress 기능만 있고, 실제 트래픽을 처리하려면 Ingress Controller(Nginx, Traefik 등)를 설치해야 한다.

Deployment : 애플리케이션 배포 및 관리

Deployment는 Pod를 생성, 업데이트, 롤백, 스케일링할 수 있도록 관리하는 리소스이다.

Deployment의 주요 기능

• ReplicaSet을 통해 원하는 개수의 Pod 유지
• 새로운 버전 배포 시 Rolling Update 또는 Recreate 전략 제공
• 특정 버전으로 되돌리는 Rollback 기능 지원

Deployment 예제 yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: my-app:1.0
        ports:
        - containerPort: 80

• replicas: 3 -> Pod 3개 유지
• image: my-app:1.0 -> 특정 버전 이미지 사용
• Rolling Update로 중단 없이 새로운 버전 배포 가능

kubectl 명령어 정리

• kubectl apply -f deployment.yaml -> Deployment 생성
• kubectl rollout status deployment my-app -> 배포 상태 확인
• kubectl rollout undo deployment my-app -> 이전 버전으로 롤백

Spring Boot + JPA 환경에서 상품 단건 조회 API를 호출했을 때 다음과 같은 예외가 발생했다.

org.springframework.orm.jpa.JpaSystemException: Unable to access lob stream  
at org.springframework.orm.jpa.vendor.HibernateJpaDialect.convertHibernateAccessException(HibernateJpaDialect.java:341)
at org.springframework.orm.jpa.vendor.HibernateJpaDialect.translateExceptionIfPossible(HibernateJpaDialect.java:241)

• 문제가 된 코드

@Override
public ProductResponseDto findProduct(Long productId) {
    Product product = productRepository.findById(productId)
            .orElseThrow(() -> new GlobalException(ProductErrorCode.PRODUCT_NOT_FOUND));
    return ProductResponseDto.toDto(product);
}

Product 엔티티는 @Lob 타입의 description 필드를 포함하고 있음 ProductPhoto 엔티티와 @OneToMany 관계를 맺고 있으며 이를 조회할 때 @EntityGraph를 사용했음

원인 추론

1. Lazy 로딩으로 인한 트랜잭션 종료 문제

• @Lob 필드는 기본적으로 Lazy 로딩이다.
• @EntityGraph(attributePaths = {"productPhotos.photo"})를 설정했지만, @Lob 필드는 즉시 로딩되지 않음.
• 트랜잭션 종료 후 description 필드에 접근하려다 보니 JpaSystemException이 발생.

2. 해당 필드가 LOB 타입이라 직접적인 스트림 접근이 필요함.

• Hibernate는 LOB 필드를 Lazy 로딩할 때 스트림을 통해 접근하는데, 트랜잭션이 끝나면 세션이 닫혀서 접근 불가.

해결 방안

1. @EntityGraph를 사용해 연관 데이터를 즉시 로딩 기존에는 productPhotos.photo만 즉시 로딩되었지만, description 필드는 포함되지 않았다. 따라서 @EntityGraph를 유지하면서 트랜잭션 범위를 확장해야 했다.

@EntityGraph(attributePaths = {"productPhotos.photo"})
Optional<Product> findProductWithPhotoById(Long id);

2. @Transactional(readOnly = true)로 트랜잭션 범위 확장 트랜잭션이 유지되면 Lazy 로딩 필드(description)에도 안전하게 접근할 수 있다.

@Override
@Transactional(readOnly = true) // 트랜잭션 유지
public ProductResponseDto findProduct(Long productId) {
    Product product = productRepository.findProductWithPhotoById(productId)
            .orElseThrow(() -> new GlobalException(ProductErrorCode.PRODUCT_NOT_FOUND));
    return ProductResponseDto.toDto(product);
}

결과 확인

• Product를 조회할 때 productPhotos.photo와 함께 description 필드도 정상적으로 로딩됨.
• JpaSystemException이 발생하지 않고, 트랜잭션이 유지된 상태에서 @Lob 필드에 접근 가능.
• 불필요한 추가 쿼리 없이 한 번의 쿼리로 데이터를 조회할 수 있어 성능도 개선됨.

Key Point

• @Lob 필드는 기본적으로 Lazy 로딩되므로, 조회 시 트랜잭션을 유지하는 것이 중요 !
• @EntityGraph를 사용하면 특정 필드를 즉시 로딩할 수 있지만, @Lob 필드는 별도로 고려해야 함 !
• 트랜잭션이 종료되기 전에 데이터를 모두 조회해야 LazyInitializationException을 방지할 수 있음 !