프론트엔드 기초 다시 쌓기 챌린지 14일차.
Week 3 "실전 배포 흐름"의 네 번째 수업.
Day 11~13에서 CI/CD + Docker로 완성된 배포 파이프라인을 만들었다면,
오늘은 "문제가 생겼을 때 어떻게 대응하는가"를 배웠다.
🍳 오늘의 비유: "신메뉴 출시했는데 손님이 배탈 났다"
월요일: 새 파스타 레시피 개발 완료
화요일: 자동 주방 시스템(CI/CD)으로 신메뉴 출시
수요일 오전: 손님 3명이 배탈 → 신메뉴에 문제가 있었다!이때 해야 할 일:
1단계: 증상 확인 (전체 장애? 특정 메뉴만?)
2단계: 일단 신메뉴 판매 중단! (롤백)
3단계: 원인 파악 (재료? 조리법?)
4단계: 고쳐서 다시 출시 (재배포)핵심 원칙: "고치기 전에 되돌려라"
🚨 에러가 생기는 3가지 타이밍
배포 과정에서 문제가 생기는 타이밍은 크게 3가지다.
git push → [① 빌드 에러] → [② 배포 에러] → [③ 런타임 에러]① 빌드 에러: "재료 손질 단계에서 실패"
yarn build가 실패하는 경우. CI/CD가 있으면 서버에 올라가기 전에 잡힌다.
자주 만나는 빌드 에러 TOP 5:
1. TypeScript 타입 에러
Type error: Property 'name' does not exist on type '{}'레시피에 '소금'이라 적었는데 재료 목록에 '소금'이 없는 상황.
// ❌ 에러
const user = {};
console.log(user.name);
// ✅ 수정
const user: { name: string } = { name: "짱효" };
console.log(user.name);2. import 경로 에러
Module not found: Can't resolve './components/Haeder'오타! Haeder → Header
3. 환경변수 누락
Error: NEXT_PUBLIC_API_URL is not defined로컬에서는 .env에 있어서 되는데, CI/CD에서는 GitHub Secrets에 안 넣어서 실패하는 경우.
4. 패키지 버전 충돌
npm ERR! Could not resolve dependency:
peer react@"^17.0.0" from some-package@1.0.0이 소스는 A브랜드 올리브오일에서만 되는데 B브랜드를 쓰고 있는 상황.
5. 메모리 부족
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory# 해결: 빌드할 때 메모리 늘려주기
NODE_OPTIONS="--max-old-space-size=4096" yarn build② 배포 에러: "주방까지 왔는데 세팅이 안 된다"
빌드는 성공했는데 서버에 올리는 과정에서 실패.
- SSH 접속 실패 → 키가 만료됐거나, 서버 IP가 바뀜
- docker pull 실패 → Docker Hub 인증 문제
- 포트 충돌 → 기존 컨테이너가 안 꺼졌음
- 디스크 용량 부족 → 서버에 공간이 없음③ 런타임 에러: "영업 시작했는데 손님이 음식을 못 받는다"
빌드도 성공, 배포도 성공, 근데 사이트가 이상한 경우.
- API 서버가 죽어있음 → 데이터를 못 가져옴
- 환경변수가 프로덕션 값이 아님 → 테스트 DB를 바라보고 있음
- 새 기능에 버그가 있음 → 특정 페이지에서 에러이게 가장 무서운 에러다. 빌드/배포 에러는 CI/CD에서 걸려서 사용자한테 안 가지만,
런타임 에러는 사용자가 직접 겪는다.
CI/CD가 잡을 수 있는 에러 vs 못 잡는 에러
✅ CI/CD가 잡아줌: 빌드 에러, 배포 에러
❌ CI/CD가 못 잡음: 런타임 에러 (테스트 코드가 있어야 잡을 수 있음)🔄 롤백 — "이전 버전으로 되돌리기"
롤백이란?
배포한 버전에 문제가 생겼을 때, 이전에 잘 되던 버전으로 돌아가는 것
Docker 이미지 복습
롤백을 이해하려면 Docker 이미지가 뭔지 다시 짚고 가야 한다.
이미지 = 코드 + 실행환경이 통째로 들어있는 박스
[이미지 안에 들어있는 것]
- Ubuntu 운영체제
- Node.js 18
- yarn
- 내 프로젝트 코드
- node_modules (패키지들)
- .next 폴더 (yarn build 결과물)즉 빌드까지 다 끝난 완성품이 이미지 안에 들어있다.
이동식 주방 설계도인데, 재료 손질(빌드)까지 다 끝난 상태가 포함된 것.
이게 왜 중요하냐면, 배포할 때마다 이미지에 버전 태그를 달아두면:
v1.0 이미지 = Node 18 + 코드 + 빌드 결과물 (정상 버전)
v1.1 이미지 = Node 18 + 코드 + 빌드 결과물 (버그 있는 버전)
버그 발견! → v1.0 이미지로 docker run → 끝!
다시 빌드할 필요 없음. 이미 빌드된 결과가 이미지 안에 있으니까.이래서 Docker 롤백이 빠른 거다.
롤백 방법 3가지
방법 1: Docker 이미지 태그로 롤백 (⚡ 가장 빠름, 1~2분)
# v1.1에서 문제 발생! → v1.0으로 롤백
docker stop my-app
docker rm my-app
docker run -d --name my-app -p 5008:5008 my-app:v1.0이전 이미지가 Docker Hub에 보관되어 있으니까 태그만 바꿔서 실행하면 끝.
다시 빌드할 필요가 없다. 이미 빌드된 완성품이 이미지 안에 있으니까.
방법 2: Git으로 롤백 (🏃 5~10분)
git revert HEAD
git push origin main
# → CI/CD가 다시 돌면서 이전 상태의 이미지를 새로 만들고 배포방법 3: 수동 롤백 — Docker 없을 때 (🐢 10~20분)
ssh -i key.pem ubuntu@서버IP
cd /var/www/my-project
git log --oneline -5 # 커밋 목록 확인
git revert HEAD # 이전 버전으로 돌리기
yarn build # 다시 빌드
pm2 restart my-app # 재시작3가지 방법 비교
| 방법 | 속도 | 조건 |
|---|---|---|
| Docker 태그 롤백 | ⚡ 1~2분 | Docker 사용 + 이전 이미지 보관 |
| git revert + CI/CD | 🏃 5~10분 | CI/CD 있어야 함 |
| 수동 checkout + 빌드 | 🐢 10~20분 | 서버에서 직접 작업 |
Docker 롤백이 압도적으로 빠른 이유: 이전 이미지가 이미 빌드된 상태로 보관되어 있어서 다시 빌드할 필요가 없다!
🚒 실전 대응 프로세스
실제로 문제가 생겼을 때의 대응 순서:
🚨 "사이트가 이상해요!" 알림 받음
↓
1단계: 증상 확인 (30초)
→ 전체 장애? 특정 페이지만? 에러 메시지는?
↓
2단계: 롤백 결정 (1분)
→ 심각하면 바로 롤백! 사소하면 핫픽스 검토
↓
3단계: 롤백 실행 (1~2분)
→ docker run으로 이전 버전 실행
↓
4단계: 정상 확인 (1분)
→ 사이트 접속 + 로그 확인 (Day 10)
↓
5단계: 원인 파악 (시간 여유 있게)
→ 로그 분석, 코드 확인, 재현 시도
↓
6단계: 수정 후 재배포
→ 코드 수정 → git push → CI/CD → 자동 배포가장 중요한 원칙:
⚡ "고치기 전에 되돌려라"
사이트가 터진 상태에서 원인 찾고 코드 고치면 30분~1시간.
그 동안 사용자는 계속 에러를 보고 있다.
먼저 롤백(1~2분)하고, 사이트 정상화한 다음 천천히 고치자.
🍳 레스토랑 비유 업데이트
| 레스토랑 | 서버 |
|---|---|
| 신메뉴 출시 후 배탈 | 배포 후 런타임 에러 |
| 일단 신메뉴 판매 중단 | 롤백 (이전 버전으로 되돌리기) |
| 중앙 창고의 이전 주방 | Docker Hub의 이전 이미지 태그 |
| 원인 파악 (재료? 조리법?) | 로그 분석 + 디버깅 |
| 수정 후 재출시 | 코드 수정 후 재배포 |
| "고치기 전에 되돌려라" | 롤백 먼저, 디버깅은 그 다음 |
🎯 오늘 배운 것 최종 정리
- 에러 3가지 타이밍: 빌드 에러 → 배포 에러 → 런타임 에러
- 가장 위험한 건 런타임 에러: CI/CD가 못 잡고, 사용자가 직접 겪음
- 빌드 에러 TOP 5: 타입 에러, import 경로, 환경변수 누락, 패키지 충돌, 메모리 부족
- 롤백: 문제 생기면 이전에 잘 되던 버전으로 되돌리는 것
- Docker 이미지 = 빌드까지 끝난 완성품: 이래서 롤백이 1~2분만에 가능
- 롤백 3가지: Docker 태그(1~2분) > git revert(5~10분) > 수동(10~20분)
- 핵심 원칙: "고치기 전에 되돌려라" — 롤백 먼저, 디버깅은 그 다음
- 실전 순서: 증상 확인 → 롤백 → 정상 확인 → 원인 파악 → 수정 후 재배포
🧪 이해도 체크
Q1. 배포 후 사이트에 버그가 발견됐을 때, 가장 먼저 해야 할 일은?
→ 정답: 증상 확인(전체 장애? 부분 장애?) 후 바로 롤백. 사용자가 계속 에러를 보고 있으니까 고치기 전에 먼저 되돌려야 한다.
Q2. Docker로 배포하는 환경에서 롤백이 빠른 이유는?
→ 정답: 이전 이미지에 빌드 결과물까지 다 들어있어서 다시 빌드할 필요 없이 docker run만 하면 끝.
Q3. CI/CD가 잡을 수 있는 에러와 못 잡는 에러는?
→ 정답: 빌드 에러, 배포 에러는 잡을 수 있다. 런타임 에러는 못 잡는다. 런타임 에러를 잡으려면 테스트 코드가 필요하다.
💭 회고
Day 11~13에서 "어떻게 배포하는가"를 배웠다면,
오늘은 "배포가 잘못됐을 때 어떻게 하는가"를 배웠다.
가장 인상 깊었던 건 "고치기 전에 되돌려라" 라는 원칙이다.
개발자 본능은 "원인 찾아서 고치자"인데, 실무에서는 사용자가 보고 있으니까
일단 되돌리고 천천히 고치는 게 맞다.
그리고 Docker 이미지가 "빌드까지 끝난 완성품"이라는 걸 다시 정리하니까
왜 Docker 롤백이 1~2분만에 되는지 확실히 이해됐다.
이전 이미지가 Docker Hub에 보관되어 있으니까 꺼내서 실행만 하면 끝이다.
📚 다음 학습 예고
Day 15: Part 1 회고 + 총정리
Week 1~3에서 배운 빌드·배포·서버·인프라 전체를 한번에 정리!
15일간의 여정을 하나의 큰 그림으로 연결한다.
#프론트엔드 #빌드에러 #롤백 #Docker #배포 #2년차개발자 #기초다시쌓기
