TIL - 20260712

juni·2026년 7월 11일

목록 보기

401/468

0712 백엔드 실무 심화 (19/N): 장애 대응, Runbook과 재발 방지 문서화

✅ 1. 장애 대응이란 무엇인가?

장애 대응(Incident Response)은 서비스에 문제가 발생했을 때 원인을 찾고, 피해를 줄이고, 정상 상태로 복구하는 과정입니다.
백엔드 실무에서는 API 오류, DB 연결 실패, 서버 다운, 배포 실패, 외부 API 장애, Queue 적체, Webhook 실패, 배치 실패, S3 파일 누락 같은 문제가 장애로 이어질 수 있습니다.
장애 대응은 “에러를 고치는 것”만이 아니라, 빠르게 감지하고, 우선순위를 판단하고, 복구하고, 재발 방지까지 정리하는 전체 과정입니다.

문제 발생
  ↓
장애 감지
  ↓
영향 범위 파악
  ↓
긴급 복구
  ↓
원인 분석
  ↓
재발 방지
  ↓
문서화

➕ 1-1. 장애 대응이 중요한 이유

고객 신청이 실패하면 매출 손실로 이어질 수 있습니다.
관리자 기능이 멈추면 상담/주문 처리가 지연됩니다.
알림톡/SMS 실패는 고객 응대 누락으로 이어질 수 있습니다.
결제/주문/정산 데이터 오류는 금전 문제로 이어질 수 있습니다.
원인을 기록하지 않으면 같은 장애가 반복됩니다.

나쁜 대응:
일단 서버 재시작
  ↓
잠깐 정상화
  ↓
원인 기록 없음
  ↓
며칠 뒤 같은 문제 반복

좋은 장애 대응은 “이번만 고치기”가 아니라 “다음에는 덜 터지게 만드는 것”입니다.

✅ 2. 장애와 버그의 차이

모든 버그가 장애는 아닙니다.
장애는 사용자, 운영자, 데이터, 매출, 보안에 실제 영향을 주는 문제입니다.

구분	의미	예시
버그	기능이 의도와 다르게 동작	버튼 문구 오류
장애	서비스 운영에 영향 발생	상담 신청 API 500 오류
보안 사고	민감정보/권한 문제	개인정보 로그 노출
데이터 사고	데이터 손실/불일치	주문 상태와 결제 상태 불일치

➕ 2-1. 실무 기준

단순 UI 문구 오류:
버그

고객이 신청을 못함:
장애

관리자 엑셀 다운로드가 실패:
운영 장애

결제 완료인데 주문 상태가 미결제:
데이터 장애

전화번호가 로그에 그대로 노출:
보안 사고 가능성

문제의 심각도를 빠르게 구분해야 대응 우선순위를 정할 수 있습니다.

✅ 3. 장애 등급 분류

장애는 영향도에 따라 등급을 나누는 것이 좋습니다.
등급이 있어야 “지금 당장 롤백할 문제인지”, “업무 시간에 수정해도 되는 문제인지”를 판단할 수 있습니다.

➕ 3-1. 장애 등급 예시

등급	기준	예시	대응
P0	서비스 핵심 기능 전체 중단	상담 신청 전체 실패, 서버 다운	즉시 복구/롤백
P1	핵심 기능 일부 장애	관리자 로그인 불가, 주문 상태 변경 실패	최우선 수정
P2	운영 기능 장애	엑셀 다운로드 실패, 알림톡 실패 일부	빠른 수정/재처리
P3	낮은 영향도	일부 문구/스타일 오류	일반 수정
Security	보안/개인정보 이슈	권한 우회, 개인정보 노출	즉시 차단/조사

➕ 3-2. 기준을 정해두는 이유

장애 발생
  ↓
등급 판단
  ↓
복구 방식 결정

P0:
롤백 우선

P2:
원인 파악 후 핫픽스 가능

장애가 터졌을 때 고민 시간이 줄어듭니다.
1인 개발자일수록 미리 기준을 만들어두는 것이 중요합니다.

✅ 4. 장애 감지 방법

장애는 사용자가 알려주기 전에 개발자가 먼저 알아차리는 것이 좋습니다.
감지 방법은 로그, 모니터링, 알림, 운영 리포트, 관리자 문의 등으로 나눌 수 있습니다.

