BigBang 배포 구축 보고서 - 100-hours-a-week/2-hertz-wiki GitHub Wiki

📚 목차

📄 BigBang 배포 인프라 구축 보고서

본 문서는 서비스 초기 단계에서 적용된 BigBang 방식의 클라우드 인프라 구축 현황과 구성 세부사항을 정리한 보고서입니다. 빠른 배포 및 개발 환경 확보, 초기 비용 절감을 위해 Google Cloud Platform(GCP)의 무료 크레딧을 기반으로 운영 환경을 구성하였으며, Monolithic 구조의 서비스 서버와 AI 모델 서버 구성으로 배포하였습니다. 이후 테스트와 운영 경험을 기반으로 점차 고도화 및 구조 분리를 진행할 계획입니다.

1. 클라우드 인프라 구성

1.1 DNS 서비스 (AWS Route 53)

향후 AWS 전환을 고려하여 DNS는 AWS Route 53을 통해 관리합니다.

  • 도메인: hertz-tuning.com(2026년 4월 29일)
  • 레코드 유형: A 타입 (IPv4)
  • 호스팅 대상: Production 환경 GCP 인스턴스 IP
  • 라우팅 정책: 단순(Simple Routing)

1.2 VPC 및 리전 전략 (GCP)

항목 설정값
리전 asia-east1 (Taiwan)
VPC CIDR 블록 10.20.0.0/24
Subnet 10.20.0.0/24 (Public Subnet)

선택 사유: 서울 리전 대비 비용 절감 효과로 타이완 리전 선택

1.3 Compute Instance 구성

Production 환경 (프로젝트: Tuning-PROD-01)

역할 용도 머신 타입 OS 디스크
App Server WEB + WAS + DB e2-standard-2 Ubuntu 22.04 LTS 80GB
AI Server AI 모델 서비스 e2-standard-4 Ubuntu 22.04 LTS 80GB

Development 환경 (프로젝트: Tuning-DEV-01)

역할 용도 머신 타입 OS 디스크
App Server WEB + WAS + DB e2-medium Ubuntu 22.04 LTS 80GB
AI Server 모델 개발 및 테스트 e2-standard-2 Ubuntu 22.04 LTS 80GB

2. VM 환경설정 및 설치 패키지

2.1 사용자 계정 및 권한 정책

계정 용도 권한
devops 시스템 설정 및 운영 관리 sudo 가능, google-sudoers 포함, deploy 그룹 포함
deploy 애플리케이션 배포 전용 /home/deploy 배포 디렉토리 소유, 제한 권한, sudo 미부여

2.2 주요 패키지 및 런타임 환경

Monolithic 서버

구성요소 버전 설명
OS Ubuntu 22.04 LTS 버전 운영체제
Node.js 22.x 프론트엔드 빌드 및 pm2 실행용 런타임
pnpm 10.x Node.js 패키지 매니저
Java (OpenJDK) 21 (Ubuntu OpenJDK 21.0.7) Spring Boot 기반 백엔드 애플리케이션 실행 환경
Nginx 최신 (apt 패키지 기준) 리버스 프록시 및 SSL 처리
Spring Boot JAR 실행 (내장 톰캣) 백엔드 API 서버
Next.js 15.3.0 ([email protected]) 프론트엔드 SPA 및 SSR 프레임워크
PM2 최신 앱 실행 관리용 프로세스 매니저
MySQL 8.0 관계형 데이터베이스
Redis 6.0 세션/캐시용 In-memory DB, 비밀번호 인증 적용
Gradle 프로젝트 빌드용 (Spring Boot 기반) 의존성 관리 및 빌드 자동화 도구

AI 서버

구성요소 버전 설명
OS Ubuntu 22.04 LTS 버전 운영체제
Python 3.x FastAPI API 실행용 런타임
FastAPI 0.115.12 Python 비동기 웹 프레임워크
Uvicorn 0.34.2 ASGI 서버
Pydantic 2.11.4 데이터 모델링/검증
python-dotenv 1.1.0 .env 환경 변수 로더
ChromaDB 0.4.13 벡터 DB
sentence-transformers 4.1.0 문장 임베딩 모델 (AI 모델)
scikit-learn 1.6.1 머신러닝 전처리 및 벡터 연산
numpy 2.2.5 수치 연산 라이브러리
psutil 7.0.0 시스템 리소스 모니터링
PM2 최신 FastAPI 앱 실행 관리용 프로세스 매니저 (venv 외부 실행)
Node.js (pm2 용) 22.x pm2 설치 및 실행 환경

Python 패키지는 venv 기반으로 구성하며, PM2는 venv 외부에서 관리됩니다.

2.3 디렉토리 및 배치 구조

