taxbaik/docs/NGINX_HARNESS.md

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 블록

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: 상대경로 유지

# ✅ 올바름 (슬래시 있음)
proxy_pass http://127.0.0.1:5001/;
# 결과: /admin/login → http://127.0.0.1:5001/admin/login

규칙 2: 경로 변환 (필요시만)

# ✅ 특수 경우: /v1/ → /api/v1/
location /v1/ {
    proxy_pass http://127.0.0.1:5001/api/v1/;
    rewrite ^/v1/(.*)$ /api/v1/$1 break;  # 이중 전달 방지
}

규칙 3: 주의사항

# ❌ 틀림 (슬래시 없음, 경로 이중 전달)
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