用 Rust 从零实现分布式锁:为什么必须有 fencing token
分布式锁是那种"写起来只要二十行,但正确性很难保证"的典型。
不夸张地说,一个只有 lock 和 unlock 两个方法的分布式锁,在绝大多数情况下都是不安全的。 原因是一个很简单的场景:
T+0 客户端 A 获取锁,租约 10 秒
T+1 A 开始处理,但它遭遇了一次长时间的 STW GC
T+11 A 的租约过期,锁被自动释放
T+11 客户端 B 获取锁,开始处理
T+12 A 的 GC 结束,它以为自己还持锁,继续写数据
—— 现在 A 和 B 同时在写问题的根源不是锁实现得不对,而是"持锁者无法感知自己失去锁"这件事无法避免。
这篇从零实现一个分布式锁,重点讲清楚怎么用 fencing token 把这个问题兜住。
先明确锁的接口,以及它做不到什么
pub trait DistributedLock {
/// 尝试获取锁,成功返回一个守卫(drop 时释放)
fn try_acquire(
&self,
key: &str,
ttl: std::time::Duration,
) -> Result<Option<LockGuard<'_>>, LockError>;
}注意返回的是 guard 而不是 bool。 因为"释放锁"必须绑定到生命周期上——忘记释放就是死锁。
但即使是这样的接口,它仍然无法解决上面那个 GC 场景。所以正确的认知是:
分布式锁保证的是"在租约有效期内,只有一个人认为自己持锁"。它不保证"只有一个人在操作共享资源"。
要保证后者,需要共享资源那一侧配合 —— 这就是 fencing token 的作用。
基础实现:Redis SET NX EX
最常用的实现基于 Redis 的单条命令:
SET key <token> NX EX <ttl_seconds>NX 保证"只在 key 不存在时设置",EX 设置过期时间。这两者必须是一条命令的原子操作。
pub struct RedisLock {
client: redis::Client,
/// 每个锁实例有一个唯一 id,用于"只释放自己的锁"
instance_id: String,
}
impl RedisLock {
pub fn try_acquire(
&self,
key: &str,
ttl: std::time::Duration,
) -> Result<Option<LockGuard<'_>>, LockError> {
let mut conn = self.client.get_connection()?;
let token = self.instance_id.clone();
// 关键:NX + EX 一次完成,不能拆成两条命令
let result: Option<String> = redis::cmd("SET")
.arg(key)
.arg(&token)
.arg("NX")
.arg("EX")
.arg(ttl.as_secs())
.query(&mut conn)?;
match result {
Some(_) => Ok(Some(LockGuard {
lock: self,
key: key.to_string(),
token,
released: false,
})),
None => Ok(None), // 别人持锁
}
}
}为什么必须用 SET NX EX 而不是 SETNX + EXPIRE?
因为拆成两条命令的话,中间会有窗口:
客户端: SETNX key token -> OK
客户端: [崩溃了]
—— 这个 key 永远不会过期,锁永久泄漏 ——这是分布式锁最经典的实现错误。 一条命令完成"判断 + 设置 + 过期",才能保证原子性。
任何"先检查再设置"的分布式锁实现都是错的,无论它用的是 Redis、etcd 还是数据库。原子性必须由存储层提供。
释放锁:必须校验持有者
释放锁不能简单 DEL:
// 错误!这会把别人的锁删掉
conn.del(key)?;场景:
T+0 A 获取锁,token = "A",ttl = 10s
T+11 A 的锁已过期,B 获取锁,token = "B"
T+12 A 处理完,执行 DEL key -> 把 B 的锁删了!
T+13 C 获取锁成功 -> B 和 C 同时持锁正确做法是"只删自己的锁":
if redis.call('GET', KEYS[1]) == ARGV[1] then
return redis.call('DEL', KEYS[1])
else
return 0
end同样必须是原子的,所以用 Lua:
const RELEASE_SCRIPT: &str = r#"
if redis.call('GET', KEYS[1]) == ARGV[1] then
return redis.call('DEL', KEYS[1])
else
return 0
end
"#;
impl Drop for LockGuard<'_> {
fn drop(&mut self) {
if self.released {
return;
}
if let Ok(mut conn) = self.lock.client.get_connection() {
let _: Result<i32, _> = redis::Script::new(RELEASE_SCRIPT)
.key(&self.key)
.arg(&self.token)
.invoke(&mut conn);
}
}
}Lua 脚本在 Redis 里是原子执行的,所以"GET + 比较 + DEL"三步不会被别的命令插入。
续租:处理"处理时间超过 TTL"
TTL 设短了,业务没跑完锁就过期;设长了,持锁者崩溃后别人要等很久。
解法是后台自动续租(watchdog):
pub struct LockGuard<'a> {
lock: &'a RedisLock,
key: String,
token: String,
released: bool,
/// 续租线程的停止信号
stop_renew: std::sync::Arc<std::sync::atomic::AtomicBool>,
renew_thread: Option<std::thread::JoinHandle<()>>,
}启动续租线程:
impl<'a> LockGuard<'a> {
fn start_renewal(&mut self, ttl: std::time::Duration) {
let client = self.lock.client.clone();
let key = self.key.clone();
let token = self.token.clone();
let stop = self.stop_renew.();
// 每 TTL/3 续一次
let interval = ttl / 3;
self.renew_thread = Some(std::thread::spawn(move || {
while !stop.load(std::sync::atomic::Ordering::Acquire) {
std::thread::sleep(interval);
if stop.load(std::sync::atomic::Ordering::Acquire) {
break;
}
// 只有"锁还是我的"才续期
if !renew_once(&client, &key, &token, ttl) {
// 续租失败 = 我已经失去锁了
// 这里必须有办法通知业务代码!
eprintln!("锁 {key} 续租失败,可能已失去锁");
break;
}
}
}));
}
}
fn renew_once(client: &redis::Client, key: &str, token: &str, ttl: std::time::Duration) -> bool {
const RENEW_SCRIPT: &str = r#"
if redis.call('GET', KEYS[1]) == ARGV[1] then
return redis.call('EXPIRE', KEYS[1], ARGV[2])
else
return 0
end
"#;
let Ok(mut conn) = client.get_connection() else {
return false;
};
redis::Script::new(RENEW_SCRIPT)
.key(key)
.arg(token)
.arg(ttl.as_secs())
.invoke::<i32>(&mut conn)
.map(|r| r == 1)
.unwrap_or(false)
}watchdog 有个致命的局限:它解决不了 STW 停顿。
因为 GC 停顿的时候,续租线程也在停顿。A 在 T+1 开始 GC,续租线程同样被冻结,锁在 T+11 过期——watchdog 完全无效。
watchdog 能处理"处理时间比预期长",但处理不了"进程被暂停"。 而后者恰恰是分布式锁最危险的一类失效。
真正的解法:fencing token
这是本文最核心的部分。思路是:给每次获取锁分配一个单调递增的编号,让共享资源自己拒绝过期的请求。
T+0 A 获取锁,得到 token = 33
T+11 A 的锁过期,B 获取锁,得到 token = 34
T+12 A 醒来,带着 token = 33 去写存储
存储发现 33 < 34(当前见过的最大值)
-> 拒绝 A 的写入
T+12 B 带着 token = 34 写入 -> 接受关键在于:共享资源(数据库、文件系统、存储服务)必须记录"见过的最大 token",并拒绝更小的。
token 怎么生成?用 Redis 的 INCR:
impl RedisLock {
pub fn try_acquire_with_fence(
&self,
key: &str,
ttl: std::time::Duration,
) -> Result<Option<FencedLockGuard<'_>>, LockError> {
let mut conn = self.client.get_connection()?;
// 用一个独立的计数器生成单调递增的 token
let fence: u64 = redis::cmd("INCR")
.arg(format!("{key}:fence"))
.query(&mut conn)?;
let token = format!("{}:{}", self.instance_id, fence);
let result: Option<String> = redis::cmd("SET")
.arg(key)
.arg(&token)
.arg("NX")
.arg("EX")
.arg(ttl.as_secs())
.query(&mut conn)?;
match result {
Some(_) => Ok(Some(FencedLockGuard {
key: key.to_string(),
token,
fence,
// ...
})),
None => Ok(None),
}
}
}pub struct FencedLockGuard<'a> {
pub fence: u64, // 业务代码需要这个值
// ...
}业务侧怎么用:
let Some(guard) = lock.try_acquire_with_fence("lock:order:42", Duration::from_secs(10))? else {
return Err(Error::LockBusy);
};
// 把 fence 传给存储层
storage.write_with_fence("order:42", &data, guard.fence)?;存储层:
impl Storage {
pub fn write_with_fence(&self, key: &str, data: &[u8], fence: u64) -> Result<(), StoreError> {
let mut meta = self.meta.lock().unwrap();
let seen = meta.fences.entry(key.to_string()).or_insert(0);
// 核心:拒绝比已见过的更小的 token
if fence < *seen {
return Err(StoreError::StaleFence {
got: fence,
current: *seen,
});
}
*seen = fence;
// 真正写入
self.data.insert(key.to_string(), data.to_vec());
Ok(())
}
}这个检查只有一行,但它是分布式锁安全性的全部。
| 方案 | 能防止"过期持锁者写数据"吗 |
|---|---|
| 只有 TTL 的锁 | ❌ |
| TTL + watchdog 续租 | ❌(GC 停顿下失效) |
| TTL + fencing token | ✅ |
分布式锁的安全性不来自锁本身,而来自"被保护的资源能识别过期的持有者"。 这是分布式锁最重要的一条认知。
注意:不是所有存储都支持 fencing。 需要存储层能做"条件写入":
| 存储 | 能否做 fencing |
|---|---|
| 数据库(条件 UPDATE) | ✅ UPDATE ... WHERE fence < ? |
| ZooKeeper(zxid/版本号) | ✅ 自带单调版本 |
| etcd(revision) | ✅ 自带单调 revision |
| 对象存储 | ❌ 没有条件写(S3 有 conditional put) |
| 普通文件系统 | ❌ |
这也解释了为什么 ZooKeeper 和 etcd 是"更正确"的分布式锁选择——它们天然提供了单调递增的版本号,本身就是 fencing token。
etcd 版本:租约 + revision
etcd 的设计比 Redis 干净得多,因为它把两个概念分开了:
- Lease(租约):独立的对象,有过期时间,需要定期续租(KeepAlive)
- Revision:全局单调递增的版本号,每次写入都递增
pub struct EtcdLock {
client: etcd_client::Client,
}
impl EtcdLock {
pub async fn acquire(&mut self, key: &str, ttl: i64) -> Result<LockHandle, LockError> {
// 1. 创建一个租约
let lease = self.client.lease_grant(ttl, None).await?.id();
// 2. 用事务"只在 key 不存在时写入",同时绑定租约
let txn = etcd_client::Txn::new()
.when(vec![etcd_client::Compare::create_revision(
key, "=", 0,
)])
.and_then(vec![etcd_client::TxnOp::put(
key,
self.client_id.as_bytes(),
Some(etcd_client::PutOptions::new().with_lease(lease)),
)]);
let resp = self.client.txn(txn).await?;
if !resp.succeeded() {
return Err(LockError::Busy);
}
// 3. revision 就是天然的 fencing token
let fence = resp.header().unwrap().revision();
Ok(LockHandle {
key: key.to_string(),
lease,
fence,
})
}
}etcd 的三个优势:
- 租约和 key 分离:一个租约可以绑定多个 key,续租只需要一次请求
- revision 天然单调:直接就是 fencing token,不需要额外
INCR - 支持 watch:可以实现"排队等锁",而不是轮询
etcd 的线性一致性(基于 Raft)也保证了它不会出现"脑裂写"。 Redis 主从切换时,可能出现"锁在一个节点上,切换到新主之后锁消失了"的问题——这是 Redis 分布式锁在故障场景下的真实弱点。
锁的两个高级形态
1. 公平锁(排队)。 上面的实现都是"抢",抢不到就重试。重试是浪费——大量客户端同时轮询会给存储层造成压力。
etcd 可以做真正的排队:
1. 所有竞争者按 revision 顺序创建一个临时 key(如 lock/req-<revision>)
2. 每个竞争者 watch 自己前一个 key
3. 前面的 key 被删除时,自己被唤醒这实现了严格的先来先服务,而且没有任何轮询。
2. 可重入锁。 同一个客户端再次获取自己已持有的锁时,不应该阻塞。做法是记录"持有者 + 重入次数":
const REENTRANT_ACQUIRE: &str = r#"
local value = redis.call('GET', KEYS[1])
if value == false then
-- 没人持锁,直接获取
redis.call('SET', KEYS[1], ARGV[1] .. ':1', 'EX', ARGV[2])
return 1
end
local owner, count = string.match(value, '(.+):(%d+)$')
if owner == ARGV[1] then
-- 是我自己的锁,重入次数 +1
redis.call('SET', KEYS[1], ARGV[1] .. ':' .. (tonumber(count) + 1), 'EX', ARGV[2])
return 1
end
return 0
"#;可重入锁有个隐患:重入次数如果不平衡(多释放一次),锁会被提前释放。所以重入计数必须在同一个进程内严格配对,通常用 RAII guard 的嵌套来保证。
结论
分布式锁的正确性是一条递进的链:
第一层:
SET NX EX一条命令完成,保证原子性;释放时校验持有者,防止误删。 第二层:TTL + watchdog 续租,处理"处理时间超预期"。 第三层:fencing token,处理"进程被暂停导致锁过期但自己不知道"——只有它才能真正保证安全。
三条实践原则:
- 能不用分布式锁就不用。 幂等 + 唯一约束、乐观锁(版本号 CAS)通常比分布式锁更简单也更安全。
- 如果一定要用,优先选 etcd/ZooKeeper。 它们的租约和单调版本号是内建能力,Redis 需要自己拼。
- 锁必须配合被保护资源的校验。 无论用什么实现,只要被保护的资源不做 fencing 检查,锁的安全性就只是"大多数时候没问题"。
理解这三点之后,你对"分布式锁"的期望会变得更准确——它不是一个能替你保证互斥的魔法,而是一个"让大多数情况下只有一个写入者"的优化,真正的安全性必须落在存储层。