TIL - 20260810

juni·2026년 8월 10일

목록 보기

427/468

0810 인프라/DevOps 운영 심화 (8/N): 배포 체크리스트와 Runbook

✅ 1. 배포 체크리스트란 무엇인가?

배포 체크리스트는 운영 서버에 코드를 반영하기 전후로 반드시 확인해야 할 항목을 정리한 목록입니다.
배포는 단순히 git pull, npm run build, S3 업로드, pm2 restart 같은 명령어 실행이 아닙니다.
배포 전 검증, 환경변수 확인, DB migration 확인, 캐시 무효화, Smoke Test, 롤백 기준까지 포함해야 합니다.

코드 변경
  ↓
로컬 검증
  ↓
CI 통과
  ↓
환경변수 확인
  ↓
배포 실행
  ↓
Health Check
  ↓
Smoke Test
  ↓
모니터링 확인
  ↓
작업 기록

➕ 1-1. 체크리스트가 필요한 이유

배포 실수를 줄일 수 있습니다.
매번 같은 기준으로 배포할 수 있습니다.
장애가 났을 때 어디까지 확인했는지 추적할 수 있습니다.
AI/Codex가 만든 코드도 사람 기준으로 검수할 수 있습니다.
1인 개발 환경에서도 팀처럼 운영 품질을 유지할 수 있습니다.

체크리스트 없음:
빌드 안 하고 배포
운영 env 누락
DB migration 빠짐
CloudFront 캐시 미반영
배포 후 핵심 기능 확인 누락

체크리스트 있음:
배포 전/후 확인 기준 명확
장애 시 원인 추적 쉬움
반복 실수 감소

✅ 2. Runbook이란 무엇인가?

Runbook은 운영 작업이나 장애 상황에서 따라 할 절차서입니다.
배포, 롤백, 장애 대응, DB 복구, 캐시 무효화, 서버 재시작 같은 반복 작업을 문서화한 것입니다.
“문제가 생기면 뭘 봐야 하지?”를 그때그때 생각하지 않도록 도와줍니다.

상황 발생
  ↓
Runbook 열기
  ↓
확인 순서대로 점검
  ↓
임시 대응
  ↓
근본 조치
  ↓
기록

➕ 2-1. 체크리스트와 Runbook 차이

구분	목적	예시
체크리스트	누락 방지	배포 전 확인 항목
Runbook	절차 수행	502 발생 시 확인 순서
Postmortem	사후 기록	장애 원인과 재발 방지

➕ 2-2. Runbook이 필요한 상황

프론트 배포
백엔드 배포
DB migration
CloudFront 캐시 무효화
운영 롤백
Nginx 502 대응
상담 신청 실패 대응
관리자 로그인 실패 대응
알림톡 발송 실패 대응

자주 반복되는 작업일수록 Runbook으로 남겨야 합니다.
특히 운영 장애 상황에서는 기억보다 문서를 믿는 것이 안전합니다.

✅ 3. 배포 전 확인할 큰 기준

배포 전에는 “코드가 돌아가는가?”만 보지 말고 “운영에 안전한가?”를 봐야 합니다.

➕ 3-1. 배포 전 5대 기준

1. 코드 검증:
lint/test/typecheck/build 통과

2. 환경 검증:
운영 env, API URL, Secret 누락 없음

3. 데이터 검증:
DB migration, seed, schema 변경 영향 확인

4. 기능 검증:
고객/관리자 핵심 흐름 확인

5. 롤백 검증:
문제 발생 시 되돌릴 방법 확인

➕ 3-2. 특히 중요한 질문

이 변경이 상담 신청에 영향을 주는가?
이 변경이 관리자 상담 처리에 영향을 주는가?
이 변경이 DB schema를 바꾸는가?
이 변경이 환경변수를 추가/변경하는가?
이 변경이 권한/인증에 영향을 주는가?
이 변경이 CloudFront 캐시에 영향을 주는가?
문제 발생 시 프론트만 롤백 가능한가?
백엔드와 함께 롤백해야 하는가?

모든 배포가 같은 위험도를 갖지는 않습니다.
DB, 인증, 상담 신청, 관리자 상태 변경, 결제/알림 연동은 더 신중하게 봐야 합니다.

✅ 4. 배포 위험도 분류

배포 전에 변경 내용을 위험도별로 나누면 QA 범위를 정하기 쉽습니다.

위험도	예시	대응
낮음	문구 수정, 여백 조정	간단 QA
중간	UI 구조 변경, 필터 개선	관련 화면 QA
높음	API 연동, 인증, 권한, 상태 변경	핵심 흐름 QA
매우 높음	DB migration, Secret 변경, 배포 구조 변경	롤백 계획 필수

➕ 4-1. 낮은 위험도

문구 수정
색상 수정
이미지 교체
단순 레이아웃 조정
FAQ 내용 수정

확인:

변경된 화면 확인
모바일 깨짐 확인
캐시 반영 확인

➕ 4-2. 중간 위험도

상담 신청 모달 UI 변경
관리자 검색/필터 UI 변경
상품 상세 구성 변경
공통 Button/Modal 사용 방식 변경

확인:

관련 화면 전체 QA
모바일/PC 확인
로딩/에러/빈 상태 확인
기존 동작 회귀 확인

➕ 4-3. 높은 위험도

API request/response 변경
TanStack Query queryKey 변경
mutation invalidate 변경
권한 조건 변경
로그인/토큰 처리 변경
상담 신청 저장 로직 변경
관리자 상태 변경 로직 변경

확인:

