프록시 호스트 관리 (Proxy Host Management)

Nginx Proxy Guard의 핵심 기능인 프록시 호스트 관리 기능을 상세히 설명합니다.

기본 기능

다중 도메인 지원

• SNI 지원: 하나의 호스트에 여러 도메인 연결
• 와일드카드: *.example.com 형식 지원
• 서브도메인: 독립적인 서브도메인 설정

포워딩 설정

WebSocket 지원

실시간 양방향 통신을 위한 WebSocket 업그레이드를 완벽하게 지원합니다.

• 자동 Connection Upgrade
• 커스텀 헤더 전달
• 타임아웃 설정

캐싱

정적 리소스에 대한 캐싱 설정을 지원합니다.

• 캐시 활성화/비활성화
• 캐시 유효 기간 설정
• 캐시 키 커스터마이징

DDNS 자동 등록

Basic 탭에서 DDNS 자동 등록을 켜면 NPG가 호스트의 DNS A 레코드를 서버의 현재 공인 IP로 유지합니다 — 동적 IP를 사용하는 가정용 회선에 유용합니다.

• Basic 탭 토글: DDNS를 켜고 DNS Provider를 선택합니다.
• 지원 Provider: Cloudflare, DuckDNS, Dynu. (A 레코드를 프로그램으로 갱신할 수 있는 Provider만 해당하며, Route53/Manual Provider는 DDNS용으로 선택할 수 없습니다.)
• Provider 재사용: DDNS Provider 목록은 인증서 메뉴에서 이미 구성한 DNS Provider에서 가져오므로, 기존 Cloudflare/DuckDNS/Dynu Provider를 재사용할 수 있습니다.

TCP/UDP 스트림 (Layer 4)

HTTP/HTTPS 가상 호스트 외에도, NPG는 TCP/UDP 스트림(Layer 4) 리버스 프록시를 지원합니다. 호스트 추가 시 프록시 모드로 TCP / UDP Stream을 선택하면 됩니다.

사용 사례

• 데이터베이스 (PostgreSQL, MySQL 등)
• 게임 서버
• SSH
• 기타 커스텀 TCP/UDP 서비스

스트림 TLS 종료

스트림 호스트도 인증서를 선택하여 **TLS 종료(SNI 기반)**를 수행할 수 있습니다. NPG가 TLS를 처리하고 백엔드로는 평문으로 전달합니다.

보안 적용 범위 (중요)

스트림은 L4에서 동작하므로 HTTP 계층 보호 기능은 적용되지 않습니다. 다음 기능은 모두 HTTP 전용입니다:

참고: 스트림 리스너에 대한 fail2ban과 GeoIP는 후속 작업으로 추적 중이며 아직 적용되지 않았습니다. IP 기반 차단(banned IPs)만 L4에서 동작하여 자동으로 주입됩니다.

고급 설정

커스텀 Location 블록

Nginx location 블록을 직접 추가하여 세밀한 설정이 가능합니다.

# 특정 경로에 대한 설정
location /api/ {
    proxy_pass http://api-server:8080;
    proxy_read_timeout 300s;
}

# 정적 파일 처리
location /static/ {
    alias /var/www/static/;
    expires 30d;
}

Advanced Configuration

Nginx 설정을 직접 편집할 수 있습니다.

주의: 보안을 위해 다음 지시어는 차단됩니다:

• load_module - 외부 모듈 로드
• lua_*, perl_*, js_* - 스크립트 실행
• 쉘 명령어가 포함된 proxy_pass

설정 예시

# 요청 타임아웃 설정
proxy_connect_timeout 60s;
proxy_read_timeout 120s;
proxy_send_timeout 60s;

# 버퍼 설정
proxy_buffer_size 128k;
proxy_buffers 4 256k;

# 헤더 설정
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Docker 컨테이너 탐색

Docker 환경에서 프록시 대상 서버를 쉽게 선택할 수 있습니다.

자동 탐색

• 실행 중인 Docker 컨테이너 자동 탐색
• 컨테이너 이름, 이미지, 네트워크 정보 표시
• NPG 자체 컨테이너(npg-*)는 자동 제외
• 컨테이너의 IP 주소와 포트를 클릭하여 자동 입력

컨테이너 정보

컨테이너 이름으로 포워딩