➕ 4-1. 감지 경로

CloudWatch/Sentry 에러 알림
API health check 실패
Nginx 502/504 증가
PM2 프로세스 down
Queue failed Job 증가
BatchJobLog FAILED
WebhookEvent FAILED
관리자 문의
고객 상담 문의

➕ 4-2. 감지 지표 예시

지표	위험 신호
API 500	10분 내 5건 이상
상담 신청 수	평소 대비 급감
Queue waiting	계속 증가
ExportJob	PROCESSING 30분 이상
알림톡 실패	1시간 내 10건 이상
RDS CPU	80% 이상 지속
디스크 사용량	90% 이상
Nginx error.log	502/504 반복

처음에는 완벽한 모니터링보다 핵심 지표 몇 개부터 시작하면 됩니다.
상담 신청, 관리자 로그인, DB 연결, Worker 상태는 우선적으로 봐야 합니다.

✅ 5. 장애 발생 시 첫 번째 원칙

장애가 발생하면 바로 코드를 고치기 전에 영향 범위와 복구 우선순위를 먼저 파악해야 합니다.

➕ 5-1. 먼저 확인할 것

1. 고객 화면이 열리는가?
2. 상담 신청이 되는가?
3. 관리자 로그인이 되는가?
4. 주요 API가 500을 반환하는가?
5. DB 연결이 정상인가?
6. 최근 배포가 있었는가?
7. 외부 API 장애인가?
8. Queue/Worker가 밀리고 있는가?

➕ 5-2. 나쁜 대응

에러 발생
  ↓
원인 모름
  ↓
일단 여러 파일 수정
  ↓
재배포
  ↓
문제 악화

➕ 5-3. 좋은 대응

에러 발생
  ↓
로그 확인
  ↓
영향 범위 파악
  ↓
최근 변경사항 확인
  ↓
롤백/핫픽스 판단
  ↓
복구 후 원인 분석

장애 대응은 침착하게 좁혀가는 작업입니다.
급할수록 체크리스트대로 움직여야 합니다.

✅ 6. 장애 대응 기본 순서

➕ 6-1. 1단계: 장애 확인

문제 제보 또는 알림 수신
  ↓
실제로 재현되는지 확인
  ↓
한 명만의 문제인지 전체 문제인지 확인

확인 예시:

curl -i https://api.example.com/health

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

➕ 6-2. 2단계: 영향 범위 파악

고객 화면 전체 문제인가?
특정 API만 문제인가?
관리자만 문제인가?
외부 API만 문제인가?
데이터 저장 실패인가?

영향 범위를 좁히면 대응 방식이 달라집니다.
고객 신청 전체 실패라면 즉시 롤백이 우선일 수 있습니다.
특정 관리자 Export 실패라면 원인 분석 후 핫픽스가 가능할 수 있습니다.

➕ 6-3. 3단계: 최근 변경사항 확인

최근 배포 커밋
DB migration
환경변수 변경
Nginx 설정 변경
외부 API 키 변경
Queue Worker 배포
Batch 스케줄 변경

장애는 최근 변경사항과 연결되는 경우가 많습니다.
배포 직후 장애라면 새 코드, migration, 환경변수를 먼저 봐야 합니다.

➕ 6-4. 4단계: 복구 방식 선택

롤백:
핵심 기능 장애, 원인 불명, 빠른 복구 필요

핫픽스:
원인이 명확하고 수정 범위가 작음

재시작:
메모리 누수, 프로세스 멈춤, 일시적 장애

재처리:
Queue/Webhook/Batch 실패 작업

수동 보정:
데이터 정합성 문제

복구 방식은 장애 등급과 원인 명확도에 따라 결정합니다.

➕ 6-5. 5단계: 복구 후 검증

health check 정상
주요 API 정상
관리자 기능 정상
로그 에러 감소
Queue 적체 해소
데이터 정합성 확인

서버가 켜졌다고 복구가 끝난 것은 아닙니다.
실제 핵심 기능이 정상인지 확인해야 합니다.

✅ 7. Runbook이란 무엇인가?