고객 상담 신청 Smoke Test
관리자 로그인 Smoke Test
상담 목록/상태 변경 QA
권한별 버튼 노출 확인
API 에러 처리 확인
배포 후 로그 확인

➕ 4-4. 매우 높은 위험도

DB schema migration
운영 환경변수 변경
JWT/Cookie Secret 변경
Nginx/CloudFront 설정 변경
배포 자동화 변경
인증/인가 구조 변경
대량 데이터 변경

확인:

배포 시간 신중히 선택
DB backup 또는 rollback plan 확인
staging 검증
운영 env 재확인
Health Check 준비
장애 대응 Runbook 준비

위험도가 높을수록 “배포 전 확인”보다 “문제 발생 시 복구 가능성”이 중요해집니다.

✅ 5. 공통 배포 전 체크리스트

## 공통 배포 전 체크리스트

### 코드 상태
- [ ] 현재 브랜치가 배포 대상 브랜치인지 확인
- [ ] `git status`가 깨끗한지 확인
- [ ] 의도하지 않은 파일 변경이 없는지 확인
- [ ] 최근 commit diff 확인
- [ ] AI/Codex가 수정한 파일을 직접 검토

### 검증
- [ ] lint 통과
- [ ] test 통과
- [ ] typecheck 통과
- [ ] build 통과
- [ ] CI 통과

### 환경
- [ ] 운영 환경변수 추가/변경 여부 확인
- [ ] Secret이 코드에 포함되지 않았는지 확인
- [ ] 프론트 빌드 결과물에 localhost가 없는지 확인
- [ ] SSM/GitHub Secrets 값 누락 여부 확인

### 데이터
- [ ] DB migration 여부 확인
- [ ] migration rollback 가능성 확인
- [ ] seed 실행 필요 여부 확인
- [ ] 운영 데이터 영향 여부 확인

### 배포
- [ ] 배포 대상 서버/버킷/distribution 확인
- [ ] 배포 명령어 확인
- [ ] 롤백 방법 확인
- [ ] 배포 후 Smoke Test 항목 준비

이 체크리스트는 모든 배포의 기본입니다.
실제 프로젝트에서는 프론트/백엔드/DB별로 더 세분화하면 됩니다.

✅ 6. 프론트엔드 배포 전 체크리스트

S3 + CloudFront로 정적 배포하는 프론트는 빌드 결과물, 환경변수, 캐시가 중요합니다.

## 프론트엔드 배포 전 체크리스트

### 코드 검증
- [ ] `pnpm lint` 또는 `npm run lint` 통과
- [ ] `pnpm test:run` 통과
- [ ] `pnpm typecheck` 통과
- [ ] `pnpm build` 통과

### 환경변수
- [ ] `VITE_API_BASE_URL`이 운영 API를 바라보는지 확인
- [ ] 프론트 env에 Secret이 없는지 확인
- [ ] 빌드 결과물에 `localhost`가 포함되지 않았는지 확인
- [ ] 스테이징/운영 env가 섞이지 않았는지 확인

### UI 영향
- [ ] 고객 메인 화면 확인
- [ ] 상품 목록/상세 확인
- [ ] 상담 신청 CTA 확인
- [ ] 상담 신청 모달 확인
- [ ] 관리자 로그인 확인
- [ ] 관리자 상담 목록 확인

### 캐시/배포
- [ ] `index.html` 캐시 정책 확인
- [ ] assets 캐시 정책 확인
- [ ] CloudFront invalidation 경로 확인
- [ ] 이미지 교체 시 파일명 또는 invalidation 확인
- [ ] SPA fallback 403/404 설정 영향 없음 확인

➕ 6-1. 프론트에서 특히 조심할 것

운영 빌드에 localhost 포함
API URL이 개발 서버를 가리킴
index.html 캐시가 너무 김
이전 JS chunk 삭제
CloudFront invalidation 누락
모바일 상담 신청 모달 깨짐

프론트 배포는 서버가 정상이어도 캐시 때문에 문제가 생길 수 있습니다.
배포 후 반드시 운영 도메인에서 직접 확인해야 합니다.

✅ 7. 백엔드 배포 전 체크리스트

백엔드는 환경변수, DB, migration, health check가 중요합니다.

## 백엔드 배포 전 체크리스트

### 코드 검증
- [ ] lint 통과
- [ ] unit test 통과
- [ ] e2e test 통과
- [ ] TypeScript build 통과
- [ ] Prisma generate 통과

### 환경변수
- [ ] 운영 `DATABASE_URL` 확인
- [ ] 운영 `REDIS_URL` 확인
- [ ] `NODE_ENV=production` 확인
- [ ] 필수 Secret 누락 없음 확인
- [ ] env validation 통과 확인

### DB
- [ ] migration 파일 확인
- [ ] `prisma migrate deploy` 실행 여부 확인
- [ ] migration 실패 시 대응 계획 확인
- [ ] schema 변경이 기존 API와 호환되는지 확인
- [ ] 데이터 삭제/컬럼 rename 여부 확인

### API
- [ ] `/health` 응답 확인
- [ ] 상담 신청 API 확인
- [ ] 관리자 로그인 API 확인
- [ ] 상담 목록 조회 API 확인
- [ ] 상태 변경 API 확인
- [ ] 권한별 API 401/403 확인

### 운영
- [ ] PM2/Docker 재시작 방식 확인
- [ ] Nginx proxy 대상 포트 확인
- [ ] 로그 확인 위치 확인
- [ ] 롤백 방식 확인

➕ 7-1. 백엔드에서 특히 조심할 것