고정 IP 대신 Docker 컨테이너 이름을 포워딩 대상으로 지정할 수 있습니다. NPG가 컨테이너 이름을 현재 IP로 자동 변환하므로, 컨테이너 재시작으로 IP가 바뀌어도 직접 수정할 필요가 없습니다.

• 컨테이너 선택: 프록시 호스트 폼의 컨테이너 선택기에서 대상 컨테이너를 고르면 이름이 포워딩 대상으로 저장됩니다.
• 자동 IP 변환: 저장 시 컨테이너의 현재 IP로 변환되어 Nginx 설정에 반영됩니다.
• 자동 갱신(재변환): 백그라운드 스케줄러가 주기적으로(기본 30초) 컨테이너 IP를 재확인하고, IP가 변경된 경우에만 설정을 재생성합니다. 변환에 실패하면 마지막으로 정상 동작하던 설정을 그대로 유지합니다(Fail-Safe).
• 네트워크 선택: 컨테이너가 여러 Docker 네트워크에 연결된 경우, 어떤 네트워크의 IP로 변환할지 선택할 수 있습니다. 선택한 네트워크 정보가 컨테이너 이름과 함께 저장되어 항상 올바른 네트워크의 IP로 변환됩니다.

참고: 백그라운드 재변환은 환경 변수 NPG_CONTAINER_RECONCILE_DISABLED=true로 끌 수 있습니다.

호스트 복제 (Clone)

기존 프록시 호스트를 복제하여 새로운 호스트를 빠르게 생성할 수 있습니다.

복제 기능

• 원본의 모든 설정 복제: WAF, 봇 필터, GeoIP, Rate Limiting, 캐싱, 고급 설정 등
• 새 도메인 지정: 복제 시 새로운 도메인 이름 입력
• 포워딩 오버라이드: 대상 서버 주소/포트 변경 가능
• 인증서 선택: 기존 인증서 사용, Let's Encrypt 새 발급, 자체 서명 중 선택

복제 시 설정 가능한 옵션

Upstream 로드 밸런싱

하나의 프록시 호스트에 다중 백엔드 서버를 구성하여 로드 밸런싱과 고가용성을 제공합니다.

로드 밸런싱 방식

Upstream 서버 설정

헬스 체크

백엔드 서버의 상태를 주기적으로 확인하여 장애 서버를 자동으로 제외합니다.

Keepalive

• Keepalive 연결 수: Upstream 서버와의 유휴 연결 수 설정
• 연결 재사용으로 성능 향상
• 기본값: 32개 연결

호스트 관리

즐겨찾기 / 고정

자주 관리하는 호스트를 목록 상단에 고정할 수 있습니다.

• 별표 클릭으로 즐겨찾기 토글
• 즐겨찾기 호스트는 목록 최상단에 표시
• 정렬 상태와 무관하게 항상 상단 유지

활성화/비활성화

호스트를 삭제하지 않고 일시적으로 비활성화할 수 있습니다.

• 비활성화 시 해당 호스트로의 트래픽 차단
• 설정 보존
• 빠른 활성화/비활성화 전환

설정 동기화

모든 프록시 호스트의 Nginx 설정을 동기화합니다.

• 설정 변경 후 일괄 적용
• 불일치 설정 수정
• Nginx 재시작 없이 적용

호스트 테스트

프록시 설정이 올바르게 동작하는지 테스트합니다.

• 백엔드 연결 확인
• SSL/TLS 설정 검증
• 응답 상태 확인

보안 설정 통합

각 프록시 호스트별로 독립적인 보안 설정을 적용할 수 있습니다.

호스트별 보안 기능

SSL/TLS 설정

인증서 연결

• Let's Encrypt 인증서 자동 연결
• 커스텀 인증서 업로드
• 자체 서명 인증서 생성

Force HTTPS

HTTP 요청을 HTTPS로 자동 리다이렉트합니다.

HTTP/2 & HTTP/3

• HTTP/2 기본 활성화
• HTTP/3 (QUIC) 지원
• ALPN 프로토콜 협상

모범 사례

새 호스트 생성 시

1. 기본 프록시 설정 구성
2. SSL 인증서 발급/연결
3. 보안 설정 (WAF, 봇 필터 등) 적용
4. 테스트 후 활성화

문제 해결

• 502 Bad Gateway: 백엔드 서버 연결 확인
• 504 Gateway Timeout: 타임아웃 설정 증가
• SSL 오류: 인증서 유효성 및 설정 확인