---
title: "Show HN: Nginx용 Redis 기반 동적 IP 허용 목록 — kvauth"
published: 2025-12-30T22:29:13.000Z
canonical: https://jeff.news/article/1307
---
# Show HN: Nginx용 Redis 기반 동적 IP 허용 목록 — kvauth

Nginx 리로드 없이 Redis 호환 KV 스토어를 통해 실시간으로 IP 허용 목록을 관리하는 경량 도구. auth_request 디렉티브 기반으로 동작하며 TTL 기반 임시 접근 권한도 지원.

- Show HN 프로젝트: Nginx에 동적 IP 허용 목록(allowlist)을 Redis 기반으로 구현하는 경량 도구 `kvauth`

- 문제 상황이 공감됨: IP 허용 목록 바꿀 때마다 `systemctl reload nginx` 해야 하는 게 오버헤드가 큼. 특히 허용 IP가 자주 바뀌는 환경에서는 운영 부담이 상당함. Nginx Plus의 `ngx_http_keyval_module`이 이걸 해결해주지만 유료 구독 필요

- kvauth는 Redis 호환 KV 스토어 위에 올라가는 방식. 동작 원리가 간단함: Redis에 요청 IP를 키로, 접근 허용할 호스트명을 필드로 설정하면 됨
  ```
  redis-cli> hset 1.1.1.1 mywebsite.com 1
  ```

- Nginx의 `auth_request` 디렉티브를 활용해서, 요청이 들어올 때 kvauth에 IP 확인 질의를 보내고, 허용 안 되면 401 반환하는 구조. 리로드 없이 실시간으로 IP 제어가 가능해짐

- Redis의 TTL 기능을 그대로 활용해서 시간 제한 IP 허용도 가능함. "20초만 허용" 같은 임시 접근 권한 부여에 유용

- L1 캐시 옵션도 있는데 기본적으로 비활성화 상태임. DB에서 항목을 삭제해도 캐시에 남아있으면 여전히 통과시켜버리는 문제가 있어서, 수동 삭제 시 `SIGHUP`으로 캐시 클리어해야 함. 그래도 인증된 요청의 속도는 확 빨라짐

> [!TIP]
> Docker Compose로 예제 환경 바로 띄울 수 있음. Valkey, Redis, KeyDB 같은 Redis 호환 스토어 다 지원하고, 영구 허용 목록이 필요하면 해당 스토어의 영속화 설정을 따로 해줘야 함.

## 핵심 포인트

- systemctl reload 없이 실시간 IP 제어 가능
- Redis hset으로 IP별 호스트 접근 권한 설정
- TTL로 시간 제한 IP 허용 지원
- L1 캐시 옵션으로 인증 속도 향상 가능하나 동기화 주의 필요

## 인사이트

Nginx Plus 유료 기능인 ngx_http_keyval_module의 무료 대안으로, 동적 IP 관리가 필요한 소규모 프로젝트에 실용적인 솔루션.