운영 DB에 migrate reset 금지
migration과 코드 배포 순서
Secret 변경 후 세션 영향
Redis/Queue worker 함께 재시작 필요 여부
알림톡/SMS 실제 발송 영향

백엔드는 데이터와 직접 연결되므로 프론트보다 더 보수적으로 배포해야 합니다.
특히 migration은 되돌리기 어려운 경우가 많습니다.

✅ 8. DB Migration 체크리스트

DB migration은 배포 중 가장 위험한 작업 중 하나입니다.
schema 변경은 코드와 데이터에 동시에 영향을 줍니다.

## DB Migration 체크리스트

### 변경 내용
- [ ] 새 테이블 추가인가?
- [ ] 새 컬럼 추가인가?
- [ ] 컬럼 삭제인가?
- [ ] 컬럼 rename인가?
- [ ] enum 변경인가?
- [ ] index 추가/삭제인가?
- [ ] unique 제약 추가인가?

### 안전성
- [ ] 기존 데이터와 호환되는가?
- [ ] nullable/default 설정이 적절한가?
- [ ] 기존 코드가 새 schema에서도 동작하는가?
- [ ] migration 실행 시간이 길지 않은가?
- [ ] lock 발생 가능성이 있는가?
- [ ] rollback 방법이 있는가?

### 실행
- [ ] staging에서 먼저 실행했는가?
- [ ] 운영 DB backup 필요 여부 확인
- [ ] `prisma migrate deploy` 사용
- [ ] 운영에서 `migrate dev/reset` 사용하지 않음
- [ ] migration 후 health check 수행

➕ 8-1. 안전한 migration 예시

1단계:
nullable 컬럼 추가

2단계:
코드에서 새 컬럼 쓰기 시작

3단계:
기존 데이터 backfill

4단계:
필요 시 not null 제약 추가

➕ 8-2. 위험한 migration 예시

운영 컬럼 바로 삭제
대량 테이블에 무거운 index 즉시 추가
기존 enum 값 제거
기존 데이터가 있는데 not null 컬럼 default 없이 추가
컬럼 rename 후 구버전 코드와 호환 불가

DB는 한 번 잘못 건드리면 복구가 어렵습니다.
schema 변경은 작은 단계로 나누는 것이 안전합니다.

✅ 9. 배포 중 체크리스트

배포 중에는 명령어 실행 결과를 대충 넘기면 안 됩니다.
실패했는데 다음 단계로 넘어가면 더 큰 장애가 될 수 있습니다.

## 배포 중 체크리스트

- [ ] 배포 명령어가 정상 종료되었는가?
- [ ] build artifact가 생성되었는가?
- [ ] S3 업로드가 정상 완료되었는가?
- [ ] CloudFront invalidation이 생성되었는가?
- [ ] 백엔드 프로세스가 정상 재시작되었는가?
- [ ] migration이 성공했는가?
- [ ] health check가 통과했는가?
- [ ] 배포 로그에 에러가 없는가?

➕ 9-1. 실패 시 기준

빌드 실패:
배포 중단

migration 실패:
배포 중단 + DB 상태 확인

health check 실패:
롤백 또는 즉시 원인 확인

CloudFront invalidation 실패:
프론트 최신 반영 지연 가능성 안내/재시도

PM2 restart 실패:
이전 프로세스 상태 확인 후 복구

실패했을 때 “일단 계속 진행”은 가장 위험합니다.
실패한 단계에서 멈추고 상태를 확인해야 합니다.

✅ 10. 배포 후 Smoke Test

Smoke Test는 배포 후 핵심 기능이 살아 있는지 빠르게 확인하는 테스트입니다.
전체 QA가 아니라 “서비스가 최소 정상 동작하는가”를 보는 것입니다.

배포 완료
  ↓
운영 URL 접속
  ↓
핵심 고객 흐름 확인
  ↓
핵심 관리자 흐름 확인
  ↓
로그/에러 확인

➕ 10-1. 고객 화면 Smoke Test

## 고객 화면 Smoke Test

- [ ] 메인 페이지 접속
- [ ] 상품 목록 접속
- [ ] 상품 상세 접속
- [ ] 주요 배너/이미지 표시 확인
- [ ] 상담 신청 버튼 클릭
- [ ] 상담 신청 모달 열림 확인
- [ ] 필수값 검증 확인
- [ ] 전화번호 입력 UX 확인
- [ ] 상담 신청 테스트 제출 가능 여부 확인
- [ ] 모바일 화면 핵심 CTA 확인

➕ 10-2. 관리자 화면 Smoke Test

## 관리자 화면 Smoke Test

- [ ] 관리자 로그인
- [ ] 상담 목록 조회
- [ ] 검색/필터 실행
- [ ] 상담 상세 모달 열기
- [ ] 상담 상태 변경 가능 여부 확인
- [ ] 권한별 버튼 노출 확인
- [ ] 상품 관리 화면 접속
- [ ] 엑셀 다운로드 버튼 동작 확인
- [ ] 로그아웃/세션 만료 흐름 확인

➕ 10-3. 백엔드 Smoke Test

## 백엔드 Smoke Test

- [ ] `GET /health` 200 확인
- [ ] DB 연결 상태 확인
- [ ] Redis 연결 상태 확인
- [ ] `POST /consults` 정상/검증 실패 응답 확인
- [ ] 관리자 로그인 API 확인
- [ ] 상담 목록 API 확인
- [ ] 상태 변경 API 확인
- [ ] 401/403 에러 응답 확인

Smoke Test는 배포 직후 바로 해야 합니다.
특히 상담 신청과 관리자 상담 처리는 최우선입니다.

✅ 11. 배포 후 모니터링 체크리스트

