taxbaik/DEPLOYMENT_GUIDE.md

# 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`

---

**배포 완료!** 🚀