Redis Distributed Lock in Practice: 5 Implementation Patterns from Redlock to Production-Grade Lock Service
数据库
Distributed Locks: You've Hit More Pitfalls Than Written Code
Overselling inventory, duplicate cron job execution, idempotent APIs breached by concurrency — these production incidents all stem from distributed concurrency control failure. You use SET NX EX for locking, but the lock expires before the business finishes; you switch to Redisson, only to find the watchdog renewal fails during GC pauses; you try Redlock, then get scared off by Martin Kleppmann's paper. In 2026, Redis distributed locks remain one of the most error-prone components in distributed systems.
This article covers 5 implementation patterns, guiding you through basic lock → reentrant lock → Redlock → lock renewal → production-grade lock service with complete code and pitfall guides.
Redis Distributed Lock Core Concepts
| Concept | Description |
|---|---|
| SET NX EX | Native Redis command; NX sets only if not exists, EX sets expiry in seconds |
| Reentrant Lock | Same thread/coroutine can acquire the same lock multiple times, requires counter |
| Watchdog | Background renewal thread preventing premature lock expiration |
| Redlock Algorithm | Multi-node distributed lock; requires N/2+1 nodes to succeed |
| Lua Script | Atomic operation guarantee; check-and-set for lock/unlock must be atomic |
| Fair Lock | Locks acquired in request order, preventing starvation |
| Read-Write Lock | Shared read lock, exclusive write lock; improves read-heavy concurrency |
| Semaphore | Allows N holders simultaneously, used for rate limiting/resource pools |
Problem Analysis: 5 Major Distributed Lock Challenges
- Lock timeout vs business duration mismatch: Lock expires in 10s, but business takes 15s, causing premature release and concurrency breach
- GC pauses breaking watchdog: JVM/Go runtime STW pauses prevent timely renewal
- Redlock clock drift: Multi-node clock desync can compromise lock safety
- Accidentally deleting others' locks: A's lock expires, B acquires it, then A releases B's lock
- Split-brain under network partition: Client-Redis network disconnect causes inconsistent lock state
Step-by-Step: 5 Redis Distributed Lock Implementations
Pattern 1: Basic SET NX EX Lock
import redis
import uuid
import time
class RedisBasicLock:
def __init__(self, redis_client: redis.Redis, lock_name: str, timeout: int = 10):
self.redis = redis_client
self.lock_name = f"lock:{lock_name}"
self.timeout = timeout
self.identifier = str(uuid.uuid4())
def acquire(self) -> bool:
result = self.redis.set(
self.lock_name,
self.identifier,
nx=True,
ex=self.timeout
)
return result is not None
def release(self) -> bool:
lua_script = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
result = self.redis.eval(lua_script, 1, self.lock_name, self.identifier)
return result == 1
def __enter__(self):
if not self.acquire():
raise RuntimeError(f"Failed to acquire lock: {self.lock_name}")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.release()
Pattern 2: Reentrant Lock
import redis
import uuid
import threading
class RedisReentrantLock:
def __init__(self, redis_client: redis.Redis, lock_name: str, timeout: int = 30):
self.redis = redis_client
self.lock_name = f"reentrant_lock:{lock_name}"
self.timeout = timeout
self.identifier = str(uuid.uuid4())
self._local = threading.local()
def acquire(self) -> bool:
count = getattr(self._local, 'count', 0)
if count > 0:
self._local.count = count + 1
return True
lua_acquire = """
if redis.call("exists", KEYS[1]) == 0 then
redis.call("hset", KEYS[1], ARGV[1], 1)
redis.call("expire", KEYS[1], ARGV[2])
return 1
elseif redis.call("hexists", KEYS[1], ARGV[1]) == 1 then
redis.call("hincrby", KEYS[1], ARGV[1], 1)
redis.call("expire", KEYS[1], ARGV[2])
return 1
else
return 0
end
"""
result = self.redis.eval(lua_acquire, 1, self.lock_name, self.identifier, str(self.timeout))
if result == 1:
self._local.count = 1
return True
return False
def release(self) -> bool:
count = getattr(self._local, 'count', 0)
if count == 0:
return False
if count > 1:
self._local.count = count - 1
lua_decr = """
if redis.call("hexists", KEYS[1], ARGV[1]) == 1 then
redis.call("hincrby", KEYS[1], ARGV[1], -1)
return 1
else
return 0
end
"""
self.redis.eval(lua_decr, 1, self.lock_name, self.identifier)
return True
lua_release = """
if redis.call("hexists", KEYS[1], ARGV[1]) == 0 then
return 0
elseif redis.call("hincrby", KEYS[1], ARGV[1], -1) > 0 then
redis.call("expire", KEYS[1], ARGV[2])
return 1
else
return redis.call("del", KEYS[1])
end
"""
result = self.redis.eval(lua_release, 1, self.lock_name, self.identifier, str(self.timeout))
self._local.count = 0
return result in (1,)
def __enter__(self):
if not self.acquire():
raise RuntimeError(f"Failed to acquire reentrant lock: {self.lock_name}")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.release()
Pattern 3: Watchdog Auto-Renewal Lock
import redis
import uuid
import threading
import time
import logging
logger = logging.getLogger(__name__)
class RedisWatchdogLock:
def __init__(self, redis_client: redis.Redis, lock_name: str, timeout: int = 30, renewal_interval: int = 10):
self.redis = redis_client
self.lock_name = f"watchdog_lock:{lock_name}"
self.timeout = timeout
self.renewal_interval = renewal_interval
self.identifier = str(uuid.uuid4())
self._watchdog_thread = None
self._stop_event = threading.Event()
def acquire(self, blocking: bool = True, wait_timeout: float = 30.0) -> bool:
deadline = time.time() + wait_timeout
while True:
result = self.redis.set(self.lock_name, self.identifier, nx=True, ex=self.timeout)
if result is not None:
self._start_watchdog()
return True
if not blocking:
return False
if time.time() >= deadline:
return False
time.sleep(0.1)
def _start_watchdog(self):
self._stop_event.clear()
self._watchdog_thread = threading.Thread(target=self._watchdog_loop, daemon=True)
self._watchdog_thread.start()
def _watchdog_loop(self):
while not self._stop_event.is_set():
self._stop_event.wait(self.renewal_interval)
if self._stop_event.is_set():
break
try:
lua_renew = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("expire", KEYS[1], ARGV[2])
else
return 0
end
"""
result = self.redis.eval(lua_renew, 1, self.lock_name, self.identifier, str(self.timeout))
if result != 1:
logger.warning("Watchdog renewal failed for lock %s", self.lock_name)
break
except Exception as e:
logger.error("Watchdog error: %s", e)
break
def release(self) -> bool:
self._stop_event.set()
if self._watchdog_thread and self._watchdog_thread.is_alive():
self._watchdog_thread.join(timeout=2.0)
lua_release = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
result = self.redis.eval(lua_release, 1, self.lock_name, self.identifier)
return result == 1
def __enter__(self):
if not self.acquire():
raise RuntimeError(f"Failed to acquire watchdog lock: {self.lock_name}")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.release()
Pattern 4: Redlock Multi-Node Lock
import redis
import uuid
import time
import logging
from typing import List
logger = logging.getLogger(__name__)
class Redlock:
def __init__(self, redis_clients: List[redis.Redis], lock_name: str, timeout: int = 10, retry_count: int = 3, retry_delay: float = 0.2):
self.redis_clients = redis_clients
self.quorum = len(redis_clients) // 2 + 1
self.lock_name = f"redlock:{lock_name}"
self.timeout = timeout
self.retry_count = retry_count
self.retry_delay = retry_delay
self.identifier = str(uuid.uuid4())
def acquire(self) -> bool:
for attempt in range(self.retry_count):
acquired_count = 0
start_time = time.monotonic()
for client in self.redis_clients:
try:
result = client.set(self.lock_name, self.identifier, nx=True, ex=self.timeout)
if result is not None:
acquired_count += 1
except Exception as e:
logger.warning("Redlock acquire error on node: %s", e)
elapsed = time.monotonic() - start_time
validity_time = self.timeout - elapsed
if acquired_count >= self.quorum and validity_time > 0:
return True
self._release_all_nodes()
if attempt < self.retry_count - 1:
jitter = (attempt * 0.01)
time.sleep(self.retry_delay + jitter)
return False
def _release_all_nodes(self):
lua_release = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
for client in self.redis_clients:
try:
client.eval(lua_release, 1, self.lock_name, self.identifier)
except Exception as e:
logger.warning("Redlock release error on node: %s", e)
def release(self) -> bool:
self._release_all_nodes()
return True
def __enter__(self):
if not self.acquire():
raise RuntimeError(f"Failed to acquire Redlock: {self.lock_name}")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.release()
Pattern 5: Production-Grade Lock Service (Go)
package distlock
import (
"context"
"crypto/rand"
"encoding/hex"
"fmt"
"log"
"sync"
"time"
"github.com/redis/go-redis/v9"
)
type LockService struct {
client *redis.Client
watchdogCancel map[string]context.CancelFunc
mu sync.Mutex
}
func NewLockService(client *redis.Client) *LockService {
return &LockService{
client: client,
watchdogCancel: make(map[string]context.CancelFunc),
}
}
type LockOptions struct {
Timeout time.Duration
RenewalInterval time.Duration
RetryCount int
RetryDelay time.Duration
}
func DefaultLockOptions() LockOptions {
return LockOptions{
Timeout: 30 * time.Second,
RenewalInterval: 10 * time.Second,
RetryCount: 3,
RetryDelay: 200 * time.Millisecond,
}
}
func generateIdentifier() string {
b := make([]byte, 16)
rand.Read(b)
return hex.EncodeToString(b)
}
var acquireScript = redis.NewScript(`
if redis.call("exists", KEYS[1]) == 0 then
redis.call("hset", KEYS[1], "identifier", ARGV[1], "count", 1)
redis.call("expire", KEYS[1], ARGV[2])
return 1
elseif redis.call("hget", KEYS[1], "identifier") == ARGV[1] then
redis.call("hincrby", KEYS[1], "count", 1)
redis.call("expire", KEYS[1], ARGV[2])
return 1
else
return 0
end
`)
var releaseScript = redis.NewScript(`
if redis.call("hget", KEYS[1], "identifier") ~= ARGV[1] then
return 0
end
local count = redis.call("hincrby", KEYS[1], "count", -1)
if count > 0 then
redis.call("expire", KEYS[1], ARGV[2])
return 1
end
return redis.call("del", KEYS[1])
`)
var renewScript = redis.NewScript(`
if redis.call("hget", KEYS[1], "identifier") == ARGV[1] then
return redis.call("expire", KEYS[1], ARGV[2])
else
return 0
end
`)
func (ls *LockService) Acquire(ctx context.Context, lockName string, opts LockOptions) (string, error) {
identifier := generateIdentifier()
key := fmt.Sprintf("lock_service:%s", lockName)
for i := 0; i < opts.RetryCount; i++ {
result, err := acquireScript.Run(ctx, ls.client, []string{key}, identifier, int(opts.Timeout.Seconds())).Int()
if err != nil {
return "", fmt.Errorf("acquire script error: %w", err)
}
if result == 1 {
ls.startWatchdog(ctx, key, identifier, opts)
return identifier, nil
}
select {
case <-ctx.Done():
return "", ctx.Err()
case <-time.After(opts.RetryDelay):
}
}
return "", fmt.Errorf("failed to acquire lock after %d retries", opts.RetryCount)
}
func (ls *LockService) startWatchdog(ctx context.Context, key, identifier string, opts LockOptions) {
wdCtx, cancel := context.WithCancel(context.Background())
ls.mu.Lock()
ls.watchdogCancel[key+":"+identifier] = cancel
ls.mu.Unlock()
go func() {
defer cancel()
ticker := time.NewTicker(opts.RenewalInterval)
defer ticker.Stop()
for {
select {
case <-wdCtx.Done():
return
case <-ticker.C:
result, err := renewScript.Run(wdCtx, ls.client, []string{key}, identifier, int(opts.Timeout.Seconds())).Int()
if err != nil || result != 1 {
log.Printf("Watchdog renewal failed for key=%s identifier=%s: result=%d err=%v", key, identifier, result, err)
return
}
}
}
}()
}
func (ls *LockService) Release(ctx context.Context, lockName, identifier string, opts LockOptions) error {
key := fmt.Sprintf("lock_service:%s", lockName)
ls.mu.Lock()
if cancel, ok := ls.watchdogCancel[key+":"+identifier]; ok {
cancel()
delete(ls.watchdogCancel, key+":"+identifier)
}
ls.mu.Unlock()
result, err := releaseScript.Run(ctx, ls.client, []string{key}, identifier, int(opts.Timeout.Seconds())).Int()
if err != nil {
return fmt.Errorf("release script error: %w", err)
}
if result == 0 {
return fmt.Errorf("lock not owned by identifier %s", identifier)
}
return nil
}
Pitfall Guide
Pitfall 1: Unlock Without Owner Verification
# ❌ Wrong: direct delete, may remove someone else's lock
redis_client.delete("lock:order:123")
# ✅ Correct: Lua script atomic check-and-delete
lua = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
redis_client.eval(lua, 1, "lock:order:123", my_identifier)
Pitfall 2: Lock Timeout Too Short
# ❌ Wrong: 3s timeout, slow DB queries will exceed it
redis_client.set("lock:order", identifier, nx=True, ex=3)
# ✅ Correct: watchdog renewal + reasonable initial timeout
lock = RedisWatchdogLock(redis_client, "order", timeout=30, renewal_interval=10)
with lock:
process_order()
Pitfall 3: Reentrant Lock Without Counting
# ❌ Wrong: each SET NX, nested calls can't acquire
def outer():
with basic_lock:
inner()
def inner():
with basic_lock: # Deadlock! Can't reacquire own lock
pass
# ✅ Correct: use reentrant lock
def outer():
with reentrant_lock:
inner()
def inner():
with reentrant_lock: # Count+1, acquires normally
pass
Pitfall 4: Redlock Ignoring Clock Drift
# ❌ Wrong: not validating remaining lock validity
acquired_count = 0
for client in redis_clients:
result = client.set(lock_name, identifier, nx=True, ex=timeout)
if result:
acquired_count += 1
if acquired_count >= quorum:
return True # Lock may be about to expire!
# ✅ Correct: validate validity time
start = time.monotonic()
# ... acquire logic ...
elapsed = time.monotonic() - start
validity = timeout - elapsed
if acquired_count >= quorum and validity > 0:
return True
Pitfall 5: Watchdog Interval Equals Lock Timeout
# ❌ Wrong: renewal interval 30s = lock timeout 30s, GC pause breaks it
lock = RedisWatchdogLock(client, "order", timeout=30, renewal_interval=30)
# ✅ Correct: renewal interval = lock timeout / 3
lock = RedisWatchdogLock(client, "order", timeout=30, renewal_interval=10)
Error Troubleshooting
| # | Error Message | Cause | Solution |
|---|---|---|---|
| 1 | UNLOCK_FAILED: lock not owned |
Identifier mismatch on unlock | Ensure same identifier for lock/unlock |
| 2 | LOCK_TIMEOUT: acquire failed after retries |
Lock held too long or high contention | Increase retry count, check for deadlock |
| 3 | WATCHDOG_RENEWAL_FAILED |
Watchdog renewal failed, lock deleted/expired | Check network, verify timeout settings |
| 4 | RedisConnectionError |
Redis connection lost | Configure connection pool retry, use Sentinel/Cluster |
| 5 | LuaScriptError: wrong number of arguments |
Lua script parameter mismatch | Check KEYS and ARGV count and order |
| 6 | Redlock quorum not reached |
Majority nodes failed to acquire | Check node status, increase retry_count |
| 7 | CONCURRENT_MODIFICATION: data inconsistency |
Premature lock release | Use watchdog renewal, increase timeout |
| 8 | OOM: Redis out of memory |
Lock keys without expiry accumulating | Ensure SET NX EX expiry parameter works |
| 9 | DEADLOCK: circular wait detected |
Multi-lock circular wait | Unify lock order, set global timeout |
| 10 | CLOCK_DRIFT: lock validity expired |
Redlock node clock drift too large | Configure NTP sync, validate validity time |
Advanced Optimization
1. Fair Lock Implementation
class RedisFairLock:
def __init__(self, redis_client: redis.Redis, lock_name: str, timeout: int = 30):
self.redis = redis_client
self.lock_name = f"fair_lock:{lock_name}"
self.queue_name = f"fair_lock_queue:{lock_name}"
self.timeout = timeout
self.identifier = str(uuid.uuid4())
def acquire(self, wait_timeout: float = 30.0) -> bool:
timestamp = time.time()
self.redis.zadd(self.queue_name, {self.identifier: timestamp})
self.redis.expire(self.queue_name, wait_timeout * 2)
deadline = time.time() + wait_timeout
while time.time() < deadline:
lua = """
local first = redis.call("zrange", KEYS[2], 0, 0)
if first[1] == ARGV[1] then
local result = redis.call("set", KEYS[1], ARGV[1], "nx", "ex", ARGV[2])
if result then
redis.call("zrem", KEYS[2], ARGV[1])
return 1
end
end
return 0
"""
result = self.redis.eval(lua, 2, self.lock_name, self.queue_name, self.identifier, str(self.timeout))
if result == 1:
return True
time.sleep(0.05)
self.redis.zrem(self.queue_name, self.identifier)
return False
def release(self) -> bool:
lua = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
result = self.redis.eval(lua, 1, self.lock_name, self.identifier)
return result == 1
2. Read-Write Lock Implementation
class RedisReadWriteLock:
def __init__(self, redis_client: redis.Redis, lock_name: str, timeout: int = 30):
self.redis = redis_client
self.read_lock_name = f"rw_lock:{lock_name}:read"
self.write_lock_name = f"rw_lock:{lock_name}:write"
self.timeout = timeout
self.identifier = str(uuid.uuid4())
def acquire_read(self) -> bool:
lua = """
if redis.call("exists", KEYS[2]) == 1 then
return 0
end
redis.call("hincrby", KEYS[1], "readers", 1)
redis.call("expire", KEYS[1], ARGV[2])
return 1
"""
result = self.redis.eval(lua, 2, self.read_lock_name, self.write_lock_name, self.identifier, str(self.timeout))
return result == 1
def release_read(self) -> bool:
lua = """
local count = redis.call("hincrby", KEYS[1], "readers", -1)
if count <= 0 then
redis.call("del", KEYS[1])
end
return 1
"""
self.redis.eval(lua, 1, self.read_lock_name, self.identifier)
return True
def acquire_write(self) -> bool:
result = self.redis.set(self.write_lock_name, self.identifier, nx=True, ex=self.timeout)
if result is None:
return False
lua = """
if redis.call("exists", KEYS[1]) == 1 and redis.call("hget", KEYS[1], "readers") ~= "0" then
redis.call("del", KEYS[2])
return 0
end
return 1
"""
check = self.redis.eval(lua, 2, self.read_lock_name, self.write_lock_name, self.identifier)
return check == 1
def release_write(self) -> bool:
lua = """
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0
end
"""
result = self.redis.eval(lua, 1, self.write_lock_name, self.identifier)
return result == 1
3. Lock Monitoring Metrics Collection
package distlock
import (
"context"
"fmt"
"time"
"github.com/redis/go-redis/v9"
)
type LockMetrics struct {
LockName string
CurrentHolder string
RemainTTL time.Duration
AcquireCount int64
WaitQueueLen int64
}
func CollectLockMetrics(ctx context.Context, client *redis.Client, lockName string) (*LockMetrics, error) {
key := fmt.Sprintf("lock_service:%s", lockName)
ttl, err := client.TTL(ctx, key).Result()
if err != nil {
return nil, err
}
identifier, _ := client.HGet(ctx, key, "identifier").Result()
count, _ := client.HGet(ctx, key, "count").Int64()
queueKey := fmt.Sprintf("fair_lock_queue:%s", lockName)
queueLen, _ := client.ZCard(ctx, queueKey).Result()
return &LockMetrics{
LockName: lockName,
CurrentHolder: identifier,
RemainTTL: ttl,
AcquireCount: count,
WaitQueueLen: queueLen,
}, nil
}
Comparison Analysis
| Dimension | SET NX EX | Reentrant Lock | Watchdog Lock | Redlock | Production Lock Service |
|---|---|---|---|---|---|
| Complexity | ⭐ Low | ⭐⭐ Medium | ⭐⭐⭐ High | ⭐⭐⭐ High | ⭐⭐⭐⭐ Very High |
| Atomicity | ⚠️ Needs Lua | ✅ Lua guaranteed | ✅ Lua guaranteed | ✅ Multi-node | ✅ Lua guaranteed |
| Reentrant | ❌ | ✅ | ✅ | ❌ | ✅ |
| Auto-renewal | ❌ | ❌ | ✅ | ❌ | ✅ |
| Multi-node fault tolerance | ❌ | ❌ | ❌ | ✅ | Optional |
| Prevents mis-deletion | ⚠️ Needs Lua | ✅ | ✅ | ✅ | ✅ |
| GC tolerance | ⭐ High | ⭐ High | ⚠️ Medium | ⭐ High | ⚠️ Medium |
| Production recommendation | Prototyping | Standard business | Long transactions | High availability | Critical paths |
Summary: Redis distributed locks aren't about "one command" — they're about "a complete system". From SET NX EX to production-grade lock services, the core principles are only three: use Lua for atomic operations, renew lock timeouts, verify owner before unlocking. Redlock is over-engineering for most scenarios — single-node + Sentinel HA handles 99% of business cases. Only invest in Redlock multi-node solutions for critical paths where lock failure causes severe data inconsistency.
Recommended Online Tools
- Hash Calculator: /en/encode/hash
- JSON Formatter: /en/json/format
- Base64 Encode/Decode: /en/encode/base64
- JWT Decode: /en/encode/jwt-decode
Try these browser-local tools — no sign-up required →
#Redis#分布式锁#Redlock#并发控制#分布式系统#2026#Redisson