배포 직후 일정 시간 동안 로그와 지표를 확인해야 합니다.
배포 성공 메시지만 보고 끝내면 안 됩니다.

## 배포 후 모니터링 체크리스트

- [ ] API 5xx 증가 여부 확인
- [ ] Nginx error log 확인
- [ ] PM2/Docker backend log 확인
- [ ] 프론트 Console 에러 확인
- [ ] CloudFront 403/404 증가 여부 확인
- [ ] 상담 신청 실패 로그 확인
- [ ] 관리자 로그인 실패 로그 확인
- [ ] 상태 변경 실패 로그 확인
- [ ] CPU/RAM/Disk 급증 여부 확인
- [ ] 외부 API/알림톡 실패 여부 확인

➕ 11-1. 배포 직후 특히 봐야 할 것

500 에러 증가
502/504 발생
Chunk Load Error
CORS 에러
로그인 유지 실패
상담 신청 실패
DB connection error
환경변수 누락

배포 직후 10~30분은 문제가 가장 잘 드러나는 시간입니다.
사용자가 알려주기 전에 로그에서 먼저 발견하는 것이 목표입니다.

✅ 12. 롤백 기준

롤백은 감정적으로 하는 것이 아니라 기준을 정해두고 판단해야 합니다.
“조금 더 고쳐볼게요” 하다가 장애 시간이 길어질 수 있습니다.

➕ 12-1. 즉시 롤백 후보

고객 사이트 접속 불가
상담 신청 불가
관리자 로그인 불가
상담 상태 변경 불가
API 5xx 급증
DB migration 후 주요 API 실패
프론트 흰 화면
인증/권한 로직 오류

➕ 12-2. Hotfix 후보

일부 문구 오류
특정 조건에서만 UI 깨짐
일부 이미지 미노출
관리자 보조 기능 실패
낮은 트래픽 기능 오류

➕ 12-3. 판단 기준

고객 전환에 직접 영향이 있는가?
운영자가 핵심 업무를 못 하는가?
데이터 정합성이 깨질 위험이 있는가?
빠른 수정이 가능한가?
롤백이 더 안전한가?
프론트만 롤백 가능한가?
백엔드/DB도 같이 봐야 하는가?

상담 신청 불가, 관리자 로그인 불가, 데이터 손상 가능성은 빠르게 롤백을 검토해야 합니다.
단순 UI 이슈는 hotfix가 더 적절할 수 있습니다.

✅ 13. 프론트엔드 롤백 Runbook

# Runbook: 프론트엔드 롤백

## 상황
- 배포 후 고객/관리자 화면에서 치명적 오류 발생
- 예: 흰 화면, 상담 신청 불가, 관리자 진입 불가

## 확인
1. 최근 배포 commit 확인
2. 브라우저 Console 에러 확인
3. Network에서 JS/CSS 404 여부 확인
4. API URL이 올바른지 확인
5. CloudFront invalidation 상태 확인

## 롤백 방법
1. 이전 안정 commit으로 checkout
2. 운영 env로 build
3. S3에 dist 재업로드
4. CloudFront invalidation 실행
5. 운영 URL Smoke Test

## 명령 예시
```bash
git checkout <previous-stable-commit>
pnpm install --frozen-lockfile
pnpm build
aws s3 sync dist/ s3://YOUR_BUCKET_NAME
aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

롤백 후 확인


*   프론트 롤백은 비교적 빠릅니다.
*   하지만 백엔드 API 변경과 맞물린 배포라면 이전 프론트가 최신 API와 호환되는지 봐야 합니다.

---

### ✅ 14. 백엔드 롤백 Runbook

```md id="backend-rollback-runbook"
# Runbook: 백엔드 롤백

## 상황
- 배포 후 API 500/502 증가
- 상담 신청, 관리자 로그인, 상태 변경 등 핵심 API 실패

## 확인
1. `/health` 확인
2. Nginx error log 확인
3. PM2/Docker backend log 확인
4. 최근 migration 여부 확인
5. 환경변수 변경 여부 확인
6. 이전 버전과 DB schema 호환 여부 확인

## PM2 롤백 예시
1. 이전 안정 commit으로 checkout
2. 의존성 설치
3. build
4. pm2 restart
5. health check

```bash
git checkout <previous-stable-commit>
pnpm install --frozen-lockfile
pnpm build
pm2 restart togethermall-api --update-env
curl -f https://api.example.com/health

Docker 롤백 예시

이전 image tag 확인
compose image tag 변경
컨테이너 재시작
health check

docker compose pull
docker compose up -d
curl -f https://api.example.com/health

주의

DB migration이 이미 적용된 경우 이전 코드와 호환되는지 확인
Secret 변경이 있었으면 이전 env와 호환성 확인
worker/queue도 함께 롤백 필요 여부 확인


*   백엔드 롤백은 프론트보다 위험합니다.
*   DB migration이 포함된 경우 단순 코드 롤백이 답이 아닐 수 있습니다.

---

### ✅ 15. DB Migration 롤백 Runbook

*   DB 롤백은 가장 조심해야 합니다.
*   Prisma migration은 자동 down migration이 기본 제공되지 않는 경우가 많으므로 수동 대응이 필요할 수 있습니다.

```md id="db-rollback-runbook"
# Runbook: DB Migration 문제 대응

## 상황
- migration 후 API 실패
- 컬럼/테이블/enum 변경으로 기존 코드 오류
- 데이터 제약조건 문제 발생

## 즉시 확인
1. 어떤 migration이 적용되었는지 확인
2. 실패하는 API와 에러 메시지 확인
3. 기존 코드와 새 schema 호환성 확인
4. 데이터 손상 여부 확인
5. backup 또는 snapshot 여부 확인

