설정 가이드
Nginx Proxy Guard의 환경 변수 및 초기 설정에 대해 안내합니다.
환경 변수 (Environment Variables)
.env 파일에서 사용자가 직접 설정하는 변수는 env.example에 정의된 아래 항목뿐입니다.
나머지 동작값(GeoIP, ACME 등)은 관리 UI에서 관리합니다.
필수 설정
| 변수 | 설명 | 기본값 | 필수 |
|---|---|---|---|
DB_PASSWORD | 데이터베이스 비밀번호 | - | O |
JWT_SECRET | JWT 서명 시크릿 (32자 hex) | - | O |
선택 설정
| 변수 | 설명 | 기본값 |
|---|---|---|
TZ | 타임존 | UTC |
DB_USER | DB 사용자 | postgres |
DB_NAME | DB 이름 | nginx_proxy_guard |
DOCKER_API_VERSION | Docker API 버전 (Synology DSM 등에서 자동 감지 실패 시에만) | 자동 감지 |
env.example에는 이 외에UI_PORT,NGINX_HTTP_PORT,NGINX_HTTPS_PORT,API_HOST_PORT,DNS_RESOLVER등 포트/네트워크 관련 변수가 주석으로 포함되어 있으며, 기본 포트(80/443/81)가 다른 서비스와 충돌할 때만 주석을 해제해 사용합니다.
GeoIP / MaxMind
GeoIP는 환경 변수로 설정하지 않습니다. 관리 UI의 설정 > GeoIP에서
MaxMind 계정 ID와 라이선스 키를 입력하면 system_settings DB 테이블
(maxmind_account_id, maxmind_license_key, geoip_enabled, geoip_auto_update,
geoip_update_interval)에 저장되고, 앱이 GeoIP 데이터베이스를 자동으로 다운로드·갱신합니다.
ACME (Let's Encrypt)
ACME 이메일·스테이징 등은 관리 UI(설정 > SSL/ACME)에서 관리합니다.
데이터베이스 구조
핵심 테이블
| 테이블 | 설명 |
|---|---|
users | 사용자 인증 (TOTP 2FA 포함) |
api_tokens | API 인증 토큰 |
audit_logs | 관리자 활동 감사 로그 |
프록시 설정 테이블
| 테이블 | 설명 |
|---|---|
proxy_hosts | 프록시 호스트 설정 (DDNS 연동 컬럼 ddns_enabled, ddns_provider_id, 도커 컨테이너 컬럼 forward_container_name, forward_container_network 포함) |
certificates | SSL/TLS 인증서 |
dns_providers | DNS Provider 설정 (ACME DNS-01 / DDNS 자격 증명) |
ddns_records | DDNS 관리 레코드 (호스트 연동 또는 수동) |
upstreams | 로드 밸런싱 업스트림 풀 (프록시 호스트별) |
upstream_servers | 업스트림 백엔드 서버 |
access_lists | IP 접근 제어 목록 |
redirect_hosts | URL 리다이렉트 규칙 |
보안 설정 테이블
| 테이블 | 설명 |
|---|---|
rate_limits | Rate Limiting 설정 |
fail2ban_configs | Fail2ban 설정 |
bot_filters | 봇 필터링 설정 |
geo_restrictions | GeoIP 지역 제한 |
waf_rule_exclusions | WAF 규칙 예외 (호스트별) |
global_waf_rule_exclusions | WAF 규칙 예외 (전역) |
banned_ips | 차단된 IP |
ip_ban_history | IP 차단 이력 |
security_headers | 보안 헤더 설정 |
uri_blocks | URI 차단 규칙 |
global_uri_blocks | 전역 URI 차단 |
challenge_configs | CAPTCHA 챌린지 설정 |
challenge_tokens | 챌린지 인증 토큰 |
cloud_provider_blocks | 클라우드 프로바이더 차단 |
filter_subscriptions | 외부 IP/CIDR 차단 목록 구독 |
filter_subscription_entries | 구독에서 동기화된 IP/CIDR 항목 |
filter_subscription_host_exclusions | 구독 적용에서 제외할 호스트 |
filter_subscription_entry_exclusions | 구독에서 제외할 개별 항목 |
로깅 테이블
| 테이블 | 설명 |
|---|---|
logs | 통합 로그 (월별 파티션) |
system_logs | 시스템 로그 (월별 파티션) |
geoip_history | GeoIP 업데이트 이력 |
설정 테이블
| 테이블 | 설명 |
|---|---|
global_settings | 전역 Nginx 설정 |
system_settings | 시스템 설정 (DDNS 새로고침 주기 ddns_check_interval_minutes 포함) |
backups | 백업 메타데이터 |
waf_rule_snapshots | WAF 설정 스냅샷 |
문제 해결 (Troubleshooting)
인증서 발급 실패
- DNS 설정 확인 (도메인이 서버 IP를 가리키는지)
- DNS Provider API 토큰 권한 확인
- Let's Encrypt Rate Limit 확인
- 스테이징 환경(
ACME_STAGING=true)에서 먼저 테스트
# 인증서 로그 확인
docker logs npg-api | grep -i cert
WAF 오탐 (False Positive)
- WAF 테스트 기능으로 어떤 룰이 트리거되는지 확인
- 해당 룰 ID를 호스트별 예외 목록에 추가
- 탐지(Detection) 모드로 변경하여 모니터링 후 차단 모드 적용
GeoIP 작동 안함
- 설정 > GeoIP에서 MaxMind 계정 ID + 라이선스 키 확인
- GeoIP 데이터베이스 존재 확인 (
/etc/nginx/geoip/) - 설정 > GeoIP에서 상태 카드 확인 (Country DB / ASN DB)
- "지금 업데이트" 버튼으로 수동 업데이트 실행
로그 조회가 느림
- 로그 보존 기간 단축 (시스템 설정)
- 필터 범위 축소
- 파티션 상태 확인
# 파티션 확인
docker exec -it npg-db psql -U postgres -d nginx_proxy_guard -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'logs_%';"
백엔드 연결 실패
- 백엔드 서버 상태 확인
- 네트워크 연결 확인
- 방화벽 설정 확인
- Docker 네트워크 확인
# 네트워크 연결 테스트
docker exec -it npg-proxy curl -v http://backend:port
높은 메모리 사용량
- 로그 보관 기간 축소
- 오래된 파티션 정리
- Nginx 워커 프로세스 수 조정
보안 권장 사항
필수 변경 사항
-
기본 비밀번호 변경: 첫 로그인 후 즉시 변경
-
강력한 시크릿 생성:
# DB 비밀번호 openssl rand -base64 24 # JWT 시크릿 openssl rand -hex 32 -
2FA 활성화: TOTP 기반 2단계 인증 설정
네트워크 보안
- 관리 포트(81) 접근 제한
- 내부 네트워크만 DB/Redis 접근 허용
- HTTPS 강제 사용
API 보안
- API 토큰 IP 제한 설정
- 최소 권한 원칙 적용
- 토큰 만료일 설정