Monolithic 서버

요소 경로 설명
프론트엔드 /home/deploy/2-hertz-fe/ Next.js 프론트엔드 소스 디렉토리
백엔드 /home/deploy/2-hertz-be/ Spring Boot 백엔드 소스 디렉토리
로그 /home/deploy/logs/ 서비스 로그 디렉토리
PM2 설정 파일 /home/deploy/ecosystem.config.js PM2 프로세스 관리 설정 파일
배포 스크립트 /home/deploy/fe_deploy.sh, ~/be_deploy.sh 프론트엔드/백엔드 배포 스크립트
Nginx 환경 설정 /home/deploy/etc/nginx/sites-available/app.conf Nginx 서비스 설정 파일 (SSL 포함)

AI 서버

요소 경로 설명
AI 애플리케이션 /home/deploy/2-hertz-ai/ FastAPI 기반 AI 서버 소스 디렉토리
가상환경 디렉터리 /home/deploy/venv/ Python 가상환경 (source venv/bin/activate 사용)
Git 커밋 해시 기록 /home/deploy/commit-hashes/ 롤백 기능을 위한 커밋 해시 저장소
ChromaDB 실행 데이터 /home/deploy/chroma-data/ 벡터 DB의 로컬 데이터 저장 경로
Chroma 로그 파일 /home/deploy/chroma.log ChromaDB 실행 로그 파일
PM2 설정 파일 /home/deploy/ecosystem.config.js PM2 프로세스 관리 설정 파일
배포 스크립트 /home/deploy/ai_deploy.sh AI 서버 배포 자동화 스크립트

3. 네트워크 및 보안 아키텍처

3.1 인바운드 규칙

Production

서비스 포트 프로토콜 소스
SSH 22 TCP 0.0.0.0/0
HTTP 80 TCP 0.0.0.0/0
HTTPS 443 TCP 0.0.0.0/0

Development

서비스 포트 프로토콜 소스
SSH 22 TCP 0.0.0.0/0
HTTP 80 TCP 0.0.0.0/0
HTTPS 443 TCP 0.0.0.0/0
Front (Next.js) 3000 TCP 0.0.0.0/0
Backend (WAS) 8080 TCP 0.0.0.0/0
AI API 8000 TCP 0.0.0.0/0
MySQL 3306 TCP 0.0.0.0/0

3.2 아웃바운드 규칙

  • 전 트래픽(0.0.0.0/0) 허용

4. Nginx 및 SSL 인증 구성

  • Nginx 역할: 리버스 프록시
  • SSL 인증: Let’s Encrypt + Certbot을 통한 무료 인증서 발급 → 발급 대상 도메인: hertz-tuning.com, www.hertz-tuning.com
  • 자동 갱신: certbot renew를 crontab에 등록하여 갱신 자동화
  • HTTPS 리디렉션: 모든 HTTP 요청은 HTTPS로 리디렉션되도록 구성

4.1 주요 프록시 경로

URI 경로 목적 프록시 대상
/ 프론트엔드 Next.js SSR http://localhost:3000
/api/ 백엔드 Spring Boot API http://localhost:8080
/swagger-ui/ Swagger UI 문서 페이지 http://localhost:8080/swagger-ui/
/v3/ Swagger v3 OpenAPI 요청 http://localhost:8080/v3/

4.2 Nginx 설정

명령 스크립트

sudo apt install certbot python3-certbot-nginx -y # Let’s Encrypt 클라이언트 설치
sudo certbot --nginx -d hertz-tuning.com -d www.hertz-tuning.com # SSL 인증서 발급 및 Nginx 자동 설정
sudo vi /etc/nginx/sites-available/app.conf # (또는 nginx.conf 안에 추가)
sudo ln -s /etc/nginx/sites-available/app.conf /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t[
]()sudo systemctl reload nginx
sudo crontab -e # 인증서 자동 갱신 설정 => 문서 가장 하단에 아래 명령어 삽입 후 저장
								# 0 3 * * * /usr/bin/certbot renew --quiet

/etc/nginx/sites-available/app.conf 파일