## 대응 방향
- 단순 컬럼 추가 문제:
  코드 hotfix 가능 여부 확인

- 제약조건 문제:
  제약 완화 migration 추가 검토

- 컬럼 삭제/rename 문제:
  이전 코드와 호환 어려움, forward fix 검토

- 데이터 손상:
  backup/snapshot 복구 검토

## 주의
- 운영 DB에서 임의로 테이블 삭제 금지
- 운영 DB에서 `migrate reset` 절대 금지
- 데이터 복구 전 현재 상태 snapshot 고려
- SQL 직접 실행 시 쿼리 검토 필수

➕ 15-1. DB 문제는 롤백보다 forward fix가 많다

코드:
이전 버전으로 되돌리기 쉬움

DB:
이미 변경된 데이터와 schema가 남음

그래서:
DB는 롤백보다 안전한 추가 migration으로 forward fix하는 경우가 많음

DB migration은 배포 전에 신중해야 하는 이유가 여기에 있습니다.
삭제/rename은 특히 조심해야 합니다.

✅ 16. Nginx 502 Runbook

# Runbook: Nginx 502 Bad Gateway

## 증상
- API 요청 시 502 발생
- 브라우저 또는 프론트 Network에서 Bad Gateway 확인

## 확인 순서
1. Nginx 상태 확인
```bash
sudo systemctl status nginx

Nginx 설정 확인

sudo nginx -t

Nginx error log 확인

sudo tail -n 100 /var/log/nginx/error.log

백엔드 health 확인

curl -f http://localhost:3000/health
curl -f https://api.example.com/health

PM2 또는 Docker 상태 확인

pm2 status
pm2 logs togethermall-api --lines 100

또는

docker compose ps
docker compose logs --tail=100 backend

주요 원인

백엔드 프로세스 종료
proxy_pass 포트 불일치
백엔드 crash loop
env 누락으로 서버 시작 실패
Docker network/port 문제

임시 대응

백엔드 프로세스 재시작
최근 배포 롤백
env 누락 수정 후 재시작
Nginx 설정 수정 후 nginx -t && reload

재발 방지

health check 추가
배포 후 자동 health check
process restart 알림
env validation 강화


*   502는 Nginx가 살아 있어도 백엔드가 죽어 있으면 발생합니다.
*   외부 health와 내부 localhost health를 비교하면 원인을 빠르게 좁힐 수 있습니다.

---

### ✅ 17. 상담 신청 실패 Runbook

```md id="consult-failure-runbook"
# Runbook: 상담 신청 실패

## 증상
- 고객이 상담 신청 제출 시 실패
- 프론트에서 실패 메시지 노출
- POST /consults 요청 실패

## 영향도
- 고객 리드 수집에 직접 영향
- P1 이상으로 판단 가능

## 확인 순서
1. 프론트 Network에서 상태 코드 확인
   - 400/409/500 구분

2. 프론트 Console 에러 확인

3. 백엔드 로그 확인
   - `consult.create.failed`
   - errorCode
   - requestId

4. DB 상태 확인
   - health check
   - insert 실패 여부
   - unique constraint 충돌 여부

5. 외부 연동 확인
   - 알림톡/SMS 실패가 신청 저장 실패로 이어지는지 확인

## 상태 코드별 판단
- 400:
  validation 문제

- 409:
  중복 신청 또는 상태 충돌

- 500:
  서버/DB/외부 연동 문제 가능성

## 임시 대응
- 최근 배포 롤백
- 외부 알림톡 실패와 신청 저장 로직 분리
- 수동 접수 안내 문구 노출
- 문제 필드 validation 완화 hotfix 검토

## 재발 방지
- 상담 신청 Smoke Test 추가
- 400/409/500 에러 메시지 구분
- 알림톡 실패와 DB 저장 transaction 분리 검토
- 상담 신청 실패율 알림 추가

상담 신청 실패는 매출과 직접 연결됩니다.
단순 UI 오류로 보더라도 우선순위는 높게 잡아야 합니다.

✅ 18. 관리자 로그인 실패 Runbook

# Runbook: 관리자 로그인 실패

## 증상
- 관리자 로그인 불가
- 로그인 후 바로 로그아웃됨
- 쿠키가 저장되지 않음
- 401/403 반복

## 확인 순서
1. API 상태 확인
   - `POST /admin/login`
   - `GET /admin/me`

2. 브라우저 Application 탭에서 Cookie 확인

3. CORS 확인
   - origin
   - credentials
   - Access-Control-Allow-Origin

4. 쿠키 옵션 확인
   - httpOnly
   - secure
   - sameSite
   - domain

5. Nginx proxy header 확인
   - X-Forwarded-Proto
   - Host

6. 백엔드 auth log 확인
   - login.success
   - login.failed
   - token.verify.failed

## 주요 원인
- secure cookie가 HTTP 환경에서 전송되지 않음
- CORS credentials 설정 누락
- axios/fetch withCredentials 누락
- SameSite/domain 설정 오류
- JWT Secret 변경으로 기존 토큰 무효화
- 백엔드가 HTTPS 요청을 인식하지 못함

## 임시 대응
- 최근 인증 관련 배포 롤백
- cookie 옵션 hotfix
- API client withCredentials 확인
- 관리자에게 재로그인 안내

## 재발 방지
- 관리자 로그인 Smoke Test 필수화
- auth env 변경 시 영향 기록
- staging에서 쿠키/CORS 검증

