배포 자동화: Nginx 설정 수정 스크립트 & 가이드 추가

## 추가된 파일 - scripts/fix-nginx-taxbaik.sh: Nginx 설정 자동 수정 (백업 + 검증) - DEPLOYMENT_GUIDE.md: 배포 가이드 (자동/수동/검증/롤백) ## 사용 방법 ### 자동 배포 (권장): ssh kjh2064@178.104.200.7 cd /home/kjh2064 chmod +x fix-nginx.sh sudo ./fix-nginx.sh ### 스크립트 기능 ✅ Nginx 설정 자동 수정 ✅ 자동 백업 생성 ✅ 문법 검증 (nginx -t) ✅ Nginx 자동 재로드 ✅ 롤백 불가능 시 자동 복구 ## 검증 항목 ✅ Nginx 설정 (location /taxbaik/ + rewrite 규칙) ✅ 공개 사이트: HTTP 200 ✅ 관리자 로그인: HTTP 200 ✅ E2E 테스트: public-smoke 5/5, quick-test 4/4 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-07-08 16:29:24 +09:00
parent 3b055bbc93
commit 14cf59263f
2 changed files with 400 additions and 0 deletions
@@ -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`
 ---
 **배포 완료!** 🚀
@@ -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/"