# Nginx 하네스 (Nginx Configuration Harness)

## 📋 개요

**root `/`와 `/admin` 경로를 검증하는 Nginx 하네스**.

---

## 🎯 핵심 원칙

```
공개 URL:  https://www.taxbaik.com/
백엔드:   http://127.0.0.1:5001/
Nginx:    경로 변환 없음
```

---

## 📍 설정 파일 위치

```
/etc/nginx/sites-available/taxbaik-domains.conf
/etc/nginx/sites-enabled/taxbaik-domains.conf (심볼릭 링크)
```

---

## 🔧 설정 구조

### 필수 server 블록

```nginx
server {
    server_name taxbaik.com www.taxbaik.com;
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/taxbaik.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/taxbaik.com/privkey.pem;

    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";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

---

## 📊 포트 매핑 규칙

| 도메인 | 포트 | 프로토콜 | 백엔드 포트 | 상태 |
|--------|------|---------|-----------|------|
| **taxbaik.com** | 443 (HTTPS) | TLS 1.3 | 5001 (프록시) | ✅ 활성 |
| **taxbaik.com** | 80 (HTTP) | - | - | 301 리다이렉트 |
| **www.taxbaik.com** | 443 (HTTPS) | TLS 1.3 | 5001 (프록시) | ✅ 활성 |
| **www.taxbaik.com** | 80 (HTTP) | - | - | 301 리다이렉트 |
| **gitea.taxbaik.com** | 80 (HTTP) | HTTP | 3000 | ✅ 활성 |

---

## 🚀 프록시 설정 (Proxy Configuration)

### proxy_pass 규칙

**규칙 1: 상대경로 유지**
```nginx
# ✅ 올바름 (슬래시 있음)
proxy_pass http://127.0.0.1:5001/;
# 결과: /admin/login → http://127.0.0.1:5001/admin/login
```

**규칙 2: 경로 변환 (필요시만)**
```nginx
# ✅ 특수 경우: /v1/ → /api/v1/
location /v1/ {
    proxy_pass http://127.0.0.1:5001/api/v1/;
    rewrite ^/v1/(.*)$ /api/v1/$1 break;  # 이중 전달 방지
}
```

**규칙 3: 주의사항**
```nginx
# ❌ 틀림 (슬래시 없음, 경로 이중 전달)
proxy_pass http://127.0.0.1:5001;
# 결과: /admin → http://127.0.0.1:5001 + /admin → 이중 슬래시 가능

# ❌ 틀림 (rewrite 없이 proxy_pass만)
location /api {
    proxy_pass http://127.0.0.1:5001/api/;
}
# 결과: /api/users → http://127.0.0.1:5001/api//users (이중 슬래시)
```

### 필수 헤더

`location /`에는 `proxy_http_version 1.1`, `Upgrade`, `Connection`, `Host`, `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`를 유지한다.

---

## 🔒 SSL/TLS 설정

### Let's Encrypt 인증서

`/etc/letsencrypt/live/taxbaik.com/fullchain.pem`과 `privkey.pem`을 사용한다.

### 보안 헤더

`HSTS`, `nosniff`, `SAMEORIGIN`은 유지한다.

---

## ⚡ Green-Blue 배포와 Nginx

### 포트 전환 원리

Nginx는 `5001` 프록시에만 연결하고, 프록시가 `~/taxbaik_port`를 읽어 `5003/5004` 중 활성 포트로 보낸다. Nginx에 `5003/5004`를 직접 하드코딩하지 않는다.

---

## 🔍 검증 체크리스트

- `sudo nginx -t` 후 `sudo systemctl reload nginx`
- `http://www.taxbaik.com/`은 301, `https://www.taxbaik.com/`은 200
- `curl -H "Host: www.taxbaik.com" http://127.0.0.1/`은 HTML 응답
- `https://www.taxbaik.com/api/blog?limit=1`은 JSON 응답

---

## 🆘 문제 해결

- 404: `http://127.0.0.1/` 응답, `:5001` 프록시, `taxbaik_port` 값 확인
- 502: Nginx 에러 로그, 프록시 로그, `5003/5004` 앱 포트 확인
- SSL 오류: `letsencrypt` 인증서 경로와 만료일 확인

---

## 📞 참고

- **배포 하네스**: `/docs/DEPLOYMENT_HARNESS.md`
- **빌드 검증**: `/docs/BUILD_VALIDATION_HARNESS.md`
- **배포 스크립트**: `/deploy_gb.sh`