Runbook은 특정 장애나 운영 작업이 발생했을 때 따라 할 수 있는 절차 문서입니다.
장애 상황에서는 당황하기 쉽기 때문에, 미리 “어떤 명령어를 보고, 무엇을 확인하고, 어떻게 복구할지” 문서화해두면 큰 도움이 됩니다.

장애 유형:
API 502 발생

확인 순서:
1. PM2 상태 확인
2. API 로그 확인
3. Nginx 로그 확인
4. DB 연결 확인
5. 최근 배포 확인

복구:
PM2 reload 또는 이전 버전 롤백

➕ 7-1. Runbook이 필요한 이유

장애 대응 속도가 빨라집니다.
매번 기억에 의존하지 않아도 됩니다.
1인 개발자라도 미래의 내가 빠르게 대응할 수 있습니다.
나중에 다른 사람이 합류해도 인수인계가 쉬워집니다.
연봉협상/경력기술서에서 운영 역량을 보여주기 좋습니다.

✅ 8. Runbook 기본 템플릿

## Runbook: API 502 오류 대응

### 증상
- 고객 화면 또는 관리자 화면에서 API 요청 실패
- Nginx에서 502 Bad Gateway 발생

### 영향 범위
- 고객 상담 신청 실패 가능
- 관리자 API 호출 실패 가능

### 우선순위
- P0 또는 P1

### 확인 순서
1. API 서버 프로세스 상태 확인
2. Nginx error.log 확인
3. API 서버 로그 확인
4. DB/Redis 연결 확인
5. 최근 배포 여부 확인

### 확인 명령어
```bash
pm2 list
pm2 logs togethermall-api --lines 100
sudo tail -n 100 /var/log/nginx/error.log
curl -i http://localhost:3000/health

복구 방법

API 프로세스 reload
계속 실패하면 최근 배포 이전 버전으로 롤백
환경변수 누락 여부 확인

복구 후 검증

/health 정상
고객 상담 신청 정상
관리자 로그인 정상
Nginx error.log 추가 오류 없음

재발 방지

배포 후 health check 자동화
PM2 프로세스 down 알림 추가


*   Runbook은 완벽할 필요는 없습니다.
*   자주 터지는 장애부터 하나씩 만들면 됩니다.

---

### ✅ 9. 장애 유형별 Runbook 후보

#### ➕ 9-1. 서버/API 장애

```txt id="server-runbook-list"
API 502/504 오류
API 500 급증
PM2 프로세스 down
서버 디스크 용량 부족
메모리 사용량 급증
Nginx 설정 오류
SSL 인증서 만료

➕ 9-2. DB 장애

RDS 연결 실패
DB CPU 급증
느린 쿼리 발생
migration 실패
DB connection pool 부족
중복 데이터 발생
데이터 정합성 불일치

➕ 9-3. Queue/Worker 장애

Worker 프로세스 down
Redis 연결 실패
Queue waiting 급증
failed Job 급증
ExportJob PROCESSING 장기 지속
알림톡 발송 Job 실패

➕ 9-4. 외부 API/Webhook 장애

알림톡 API timeout
SMS 발송 실패
결제 Webhook 실패
Webhook 서명 검증 실패
CRM 연동 실패
외부 API rate limit 발생

➕ 9-5. 배포 장애

배포 후 API 500
환경변수 누락
Prisma migration 실패
프론트/백엔드 응답 구조 불일치
Worker jobName 불일치
CloudFront 캐시 문제

✅ 10. API 500 급증 Runbook

➕ 10-1. 증상

CloudWatch/Sentry에서 API 500 에러 증가
관리자 화면 일부 API 실패
고객 신청 실패 가능성

➕ 10-2. 확인 순서

pm2 logs togethermall-api --lines 200
sudo tail -n 100 /var/log/nginx/error.log
curl -i https://api.example.com/health

확인할 것:

최근 배포 여부
특정 API만 실패하는지
DB 연결 오류인지
환경변수 누락인지
Prisma 에러인지
외부 API timeout인지

➕ 10-3. 복구 기준

최근 배포 직후 전체 500:
즉시 롤백 우선

특정 API에서만 500:
해당 API 핫픽스 또는 기능 플래그 OFF

