WuKongIM 三节点压力测试实录：从 4000 QPS 容量门槛到存储尾部延迟的完整归因方法-平芜编程栈

即时通讯
后端

【免费下载链接】WuKongIM

More than just IM 不只是即时通讯(IM)

项目地址：https://gitcode.com/gh_mirrors/wu/WuKongIM

本文基于 WuKongIM 仓库的开发记录 WKSIM_STRESS_FINDINGS.md 整理，系统梳理该仓库在 2026 年 6 月至 8 月间对本地三节点群聊场景开展的一轮持续压测：从channelwrite工作线程调优、commit coordinator 分片收敛、Pull 批处理改造，到存储 backing-device 归因、传输层writev写形状优化，再到 wkcli sim 压测器的 4000 SEND/s 验收。读完本文，你可以掌握一套“单变量实验 + pprof 归因 + 门槛（gate）验收”的 IM 集群压测方法论，以及 WuKongIM 当前 4000 QPS 稳定容量结论背后的全部证据链。

压测基线：脚本、负载形态与验收门槛

所有关键结论都来自同一套可复现的压测工具链：

真实 QPS 基线脚本 scripts/bench-wukongim-three-nodes-real-qps.sh：默认 1000 个群频道、4096 在线用户、每群 10 成员，支持--qps LIST（每个 QPS 值独立冷启动一轮）、--duration、--warmup、--cooldown、--stable-p99（p99 门槛）、--min-actual-ratio（默认 0.95）、--sender-pick（round_robin/first_online）、--profile-seconds（在压测窗口内对每个节点抓取 CPU pprof）等参数，并把每轮证据落到docs/development/perf-runs/<时间戳>-three-node-real-qps/目录；
三节点启动脚本 scripts/start-wukongim-three-nodes.sh：支持--data-root/ 环境变量WK_WUKONGIM_THREE_NODES_DATA_ROOT为三个节点指定独立数据目录（后期用于把某个节点挂到 RAM 卷做存储归因）；
wkcli 模拟压测脚本 scripts/smoke-wkcli-sim-wukongim-three-nodes.sh：面向wkcli sim客户端模拟，暴露--connect-rate与--concurrency两个参数并写入证据；脚本中默认以WK_GATEWAY_RUNTIME_ASYNC_SEND_WORKERS=4096启动集群的 Gateway 异步 SEND 工作池、以WK_DELIVERY_RECIPIENT_WORKER_CONCURRENCY=800启动投递接收方工作池；
群频道基准脚本 scripts/bench-wukongim-three-nodes-1000ch.sh，被 real-qps 脚本作为子 runner 复用，默认--sender-pick round_robin。

验收门槛（gate）的统一形态是：在测量run阶段内，实际 QPS/目标 QPS 比例达标（≥0.95）且 p99 延迟不越门槛（多数轮次采用 400ms 门槛），并要求连续通过重复轮（30s）才算稳定结论。这一标准贯穿全文，也是后续大量“拒绝实验”的判定依据。

channelwrite 工作线程系列实验：先解开前台准入的瓶颈

2026-06-09 起的几轮 5000/10000 QPS 压测发现，前台吞吐的第一限制因素是channelwrite的 append-effect 并发：

5000 QPS 基线：默认WK_DELIVERY_CHANNEL_WRITE_EFFECT_WORKERS=0解析为每 reactor 2 个 effect worker，把channel/store_appendinflight 压到每节点 20，只能跑出 2651.9 实际 QPS、p99 2334.2ms；
单变量实验：设为 8 后实际 QPS 跳到 4917.6、p99 977.7ms，store_append/store_apply打到 64 inflight，瓶颈移到存储/复制；设为 4 时 4338.4 QPS、p99 1550.2ms；
结论：默认ChannelWriteEffectWorkers从每 reactor 2 提升到 8 并保留环境变量显式覆盖。

10000 QPS 形态下，effect workers=16 会把瓶颈进一步后移：channelwrite准入保持干净（router 错误、背压、channel-busy 拒绝、本地准入拒绝全为零），但 post-commit 积压最高 5275、effect error 增量 91329，下游store_append/store_apply/channel/rpc全部饱和。为此文档记录了后续三处改造（对应 internal/runtime/channelappend 与 app 层 channelwrite 路径）：