로그인 문제는 프론트, 백엔드, Nginx, HTTPS, CORS, 쿠키가 모두 엮입니다.
한쪽만 보고 판단하면 오래 걸릴 수 있습니다.

✅ 19. CloudFront 캐시 문제 Runbook

# Runbook: CloudFront 캐시 문제

## 증상
- 새 배포가 반영되지 않음
- 이전 배너/이미지가 계속 보임
- 일부 사용자만 오래된 화면을 봄
- JS chunk 404 또는 흰 화면 발생

## 확인 순서
1. S3에 최신 파일이 올라갔는지 확인
2. CloudFront invalidation 상태 확인
3. 브라우저 Network에서 cache-control 확인
4. index.html이 최신 assets를 참조하는지 확인
5. JS/CSS chunk가 404인지 확인
6. 이미지 파일명이 동일한지 확인

## 임시 대응
- `/index.html`, `/`, 필요 시 `/*` invalidation
- 문제 이미지 경로 invalidation
- 사용자에게 새로고침 안내
- 이전 assets를 복구하거나 재배포

## 재발 방지
- index.html은 짧은 캐시
- hashed assets는 긴 캐시
- 이미지 파일명에 버전/hash 포함
- `--delete` 사용 시 이전 chunk 삭제 위험 고려

캐시 문제는 배포가 실패한 것처럼 보이지만 실제로는 오래된 파일을 보고 있는 경우가 많습니다.
S3 원본, CloudFront, 브라우저 캐시를 나눠서 봐야 합니다.

✅ 20. 배포 기록 템플릿

배포 후에는 어떤 배포를 했는지 기록해야 합니다.
장애가 나면 이 기록이 원인 추적의 기준이 됩니다.

# 배포 기록

## 기본 정보
- 배포일시:
- 배포자:
- 환경: production / staging
- 대상: front / admin / back / infra
- commit:
- branch:

## 변경 요약
- 

## 영향 범위
- 고객 화면:
- 관리자 화면:
- API:
- DB:
- 인프라:

## 배포 전 확인
- [ ] lint
- [ ] test
- [ ] typecheck
- [ ] build
- [ ] CI 통과
- [ ] env 확인
- [ ] migration 확인

## 배포 작업
- S3 업로드:
- CloudFront invalidation:
- PM2/Docker restart:
- migration:
- health check:

## 배포 후 Smoke Test
- [ ] 메인/상품 상세
- [ ] 상담 신청
- [ ] 관리자 로그인
- [ ] 상담 목록
- [ ] 상태 변경

## 모니터링 결과
- API 5xx:
- Nginx error:
- 상담 신청 실패:
- 기타:

## 롤백 여부
- 필요 없음 / 롤백 진행 / hotfix 진행

## 남은 TODO
-

이 템플릿은 Notion이나 Markdown으로 남기면 좋습니다.
나중에 연봉협상이나 이직 자료에도 “운영 체계 구축”으로 설명할 수 있습니다.

✅ 21. 배포 전 AI 리뷰 프롬프트

배포 전에는 AI에게 git diff 기반으로 위험 요소를 점검하게 할 수 있습니다.
단, AI가 배포 승인을 대신하는 것은 아닙니다.
AI는 놓친 부분을 찾는 보조 도구로 쓰는 것이 안전합니다.

아래 git diff를 운영 배포 전 관점으로 리뷰해줘.

프로젝트 상황:
- 온라인 휴대폰 판매몰
- 고객 화면: 상품 상세, 상담 신청, 사전예약
- 관리자 화면: 상담 목록, 상태 변경, 상품/배너 관리
- 백엔드: NestJS + Prisma
- 프론트: React + TypeScript + TanStack Query
- 배포: S3 + CloudFront, 백엔드는 PM2 또는 Docker
- DB migration이 있으면 특히 조심해야 함
- 개인정보/Secret은 마스킹됨

중점:
1. 상담 신청 흐름 영향
2. 관리자 상담 처리 영향
3. 인증/권한 영향
4. API request/response 변경
5. queryKey/invalidate 누락 가능성
6. DB migration 위험
7. 환경변수 추가/변경
8. 캐시/배포 영향
9. 개인정보 로그 노출 위험
10. 배포 후 Smoke Test 항목

출력:
- 위험도 요약
- 배포 전 반드시 확인할 것
- 롤백 시 주의할 것
- 수동 QA 체크리스트
- 커밋 분리 또는 배포 분리 제안

➕ 21-1. AI 리뷰 결과 검증 기준

실제 diff 기준으로 말하는가?
과장된 성과를 만들지 않는가?
DB/Secret/권한 위험을 제대로 보는가?
상담 신청과 관리자 처리 흐름을 우선순위로 보는가?
배포 후 확인 항목이 구체적인가?
운영 DB 위험 명령을 제안하지 않는가?

AI 리뷰는 매우 유용하지만 최종 책임은 사람에게 있습니다.
AI가 괜찮다고 해도 직접 diff와 핵심 화면을 확인해야 합니다.

✅ 22. 1인 개발자용 최소 배포 루틴

처음부터 복잡한 DevOps 체계를 만들 필요는 없습니다.
현실적으로 반복 가능한 최소 루틴을 만드는 것이 먼저입니다.

1. git diff 확인
2. pnpm verify 또는 npm run verify
3. 환경변수 변경 여부 확인
4. DB migration 여부 확인
5. 배포 실행
6. health check
7. 고객 상담 신청 Smoke Test
8. 관리자 상담 목록 Smoke Test
9. 로그 확인
10. 배포 기록 작성

➕ 22-1. 최소 Smoke Test

