taxbaik/docs/DEPLOYMENT_HARNESS.md

배포 하네스 (Deployment Harness)

📋 개요

Green-Blue 배포 정책에서 배포 버전의 안정성을 보장하는 사전 검증 프로세스.

---

🎯 핵심 원칙

배포 버전에 문제 있음 → 배포 중단 + 자동 롤백
모든 검증 통과 → 배포 진행 + 포트 전환

---

🔍 사전 검증 (Pre-Deployment Validation)

1단계: 빌드 아티팩트 검증

파일 존재 확인:

✓ appsettings.Production.json
✓ TaxBaik.Web.dll
✓ TaxBaik.Proxy.dll
✓ wwwroot/version.json
✓ css/admin.css

실행 권한:

chmod +x deploy_gb.sh

2단계: 배포 환경 검증

필수 환경 변수:

ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://127.0.0.1:${TARGET_PORT}
ConnectionStrings__Default=Host=localhost;Database=taxbaikdb;...
ApiClient__BaseUrl=http://127.0.0.1:${TARGET_PORT}/api/

데이터베이스 연결:

✓ 호스트 접근 가능 (localhost:5432)
✓ 사용자 권한 확인 (taxbaik)
✓ 데이터베이스 존재 (taxbaikdb)
✓ 마이그레이션 최신 상태

3단계: 포트 상태 확인

포트 사용 여부:

Active Port:  5003 또는 5004 (이미 점유)
Target Port: 5004 또는 5003 (배포 대상, 비어있어야 함)

# 검증
netstat -tlnp | grep :${TARGET_PORT}
# 결과: (없음) → ✓ 통과

---

📈 배포 중 헬스 체크

단계별 검증

1. 프로세스 시작

nohup dotnet TaxBaik.Web.dll &
sleep 2
ps -p ${NEW_PID} # 확인

2. 기본 헬스 체크 (최대 20회, 2초 간격)

curl http://127.0.0.1:${TARGET_PORT}/healthz
# 예상: HTTP 200 + "Healthy"

3. API 엔드포인트 검증

curl http://127.0.0.1:${TARGET_PORT}/api/blog?limit=1
# 예상: HTTP 200
# 의미: 데이터베이스 연결 확인

4. 로그 오류 확인

grep -i "fatal\|unhandled exception" web_${TARGET_PORT}.log
# 결과: (없음) → ✓ 통과

---

🚀 포트 전환 (Traffic Switch)

전환 전 최종 검증

Nginx 설정 검증:

sudo nginx -t
# 예상: "syntax is ok" + "test is successful"

프록시 상태:

ss -tlnp | grep :5001
# 예상: TaxBaik.Proxy.dll 실행 중

포트 파일 업데이트:

echo "${TARGET_PORT}" > /home/kjh2064/taxbaik_port
# 프록시가 이 파일을 읽어 트래픽 전환

Nginx 재로드:

sudo systemctl reload nginx

---

❌ 배포 실패 기준

배포 자동 중단 조건

조건	행동	복구
프로세스 시작 실패	즉시 종료	롤백
헬스 체크 20회 실패	즉시 종료	롤백
API 엔드포인트 오류	즉시 종료	롤백
로그에 FATAL 오류	즉시 종료	롤백
Nginx 설정 무효	포트 전환 중단	이전 포트 유지
포트 전환 후 서비스 불가	즉시 롤백	이전 포트로 복구

자동 롤백 프로세스

# 1. 새 프로세스 종료
kill -9 ${NEW_PID}

# 2. 이전 포트 파일 복구
echo "${ACTIVE_PORT}" > /home/kjh2064/taxbaik_port

# 3. Nginx 재로드
sudo systemctl reload nginx

# 4. 실패 알림
send_telegram "❌ 배포 실패: ${REASON}"

# 5. 종료 코드 1
exit 1

---

📊 배포 검증 체크리스트

배포 전:

• 빌드 성공 (0 오류)
• 테스트 성공 (모든 테스트 통과)
• 아티팩트 완전성 (파일 모두 존재)
• 환경 변수 설정 (필수 변수 모두 정의)
• DB 연결 가능

배포 중:

• 프로세스 시작 성공
• 헬스 체크 통과 (20회 이내)
• API 엔드포인트 응답
• 로그 오류 없음 (FATAL/Exception 없음)
• Nginx 설정 유효

포트 전환:

• 이전 Nginx 상태 정상
• 프록시 정상 실행
• 포트 파일 업데이트
• Nginx 재로드 성공
• 트래픽 정상 전환

배포 후:

• 공개 URL 접근 가능 (HTTP 200)
• 관리자 페이지 로드 (HTTP 200)
• E2E 테스트 통과 (1/1 성공)
• 배포 완료 알림 (Telegram)

---

🔄 롤백 절차

수동 롤백

상황: 배포 후 심각한 오류 발생

# 1. 이전 포트 확인
cat /home/kjh2064/taxbaik_port
# 결과: 5004 (새 포트)

# 2. 이전 포트로 복구
echo "5003" > /home/kjh2064/taxbaik_port

# 3. Nginx 재로드
sudo systemctl reload nginx

# 4. 확인
curl https://www.taxbaik.com/
# 예상: 이전 버전의 응답

배포 디렉토리 복구

상황: 배포 파일 손상

# 1. 최근 배포 목록
ls -ldt /home/kjh2064/deployments/taxbaik_*

# 2. 이전 배포 선택
PREVIOUS_DEPLOY="/home/kjh2064/deployments/taxbaik_20260708_170000"

# 3. 수동 배포 (deploy_gb.sh 다시 실행)
bash deploy_gb.sh $PREVIOUS_DEPLOY

---

📞 배포 실패 진단

로그 확인 순서

1단계: 앱 로그

tail -100 /home/kjh2064/deployments/taxbaik_*/web_500*.log
# 찾기: ERROR, FATAL, Exception, connection refused

2단계: 프록시 로그

tail -100 /home/kjh2064/taxbaik_proxy.log
# 찾기: 5001 포트 문제, 포트 파일 읽기 실패

3단계: Nginx 로그

sudo tail -100 /var/log/nginx/error.log
# 찾기: upstream connect failed, configuration error

4단계: 시스템 로그

sudo journalctl -u nginx -n 50
sudo dmesg | tail -20

---

✅ 성공 기준

모든 헬스 체크 통과
  ↓
포트 전환 성공
  ↓
E2E 테스트 1/1 통과
  ↓
배포 완료 알림 발송
  ↓
✅ 배포 성공

---

참고

• 배포 스크립트: /deploy_gb.sh
• 검증 스크립트: /scripts/validate-deploy.sh
• Nginx 설정: /docs/NGINX_HARNESS.md
• CI/CD: .gitea/workflows/deploy.yml