DB 연결 오류:
DB 상태와 connection pool 확인

환경변수 누락:
운영 env 반영 후 reload

✅ 11. DB 연결 실패 Runbook

➕ 11-1. 증상

PrismaClientInitializationError
Can't reach database server
API 500 증가
관리자 목록 조회 실패

➕ 11-2. 확인 명령어

pm2 logs togethermall-api --lines 100
echo $DATABASE_URL
nc -zv <rds-endpoint> 5432

확인할 것:

RDS가 running 상태인가?
보안 그룹에서 EC2 접근 허용인가?
DATABASE_URL이 올바른가?
비밀번호/포트/DB명이 맞는가?
connection limit에 도달했는가?
최근 RDS 변경이 있었는가?

➕ 11-3. 복구 방법

환경변수 오류:
DATABASE_URL 수정 후 reload

보안 그룹 오류:
EC2 → RDS 5432 허용 확인

RDS 장애:
AWS 콘솔 상태 확인

connection 과다:
PM2 인스턴스/Prisma connection 관리 확인

DB 문제는 무작정 서버 재시작만 반복하면 안 됩니다.
connection 수, RDS 상태, 네트워크 설정을 같이 봐야 합니다.

✅ 12. Queue 적체 Runbook

➕ 12-1. 증상

상담 신청은 되지만 알림톡이 안 감
엑셀 Export가 계속 처리 중
Webhook 후속 작업이 밀림
Queue waiting count 증가

➕ 12-2. 확인 명령어

pm2 list
pm2 logs togethermall-worker --lines 200
docker compose logs -f worker
docker compose logs -f redis

확인할 것:

Worker 프로세스가 online인가?
Redis 연결이 정상인가?
failed Job이 급증했는가?
특정 jobName에서만 실패하는가?
외부 API timeout이 증가했는가?
Worker 배포 후 Unknown job name이 있는가?

➕ 12-3. 복구 방법

Worker down:
Worker 재시작

Redis 연결 실패:
Redis 상태 확인

외부 API 장애:
재시도 간격 조정, 일시 중단 검토

Unknown job name:
Worker/API 버전 호환 확인 후 재배포

대량 적체:
concurrency 조정 또는 Worker 추가 검토

Queue 적체는 고객 화면이 정상이어도 운영 문제가 됩니다.
알림, Export, 외부 연동이 조용히 밀릴 수 있으므로 별도 모니터링이 필요합니다.

✅ 13. ExportJob 장기 PROCESSING Runbook

➕ 13-1. 증상

관리자 엑셀 다운로드가 계속 처리 중
ExportJob.status = PROCESSING
startedAt이 오래됨
S3 fileKey 없음

➕ 13-2. 확인 SQL

SELECT id, status, "startedAt", "updatedAt", "errorMessage"
FROM "ExportJob"
WHERE status = 'PROCESSING'
  AND "startedAt" < NOW() - INTERVAL '30 minutes';

➕ 13-3. 확인할 것

Worker가 실행 중인가?
Export Worker 로그에 에러가 있는가?
DB 조회가 너무 오래 걸리는가?
S3 업로드 실패인가?
메모리 부족으로 Worker가 죽었는가?

➕ 13-4. 복구 방법

1. 해당 ExportJob을 FAILED로 변경
2. errorMessage에 사유 기록
3. 관리자에게 재시도 버튼 제공
4. 대용량 조건이면 기간 제한 안내
5. Worker 메모리/쿼리 최적화

오래된 PROCESSING은 자동으로 감지해서 FAILED 처리하거나 관리자 확인 대상으로 올리는 것이 좋습니다.

✅ 14. Webhook 실패 Runbook

➕ 14-1. 증상

WebhookEvent.status = FAILED
외부 결제/인증/알림 결과가 반영되지 않음
같은 eventId가 반복 수신됨

➕ 14-2. 확인 SQL

SELECT id, provider, "eventId", "eventType", status, "errorMessage", "receivedAt"
FROM "WebhookEvent"
WHERE status = 'FAILED'
ORDER BY "receivedAt" DESC
LIMIT 50;

➕ 14-3. 확인할 것

