diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..5bb41f3 --- /dev/null +++ b/DEPLOYMENT_GUIDE.md @@ -0,0 +1,240 @@ +# TaxBaik 경로 최적화 배포 가이드 + +## 📋 개요 + +**상대 경로 최적화** 이후 운영 서버 Nginx 설정을 자동으로 수정합니다. + +- **변경 사항**: `/taxbaik` 프리픽스를 Nginx에서 제거하도록 설정 +- **영향 범위**: Nginx 설정 파일만 수정 (앱 코드 변경 없음) +- **복구 방법**: 자동 백업 생성 (롤백 가능) + +--- + +## 🚀 빠른 배포 (자동화) + +### Step 1: 스크립트 실행 + +운영 서버에서: + +```bash +# 스크립트 다운로드 & 실행 +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 +``` + +또는 로컬에서: + +```bash +# 로컬에서 스크립트 업로드 및 실행 +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` + +**변경 전** ❌: +```nginx +location /taxbaik { + proxy_pass http://127.0.0.1:5001; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + # ... 나머지 설정 +} +``` + +**변경 후** ✅: +```nginx +location /taxbaik/ { + proxy_pass http://127.0.0.1:5001/; + rewrite ^/taxbaik/(.*)$ /$1 break; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + # ... 나머지 설정 +} +``` + +**적용**: +```bash +# 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 설정 확인 + +```bash +# 설정 내용 확인 +sudo grep -A 5 "location /taxbaik" /etc/nginx/sites-available/taxbaik-domains.conf + +# 예상 출력: +# location /taxbaik/ { +# proxy_pass http://127.0.0.1:5001/; +# rewrite ^/taxbaik/(.*)$ /$1 break; +``` + +### 2. 웹사이트 접속 확인 + +```bash +# 공개 사이트 +curl -I http://www.taxbaik.com/taxbaik/ +# 예상: HTTP 200 + +# 관리자 로그인 +curl -I http://www.taxbaik.com/taxbaik/admin/login +# 예상: HTTP 200 +``` + +### 3. E2E 테스트 + +```bash +# 로컬에서 운영 서버 테스트 +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/taxbaik/ +- [ ] 로그인 페이지: http://www.taxbaik.com/taxbaik/admin/login +- [ ] 로그인 후 대시보드: http://www.taxbaik.com/taxbaik/admin/dashboard +- [ ] 메뉴 네비게이션 정상 작동 +- [ ] API 호출 정상 (네트워크 탭 확인) + +--- + +## 🔙 롤백 방법 + +설정 변경 후 문제가 발생하면: + +```bash +# 자동 스크립트로 수정했을 경우: +# - 백업 파일명: /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 제거 → 앱이 `/taxbaik` 경로를 인식하지 않음 +2. **로컬 동작**: localhost:5001에서는 `/admin/...`로 바로 접속 +3. **운영 문제**: Nginx가 `/taxbaik` 프리픽스를 전달 → 경로 충돌 + +### 해결 원리 + +``` +요청 경로: /taxbaik/admin/login + ↓ (rewrite 규칙) +변환: /admin/login + ↓ (proxy_pass) +앱 수신: http://127.0.0.1:5001/admin/login + ↓ (base href="/taxbaik/admin/") +브라우저 렌더: /taxbaik/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` + +--- + +**배포 완료!** 🚀 diff --git a/scripts/fix-nginx-taxbaik.sh b/scripts/fix-nginx-taxbaik.sh new file mode 100644 index 0000000..1293812 --- /dev/null +++ b/scripts/fix-nginx-taxbaik.sh @@ -0,0 +1,160 @@ +#!/bin/bash +# TaxBaik Nginx 설정 자동 수정 스크립트 +# 경로 최적화 이후 Nginx에서 /taxbaik 프리픽스를 제거하도록 설정 + +set -e + +echo "🚀 TaxBaik Nginx 설정 수정" +echo "==============================" +echo "" + +# 색상 정의 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# 1. Nginx 설정 파일 찾기 +echo "📍 Nginx 설정 파일 찾기..." + +if [ ! -f "/etc/nginx/sites-available/taxbaik-domains.conf" ]; then + echo -e "${RED}❌ 파일 없음: /etc/nginx/sites-available/taxbaik-domains.conf${NC}" + exit 1 +fi + +NGINX_FILE="/etc/nginx/sites-available/taxbaik-domains.conf" +echo -e "${GREEN}✅ 파일 발견: $NGINX_FILE${NC}" +echo "" + +# 2. 백업 생성 +echo "💾 백업 생성..." +BACKUP_FILE="${NGINX_FILE}.backup.$(date +%Y%m%d_%H%M%S)" +cp "$NGINX_FILE" "$BACKUP_FILE" +echo -e "${GREEN}✅ 백업: $BACKUP_FILE${NC}" +echo "" + +# 3. 현재 설정 확인 +echo "📋 현재 설정 확인..." +echo -e "${BLUE}" +grep -A 10 "location /taxbaik" "$NGINX_FILE" | head -15 +echo -e "${NC}" +echo "" + +# 4. 설정 수정 +echo "🔧 설정 수정 중..." + +# 임시 파일 생성 +TEMP_FILE="${NGINX_FILE}.tmp" + +# sed를 사용하여 설정 수정 +sed -e '/location \/taxbaik {/,/^[[:space:]]*}[[:space:]]*$/{ + /location \/taxbaik {/c\ + location /taxbaik/ { + /proxy_pass[[:space:]]*http:\/\/127.0.0.1:5001;/c\ + proxy_pass http://127.0.0.1:5001/; + /proxy_pass[[:space:]]*http:\/\/127.0.0.1:5001;/a\ + rewrite ^/taxbaik/(.*)$ /$1 break; +}' "$NGINX_FILE" > "$TEMP_FILE" + +# 수정된 설정 확인 +if grep -q "rewrite ^/taxbaik/" "$TEMP_FILE"; then + mv "$TEMP_FILE" "$NGINX_FILE" + echo -e "${GREEN}✅ 설정 수정 완료${NC}" +else + echo -e "${YELLOW}⚠️ 수정 실패, 다른 방법 시도 중...${NC}" + rm "$TEMP_FILE" + + # 수동 수정 (더 신뢰할 수 있는 방법) + python3 << 'PYTHON_SCRIPT' +import re + +nginx_file = "/etc/nginx/sites-available/taxbaik-domains.conf" + +with open(nginx_file, 'r') as f: + content = f.read() + +# location /taxbaik { 을 location /taxbaik/ { 로 변경 +content = content.replace('location /taxbaik {', 'location /taxbaik/ {') + +# proxy_pass http://127.0.0.1:5001; 을 찾아서 수정 +pattern = r'(location /taxbaik/ \{.*?)(proxy_pass\s+http://127\.0\.0\.1:5001;)' +replacement = r'\1proxy_pass http://127.0.0.1:5001/;' +content = re.sub(pattern, replacement, content, flags=re.DOTALL) + +# rewrite 규칙 추가 (이미 있으면 스킵) +if 'rewrite ^/taxbaik/' not in content: + pattern = r'(location /taxbaik/ \{.*?proxy_pass.*?;)' + replacement = r'\1\n rewrite ^/taxbaik/(.*)$ /$1 break;' + content = re.sub(pattern, replacement, content, flags=re.DOTALL) + +with open(nginx_file, 'w') as f: + f.write(content) + +print("✅ Python을 통한 수정 완료") +PYTHON_SCRIPT + +fi + +echo "" + +# 5. 수정 결과 확인 +echo "📋 수정된 설정 확인..." +echo -e "${BLUE}" +grep -A 10 "location /taxbaik" "$NGINX_FILE" | head -15 +echo -e "${NC}" +echo "" + +# 6. Nginx 문법 검증 +echo "🔍 Nginx 문법 검증..." +if nginx -t 2>&1 | grep -q "successful"; then + echo -e "${GREEN}✅ 문법 검증 성공${NC}" + SYNTAX_OK=1 +else + echo -e "${RED}❌ 문법 오류 발생${NC}" + echo "오류 내용:" + nginx -t + SYNTAX_OK=0 +fi + +echo "" + +# 7. Nginx 재시작 또는 롤백 +if [ $SYNTAX_OK -eq 1 ]; then + echo "🔄 Nginx 재로드..." + if systemctl reload nginx 2>&1; then + echo -e "${GREEN}✅ Nginx 재로드 성공${NC}" + else + echo -e "${YELLOW}⚠️ Nginx 재로드 실패, 설정 롤백...${NC}" + cp "$BACKUP_FILE" "$NGINX_FILE" + systemctl reload nginx + echo -e "${RED}❌ 롤백 완료${NC}" + exit 1 + fi +else + echo -e "${RED}❌ 문법 오류로 인해 설정 롤백${NC}" + cp "$BACKUP_FILE" "$NGINX_FILE" + exit 1 +fi + +echo "" + +# 8. 최종 확인 +echo "🧪 최종 확인..." +echo "" +echo -e "${BLUE}=== 설정 확인 ===${NC}" +grep -A 5 "location /taxbaik" "$NGINX_FILE" | head -8 +echo "" +echo -e "${GREEN}✅ 설정 수정 완료!${NC}" +echo "" +echo "📝 변경 사항:" +echo " 1. location /taxbaik → location /taxbaik/ (슬래시 추가)" +echo " 2. proxy_pass http://127.0.0.1:5001; → proxy_pass http://127.0.0.1:5001/; (슬래시 추가)" +echo " 3. rewrite 규칙 추가: ^/taxbaik/(.*)$ /$1 break" +echo "" +echo "🔙 백업 파일: $BACKUP_FILE" +echo "" +echo "✨ 배포 다음 단계:" +echo " 1. E2E 테스트 실행: npx playwright test" +echo " 2. 공개 사이트 확인: http://www.taxbaik.com/taxbaik/" +echo " 3. 관리자 페이지 확인: http://www.taxbaik.com/taxbaik/admin/"