指标先行：新增channelwriteeffect worker 的 inflight/容量/队列深度/队列容量 gauge，父汇总暴露cw_wkr（最大 effect worker 利用率）与cw_eq（最大 effect 队列填充率）。验证轮中cw_wkr=1.000、cw_eq=0.023，证明饱和点在 post-commit 路径而非准入或 effect 队列容量；
解耦接收方派发并发：EffectWorkerCount同时约束了 post-commit 外层 worker 与每条消息的 recipient-authority 派发扇出，把二者绑死导致“翻倍 worker”同时翻倍内层扇出。新增WK_DELIVERY_CHANNEL_WRITE_RECIPIENT_DISPATCH_CONCURRENCY（默认 4）独立控制，10000 QPS 下实际吞吐从 6949.5 提升到 8646.2；
post-commit 副作用改为 best-effort：conversation/push 这类 SENDACK 之后的旁路效果不再重试，失败经PostCommitFailureObserver（见 internal/runtime/channelappend/observer.go）记录、由 effect 指标计数后直接丢弃，post-commit cursor 的 checkpoint/replay 禁用；同时ConversationAuthorityClient.AdmitPatches不再对 route-not-ready / stale-route / not-leader 重试，一次性解析 UID authority 目标并直接返回首个错误。验证轮 post-commit backlog 归零（channelwrite_post_commit_backlog_max=0），post-commit 错误从数千降到 257，且全部集中在测量开始首秒的no slot leader瞬态。

3000→4000 QPS：commit coordinator、mailbox 与 Pull 批处理

2026-07-12 的 3000 QPS 轮确立了三个默认值并首次推高稳定门槛：

commit coordinator 8 分片 → 1 分片：8 个 coordinator 共享同一 Pebble DB 时碎片化了同步组提交。单分片使每次物理提交的逻辑请求数提高约 3.9 倍、物理提交频率下降约 72%、物理提交 p99 从 155-222ms 降到 57-61ms；三节点 Docker 与 real-QPS 配置随之默认 1 分片。
mailbox 预分配收敛：每个 Channel reactor 曾预分配 3 条 1024 条目的 1096 字节Eventchannel，128-reactor 形态下每节点预留约 411MiB 而实际 mailbox 深度恒为 0。三节点基准默认降到 32 reactors 后，峰值 RSS 从 1.4-1.7GiB 降到 0.73-1.03GiB，实际 QPS 不受影响。
ObserverDrain 准入栅栏：非终态ObserverDrain.ObserveTransport原每事件要走两个 select，改为“计数原子准入栅栏 + 一次非阻塞 send”，微基准从 86.6-88.8ns/op 降到 77.0-78.4ns/op 且零分配；仅靠 stopped-bit 的更快原型因可能在Stopdrain 后仍入队而被否决。

验证：30s 轮 2994.8 QPS、0.998 比例、p99 346.8ms、零发送错误；15s profile 轮同样通过。随后AckOffset Pull 批处理把稳定门槛从 3000 推到 4000：Pull 主导的收集窗口最多收 4 个相邻项（PullHint 主导仍限 2，二者均保留 250us 收集窗口），首个任务决定策略，后续混合类型/目标以串行子组执行。3500 QPS A/B 中 Pull 传输调用数降约 28.6%，follower apply-to-ACK p99 改善 32-51%；4000 QPS 的 15s 与 30s 轮双双通过（30s 轮 3990.9 QPS、0.998、p99 284.6ms），且未改动同步持久化与 quorum ACK 语义。4500 QPS 当时只能过一轮 15s，30s 重复失败（p99 786.0ms），文档据此明确“稳定上限 = 4000 QPS”，并要求先用 leader 侧 PullBatch 观测（提交到全部 await 的时延、最慢 future、批大小、返回记录/字节数）来决定是否做 target-aware 收集。

4500 QPS：Pull 观测细化与 channelWriter 空转修复

同日的 4500 QPS 专项做了两件重要的归因：

Pull 观测细化：leader PullBatch 指标拆分 batch items/records/字节数、submit 时间、all-future await、最慢串行 await、总时长、RPC worker 队列等待、leader mailbox 等待、AckOffset apply、handler 时间与完成的 waiter 数。数据显示 leader 的 AckOffset apply 与 handler p99 < 0.5ms，而 PullBatch all-future await 约 47-69ms、RPC worker 队列等待 101-144ms、follower Pull RPC 215-225ms——剩余前台尾延迟是“调度 + 存储/quorum 等待”，不是 Pull handler CPU。
channelWriter 空转（gap-spin）修复：pprof 显示channelWriter.advance占 14-30% 累计 CPU——乱序 append 完成在等待更早 sequence 时被误判为 runnable，deactivateLocked立即重新激活 writer 空转到缺失回调到达。修复后 internal/runtime/channelappend/state.go 中hasRunnableWork不再把 completion gap 视为 runnable（缺口是 pending 状态，只有缺失的完成回调能关闭 ordered-drain 缺口），internal/runtime/channelappend/writer.go 的deactivateLocked/rescheduleIfNeeded因此不再反复空转。同形态 10s 4500 QPS profile 下channelWriter.advance累计 CPU 降到 1.3-1.9%，RPC Pull 任务 p99 从 151-182ms 降到 97-100ms，post-store commit wait 从 393-422ms 降到 324-351ms。

