Nginx Proxy Guard의 환경 변수 및 초기 설정에 대해 안내합니다.
환경 변수 (Environment Variables)
.env 파일을 통해 시스템의 주요 설정을 변경할 수 있습니다.
필수 설정
| 변수 | 설명 | 기본값 | 필수 |
|---|
DB_PASSWORD | 데이터베이스 비밀번호 | - | O |
JWT_SECRET | JWT 서명 시크릿 (32자 hex) | - | O |
데이터베이스 설정
| 변수 | 설명 | 기본값 |
|---|
DB_USER | DB 사용자 | postgres |
DB_NAME | DB 이름 | nginx_proxy_guard |
DB_HOST | DB 호스트 | db |
DB_PORT | DB 포트 | 5432 |
GeoIP 설정
| 변수 | 설명 | 기본값 |
|---|
MAXMIND_LICENSE_KEY | MaxMind 라이선스 키 | - |
MAXMIND_ACCOUNT_ID | MaxMind 계정 ID | - |
ACME (Let's Encrypt) 설정
| 변수 | 설명 | 기본값 |
|---|
ACME_EMAIL | Let's Encrypt 이메일 | - |
ACME_STAGING | 스테이징 모드 | false |
시스템 설정
| 변수 | 설명 | 기본값 |
|---|
ENVIRONMENT | 환경 (production/development) | production |
TZ | 타임존 | UTC |
CORS_ALLOWED_ORIGINS | CORS 허용 출처 | https://localhost:81 |
Rate Limiting 설정
| 변수 | 설명 | 기본값 |
|---|
RATE_LIMIT_ENABLED | Rate Limiting 활성화 | true |
RATE_LIMIT_RPS | 초당 요청 수 | 100.0 |
로깅 설정
| 변수 | 설명 | 기본값 |
|---|
LOG_COLLECTION | 로그 수집 활성화 | true |
ENABLE_DOCKER_LOGS | Docker 로그 수집 | true |
Nginx 연동 설정
| 변수 | 설명 | 기본값 |
|---|
NGINX_CONTAINER | Nginx 컨테이너 이름 | npg-proxy |
NGINX_STATUS_URL | Nginx 상태 URL | http://nginx:8080/nginx_status |
NGINX_ACCESS_LOG | 액세스 로그 경로 | /var/log/nginx/access.log |
백업 설정
| 변수 | 설명 | 기본값 |
|---|
BACKUP_PATH | 백업 저장 경로 | /app/data/backups |
데이터베이스 구조
핵심 테이블
| 테이블 | 설명 |
|---|
users | 사용자 인증 (TOTP 2FA 포함) |
api_tokens | API 인증 토큰 |
audit_logs | 관리자 활동 감사 로그 |
프록시 설정 테이블
| 테이블 | 설명 |
|---|
proxy_hosts | 프록시 호스트 설정 |
certificates | SSL/TLS 인증서 |
dns_providers | DNS Provider 설정 |
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 | 클라우드 프로바이더 차단 |
로깅 테이블
| 테이블 | 설명 |
|---|
logs | 통합 로그 (월별 파티션) |
system_logs | 시스템 로그 (월별 파티션) |
geoip_history | GeoIP 업데이트 이력 |
설정 테이블
| 테이블 | 설명 |
|---|
global_settings | 전역 Nginx 설정 |
system_settings | 시스템 설정 |
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 작동 안함
- MaxMind 라이선스 키 확인
- GeoIP 데이터베이스 존재 확인 (
/etc/nginx/geoip/)
- 시스템 설정에서 GeoIP 상태 확인
- 수동 업데이트 실행
로그 조회가 느림
- 로그 보존 기간 단축 (시스템 설정)
- 필터 범위 축소
- 파티션 상태 확인
# 파티션 확인
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 제한 설정
- 최소 권한 원칙 적용
- 토큰 만료일 설정
