[CL]1단계_BingBang방식_배포_설계 - 100-hours-a-week/12-marong-Wiki GitHub Wiki
📚 목차
📌 개요
- 서비스 구성: React (Vite) 프론트엔드 + Spring Boot 백엔드 + Python 기반 AI 추론 로직 + MySQL DB
- 인프라 환경: Google Cloud Platform(GCP) - 단일 VPC 내 단일 Compute Engine 인스턴스 구성
- 배포 방식: CI/CD 미사용, 수동 SFTP 업로드 및 SSH 접속을 통한 직접 실행 (Big Bang 수작업 방식)
0. Bing Bang 배포 Architecture Diagram
1. 인스턴스 초기 환경 세팅 (최초 1회)
신규 인스턴스 생성 후 필수적으로 수행해야 할 기본 환경 설치 및 설정 절차입니다.
# 시스템 업데이트
sudo apt update && sudo apt upgrade -y
# Java 설치 (Spring Boot 실행용)
sudo apt install openjdk-21-jdk -y
# Python 및 패키지 설치 (AI 추론 로직 실행용)
sudo apt install python3 python3-pip -y
pip3 install -r /home/ubuntu/ai/requirements.txt
# MySQL 설치
sudo apt install mysql-server -y
# Nginx 설치 (정적 파일 서빙용)
sudo apt install nginx -y
# SFTP (OpenSSH 서버 기반으로 활용)
sudo apt install openssh-server -y
# 방화벽 설정 (필요시)
sudo ufw allow OpenSSH
sudo ufw allow 22/tcp # SFTP
sudo ufw allow 80/tcp # 프론트엔드 접근
sudo ufw allow 8080/tcp # 백엔드 API 접근
2. 수작업 배포 절차
| 단계 | 작업 내용 | 사용 도구 | 명령어/경로 | 다운타임 |
|---|---|---|---|---|
| 0 | 기존 프론트/백엔드 백업 | SSH | cp -r /var/www/html /var/www/html_backup_$(date +%Y%m%d_%H%M)cp /opt/tomcat/webapps/ /opt/tomcat/backup_$(date +%Y%m%d_%H%M) |
❌ |
| 1 | 점검 페이지 표시 | SSH | cp /var/www/html/maintenance.html /var/www/html/index.html |
⭕️ (프론트 단기 중단 안내) |
| 2 | 프론트엔드(Vite) 빌드 | 로컬 터미널 | npm run build |
❌ |
| 3 | 백엔드(Spring JAR) 빌드 | 로컬 터미널 | ./gradlew build |
❌ |
| 3-1 | 프론트엔드(Vite) 빌드 | SSH | sudo apt install nginx |
❌ |
| 4 | SFTP로 파일 업로드 | 로컬 터미널 | sftp -i /키파일경로.pem ubuntu@EC2_PUBLIC_IP -> put path/to/file.jar | ⭕️ (프론트 단기 중단 가능) |
| 4-1 | SFTP로 vite 파일 업로드 | 로컬 터미널 | sftp -i /키파일경로.pem ubuntu@EC2_PUBLIC_IP -> put -r dist, sudo cp -r /home/ubuntu/dist /var/www/marong | ⭕️ (프론트 단기 중단 가능) |
| 5 | 백엔드 앱 실행 | SSH | java -jar ~/app/app.jar |
⭕️ (API 단기 중단 가능) |
| 6 | 프론트엔드 배포 확인 | 브라우저 | - | ❌ |
| 7 | AI 추론 파이프라인 테스트 | SSH + Python | python3 ai_executor.py |
❌ |
| 8 | API / DB 연동 점검 | Postman / 브라우저 | GET/POST 요청 테스트 | ❌ |
| 9 | 로그 점검 및 마무리 | SSH | tail -f /var/log/nginx/access.logtail -f ~/logs/app.log |
❌ |
📌 본 배포 절차는 서비스 사용자가 거의 없는 심야 시간대(예: 12:00~12:20)에 진행됩니다.
이를 통해 사용자에게 미치는 영향을 최소화하고, 다운타임 발생 시 신속하게 대응할 수 있도록 합니다.
✅ 배포 체크리스트
사전 준비
- 기존 Nginx 정적 파일 디렉토리
/var/www/html백업 완료- 백업 명:
/var/www/html_backup_YYYYMMDD_HHMM
- 백업 명:
- 기존 Tomcat JAR 디렉토리
/opt/tomcat/webapps/백업 완료- 백업 명:
/opt/tomcat/backup_YYYYMMDD_HHMM
- 백업 명:
- 백업 파일 권한 및 저장 경로 확인 완료
프론트엔드
- 로컬에서
npm run build수행 완료 (vite 기반) -
dist/또는build/디렉토리 생성 확인 - SFTP를 통해
/var/www/html/에 파일 정상 업로드 - 프론트 페이지 최초 접속 확인 (브라우저 200 응답)
- 화면 스타일, JS 동작 등 주요 UI 정상 동작 확인
백엔드
- 로컬에서
./gradlew build수행 완료 -
build/libs/경로에 JAR 파일 생성 확인 - 기존 백엔드 프로세스 종료 (
ps aux | grep java,kill) - 새 JAR 파일을 서버에 업로드 (예:
/home/ubuntu/app/app.jar) - 앱 실행:
nohup java -jar ~/app/app.jar > ~/logs/app.log 2>&1 & - API 호출 정상 여부 확인
AI 추론 및 API 점검
- SSH로 접속 후
python3 ai_executor.py실행 - 예상 결과가 정상적으로 출력되거나 DB에 저장됨 확인
- Postman 또는 브라우저로 API 호출 → 정상 응답 확인
-
/api/user,/api/mission,/api/recommendation등 주요 API 테스트
-
로그 및 기타
- Nginx access log 확인 (
/var/log/nginx/access.log) - Spring log 확인 (
var/logs/app.log) - 에러 또는 경고 로그가 없는지 확인
🔄 수작업 롤백 전략
배포 중 아래와 같은 문제가 발생하면 백업 파일을 기반으로 즉시 롤백합니다:
🔥 롤백 트리거 예시
- 새 React 화면이 백지/깨짐/404 등 비정상
- API 호출 시 500 응답 다발 발생
- Tomcat 기동 실패
- AI 추론 스크립트 오류 or DB 저장 실패
롤백 절차
프론트엔드 백업
cd /var/www/marong-front/
# 백업
timestamp=$(date +%Y%m%d-%H%M)
cp -r current "backups/marong-$timestamp"
# 새 버전 덮어쓰기
rm -rf current
mv /tmp/marong-new current
프론트엔드 롤백
cd /var/www/marong-front/
rm -rf current
cp -r backups/marong-20240504-2100 current
sudo systemctl reload nginx
브라우저 새로고침으로 정상 로딩 확인
백엔드 백업
폴더 구조
/home/ubuntu/marong-app/
├── current.jar # 현재 실행 중인 버전 (symlink 사용 가능)
├── backups/
│ ├── marong-v1.0.0.jar
│ ├── marong-v1.1.0.jar
│ └── marong-v1.2.0.jar
# 새 버전 업로드 후 기존 백업
timestamp=$(date +%Y%m%d%H%M%S)
cp "$TARGET_DIR/current.jar" "$BACKUP_DIR/$APP_NAME-$timestamp.jar"
# 현재 JAR 교체
cp "$NEW_JAR_PATH" "$TARGET_DIR/current.jar"
# 애플리케이션 재시작
pkill -f 'java -jar' # 기존 앱 종료
nohup java -jar "$TARGET_DIR/current.jar" > "$TARGET_DIR/app.log" 2>&1 &
백엔드 롤백
# 백엔드 롤백 (JAR 파일 복구)
cp ~/backup/app_backup_YYYYMMDD_HHMM.jar ~/app/app.jar
pkill -f 'app.jar'
nohup java -jar ~/app/app.jar > ~/logs/app.log 2>&1 &
tail -f /var/log/tomcat9/catalina.out로 복구 상태 확인
3. 도입 배경 및 한계 분석
✅ 도입 배경: 왜 수작업 Big Bang 배포를 선택했는가?
-
MVP 중심의 단기 배포 전략
- 현재는 마니또 서비스의 초기 사용자 확보 및 시장 반응 확인이 목표이므로, 복잡한 자동화 파이프라인 없이 빠르게 배포하는 것이 더 중요했습니다.
- 기능 구현 완료 후 SFTP를 통해 단일 인스턴스에 수작업으로 배포하는 구조는 MVP 환경에 적합했습니다.
-
리소스 제약 속 최소 비용 배포
- 예산과 인력이 제한된 상황에서, CI/CD 시스템을 구축하거나 멀티 인프라를 구성하는 대신, GCP Compute Engine 단일 인스턴스에 프론트/백엔드/AI 모델을 모두 통합 운영하는 방식으로 비용을 절감했습니다.
-
낮은 변경 빈도와 단일 인스턴스 구조
- 서비스 구조상 MVP 단계에서는 수시 업데이트보다는 초기 버전을 안정적으로 올려두는 것이 핵심이었으며, 버전 변경이 적을 것이라는 가정 하에 반복 배포 부담도 크지 않았습니다.
-
기술 복잡도 최소화
- React(Vite), Spring Boot, Python 기반 AI 추론 등은 빌드 결과물이 명확하고 SFTP로 업로드하기 용이하여, 굳이 Docker나 배포 자동화를 도입하지 않아도 운영이 가능했습니다.
⚠️ 수작업 배포의 한계
| 항목 | 내용 |
|---|---|
| 운영 자동화 부족 | 버전이 올라가고 기능이 추가될수록 CI/CD 없이 수작업 배포 유지가 어려움 (예: v2, v3 등) |
| 코드 통합 오류 위험 | 여러 명이 동시에 개발하다 보니 코드 병합 과정에서 충돌이 발생하며, 수동 조정 중 실수가 생길 가능성 존재 |
| 예상 외 다운타임 | 사람이 직접 SFTP로 파일을 올리고 서비스를 재시작하는 구조상, 예상보다 배포 시간이 길어지거나 중단 시간이 길어질 수 있음 |
| 배포 후 확인 부담 | 로컬에서는 정상 동작하던 코드가 병합 후 서버에 배포되면 에러가 발생할 수 있음에도, 배포 전에는 이를 자동으로 검증할 수단이 없음 |
| 롤백 어려움 | 배포 후 문제가 발생해도 이전 상태로 빠르게 롤백할 방법이 마땅치 않음, 별도 버전 관리나 백업 없이 진행되는 경우 위험 증가 |
📈 향후 개선 방향
| 제안 | 설명 |
|---|---|
| CI/CD 도입 | GitHub Actions 등을 활용한 테스트 및 자동 빌드, 배포 체계 마련 |
| 코드 통합 자동 검증 | PR 병합 시 Lint/Build/Test 수행으로 병합 안정성 확보 |
| Docker 컨테이너화 | 백엔드, 프론트, AI 파이프라인을 개별 이미지로 분리 가능 |
| 롤백 체계 마련 | 버전된 아티팩트를 저장하고, 실패 시 빠르게 이전 버전으로 복구할 수 있는 환경 구성 |
| 무중단 배포 구조 | 추후 사용자 수 증가에 대비한 Blue/Green 또는 Rolling 배포 전략 도입 검토 |