서명 검증 실패인가?
payload 구조가 변경되었는가?
연관 orderId/consultId가 존재하는가?
상태 전이 불가인가?
중복 이벤트인가?
처리 중 DB 오류가 있었는가?

➕ 14-4. 복구 방법

서명 실패:
Secret/Raw Body 설정 확인

payload 변경:
DTO/normalize 로직 수정

연관 데이터 없음:
외부 ID 매핑 확인

상태 전이 불가:
수동 확인 후 처리 여부 결정

일시적 DB 오류:
재처리 Queue 등록

Webhook은 외부 이벤트이므로 무조건 재처리하면 안 됩니다.
결제/인증/상태 변경과 연결된 경우 현재 상태와 이벤트 순서를 반드시 확인해야 합니다.

✅ 15. 배포 실패 Runbook

➕ 15-1. 증상

배포 직후 API 500 증가
PM2 프로세스 재시작 반복
health check 실패
관리자 화면 오류
Worker Job 실패 증가

➕ 15-2. 확인할 것

최근 배포 커밋
환경변수 추가 여부
migration 성공 여부
build 결과
PM2 logs
Worker logs
프론트/백엔드 API 응답 호환성

➕ 15-3. 복구 기준

핵심 기능 장애:
즉시 이전 버전 롤백

환경변수 누락:
env 추가 후 reload

migration 실패:
DB 상태 확인 후 중단/복구

응답 구조 불일치:
프론트 또는 백엔드 빠른 호환 패치

Worker jobName 오류:
Worker 먼저 호환 배포

➕ 15-4. 롤백 명령 예시

git checkout <previous-release-tag>
npm ci
npm run build
npx prisma migrate deploy
pm2 reload togethermall-api

DB migration이 포함된 배포는 코드 롤백만으로 해결되지 않을 수 있습니다.
migration이 위험한 경우 배포 전부터 롤백 계획을 따로 잡아야 합니다.

✅ 16. 장애 기록 문서

장애가 해결되면 반드시 기록을 남겨야 합니다.
장애 기록은 다음 대응을 빠르게 하고, 재발 방지를 만드는 핵심 자료입니다.

➕ 16-1. 장애 기록 템플릿

## 장애 기록: 2026-07-12 상담 신청 API 500 오류

### 1. 개요
- 발생 시간:
- 복구 시간:
- 장애 등급:
- 영향 범위:

### 2. 증상
- 고객 상담 신청 API에서 500 오류 발생
- 관리자 상담 목록 일부 조회 실패

### 3. 원인
- 최근 배포에서 새 환경변수 누락
- NotificationQueue 초기화 중 오류 발생

### 4. 대응 과정
- 10:05 장애 감지
- 10:08 API 로그 확인
- 10:12 환경변수 누락 확인
- 10:15 운영 env 반영
- 10:17 PM2 reload
- 10:20 상담 신청 정상 확인

### 5. 영향
- 약 15분간 상담 신청 실패 가능
- 실패 요청 8건 확인

### 6. 복구 확인
- /health 정상
- 상담 신청 테스트 정상
- 관리자 목록 정상
- Queue Worker 정상

### 7. 재발 방지
- 배포 전 환경변수 체크리스트 추가
- 서버 시작 시 필수 env validation 적용
- 배포 후 상담 신청 smoke test 추가

중요한 것은 멋진 문서가 아니라, 다음에 같은 일이 생겼을 때 바로 써먹을 수 있는 기록입니다.

✅ 17. Postmortem이란 무엇인가?

Postmortem은 장애가 끝난 뒤 원인과 대응 과정을 돌아보고 재발 방지책을 정리하는 문서입니다.
장애 대응이 “불 끄기”라면, Postmortem은 “왜 불이 났고 다음엔 어떻게 막을지”를 정리하는 작업입니다.

➕ 17-1. Postmortem에 들어갈 내용

무슨 일이 있었는가?
언제 발생했는가?
누가/어떻게 감지했는가?
사용자 영향은 무엇인가?
근본 원인은 무엇인가?
대응 과정은 어땠는가?
잘한 점은 무엇인가?
부족한 점은 무엇인가?
재발 방지 액션은 무엇인가?

➕ 17-2. 좋은 Postmortem 기준