server {
    listen 443 ssl;
    server_name hertz-tuning.com www.hertz-tuning.com;  # <- 여기 본인 도메인 또는 공인 IP 입력

    ssl_certificate /etc/letsencrypt/live/hertz-tuning.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hertz-tuning.com/privkey.pem;

    # --- Frontend (Next.js)
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # --- Backend (Spring Boot)
    location /api/ {
        proxy_pass http://localhost:8080/api/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
    location /swagger-ui {
    proxy_pass http://localhost:8080/swagger-ui/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    }
    location /v3/ {
	    proxy_pass http://localhost:8080/v3/;
	    proxy_http_version 1.1;
	    proxy_set_header Upgrade $http_upgrade;
	    proxy_set_header Connection 'upgrade';
	    proxy_set_header Host $host;
	    proxy_cache_bypass $http_upgrade;
		}
}

server {
    listen 80;
    server_name hertz-tuning.com www.hertz-tuning.com;
    return 301 https://$host$request_uri;  # HTTP → HTTPS 리디렉션
}

5. 배포 전략 및 롤백 전략

5.1. 프로세스 관리 도구(PM2) 사용 이유

빅뱅 배포에서는 Spring Boot, Next.js와 같은 여러 애플리케이션이 단일 인스턴스에서 동작합니다. 각 애플리케이션은 독립적으로 실행되어야 하며, 동시에 안정적인 운영을 위한 일관성 있는 배포 및 실행 환경 구성이 필요합니다.

PM2는 Node.js 기반 애플리케이션을 백그라운드에서 안정적으로 실행할 수 있도록 지원하며, ecosystem.config.js를 통해 환경 변수 설정, 포트 및 실행 인자 정의, 로그 파일 경로 지정, 리소스 제한 등을 코드 기반으로 통합 관리할 수 있습니다. 이를 통해 애플리케이션의 실행 환경을 버전 관리 및 자동화된 방식으로 통제할 수 있으며, 팀원 간 설정 불일치나 수동 배포로 인한 운영 리스크를 줄일 수 있습니다.

또한 로그 수집 및 CLI 기반의 간단한 모니터링 환경을 제공하여 서비스의 상태를 손쉽게 확인하고, 초기 서비스 단계의 이슈를 신속하게 대응할 수 있는 운영 편의성을 갖추고 있습니다. 이러한 이유로 빅뱅 배포에서는 PM2를 도입하여 애플리케이션의 실행을 통합적으로 관리하고, 운영 안정성을 확보하는 기반을 마련하였습니다.

5.2 배포 및 롤백 스크립트

  • 각 인스턴스는 Shell 기반 배포 스크립트를 사용하며, 서비스마다 별도의 스크립트를 관리합니다.
  • 커밋 해시 기반의 롤백 구조를 도입하여, 배포 실패 시 마지막으로 배포되었던 커밋을 기준으로 복구됩니다.
서비스 배포 스크립트 PM2 프로세스 관리 파일
프론트엔드 🔗 fe_deploy.sh 🔗 ecosystem.config.js [Monolithic]
백엔드 🔗 be_deploy.sh -
AI 서버 🔗 ai_deploy.sh 🔗 ecosystem.config.js [AI]

배포 성공 여부는 각 애플리케이션의 Health Check API를 통해서 확인 후, Discord Webhook을 통한 알림으로 처리됨

6. 초기 설계 대비 실제 환경 조정 내역

서비스 인프라는 최소한의 리소스로 시작하고, 테스트 및 시뮬레이션 결과를 기반으로 점진적으로 고도화하는 전략 아래 설계되었습니다. 이에 따라 초기 설계와 일부 차이를 보이는 환경 조정이 이뤄졌으며, 주요 내용은 다음과 같습니다.

6.1 배포 환경 분리 결정

초기에는 주간 22:00 ~ 22:30 내 배포가 이루어진다는 가정 하에 운영(Production)과 개발(Develop) 환경을 통합하여 구성하였습니다.

그러나 사전 배포 테스트 및 시뮬레이션 과정에서 다음과 같은 문제가 예상되었습니다:

  • 기능 테스트 중 서비스가 중단되는 구조적 리스크 존재
  • 배포 과정 중 일부 장애 상황 발생 시, 해당일 전체 서비스 운영 불가 가능성
  • 향후 QA 및 운영 안정성을 확보하기 어려움

이러한 점을 고려하여, 개발과 운영을 분리하여 독립적인 배포 및 검증이 가능한 이중 환경 구성으로 전략을 수정하였습니다.

6.2 소스 배포 방식 개선 (FTP → Git 기반)

초기에는 FTP를 통한 수동 배포를 고려하였으나, 개발 과정에서 반복적인 배포와 빈번한 기능 변경이 발생 함에 따라 다음과 같은 리스크가 확인되었습니다:

  • 수작업 배포로 인한 효율 저하
  • 형상 불일치로 인한 오류 발생 가능성
  • 협업 환경에서 코드 동기화 어려움

이에 따라 GitHub 기반 소스 관리 방식으로 전환하였습니다. 주요 개선사항은 다음과 같습니다:

  • 배포 스크립트에서 소스를 받는 과정을 Git pull로 변경
  • 커밋 해시 기반 롤백 기능 도입
  • 코드 일관성 확보 및 배포 편의성 향상