Redis 7 클러스터 운영과 메모리 최적화 핸드북 2026

#!lua name=mylib

-- 조회수 증가와 조회 기록을 원자적으로 처리하는 함수
redis.register_function('increment_view', function(keys, args)
  local current = redis.call('HINCRBY', keys[1], 'views', 1)
  redis.call('ZADD', keys[1] .. ':history', redis.call('TIME')[1], args[1])
  return current
end)

# 라이브러리 로드
cat mylib.lua | redis-cli -x FUNCTION LOAD REPLACE

# 함수 호출
redis-cli FCALL increment_view 1 article:1001 "user:42"

# 등록된 함수 목록 확인
redis-cli FUNCTION LIST

# 캐시 전용 사용자: cache:* 키에 읽기/쓰기, session:* 키에 읽기만 허용
redis-cli ACL SETUSER cache_worker on >StrongP@ss123 \
  ~cache:* +@all \
  (~session:* %R~session:* +@read)

# ACL 규칙 확인
redis-cli ACL GETUSER cache_worker

# 현재 ACL 목록을 파일로 저장
redis-cli ACL SAVE

# 6개 Redis 인스턴스 설정 (포트 7000~7005)
for port in 7000 7001 7002 7003 7004 7005; do
  mkdir -p /opt/redis-cluster/${port}
  cat > /opt/redis-cluster/${port}/redis.conf << CONF
port ${port}
cluster-enabled yes
cluster-config-file nodes-${port}.conf
cluster-node-timeout 5000
appendonly yes
appendfilename "appendonly.aof"
dir /opt/redis-cluster/${port}
maxmemory 4gb
maxmemory-policy allkeys-lfu
bind 0.0.0.0
protected-mode no
save 3600 1 300 100 60 10000
aof-use-rdb-preamble yes
CONF
  redis-server /opt/redis-cluster/${port}/redis.conf &
done

# 클러스터 생성 (마스터 3 + 레플리카 3)
redis-cli --cluster create \
  192.168.1.10:7000 192.168.1.10:7001 192.168.1.10:7002 \
  192.168.1.10:7003 192.168.1.10:7004 192.168.1.10:7005 \
  --cluster-replicas 1

# 동일 슬롯에 배치: {user:1000} 부분만 해시 계산에 사용
redis-cli SET "{user:1000}.profile" '{"name":"Kim"}'
redis-cli SET "{user:1000}.settings" '{"theme":"dark"}'
redis-cli SET "{user:1000}.cart" '["item1","item2"]'

# 같은 슬롯인지 확인
redis-cli CLUSTER KEYSLOT "{user:1000}.profile"
redis-cli CLUSTER KEYSLOT "{user:1000}.settings"

# 새 노드를 클러스터에 추가
redis-cli --cluster add-node 192.168.1.10:7006 192.168.1.10:7000

# 자동 리밸런싱: 모든 마스터에 슬롯을 균등 분배
redis-cli --cluster rebalance 192.168.1.10:7000

# 특정 노드에서 다른 노드로 슬롯 수동 이동
redis-cli --cluster reshard 192.168.1.10:7000 \
  --cluster-from <source-node-id> \
  --cluster-to <target-node-id> \
  --cluster-slots 1000 \
  --cluster-yes

# 클러스터 상태 확인
redis-cli --cluster check 192.168.1.10:7000
redis-cli --cluster info 192.168.1.10:7000

# 특정 키의 메모리 사용량 확인 (바이트 단위)
redis-cli MEMORY USAGE user:profile:10001
# (integer) 256

# 중첩 구조의 경우 샘플 수 지정 (0이면 전체 탐색)
redis-cli MEMORY USAGE myhash SAMPLES 0

# 메모리 진단 리포트
redis-cli MEMORY DOCTOR
# "Sam, I have no memory problems"

# 메모리 통계 요약
redis-cli MEMORY STATS

# 전체 서버 메모리 정보
redis-cli INFO memory

# 최대 메모리 및 제거 정책
maxmemory 4gb
maxmemory-policy allkeys-lfu

# LFU 알고리즘 튜닝
# lfu-log-factor: 값이 클수록 카운터 증가가 느림 (기본 10)
# lfu-decay-time: 카운터 감소 주기 (분 단위, 기본 1)
lfu-log-factor 10
lfu-decay-time 1

