taxbaik/docs/NGINX_HARNESS.md

Nginx 하네스 (Nginx Configuration Harness)

📋 개요

상대경로 기반 Nginx 설정으로 PathBase 제거 후 경로를 올바르게 매핑하는 하네스.

---

🎯 핵심 원칙

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

# 1. TaxBaik (HTTPS 443)
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;
    }
}

# 2. HTTP → HTTPS 리다이렉트
server {
    listen 80;
    server_name taxbaik.com www.taxbaik.com;
    return 301 https://$host$request_uri;
}

# 3. Gitea (선택사항, SSL 없으면 HTTP만)
server {
    server_name gitea.taxbaik.com;
    listen 80;  # SSL 인증서 없으면 HTTP만
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        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/;
# 결과: /taxbaik/admin/login → http://127.0.0.1:5001/taxbaik/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 / {
    # 1. HTTP 버전 업그레이드 (HTTP/1.1로 유지)
    proxy_http_version 1.1;
    
    # 2. WebSocket 지원 (Blazor SignalR)
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    
    # 3. 호스트 정보
    proxy_set_header Host $host;
    
    # 4. 클라이언트 IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    # 5. 프로토콜 (HTTP vs HTTPS)
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 6. 캐시 바이패스
    proxy_cache_bypass $http_upgrade;
    
    # 7. 타임아웃 (길게)
    proxy_read_timeout 120s;
}

---

🔒 SSL/TLS 설정

Let's Encrypt 인증서

server {
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/taxbaik.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/taxbaik.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

보안 헤더

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;

---

⚡ Green-Blue 배포와 Nginx

포트 전환 원리

Nginx (고정)
    ↓
/etc/nginx/sites-available/taxbaik-domains.conf
    ↓
proxy_pass http://127.0.0.1:5001/;  (절대 변경하지 말 것!)
    ↓
TaxBaik.Proxy (포트 5001)
    ↓
/home/kjh2064/taxbaik_port 파일 읽기
    ↓
Active Port: 5003 또는 5004
    ↓
실제 앱 (http://127.0.0.1:5003 또는 5004)

중요: Nginx는 수정하지 않음

# ❌ 절대 하지 말 것: Nginx 설정에 5003/5004 하드코딩
# 이렇게 하면 포트 전환이 작동하지 않음
proxy_pass http://127.0.0.1:5003/;  # 위험!

# ✅ 올바름: 프록시 포트 고정
proxy_pass http://127.0.0.1:5001/;  # 프록시가 실제 포트로 포워딩

---

🔍 검증 체크리스트

설정 적용 전

• 백업 생성: sudo cp /etc/nginx/sites-available/taxbaik-domains.conf ...backup
• 편집기로 수정: sudo nano /etc/nginx/sites-available/taxbaik-domains.conf
• 문법 검증: sudo nginx -t
  • 예상: "syntax is ok" + "test is successful"

설정 적용 후

• Nginx 재로드: sudo systemctl reload nginx
• 상태 확인: sudo systemctl status nginx
  • 예상: "active (running)"

실제 동작 확인

# 1. HTTP → HTTPS 리다이렉트 확인
curl -I http://www.taxbaik.com/
# 예상: HTTP 301 + Location: https://

# 2. HTTPS 접근 확인
curl -I https://www.taxbaik.com/
# 예상: HTTP/2 200

# 3. 로컬호스트 경유 확인
curl -H "Host: www.taxbaik.com" http://127.0.0.1/
# 예상: HTML 응답 (프록시 정상)

# 4. API 엔드포인트 확인
curl https://www.taxbaik.com/api/blog?limit=1
# 예상: JSON 응답

---

📋 설정 변경 이력

날짜	변경 사항	이유
2026-07-08	PathBase 제거 후 상대경로로 통일	경로 정규화
2026-07-08	proxy_pass 슬래시 명시	이중 슬래시 방지
2026-07-08	프록시 포트 5001 고정	Green-Blue 배포 대응

---

🆘 문제 해결

문제 1: 404 응답

증상:

curl https://www.taxbaik.com/
# 결과: HTTP 404

진단:

# 1. Nginx가 올바른 백엔드 포트로 프록싱하는지 확인
curl -H "Host: www.taxbaik.com" http://127.0.0.1/
# 같은 404? → 백엔드 문제
# 다른 응답? → Nginx 설정 문제

# 2. 포트 5001 확인
ss -tlnp | grep :5001
# 없음? → TaxBaik.Proxy 실행 안 함

# 3. 활성 포트 확인
cat /home/kjh2064/taxbaik_port
# 예상: 5003 또는 5004

문제 2: 502 Bad Gateway

증상:

Nginx가 백엔드에 연결 불가

진단:

# 1. Nginx 로그 확인
sudo tail -50 /var/log/nginx/error.log
# 찾기: "upstream connect failed"

# 2. 프록시 로그 확인
tail -50 /home/kjh2064/taxbaik_proxy.log

# 3. 앱 포트 확인
ss -tlnp | grep :{5003,5004}
# 없음? → 앱 실행 안 함

문제 3: SSL 인증서 오류

증상:

NET::ERR_CERT_AUTHORITY_INVALID

진단:

# 1. 인증서 경로 확인
sudo ls -la /etc/letsencrypt/live/taxbaik.com/
# 파일 존재? → OK
# 없음? → certbot으로 새 인증서 생성

# 2. 인증서 유효 기간
sudo openssl x509 -in /etc/letsencrypt/live/taxbaik.com/fullchain.pem -noout -dates

# 3. Nginx 설정에서 경로 확인
sudo grep "ssl_certificate" /etc/nginx/sites-available/taxbaik-domains.conf

---

📞 참고

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