고객:
메인 → 상품 상세 → 상담 신청 모달 → 필수값 검증

관리자:
로그인 → 상담 목록 → 검색/필터 → 상세 모달

백엔드:
GET /health

➕ 22-2. 최소 기록

언제 배포했는가?
무엇을 바꿨는가?
어떤 commit인가?
검증은 무엇을 했는가?
문제는 없었는가?

혼자 개발해도 이 정도는 반드시 남기는 것이 좋습니다.
기억에 의존하면 나중에 장애 원인 추적이 어려워집니다.

✅ 23. 배포 자동화와 수동 확인의 균형

배포 자동화가 모든 것을 해결해주지는 않습니다.
자동화는 반복 명령어를 줄여주지만, 운영 판단은 사람이 해야 합니다.

➕ 23-1. 자동화하면 좋은 것

lint/test/build 실행
S3 업로드
CloudFront invalidation
Docker image build
health check
배포 기록 초안 생성
QA 체크리스트 생성

➕ 23-2. 사람이 확인해야 하는 것

이번 배포가 운영에 안전한가?
DB migration이 위험하지 않은가?
상담 신청이 실제로 되는가?
관리자 상태 변경이 실제로 되는가?
권한/개인정보 문제가 없는가?
장애 시 롤백이 가능한가?

자동화는 손을 줄여주는 것이고, 판단을 없애는 것이 아닙니다.
특히 1인 개발자는 사람이 마지막 방어선입니다.

✅ 24. Runbook 문서 구조 추천

Runbook은 한 파일에 모두 넣기보다 상황별로 나누는 것이 좋습니다.

docs/
  runbooks/
    deploy-frontend.md
    deploy-backend.md
    rollback-frontend.md
    rollback-backend.md
    incident-nginx-502.md
    incident-consult-submit-failed.md
    incident-admin-login-failed.md
    incident-cloudfront-cache.md
    incident-db-migration.md
  checklists/
    pre-deploy.md
    smoke-test.md
    post-deploy-monitoring.md

➕ 24-1. 각 Runbook에 들어갈 것

증상
영향도
확인 순서
주요 원인
임시 대응
근본 해결
재발 방지
관련 명령어
주의사항

파일 이름은 상황을 바로 알 수 있게 만들어야 합니다.
incident-502.md, rollback-frontend.md처럼 검색하기 쉬운 이름이 좋습니다.

✅ 25. 실무 체크리스트

➕ 25-1. 배포 전 체크리스트

현재 브랜치와 commit을 확인했는가?
git diff를 직접 확인했는가?
AI/Codex 변경 파일을 직접 검토했는가?
lint/test/typecheck/build가 통과했는가?
CI가 통과했는가?
환경변수 추가/변경 여부를 확인했는가?
DB migration 여부를 확인했는가?
롤백 방법을 확인했는가?

➕ 25-2. 배포 후 체크리스트

배포 명령이 정상 종료되었는가?
health check가 통과했는가?
고객 화면 Smoke Test를 했는가?
관리자 화면 Smoke Test를 했는가?
Nginx/PM2/Docker 로그를 확인했는가?
API 5xx 증가 여부를 확인했는가?
상담 신청 실패 로그를 확인했는가?
배포 기록을 남겼는가?

➕ 25-3. Runbook 체크리스트

프론트 배포 Runbook이 있는가?
백엔드 배포 Runbook이 있는가?
프론트 롤백 Runbook이 있는가?
백엔드 롤백 Runbook이 있는가?
DB migration 문제 대응 Runbook이 있는가?
Nginx 502 대응 Runbook이 있는가?
상담 신청 실패 대응 Runbook이 있는가?
관리자 로그인 실패 대응 Runbook이 있는가?
CloudFront 캐시 문제 Runbook이 있는가?
실제 장애 후 Runbook을 업데이트하는가?

✅ 26. AI에게 배포/Runbook 점검을 맡길 때 좋은 질문법

AI에게 배포 절차를 점검시킬 때는 프로젝트 구조, 배포 방식, 핵심 기능, 위험 요소를 함께 알려줘야 합니다.

➕ 26-1. 좋은 질문 예시

온라인 휴대폰 판매몰의 배포 체크리스트와 Runbook을 정리하려고 해.

상황:
1. 프론트는 React + Vite이고 S3 + CloudFront로 배포함
2. 백엔드는 NestJS + Prisma이고 PM2 또는 Docker로 운영함
3. DB는 PostgreSQL/RDS를 사용함
4. 환경변수와 Secret은 SSM/GitHub Secrets로 관리하려고 함
5. 고객 핵심 흐름은 상품 상세 → 상담 신청임
6. 관리자 핵심 흐름은 로그인 → 상담 목록 → 상태 변경임
7. 배포 전 lint/test/build/CI를 확인하고 싶음
8. 배포 후 health check와 Smoke Test를 하고 싶음
9. 장애 상황별 Runbook도 만들고 싶음

요청:
- 공통 배포 전 체크리스트
- 프론트 배포 체크리스트
- 백엔드 배포 체크리스트
- DB migration 체크리스트
- 배포 후 Smoke Test
- 롤백 기준
- 프론트 롤백 Runbook
- 백엔드 롤백 Runbook
- Nginx 502 Runbook
- 상담 신청 실패 Runbook
- 관리자 로그인 실패 Runbook
- CloudFront 캐시 문제 Runbook
을 1인 개발자 실무 기준으로 정리해줘.

➕ 26-2. AI 답변 검증 기준