# 메모리 조각 모음 활성화 (jemalloc 기반)
activedefrag yes
active-defrag-enabled yes
active-defrag-ignore-bytes 100mb
active-defrag-threshold-lower 10
active-defrag-threshold-upper 100
active-defrag-cycle-min 1
active-defrag-cycle-max 25

# Lazy Free 설정: 대용량 키 삭제 시 백그라운드 처리
lazyfree-lazy-eviction yes
lazyfree-lazy-expire yes
lazyfree-lazy-server-del yes
replica-lazy-flush yes

# I/O 스레드 설정 (Redis 7+)
io-threads 4
io-threads-do-reads yes

# redis.conf: 인코딩 임계값 조정 예시
# 소형 해시가 많은 워크로드: 임계값을 높여 listpack 유지
hash-max-listpack-entries 256
hash-max-listpack-value 128

# 소형 정렬 셋이 많은 랭킹 서비스
zset-max-listpack-entries 256
zset-max-listpack-value 64

# 소형 셋이 많은 태그 시스템
set-max-listpack-entries 256
set-max-intset-entries 1024

# List 노드당 최대 크기 (-2 = 8KB, -1 = 4KB)
list-max-listpack-size -2
list-compress-depth 1

# 현재 인코딩 확인
redis-cli OBJECT ENCODING mykey

# 소형 해시 (listpack)
redis-cli HSET small:hash f1 v1 f2 v2 f3 v3
redis-cli OBJECT ENCODING small:hash
# "listpack"

# 임계값 초과 시 hashtable로 자동 전환
# 129개 필드를 가진 해시 생성 (기본 hash-max-listpack-entries=128 초과)
for i in $(seq 1 129); do
  redis-cli HSET big:hash "field_${i}" "value_${i}"
done
redis-cli OBJECT ENCODING big:hash
# "hashtable"

# 정수만으로 구성된 Set: intset 인코딩
redis-cli SADD int:set 1 2 3 4 5
redis-cli OBJECT ENCODING int:set
# "intset"

# redis.conf: 혼합 모드 (프로덕션 권장)

# RDB 스냅샷 주기: 3600초(1시간) 내 1회 변경, 300초 내 100회, 60초 내 10000회
save 3600 1 300 100 60 10000

# AOF 활성화
appendonly yes
appendfilename "appendonly.aof"

# AOF fsync 정책: everysec (성능과 안정성 균형)
appendfsync everysec

# 혼합 모드 활성화: AOF 리라이트 시 RDB 형식을 프리앰블로 사용
aof-use-rdb-preamble yes

# Multi-Part AOF 디렉토리 (Redis 7 기본)
appenddirname "appendonlydir"

# AOF 리라이트 트리거 조건
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb

# RDB 압축 및 체크섬
rdbcompression yes
rdbchecksum yes
dbfilename dump.rdb

# 백그라운드 저장 실패 시 쓰기 중단
stop-writes-on-bgsave-error yes

# 메모리 사용률 확인
redis-cli INFO memory | grep -E "used_memory_human|used_memory_rss_human|mem_fragmentation_ratio"
# used_memory_human:2.85G
# used_memory_rss_human:3.12G
# mem_fragmentation_ratio:1.09

# 클러스터 상태 확인
redis-cli CLUSTER INFO
# cluster_state:ok
# cluster_slots_assigned:16384
# cluster_slots_ok:16384
# cluster_known_nodes:6
# cluster_size:3

# 초당 명령 처리량
redis-cli INFO stats | grep instantaneous_ops_per_sec

# 연결 수 확인
redis-cli INFO clients | grep connected_clients

# 키스페이스 히트율 (캐시 효율)
redis-cli INFO stats | grep -E "keyspace_hits|keyspace_misses"

# Slow Log 확인 (10ms 이상 소요 명령)
redis-cli SLOWLOG GET 10
redis-cli SLOWLOG LEN

import redis
from redis.cluster import RedisCluster

# Redis Cluster 연결
startup_nodes = [
    {"host": "192.168.1.10", "port": 7000},
    {"host": "192.168.1.10", "port": 7001},
    {"host": "192.168.1.10", "port": 7002},
]

rc = RedisCluster(
    startup_nodes=startup_nodes,
    decode_responses=True,
    password="your_secure_password",
    socket_timeout=5,
    retry_on_timeout=True,
)

