147 lines
3.7 KiB
Markdown
147 lines
3.7 KiB
Markdown
# 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`
|