taxbaik/DEPLOYMENT_GUIDE.md

TaxBaik 경로 최적화 배포 가이드

📋 개요

루트 경로 기준 운영 서버 Nginx 설정을 자동으로 적용합니다.

• 변경 사항: Nginx가 루트(/)를 TaxBaik 웹앱에 프록시하도록 설정
• 영향 범위: Nginx 설정 파일만 수정 (앱 코드 변경 없음)
• 복구 방법: 자동 백업 생성 (롤백 가능)

---

🚀 빠른 배포 (자동화)

Step 1: 스크립트 실행

운영 서버에서:

# 스크립트 다운로드 & 실행
ssh kjh2064@178.104.200.7
cd /home/kjh2064
curl -L https://raw.githubusercontent.com/kjh2064/taxbaik/master/scripts/fix-nginx-taxbaik.sh -o fix-nginx.sh
chmod +x fix-nginx.sh
sudo ./fix-nginx.sh

또는 로컬에서:

# 로컬에서 스크립트 업로드 및 실행
scp scripts/fix-nginx-taxbaik.sh kjh2064@178.104.200.7:/tmp/
ssh kjh2064@178.104.200.7 "sudo /tmp/fix-nginx-taxbaik.sh"

Step 2: 자동 검증

스크립트가 다음을 자동으로 수행합니다:

• ✅ 백업 생성
• ✅ Nginx 설정 수정
• ✅ 문법 검증
• ✅ Nginx 재로드
• ✅ 결과 확인

---

🔧 수동 배포 (필요 시)

Nginx 설정 수정

파일: /etc/nginx/sites-available/taxbaik-domains.conf

변경 전 ❌:

location / {
    proxy_pass         http://127.0.0.1:5001/;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection "Upgrade";
    # ... 나머지 설정
}

변경 후 ✅:

location / {
    proxy_pass         http://127.0.0.1:5001/;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection "Upgrade";
    # ... 나머지 설정
}

적용:

# 1. 백업 생성
sudo cp /etc/nginx/sites-available/taxbaik-domains.conf /etc/nginx/sites-available/taxbaik-domains.conf.backup

# 2. 설정 수정 (위 내용으로 편집)
sudo nano /etc/nginx/sites-available/taxbaik-domains.conf

# 3. 문법 검증
sudo nginx -t

# 4. Nginx 재로드
sudo systemctl reload nginx

---

✅ 배포 후 검증

1. Nginx 설정 확인

# 설정 내용 확인
sudo grep -A 5 "location /" /etc/nginx/sites-available/taxbaik-domains.conf

# 예상 출력:
# location /taxbaik/ {
#     proxy_pass         http://127.0.0.1:5001/;
#     rewrite ^/taxbaik/(.*)$ /$1 break;

2. 웹사이트 접속 확인

# 공개 사이트
curl -I http://www.taxbaik.com/
# 예상: HTTP 200

# 관리자 로그인
curl -I http://www.taxbaik.com/admin/login
# 예상: HTTP 200

3. E2E 테스트

# 로컬에서 운영 서버 테스트
export E2E_BASE_URL="http://www.taxbaik.com"
npx playwright test tests/e2e/admin-smoke.spec.ts tests/e2e/public-smoke.spec.ts

4. 실제 브라우저 확인

• 공개 사이트: http://www.taxbaik.com/
• 로그인 페이지: http://www.taxbaik.com/admin/login
• 로그인 후 대시보드: http://www.taxbaik.com/admin/dashboard
• 메뉴 네비게이션 정상 작동
• API 호출 정상 (네트워크 탭 확인)

---

🔙 롤백 방법

설정 변경 후 문제가 발생하면:

# 자동 스크립트로 수정했을 경우:
# - 백업 파일명: /etc/nginx/sites-available/taxbaik-domains.conf.backup.YYYYMMDD_HHMMSS
sudo cp /etc/nginx/sites-available/taxbaik-domains.conf.backup.YYYYMMDD_HHMMSS /etc/nginx/sites-available/taxbaik-domains.conf

# 또는 수동 설정으로 변경했을 경우:
sudo cp /etc/nginx/sites-available/taxbaik-domains.conf.backup /etc/nginx/sites-available/taxbaik-domains.conf

# Nginx 재로드
sudo systemctl reload nginx

---

📊 기술 상세

왜 이 변경이 필요한가?

1. 코드 변경: PathBase 제거 → 앱이 루트 경로를 인식함
2. 로컬 동작: localhost:5001에서는 /admin/...로 바로 접속
3. 운영 문제: Nginx가 루트(/)를 전달해야 함

해결 원리

요청 경로: /admin/login
    ↓ (proxy_pass)
앱 수신: http://127.0.0.1:5001/admin/login
    ↓ (base href="/admin/")
브라우저 렌더: /admin/...

---

📝 체크리스트

배포 전:

• git push origin master 완료
• CI/CD 빌드 성공
• 운영 서버 배포 완료

배포 후:

• Nginx 설정 변경 완료 (또는 스크립트 실행)
• sudo nginx -t 문법 검증 성공
• sudo systemctl reload nginx 재로드 성공
• 공개 사이트 HTTP 200 확인
• 관리자 로그인 페이지 HTTP 200 확인
• E2E 테스트 통과 (또는 브라우저 수동 테스트)

---

🆘 문제 해결

증상: 404 오류 (Nginx 적용 전)

원인: Nginx가 /taxbaik을 제거하지 않음
해결: 위 "배포" 단계 실행

증상: Nginx 문법 오류

해결:
1. 백업에서 복구
2. 문법 재확인
3. sudo nginx -t 로 검증
4. 스크립트 다시 실행

증상: 재로드 실패

원인: 다른 설정 충돌
해결:
1. sudo systemctl status nginx 로 상태 확인
2. sudo journalctl -u nginx -n 50 로 로그 확인
3. 백업에서 복구
4. 기술팀 연락

---

📞 기술 지원

문제 발생 시:

1. 로그 수집: sudo journalctl -u nginx -n 100 > /tmp/nginx.log
2. Nginx 상태: sudo systemctl status nginx
3. 포트 확인: sudo netstat -tlnp | grep 5001
4. DNS: nslookup www.taxbaik.com 8.8.8.8

---

배포 완료! 🚀