门槛结果诚实记录为一过一不过（387.0ms / 445.5ms 两次 30s 轮），因此稳定门槛维持 4000 QPS。被否决实验同样留档：64 reactors 使 mailbox 内存翻倍、16 reactors/192 RPC workers/Pull cap 8 首轮好但重复失败、多目标投递打包让前台 p99 全轮变差、并发 owner push 把 Channel append p99 推到 746-801ms。

存储归因：backing device 决定 commit 尾延迟

2026-07-12 的 4500 QPS 存储分离实验是全文档最具方法论价值的一节。三节点共用一块 APFS 物理卷且剩余空间 <1% 时，4480.2 实际 QPS、零错误，但 p99 563.1ms、物理提交 p99 94-99ms、逻辑请求 p99 约 239ms——尽管每节点只写约 17.8MB，说明瓶颈是 fsync 延迟而非顺序带宽。

同窗口分离探针：node1 挂 4GiB APFS RAM 卷、node2/node3 留在宿主盘。node1 物理提交 p99 降到 8.9ms、逻辑请求 p99 58.8ms；两个宿主节点物理 101-128ms、逻辑 847-907ms。直接证明 backing device 实质控制观察到的 commit 尾延迟；
全 RAM 归因：同拓扑三节点全 RAM 跑 4496.2 QPS、0.999 比例、p99 223.2ms、零错误，物理提交 p99 8.4-10.0ms。文档明确标注这是“软件路径归因”，不是生产持久化或容量证据；
被否决的调优：commit shards=2 把物理提交 p99 抬到 192-218ms；“depth-2 并发同步提交”原型端到端 p99 1695.2ms 且有物理顺序风险；delivery workers=128 仍以 506.9ms 失败；PullHint 子组优先级降低 Hint 任务延迟却把最终 p99 抬到 647.3ms。所有代码实验均回滚。

后续 2026-07-13 的 4000 QPS 存储/coordinator 边界轮复现了同一结论：宿主基线 3981.8 QPS、p99 622.1ms（物理提交 p99 89-97ms、逻辑请求 226-233ms），全 RAM 同拓扑 3996.7 QPS、p99 229.8ms（物理提交 8.5-9.3ms、逻辑 40-48ms）。并给出机制性解释：串行同步提交下，落在慢 fsync 之后的请求可能同时等待当前物理提交和包含自身变更的下一个提交；在准入队列与 flush 窗口有界的前提下，默认收集没有正的请求/记录/字节上限，放大收集窗口或并发 sync commit 都消除不了设备尾部。下一步安全改进是“每节点独立低延迟存储 + 保持同步持久化”，并给出了复现命令：宿主基线GOWORK=off scripts/bench-wukongim-three-nodes-real-qps.sh --qps 4500 --duration 30s --out-dir <evidence-dir>，存储归因则挂载目标卷后以WK_WUKONGIM_THREE_NODES_DATA_ROOT=<mounted-path>重跑且保持同步提交。

传输层写形状：观测驱动的机会式合并

同日的 4000 QPS 传输两轮分别解决分配与 syscall 两个问题：

分配调优。三节点采样窗口基线分配 3177.7MB，其中transport/internal/sched.(*Scheduler).nextBatchLocked（见 pkg/transport/internal/sched/scheduler.go）因每个写批物化一个观测事件 slice 分配 428.5MB，Prometheus label 绑定分配 450.5MB。修复后调度器出队只记录一个定长批观测、在释放锁后重建逐项 wait 观测与 touched-lane 队列观测；runtime-pressure 指标缓存已绑定的低基数 Prometheus 子指标。微基准证据：64 帧批处理从约 8.2-9.8us/op、10880B/op、1 alloc/op 降到 6.78-6.80us/op、0B/op、0 alloc/op。最终 profile 采样分配降到 1641.6MB（-48.3%），constrainLabelValues从 450.5MB 降到 38.0MB；无 profile 同负载 3985.4 QPS、0.996 比例、零错误、p99 306.7ms 通过 400ms 门槛，RPC worker 队列等待从 92-96ms 降到 49-59ms，follower Pull RPC 从 164-189ms 降到 84-92ms。