고객 상담 신청과 관리자 상담 처리를 최우선으로 보는가?
프론트/백엔드/DB/인프라를 구분하는가?
DB migration 위험을 과소평가하지 않는가?
운영 DB에서 위험한 명령을 제안하지 않는가?
배포 후 Smoke Test와 로그 확인을 포함하는가?
롤백 기준을 명확히 나누는가?
Secret/개인정보 노출 주의사항을 포함하는가?
1인 개발자가 실제로 따라 할 수 있는 수준인가?

📌 요약

배포 체크리스트는 운영 반영 전후에 놓치면 안 되는 항목을 정리한 목록이고, Runbook은 배포/장애/롤백 상황에서 따라 할 절차서입니다.
배포는 단순히 코드를 서버에 올리는 작업이 아니라 코드 검증, 환경변수 확인, DB migration, 캐시 무효화, Health Check, Smoke Test, 모니터링, 기록까지 포함하는 운영 절차입니다.
배포 전에는 코드 검증, 환경 검증, 데이터 검증, 기능 검증, 롤백 가능성을 반드시 확인해야 합니다.
변경 위험도는 문구 수정 같은 낮은 위험부터 DB migration, Secret 변경, 인증 구조 변경 같은 매우 높은 위험까지 나눠서 QA 범위를 정해야 합니다.
프론트 배포에서는 운영 API URL, 빌드 결과물의 localhost 포함 여부, CloudFront invalidation, SPA fallback, index.html/assets 캐시 정책을 확인해야 합니다.
백엔드 배포에서는 env validation, Prisma generate, migration, health check, PM2/Docker 재시작, Nginx proxy, 로그 위치를 확인해야 합니다.
DB migration은 가장 위험한 배포 요소 중 하나이며, 운영에서 migrate reset 같은 명령은 절대 사용하면 안 됩니다.
배포 후에는 고객 상담 신청 흐름과 관리자 상담 목록/상태 변경 흐름을 우선 Smoke Test해야 합니다.
롤백은 고객 신청 불가, 관리자 로그인 불가, API 5xx 급증, 프론트 흰 화면, 데이터 정합성 위험처럼 핵심 기능에 영향이 있을 때 빠르게 검토해야 합니다.
1인 개발자라도 git diff 확인 → verify → env/migration 확인 → 배포 → health check → Smoke Test → 로그 확인 → 배포 기록 루틴은 반드시 갖추는 것이 좋습니다.

juni

이전 포스트

TIL - 20260808

다음 포스트

TIL - 20260810

TIL

0810 인프라/DevOps 운영 심화 (8/N): 배포 체크리스트와 Runbook

✅ 1. 배포 체크리스트란 무엇인가?

➕ 1-1. 체크리스트가 필요한 이유

✅ 2. Runbook이란 무엇인가?

➕ 2-1. 체크리스트와 Runbook 차이

➕ 2-2. Runbook이 필요한 상황

✅ 3. 배포 전 확인할 큰 기준

➕ 3-1. 배포 전 5대 기준

➕ 3-2. 특히 중요한 질문

✅ 4. 배포 위험도 분류

➕ 4-1. 낮은 위험도

➕ 4-2. 중간 위험도

➕ 4-3. 높은 위험도

➕ 4-4. 매우 높은 위험도

✅ 5. 공통 배포 전 체크리스트

✅ 6. 프론트엔드 배포 전 체크리스트

➕ 6-1. 프론트에서 특히 조심할 것

✅ 7. 백엔드 배포 전 체크리스트

➕ 7-1. 백엔드에서 특히 조심할 것

✅ 8. DB Migration 체크리스트

➕ 8-1. 안전한 migration 예시

➕ 8-2. 위험한 migration 예시

✅ 9. 배포 중 체크리스트

➕ 9-1. 실패 시 기준

✅ 10. 배포 후 Smoke Test

➕ 10-1. 고객 화면 Smoke Test

➕ 10-2. 관리자 화면 Smoke Test

➕ 10-3. 백엔드 Smoke Test

✅ 11. 배포 후 모니터링 체크리스트

➕ 11-1. 배포 직후 특히 봐야 할 것

✅ 12. 롤백 기준

➕ 12-1. 즉시 롤백 후보

➕ 12-2. Hotfix 후보

➕ 12-3. 판단 기준

✅ 13. 프론트엔드 롤백 Runbook

롤백 후 확인

Docker 롤백 예시

주의

➕ 15-1. DB 문제는 롤백보다 forward fix가 많다

✅ 16. Nginx 502 Runbook

주요 원인

임시 대응

재발 방지

✅ 18. 관리자 로그인 실패 Runbook

✅ 19. CloudFront 캐시 문제 Runbook

✅ 20. 배포 기록 템플릿

✅ 21. 배포 전 AI 리뷰 프롬프트

➕ 21-1. AI 리뷰 결과 검증 기준

✅ 22. 1인 개발자용 최소 배포 루틴

➕ 22-1. 최소 Smoke Test

➕ 22-2. 최소 기록

✅ 23. 배포 자동화와 수동 확인의 균형

➕ 23-1. 자동화하면 좋은 것

➕ 23-2. 사람이 확인해야 하는 것

✅ 24. Runbook 문서 구조 추천

➕ 24-1. 각 Runbook에 들어갈 것

✅ 25. 실무 체크리스트

➕ 25-1. 배포 전 체크리스트

➕ 25-2. 배포 후 체크리스트

➕ 25-3. Runbook 체크리스트

✅ 26. AI에게 배포/Runbook 점검을 맡길 때 좋은 질문법

➕ 26-1. 좋은 질문 예시

➕ 26-2. AI 답변 검증 기준

📌 요약

TIL - 20260808

TIL - 20260811

0개의 댓글