시스템 아키텍처

Nginx Proxy Guard의 내부 구조 및 데이터 흐름을 시각적으로 설명합니다.

아키텍처 다이어그램

┌─────────────────────────────────────────────────────────────────────┐
│                            인터넷                                    │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Nginx Proxy (포트 80/443)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │ Rate Limit  │  │ModSecurity  │  │  Bot Filter │  │ Geo Block  │ │
│  │             │  │ WAF+CRS4    │  │  130+ Sigs  │  │  GeoIP2    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │  SSL/TLS    │  │  Fail2ban   │  │  Challenge  │  │ URI Block  │ │
│  │HTTP/2 HTTP/3│  │ Auto-Ban    │  │  CAPTCHA    │  │            │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   Headers   │  │  Cloud IP   │  │   Caching   │  │  Exploit   │ │
│  │   Security  │  │   Block     │  │ Compression │  │   Block    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
    ┌───────────┐       ┌───────────┐       ┌───────────┐
    │ Backend 1 │       │ Backend 2 │       │ Backend N │
    │           │       │           │       │           │
    └───────────┘       └───────────┘       └───────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        관리 레이어                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │  React UI   │◄─│   Go API    │◄─│ PostgreSQL  │  │  Valkey    │ │
│  │  (포트 81)  │  │ (포트 8080) │  │    17       │  │ (Redis)    │ │
│  │ TypeScript  │  │  Echo v4    │  │             │  │  Cache     │ │
│  │ Tailwind    │  │  JWT+TOTP   │  │             │  │  Ban List  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Docker 서비스

서비스	컨테이너	이미지	설명	포트
`nginx`	npg-proxy	Custom Build	리버스 프록시 + WAF + GeoIP + HTTP/3 (호스트 네트워크 모드)	80, 443 (TCP/UDP)
`ui`	npg-ui	Custom Build	React 웹 인터페이스	81→443
`api`	npg-api	Custom Build	Go 백엔드 API	127.0.0.1:9080→8080 (내부)
`db`	npg-db	timescale/timescaledb:latest-pg17	데이터베이스 (TimescaleDB)	5432 (내부)
`valkey`	npg-valkey	valkey/valkey:9-alpine	캐시 (Redis 호환)	6379 (내부)

참고: nginx 컨테이너는 호스트 네트워크 모드로 실행되어 프록시 프로토콜 없이도 실제 클라이언트 IP를 직접 확인할 수 있습니다. 나머지 서비스는 npg-network 브리지 네트워크에 속합니다.

기술 스택

백엔드

기술	버전	용도
Go	1.26	백엔드 API 서버
Echo	v4.15	웹 프레임워크
PostgreSQL	17	관계형 데이터베이스
Valkey	9	캐시 및 세션 관리
JWT	-	무상태 인증
TOTP	-	2단계 인증

프론트엔드

기술	버전	용도
React	19	UI 프레임워크
TypeScript	6	타입 안전성
Vite	8 (Rolldown)	빌드 도구
Tailwind CSS	4	스타일링
TanStack Query	v5	서버 상태 관리
React Router	v7	클라이언트 라우팅
Recharts	-	데이터 시각화
react-simple-maps	-	GeoIP 지도

프록시 & 보안

기술	버전	용도
Nginx	1.30.2	웹 서버 / 리버스 프록시
ModSecurity	v3.0.15	WAF 엔진
OWASP CRS	v4.26.0	WAF 룰셋
MaxMind GeoIP2	-	지역 기반 접근 제어
Brotli/Zstd	-	고급 압축
HTTP/3 (QUIC)	-	차세대 프로토콜

주요 라이브러리

라이브러리	용도
lego/v4	ACME/Let's Encrypt 클라이언트
geoip2-golang	MaxMind GeoIP2 파싱
go-redis/v9	Redis/Valkey 클라이언트
gopsutil/v3	시스템 모니터링
lib/pq	PostgreSQL 드라이버

데이터 흐름

요청 처리 흐름

클라이언트 요청
       ↓
┌──────────────────────────────────────────┐
│           Nginx (Layer 1)                │
│  1. Rate Limiting 체크                   │
│  2. IP 차단 목록 확인                    │
│  3. GeoIP 지역 제한 확인                 │
│  4. Bot Filter 검사                      │
│  5. Challenge (CAPTCHA) 확인             │
│  6. Cloud Provider IP 차단               │
│  7. URI 차단 규칙 확인                   │
└──────────────────────────────────────────┘
       ↓ (통과 시)