写形状与机会式合并。观测显示三节点 2447646 个成功writev批承载 3254612 帧，平均批大小仅 1.330 帧、94.23% 的单帧批、只有 0.0198% 触及 64 帧上限——因此“调大MaxBatchFrames”不被数据支持。实际改动：连接在写前执行一次非阻塞、复用分配的调度器 drain，收集首次唤醒后到达的积压，不引入任何定时器、sleep 或 Raft/Control 延迟；同一窗口内writev调用/帧从 0.7521 降到 0.6926（-7.9%），平均批大小升到 1.444。profile 显示三节点合并 CPU 中writev仍占 34.23s/90.59s（37.79%），所以机会式 drain 只是“有界改进”。文档还明确记录了一个被否决的 localhost 微基准更快的连续小单帧write原型：真实运行保不住延迟门槛即回滚，且后续复跑退化到 p99 1605.9ms（当时 APFS 仅剩 6% 空间）——结论是不要在未换独立低延迟存储前追加计时合并窗口或抬高稳定容量声明。

wkcli sim 压测器：4000 SEND/s 的 pacing 与有界准入验收

2026-08-04 的专项证明了一个容易忽视的问题：达不到目标 QPS 时，先怀疑压测器自己。场景为 scripts/smoke-wkcli-sim-wukongim-three-nodes.sh 的 2000 用户、2000 群、每群 10 成员、--rate 2/s（rate 是每群速率，聚合目标 4000 SEND/s；原始命令--rate 4/s实际是 8000）。

基线证据：smoke 默认（--connect-rate 20 --concurrency 64）只跑出 728.3 SEND/s；把客户端并发提到 1536 后仍是 3084.8 SEND/s，Gateway 异步派发等待平均 167.2ms——因为该 smoke 未注入已验证的 2048 worker 吞吐 profile；
压测器修复：per-message 间隔 <10ms 的速率改用 10ms 定时器并按累计目标时间调度，避免延迟/丢 tick 永久丢失目标消息；确定性群成员窗口在用户池上均匀分布，不再重复同一小发送者 cohort；max-runtime 关闭先标记 observer 停止再取消，期望中的 deadline/closed-session 错误不再计为发送失败；
客户端内存修复：模拟器全局并发曾被复制到每个客户端的发送队列、max-inflight 与未消费 RECV 队列，2000 用户下产生数千万队列槽位并长期持有已投递帧。修复后 per-client SEND 队列/max-inflight 固定 128/32，auto-ack 的未消费 RECV 队列只保留最新一帧；
单变量归因：并发保持 1536、仅把 Gateway worker 提到 2048，吞吐 3084.8→3730.9 SEND/s，异步派发等待 167.2ms→20.2ms（该轮 74 次 conversation-authority handoff 超时，只作归因证据不作验收证据）；
持续验收：--connect-rate 600 --concurrency 6000，4096 Gateway worker + 800 投递 worker，384.6s 运行阶段投递 1537642 条消息，即 3997.7 SEND/s，零发送错误、零重连；首 5 分钟 10 个 30s Prometheus 样本 3877.6-4027.5、均值 3985.4；收尾投递队列 0/0/0，post-commit handoff 深度 39/0/1（容量 128000）。加速连接验收--connect-rate 1000 --concurrency 6000同样达标（3996.5 SEND/s，30s/1min/4min 窗口 3998-4003）。服务端对照（real-QPS harness 3948.9、同规模 matched 对照 3915.4，均零错误）把原始缺口归因到模拟器/harness pacing 与有界准入，而非 4000 QPS 服务端上限；
持续运行诊断还留下重要的容量教训：100 投递 worker 时三个接收方队列全部打满 1024/1024、inflight 100/100，node2 填满 128000 项的 post-commit handoff 后返回 1427 次channel busy；只调大容量只是推迟失败。800 worker 形态在通过轮中接收方队列保持为零。由于本地三节点占用宿主机 92-96% CPU，这些运行“证明吞吐但不留主机余量”，且 APFS 数据卷 95% 已用，不构成延迟尾部容量声明。

2026-08-15：durable commit 收集窗口定标为 500us