def check_cluster_health():
    """클러스터 전체 상태를 점검하고 이상 시 알림을 발송한다."""
    alerts = []

    # 클러스터 상태 확인
    cluster_info = rc.cluster_info()
    if cluster_info.get("cluster_state") != "ok":
        alerts.append(f"[CRITICAL] 클러스터 상태 이상: {cluster_info.get('cluster_state')}")

    # 각 노드별 메모리 사용률 점검
    for node in rc.get_nodes():
        try:
            info = rc.get_redis_connection(node).info("memory")
            used = info["used_memory"]
            maxmem = info.get("maxmemory", 0)
            if maxmem > 0:
                usage_pct = (used / maxmem) * 100
                if usage_pct > 85:
                    alerts.append(
                        f"[WARNING] 노드 {node.host}:{node.port} "
                        f"메모리 사용률 {usage_pct:.1f}%"
                    )

            # 메모리 단편화율 점검
            frag_ratio = info.get("mem_fragmentation_ratio", 1.0)
            if frag_ratio > 1.5:
                alerts.append(
                    f"[WARNING] 노드 {node.host}:{node.port} "
                    f"메모리 단편화율 {frag_ratio:.2f}"
                )
        except Exception as e:
            alerts.append(f"[ERROR] 노드 {node.host}:{node.port} 접속 실패: {e}")

    return alerts


def get_memory_report():
    """노드별 메모리 사용 현황 리포트를 생성한다."""
    report = []
    for node in rc.get_nodes():
        try:
            info = rc.get_redis_connection(node).info("memory")
            report.append({
                "node": f"{node.host}:{node.port}",
                "role": node.server_type,
                "used_memory_human": info["used_memory_human"],
                "used_memory_rss_human": info["used_memory_rss_human"],
                "fragmentation_ratio": info["mem_fragmentation_ratio"],
                "used_memory_peak_human": info["used_memory_peak_human"],
            })
        except Exception as e:
            report.append({"node": f"{node.host}:{node.port}", "error": str(e)})
    return report


if __name__ == "__main__":
    # 클러스터 헬스 체크
    alerts = check_cluster_health()
    if alerts:
        for alert in alerts:
            print(alert)
        # send_to_slack(alerts) 또는 send_to_pagerduty(alerts)
    else:
        print("모든 노드 정상")

    # 메모리 리포트 출력
    for item in get_memory_report():
        print(item)

# 현재 단편화율 확인
redis-cli INFO memory | grep mem_fragmentation_ratio

# 런타임에서 Active Defrag 활성화
redis-cli CONFIG SET activedefrag yes
redis-cli CONFIG SET active-defrag-threshold-lower 10

# 조각 모음 진행 상태 확인
redis-cli INFO memory | grep -E "active_defrag"

# 빅 키 스캔 (프로덕션에서도 안전한 SCAN 기반)
redis-cli --bigkeys

# 특정 키의 정확한 메모리 사용량
redis-cli MEMORY USAGE large:hash SAMPLES 0

# 빅 키를 비동기 삭제 (UNLINK = 비차단 DEL)
redis-cli UNLINK large:hash

# redis.conf
repl-backlog-size 256mb
repl-backlog-ttl 3600

# 현재 클러스터 노드 상태 확인
redis-cli CLUSTER NODES

# 특정 노드가 FAIL 상태인지 확인
redis-cli CLUSTER INFO | grep cluster_state

# 수동 페일오버 (레플리카에서 실행)
redis-cli -p 7003 CLUSTER FAILOVER

# 강제 페일오버 (마스터 응답 불가 시)
redis-cli -p 7003 CLUSTER FAILOVER FORCE

# AOF 파일 무결성 검증
redis-check-aof --fix /opt/redis-cluster/7000/appendonlydir/appendonly.aof.1.incr.aof

# RDB 파일 무결성 검증
redis-check-rdb /opt/redis-cluster/7000/dump.rdb

# 백업에서 복구: 인스턴스 중지 후 RDB/AOF 파일 교체
redis-cli -p 7000 SHUTDOWN NOSAVE
cp /backup/dump.rdb /opt/redis-cluster/7000/dump.rdb
redis-server /opt/redis-cluster/7000/redis.conf