사람 탓보다 시스템 개선에 집중합니다.
추측보다 로그와 시간 기록을 기반으로 합니다.
재발 방지 액션이 구체적이어야 합니다.
담당자와 완료 기준이 있어야 합니다.

나쁜 재발 방지:
다음부터 조심한다

좋은 재발 방지:
필수 환경변수 validation을 추가하고,
GitHub Actions 배포 전 env 체크 스크립트를 실행한다

✅ 18. 재발 방지 액션 설계

장애 기록에서 가장 중요한 부분은 재발 방지입니다.
단순히 “주의”라고 쓰면 아무것도 바뀌지 않습니다.

➕ 18-1. 재발 방지 예시

장애 원인	재발 방지
환경변수 누락	Config validation 추가
DB migration 실패	배포 전 migration dry-run/checklist
Worker down 미감지	Worker health 알림 추가
Queue 적체	waiting count 모니터링
Export 메모리 부족	streaming/chunk 처리
Webhook 중복 처리 오류	eventId unique 제약
상태 이력 누락	상태 변경 트랜잭션 강제
Nginx 502	PM2 health check와 자동 restart

➕ 18-2. 액션 아이템 형식

문제:
환경변수 누락으로 서버 시작 실패

액션:
ConfigService validationSchema에 필수 env 검증 추가

완료 기준:
필수 env가 없으면 서버가 시작되지 않고 명확한 에러 출력

우선순위:
P1

기한:
이번 주 내

재발 방지는 코드, 모니터링, 테스트, 문서, 배포 절차 중 하나로 연결되어야 합니다.

✅ 19. 장애 대응과 커리어 성과

장애 대응 문서화는 단순 운영 기록이 아니라 커리어 자산이 될 수 있습니다.
특히 1인 개발자라면 “개발만 했다”보다 “운영 안정성을 설계했다”가 훨씬 강한 성과입니다.

➕ 19-1. 경력기술서 표현 예시

관리자 상담/주문 시스템 운영 중 발생 가능한 장애 유형을 기준으로
API, DB, Queue, Webhook, Batch Runbook을 정리하고,
장애 발생 시 확인 명령어, 영향 범위, 복구 절차, 재발 방지 항목을 문서화하여
1인 개발 환경에서도 운영 대응 속도와 서비스 안정성을 개선했습니다.

➕ 19-2. 연봉협상 표현 예시

단순 기능 개발을 넘어, 배포/장애/데이터 정합성/외부 API 실패 대응까지
운영 관점의 대응 체계를 구축했습니다.
특히 상담 신청, 알림톡, 엑셀 Export, Webhook, Batch 작업에 대해
장애 원인 추적과 재처리 가능한 구조를 정리해 운영 리스크를 낮췄습니다.

이런 내용은 개발 회사가 아니어도 설득력이 있습니다.
회사 입장에서는 “문제가 생겼을 때 혼자 수습 가능한 사람”이 가치가 큽니다.

✅ 20. 실무 체크리스트

➕ 20-1. 장애 대응 체크리스트

장애 등급 기준이 있는가?
핵심 기능별 장애 영향 범위를 알고 있는가?
API 500/502/504 확인 방법이 정리되어 있는가?
PM2/Docker/Nginx 로그 확인 명령어가 정리되어 있는가?
DB 연결 실패 대응 절차가 있는가?
Queue/Worker 장애 확인 절차가 있는가?
Webhook 실패 재처리 기준이 있는가?
배포 실패 시 롤백 기준이 있는가?

➕ 20-2. Runbook 체크리스트

자주 발생할 수 있는 장애별 Runbook이 있는가?
각 Runbook에 증상, 영향 범위, 확인 순서가 있는가?
확인 명령어가 포함되어 있는가?
복구 방법과 롤백 기준이 있는가?
복구 후 검증 항목이 있는가?
재발 방지 항목이 있는가?
최신 운영 환경과 맞게 유지되는가?
다른 사람이 봐도 따라 할 수 있는가?

➕ 20-3. 장애 기록 체크리스트

발생 시간과 복구 시간이 기록되는가?
장애 등급과 영향 범위가 기록되는가?
실제 원인이 기록되는가?
대응 과정이 시간순으로 기록되는가?
복구 확인 항목이 기록되는가?
실패 요청이나 영향 데이터가 확인되는가?
재발 방지 액션이 구체적인가?
액션 완료 여부를 추적하는가?