文档最新一轮对三节点 lifecycle 250 SEND/s 阶段做了 commit 收集窗口矩阵：同一代码上直接同步 append 矩阵，单 coordinator shard 下比较 200us/500us/1ms/2ms/5ms 窗口。200us→500us：基准 631199ns/op→506728ns/op，append 等待 6280us→5037us，每次物理提交的逻辑请求数 1.732→2.159，每次操作物理提交数 0.1500→0.1003；1ms 及更宽窗口请求等待再次上升。250 SEND/s 真实复跑（500us）热均值 212.6ms→199.3ms、最大值 3.36s→2.77s、>2s 样本 310→65，但 p99 仍落在 2s 桶、未过不变的 200ms 门槛；跨三节点物理提交总量仅降约 0.9%，store append 与 post-store quorum 等待仍是两段各约 43-50ms 的串行持久化等待，Pull RPC 本身约 2ms。因此默认与本地 lifecycle profile 采用“500us 收集窗口 + 单 coordinator shard”作为有界改进而非容量修复，同步持久化、quorum 语义、错误门槛与延迟门槛均保持不变。

一次内存增长修复：Slot Raft 的 JSON 编码与日志压缩

2026-06-19 的 wkcli sim 一小时长跑（--duration 1h --users 1000 --groups 1000 --members 10 --rate 3/s）中，节点 pprof 显示多 GB 堆被 Slot Raft 元数据复制/保留路径支配：pkg/cluster.encodeSlotRaftBatch -> encoding/json.Marshal -> bytes.growSlice、pkg/raftlog.cloneEntry、raftpb.Entry.Unmarshal、pkg/slot/multiraft.cloneEntry/Propose。根因是 Slot Raft 传输用 JSON 编码裸 Raft 消息，强制 base64 膨胀与大临时缓冲，而 wukongim 又无法调既有压缩窗口。修复组合：Slot Raft 传输批改用带版本的二进制帧承载原始raftpb.Message字节；cluster 的 Slot 日志压缩配置暴露到 internal/config/build.go 的WK_CLUSTER_SLOT_LOG_COMPACTION_ENABLED/WK_CLUSTER_SLOT_LOG_COMPACTION_TRIGGER_ENTRIES/WK_CLUSTER_SLOT_LOG_COMPACTION_CHECK_INTERVAL（取值需 >0，安全边界测试见 internal/config/build_safety_boundaries_test.go），本地脚本采用WK_CLUSTER_SLOT_LOG_COMPACTION_TRIGGER_ENTRIES=1000与WK_CLUSTER_SLOT_LOG_COMPACTION_CHECK_INTERVAL=5s；ConversationAuthorityClient.AdmitActiveBatch在小窗口内重试路由迁移，期望的 post-commit 路由失败降级为 WARN。短程三节点 smoke（1m、100 用户/100 群）以messages_sent=528、send_errors=0通过。

方法总结：证据边界与稳定容量声明

这组 findings 最值得复用的是它对“证据级别”的严格区分，几乎每条结论都标注了边界：

归因证据 ≠ 验收证据：profile 轮只用于定位热点（live 采样会扰动延迟，例如某 profile 轮 p99 高达 2351.6ms，不得用于容量声明）；验收必须用无 profile 的重复轮通过 30s 门槛；
单变量实验优先：每次只动一个变量（worker 数、分片数、收集窗口、sender 选择策略），并在失败时如实回滚（文档中多个“rejected/reverted”实验保留完整证据路径）；
环境边界显式声明：APFS 剩余空间 <10% 的轮次一律标注“等待/存储主导，不能支持进一步传输策略结论”；全 RAM 拓扑只作软件路径归因；
稳定门槛只在重复通过后上调：3000→4000 QPS 的门槛提升由 15s+30s 双轮通过支撑；4500 QPS 一过一不过则明确维持 4000。

对读者而言，如果你想在自己的 IM/消息系统上做类似压测，可以从 scripts/bench-wukongim-three-nodes-real-qps.sh 的“独立冷启动 + 单点测量 + 门槛判定 + 证据目录”结构，以及 scripts/start-wukongim-three-nodes.sh 的--data-root隔离思路起步：前者保证每轮 QPS 可复现，后者让存储归因成为一次环境变量级别的可执行操作。WuKongIM 当前由此确立的稳定结论是：三节点同步三副本 quorum 提交、1000 群频道/4096 用户形态下，4000 QPS 为经重复验证的本地稳定容量门槛，其 4500 QPS 以上的尾部延迟由 backing device fsync 与串行同步提交语义共同决定，软件侧的下一安全改进方向是每节点独立低延迟存储，以及 leader-durableReplicateBatch快路径（需要独立的协议/状态机变更，而非不安全的同消息 fsync 重叠补丁）。