zclaw_openfang/docs/knowledge-base/axum-dashmap-deadlock.md

Axum + DashMap 运行时死锁：根因分析与修复

2026-03-30 | 严重级别: P0 | 影响范围: SaaS 后端所有 protected route

---

问题描述

Admin V2 管理后台（Ant Design Pro SPA）浏览器访问后端时，protected route 的 handler 链进入后永不返回。后端冻结，health 端点也无响应，必须 kill 进程重启。

关键特征:

• curl 单请求测试一切正常（包括 abort 模拟）
• 浏览器访问必然触发冻结
• TimeoutLayer（15s）无法触发超时
• health 端点（public route，不经过 auth 中间件）正常返回
• protected routes（经过 auth → rate_limit → request_id → api_version 中间件链）全部卡死

---

根本原因

直接原因：DashMap RefMut 跨 .await 持有

rate_limit_middleware（middleware.rs）中，DashMap::entry().or_insert_with() 返回的 RefMut 持有 parking_lot::RwLockWriteGuard，跨越了 next.run(req).await。

// ❌ 原始代码（有 bug）
let mut entries = state.rate_limit_entries.entry(key).or_insert_with(Vec::new);
entries.retain(|&time| time > window_start);
entries.push(now);

next.run(req).await  // ← RefMut 仍持有 parking_lot shard 写锁！

死锁机制

时间线:
T0: Worker Thread 1 → 请求 A 获取 DashMap shard X 写锁 → await DB 查询 → yield
T1: Worker Thread 2 → 请求 B 尝试获取 shard X 写锁 → parking_lot 阻塞 → Thread 2 冻结
T2: Worker Thread 3 → 请求 C 尝试获取 shard X 写锁 → parking_lot 阻塞 → Thread 3 冻结
...
TN: 所有 Worker Thread 都被 parking_lot 阻塞 → Tokio 运行时无法调度任何 task
    → TimeoutLayer 的 timeout future 无法被 poll → 超时机制失效
    → 运行时全局死锁

为什么 curl 不触发

curl 每次发送单个请求，请求完成后连接关闭。没有并发争抢同一 DashMap shard 的场景。

为什么浏览器触发

浏览器对同一域名默认保持 6 个并发连接（HTTP/1.1 RFC 规范）。SPA 页面加载时同时发起多个 API 请求（dashboard stats、logs、models 等），这些请求都使用同一 JWT token → 同一 account_id → 同一 DashMap shard key。

---

解决方案

核心修复：作用域块限定 DashMap 锁

将 DashMap 操作限定在独立的作用域块 { ... } 内，确保 RefMut（持有 parking_lot 锁）在 next.run(req).await 之前 drop：

// ✅ 修复后代码
let blocked = {
    let mut entries = state.rate_limit_entries.entry(key).or_insert_with(Vec::new);
    entries.retain(|&time| time > window_start);

    if entries.len() >= rate_limit {
        true
    } else {
        entries.push(now);
        false
    }
}; // ← RefMut 在此处 drop，释放 parking_lot shard 锁

if blocked {
    return SaasError::RateLimited(...).into_response();
}

next.run(req).await  // 安全：无同步锁持有

附加修复

修复项	文件	说明
ConnectInfo 提取	main.rs	into_make_service() → into_make_service_with_connect_info::<SocketAddr>()，修复 login handler 的 IP 提取
移除诊断中间件	main.rs	移除 close_connection_middleware 和 diag_middleware
AbortSignal 链路	admin-v2/src/services/	44 个 service 方法 + 17 个 useQuery 传入 signal，页面切换时自动取消请求
Vite proxy 超时	admin-v2/vite.config.ts	proxy timeout 30s + configure hook
PG 连接池调优	db.rs	max=20, min=2, acquire=5s, idle=180s

---

验证结果

测试项	结果
Health check	200, ~0.2s
Login + JWT 获取	200, token 正常
Dashboard API	200, ~0.23s
Logs API	200, ~0.22s
8 并发同端点	全部 200, <0.25s
10 并发混合端点	全部 200
并发后 health check	200, 正常

---

防范模式

Rust async 中同步锁使用规则

绝对禁止：在 .await 点持有任何同步锁（std::sync::Mutex、parking_lot::Mutex、parking_lot::RwLock、DashMap::Ref/RefMut）。

// ❌ 危险：同步锁跨 await
let guard = some_sync_lock.lock();
do_async_work().await;  // guard 仍持有！

// ✅ 安全：作用域块确保锁释放
let result = {
    let guard = some_sync_lock.lock();
    compute_something(&guard)
}; // guard drop
do_async_work(result).await;  // 安全

何时用 tokio::sync vs parking_lot

场景	推荐	原因
短暂持有，无 .await	parking_lot / DashMap	性能更好，无 async 开销
需要跨 .await 持有	tokio::sync::Mutex / RwLock	guard 是 Send，yield 友好
高并发读多写少	DashMap（但注意作用域）	分片锁，读不阻塞
需要跨 .await 持有 + 高并发	tokio::sync::RwLock 或消息传递	避免锁竞争

代码审计清单

审计 crates/zclaw-saas/src/ 下所有 DashMap 使用：

文件	使用位置	状态
middleware.rs	rate_limit_entries.entry()	✅ 已修复，作用域块限定
state.rs	rate_limit_entries.retain() (cleanup)	✅ 安全，同步函数无 .await
state.rs	role_permissions_cache 定义	✅ 安全，只在 handlers.rs 中使用
auth/handlers.rs	get_role_permissions() 中 .get()	✅ 安全，guard 在 .await 前 drop（但模式脆弱，建议后续重构）

---

外部参考

• DashMap Issue #79: Deadlock in async threads — DashMap 维护者确认的 canonical issue
• Beware of the DashMap Deadlock — 深入分析 DashMap 死锁机制
• How to Prevent Async Deadlocks in Rust — 同步锁跨 await 的通用模式
• Turso: How to deadlock Tokio with just a single mutex — 单锁即可死锁运行时的最小复现
• Hyper Issue #2366: Server stops accepting connections — Hyper 层面的连接累积问题
• Axum Discussion #1094: Detect connection closed — handler 中检测客户端断开

---

相关文件

文件	角色
crates/zclaw-saas/src/middleware.rs	rate_limit_middleware — 修复点
crates/zclaw-saas/src/auth/mod.rs	auth_middleware — 中间件链上层
crates/zclaw-saas/src/state.rs	AppState 定义，含 DashMap 字段
crates/zclaw-saas/src/main.rs	路由构建、TimeoutLayer、ConnectInfo
crates/zclaw-saas/src/db.rs	PG 连接池配置
admin-v2/src/services/request.ts	AbortSignal 传递工具函数
admin-v2/vite.config.ts	Vite 代理超时配置