✅ 21. AI를 활용해 장애 대응/Runbook을 만들 때 질문법

AI에게 장애 대응을 물어볼 때는 서비스 구조, 실행 방식, 사용하는 인프라, 장애 증상, 로그 일부를 함께 알려줘야 합니다.
단순히 “서버 에러났어”라고 하면 원인을 좁히기 어렵습니다.

➕ 21-1. 좋은 질문 예시

NestJS + Prisma + PostgreSQL + Redis + BullMQ + PM2 + Nginx 구조에서 장애 대응 Runbook을 만들고 싶어.

상황:
1. 백엔드는 EC2에서 PM2로 실행 중
2. Nginx가 api.example.com 요청을 localhost:3000으로 proxy_pass함
3. DB는 AWS RDS PostgreSQL
4. Redis는 Queue와 Rate Limit에 사용함
5. Worker는 알림톡, 엑셀 Export, Webhook 후속 처리를 담당함
6. 주요 기능은 상담 신청, 관리자 상담 목록, 엑셀 다운로드, 알림톡 발송임
7. 장애 유형별로 확인 명령어와 복구 절차를 정리하고 싶음
8. 장애 후 재발 방지 문서까지 남기고 싶음

요청:
- API 502 Runbook
- API 500 급증 Runbook
- DB 연결 실패 Runbook
- Queue 적체 Runbook
- ExportJob 장기 PROCESSING Runbook
- Webhook 실패 Runbook
- 배포 실패 롤백 Runbook
- 장애 기록 템플릿
- 재발 방지 액션 예시
를 실무 기준으로 정리해줘.

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

무작정 서버 재시작만 권하지 않는가?
장애 등급과 영향 범위를 먼저 파악하라고 하는가?
PM2/Nginx/API/DB/Redis/Worker 로그 확인을 나눠서 설명하는가?
최근 배포와 환경변수 변경을 확인하라고 하는가?
Queue/Worker/Webhook/Batch 장애를 일반 API 장애와 구분하는가?
복구 후 검증 항목을 포함하는가?
장애 기록과 Postmortem 템플릿을 제안하는가?
재발 방지를 “조심”이 아니라 구체적 액션으로 정리하는가?

📌 요약

장애 대응은 서비스 문제가 발생했을 때 감지, 영향 범위 파악, 복구, 원인 분석, 재발 방지까지 수행하는 전체 과정입니다.
모든 버그가 장애는 아니며, 고객 신청, 관리자 운영, 결제/주문, 개인정보, 데이터 정합성에 영향을 주는 문제는 장애로 보고 우선 대응해야 합니다.
장애는 P0, P1, P2, P3, Security처럼 등급을 나누면 롤백과 핫픽스 판단이 빨라집니다.
장애 발생 시 바로 코드를 수정하기보다 health check, 로그, 최근 배포, DB/Redis/Worker 상태를 확인해 영향 범위를 먼저 좁혀야 합니다.
Runbook은 특정 장애가 발생했을 때 따라 할 수 있는 절차 문서이며, 증상, 영향 범위, 확인 명령어, 복구 방법, 복구 후 검증, 재발 방지를 포함해야 합니다.
API 500/502, DB 연결 실패, Queue 적체, ExportJob 장기 PROCESSING, Webhook 실패, 배포 실패는 우선적으로 Runbook을 만들어두면 좋습니다.
장애가 해결된 뒤에는 발생 시간, 복구 시간, 원인, 대응 과정, 영향 범위, 재발 방지 액션을 장애 기록으로 남겨야 합니다.
좋은 재발 방지는 “다음부터 조심”이 아니라 Config validation 추가, 모니터링 알림 추가, 상태 전이 검증, unique 제약, 배포 체크리스트 개선처럼 구체적인 시스템 개선으로 연결되어야 합니다.
장애 대응 문서화는 1인 개발자에게 매우 강한 운영 역량 증거가 되며, 연봉협상과 경력기술서에서도 설득력 있는 성과로 활용할 수 있습니다.

juni

이전 포스트

TIL - 20260711

다음 포스트