필터 구독 (Filter Subscriptions)

외부 IP/CIDR 차단 목록을 구독하면 자동으로 동기화되어 Nginx에 통합됩니다.

개요

홈서버 하나에도 스캐너, 무차별 대입 봇, 알려진 악성 네트워크의 탐색이 끊임없이 들어옵니다. 차단 목록을 수동으로 관리하는 것은 현실적이지 않습니다. 필터 구독을 사용하면 Nginx Proxy Guard가 커뮤니티에서 관리하는 IP/CIDR 차단 목록을 참조하도록 설정할 수 있습니다. 시스템은 각 목록을 주기적으로 가져와 항목을 중복 제거한 뒤 Nginx에 반영하여 해당 주소를 프록시 단에서 차단합니다.

동작 방식

단계	동작
구독	URL로 목록을 추가하거나 내장 카탈로그에서 선택
가져오기	HTTPS로 목록을 다운로드하여 IP/CIDR 항목으로 파싱
중복 제거	목록 내부 및 다른 구독·차단 IP 간 항목 중복 제거
적용	병합된 항목을 Nginx 설정에 기록하고 reload
새로고침	설정된 새로고침 주기에 따라 목록 자동 재가져오기

구독 추가

구독은 두 가지 방법으로 추가할 수 있습니다.

방법	설명
카탈로그에서	NPG용으로 큐레이션된 프리셋 차단 목록을 클릭 한 번으로 구독
URL로	임의의 외부 IP/CIDR 목록 URL을 직접 입력

카탈로그는 공식 npg-filters 저장소에서 제공되므로, 별도 설정 없이도 프리셋 목록이 최신 상태로 유지됩니다.

자동 새로고침 스케줄링

각 구독은 고유한 새로고침 주기를 가지므로, 자주 바뀌는 목록은 안정적인 목록보다 더 짧은 주기로 갱신할 수 있습니다.

설정	설명	기본값
새로고침 유형	새로고침 주기를 해석하는 방식 (예: interval)	`interval`
새로고침 값	목록을 다시 가져오는 간격	`24h`

백그라운드 스케줄러가 활성화된 모든 구독을 주기적으로 점검하여, 새로고침 간격이 지난 목록을 다시 가져옵니다. 상세 화면에서 새로고침을 직접 실행하면 스케줄러를 기다리지 않고 즉시 갱신할 수도 있습니다.

중복 제거

차단 목록은 서로 많이 겹치며, 중복 항목은 아무 이득 없이 Nginx 리소스만 낭비합니다. NPG는 두 단계로 중복을 제거합니다.

구독 내부 — 같은 목록 안의 동일 항목을 하나로 합칩니다.
소스 간 — 다른 구독이나 차단 IP에 이미 존재하는 항목은 중복으로 추가하지 않습니다.

덕분에 서로 겹치는 여러 소스를 구독해도 실제 적용되는 차단 목록은 작게 유지됩니다.

예외 처리

특정 서비스에는 차단 목록이 다소 과하게 동작할 수 있습니다. NPG는 두 가지 예외를 지원합니다.

예외 유형	범위	사용 사례
호스트별 예외	프록시 호스트를 구독 적용에서 제외	협력사가 사용하는 IP 대역을 차단하는 목록을 특정 앱에서만 제외
항목 예외	특정 IP/CIDR을 구독에서 제거	오탐 항목 하나가 정상 클라이언트를 차단할 때

호스트별 예외는 구독을 기준으로 프록시 호스트를 지정하여 관리하고, 항목 예외는 적용 집합에서 특정 값을 제거합니다.

팁: 주소 하나가 잘못되었다면 항목 예외를, 서비스 전체가 목록을 우회해야 한다면 호스트별 예외를 사용하세요.

사설 IP 처리

각 구독에는 사설 IP 제외 옵션이 있습니다. 활성화하면 목록에 포함된 사설/내부 주소 대역이 적용 전에 제거되므로, 범위가 지나치게 넓은 공개 차단 목록이 실수로 LAN이나 도커 네트워크를 끊는 일을 방지합니다.

제한

Nginx 성능과 메모리를 보호하기 위해 차단 목록 크기에 하드 제한이 적용됩니다.

제한	값
목록당 항목 수	25,000
전체 항목 수 (모든 구독)	100,000
목록당 최대 다운로드 크기	10 MB

목록이 목록당 제한을 초과하면 앞쪽 25,000개 항목만 적용됩니다. 목록 추가로 합계가 100,000개를 넘게 되면, 전역 한도를 지키도록 잘려서 적용됩니다.

위치

필터 구독은 대시보드의 전용 페이지에서 관리합니다. 이 페이지에서 다음을 할 수 있습니다.

프리셋 카탈로그 탐색 및 구독
URL로 커스텀 목록 추가
즉시 새로고침 실행
가져온 항목과 마지막 동기화 상태 확인
호스트별·항목별 예외 관리