┌──────────────────────────────────────────┐
│        ModSecurity WAF (Layer 2)         │
│  1. OWASP CRS 규칙 검사                  │
│  2. SQL Injection 탐지                   │
│  3. XSS 탐지                             │
│  4. 경로 탐색 탐지                       │
│  5. 명령어 인젝션 탐지                   │
└──────────────────────────────────────────┘
       ↓ (통과 시)
┌──────────────────────────────────────────┐
│       프록시 처리 (Layer 3)              │
│  1. SSL/TLS 종료                         │
│  2. 캐싱 및 압축                         │
│  3. 보안 헤더 추가                       │
└──────────────────────────────────────────┘
       ↓
   백엔드 서버

관리 인터페이스 흐름

관리자 브라우저
       ↓
┌──────────────────────────────────────────┐
│           React UI (포트 81)             │
│  - SPA 렌더링                            │
│  - TanStack Query 상태 관리              │
└──────────────────────────────────────────┘
       ↓ (API 요청)
┌──────────────────────────────────────────┐
│           Go API (포트 8080)             │
│  - JWT 인증                              │
│  - TOTP 2FA 검증                         │
│  - 비즈니스 로직                         │
└──────────────────────────────────────────┘
       ↓
┌──────────────────────────────────────────┐
│           데이터 레이어                  │
│  PostgreSQL: 설정, 로그, 인증서          │
│  Valkey: 캐시, 차단 목록, 세션           │
└──────────────────────────────────────────┘
       ↓
┌──────────────────────────────────────────┐
│           Nginx 설정 적용                │
│  - conf.d/ 파일 생성                     │
│  - nginx -s reload                       │
└──────────────────────────────────────────┘

보안 레이어

Layer 1: 네트워크 레벨

Rate Limiting (초당 요청 제한)
IP 차단 (Fail2ban, WAF, 수동)
GeoIP 지역 제한
클라우드 프로바이더 IP 차단

Layer 2: 애플리케이션 레벨

봇 필터링 (130+ 시그니처)
URI 차단
CAPTCHA 챌린지
보안 헤더

Layer 3: WAF 레벨

ModSecurity v3
OWASP CRS v4.26.0
Paranoia Level 1-4
커스텀 규칙

Layer 4: 인증/인가

JWT 토큰 인증
TOTP 2FA
API 토큰 권한 관리
감사 로깅

스케줄러 (백그라운드 작업)

작업	주기	설명
인증서 갱신	6시간	Let's Encrypt 자동 갱신
로그 파티션	매일	월별 로그 테이블 파티션 생성
로그 로테이션	매일	Raw 로그 파일 로테이션
GeoIP 업데이트	설정에 따름	MaxMind DB 자동 업데이트
IP 차단 만료	1분	만료된 IP 차단 해제
Challenge 토큰 정리	1시간	만료된 CAPTCHA 토큰 삭제
DDNS 동기화	설정에 따름 (최소 1분)	공인 IP 확인 후 DDNS 레코드 갱신
필터 구독 새로고침	구독별 주기	외부 IP/CIDR 차단 목록 재가져오기
백업	설정에 따름	DB + 설정 자동 백업

데이터베이스 파티셔닝

대용량 로그 데이터를 효율적으로 관리하기 위해 월별 파티셔닝을 사용합니다.

-- 로그 테이블 구조
logs (parent table)
├── logs_2024_01
├── logs_2024_02
├── ...
└── logs_2024_12

system_logs (parent table)
├── system_logs_2024_01
└── ...

네트워크 구성

┌─────────────────────────────────────────┐
│           Docker Network                │
│           (npg-network, bridge)         │
│                                         │
│          api ◄──► db                   │
│           ▲                             │
│           └───► valkey                 │
│           ▲                             │
│           └──────────► ui              │
│                                         │
└─────────────────────────────────────────┘
         │  (nginx는 호스트 네트워크 모드)
         ▼
    nginx (호스트 네트워크) ──► api
    호스트 포트: 80, 443 (nginx), 81 (ui)