WuKongIM pkg/transport 混合负载压力测试设计:为高优先级 Raft 发送建立稳定延迟护栏
WuKongIM pkg/transport 混合负载压力测试设计:为高优先级 Raft 发送建立稳定延迟护栏
本文以 docs/superpowers/specs/2026-04-11-transport-stress-test-design.md 为骨架,结合 WuKongIM 仓库中
pkg/transport的优先级调度源码、stress_test.go落地实现与testkit测试基础设施,系统讲解如何为集群节点间通信层设计一条"Raft 流量 + RPC 流量并发下、高优先级发送延迟不退化"的混合负载回归护栏。读者读完可以掌握:transport 的优先级调度模型与源码结构、压力测试的环境变量开关体系、延迟测量与 p99 门槛判定方法,以及如何在本地显式开启并解读压测日志。
1. 背景与目标:为什么需要一条混合负载性能护栏
pkg/transport 是 WuKongIM 集群节点间通信的基础层,承载三类核心流量:
| 流量类型 | 模式 | 频率 |
|---|---|---|
| Slot Raft(心跳 / append entries) | 单向 fire-and-forget | heartbeat 100ms / slot |
| Controller Raft | 单向 fire-and-forget | heartbeat 100ms |
| RPC(Forward / Controller / ISR) | 请求-响应 | 随业务负载 |
这里有一个关键时序约束:election timeout = 1s(= 10 × heartbeat tick),即连续 10 个 heartbeat 丢失或延迟就触发选举(详见 docs/raw/transport-pipeline-priority-refactor.md)。这意味着,如果业务 RPC 负载把 Raft 心跳/日志发送拖慢到秒级,整个集群的稳定性会直接受损——这正是"Raft 流量永不被业务 RPC 阻塞"这一设计目标的由来。
pkg/transport 当前已经有较完整的单元测试,覆盖 frame 编解码、MuxConn、Pool、Server、RPCMux 与优先级 writer 的基础行为。但这些测试主要验证功能正确性,尚未提供一条稳定的混合负载性能护栏。本设计的目标因此不是追求极限吞吐,而是建立一个可复现的回归护栏:
PriorityRaft发送链路在PriorityRPC压力下保持低延迟;Send/RPC路径在持续并发期间不出现非预期错误;- 测试默认不干扰日常开发与 CI,仅在显式开启时运行;
- 输出足够的统计信息,便于后续版本间对比。
2. 优先级调度模型:从源码看 transport 如何保护 Raft 流量
在展开测试设计之前,先看 transport 实际实现的优先级模型,这是理解"压什么、测什么"的前提。
2.1 四档优先级车道
在 pkg/transport/internal/core/types.go 中定义了四个优先级常量:
const (
PriorityRaft Priority = iota + 1
PriorityControl
PriorityRPC
PriorityBulk
)
并在 pkg/transport/types.go 对外导出为 PriorityRaft、PriorityControl、PriorityRPC、PriorityBulk。压力测试设计文档中重点关注的正是 PriorityRaft(高优先级单向发送)与 PriorityRPC(请求-响应)。
2.2 字节感知的加权优先级调度器
重构后,发送不再采用"独占连接 → 写数据 → 释放连接"的旧模型,而是"入队到连接的优先级缓冲 → 独立 writer goroutine 按优先级批量发送"。
在 pkg/transport/internal/sched/scheduler.go 中,四个车道被赋予不同的权重:
lanes: []lane{
{priority: core.PriorityRaft, weight: 8},
{priority: core.PriorityControl, weight: 6},
{priority: core.PriorityRPC, weight: 4},
{priority: core.PriorityBulk, weight: 1},
},
这是一个字节感知(byte-aware)的加权轮转调度器:每个 lane 维护自己的 deficit(信用),按权重累积后调度出队,batch 上限受 MaxBatchFrames(默认 64)与 MaxBatchBytes(默认 1MB)约束(见 scheduler.go)。Raft 车道权重最高(8),Bulk 最低(1),从调度器层面保证高优先级帧的等待时间有界。
此外,Enqueue 对 PriorityControl 与 PriorityRaft 会额外触发 urgentReady 信号(scheduler.go),用于中断写循环的可选合包延迟,进一步压低高优先级帧的延迟。
2.3 压测要验证的核心命题
因此,压力测试要验证的核心命题就是:当 PriorityRPC 负载持续饱和时,PriorityRaft 发送的端到端延迟不应出现明显退化——即调度器、连接复用、RPC 回包与服务端分发在混部压力下依然保持优先级隔离。
3. 测试范围:本次覆盖与暂不覆盖
3.1 本次覆盖
新增 pkg/transport/stress_test.go,提供一个主压力测试:
TestTransportStressRaftSendUnderRPCLoad
测试使用真实 transport 组件拼装,不使用 mock:
ServerPoolClientMuxConn- frame 编解码与 RPC pending 路径
测试场景:
- 一组 worker 持续通过
PriorityRaft对服务端执行Send; - 一组 worker 持续通过
PriorityRPC对服务端执行RPC; - 服务端为普通消息注册轻量 handler,为 RPC 注册可控延迟 handler;
- 统计
PriorityRaft端到端延迟分位数,确认其在混部下仍满足预算。
3.2 暂不覆盖
首版不纳入以下内容(后续可独立补充,但不阻塞首条护栏落地):
- benchmark(
Benchmark*)与历史版本性能对比; - 多节点、多 server、真实跨机网络抖动场景;
- 复杂背景噪声,例如连接抖动、突发重连、半开连接恢复;
- 长时间 soak test(分钟级 / 小时级)。
4. 设计原则
- 真实路径优先:不引入 mock transport 主链路,直接使用真实
Server + Pool + Client,确保覆盖优先级队列、连接复用、RPC 回包与服务端分发。 - 默认关闭:遵循仓库既有 stress test 风格,未设置环境变量时
t.Skip。 - 单职责:首版只做一个主压力测试,避免测试框架过度抽象。
- 统计可解释:聚焦
PriorityRaft的p99作为硬门槛,其余分位数与负载信息作为日志输出。 - 单节点集群语义:测试描述统一面向单节点集群,不引入绕过集群语义的特殊分支。
5. 测试结构:文件布局与核心组件关系
5.1 文件布局
新增文件 pkg/transport/stress_test.go,文件内维持单文件实现,主要包含四类内容:
transportStressConfig- 加载环境变量;
- 提供默认值与参数校验。
transportLatencySummary/transportStressStats- 收集
raft send与rpc延迟样本; - 汇总
count / p50 / p95 / p99 / max; - 记录错误数与操作总数。
- 收集
transportStressHarness- 启动本地
Server; - 注册普通消息与 RPC handler;
- 创建
raftPool、rpcPool以及对应Client; - 负责资源清理。
- 启动本地
TestTransportStressRaftSendUnderRPCLoad- 协调 worker 生命周期;
- 汇总统计结果;
- 执行最终断言并输出测试日志。
5.2 核心组件关系
服务端:
- 启动一个本地
Server; - 注册一个测试专用消息类型(仅在测试文件内定义的常量);
- 该消息 handler 接收
PriorityRaft发送的数据、解码时间戳并记录到达延迟; - 注册一个
RPChandler,按配置注入少量固定延迟,再返回响应。
客户端:
- 创建
raftPool,DefaultPri = PriorityRaft; - 创建
rpcPool,DefaultPri = PriorityRPC; - 使用固定 discovery 将测试 node id 指向本地服务端监听地址;
- 可直接使用
Client包装调用,也可直接经由Pool;推荐复用Client以贴近上游调用习惯。
worker:
raftworkers:循环发送小体积消息,消息体包含发送时间戳与序号;rpcworkers:循环发起 RPC,确保服务端存在持续 RPC 压力;- 所有 worker 通过同一个
context.WithTimeout受控退出。
5.3 仓库中的落地实现
设计文档落地后,仓库中的 pkg/transport/stress_test.go 采用了更简洁的实现:直接复用 pkg/transport/testkit/harness.go 提供的 Harness(本地 Server + Client 配对,node id 1/2,service id 7,连接池大小 4)。实际测试名是 TestTransportStressMixedRPCAndSend,每个 worker 循环执行 Client.Call(PriorityRPC) 与 Client.Send(PriorityControl),整体超时 5s,handler 用原子计数验证确实收到了请求:
func TestTransportStressMixedRPCAndSend(t *testing.T) {
if os.Getenv("WK_TRANSPORT_STRESS") != "1" && os.Getenv("WK_TRANSPORTV2_STRESS") != "1" {
t.Skip("set WK_TRANSPORT_STRESS=1 to run transport stress test")
}
// ... testkit.NewHarness + 4 个 worker 并发 Call / Send ...
}
Harness 内部的关键配置(testkit/harness.go):
- 服务端:
transport.NewServer(ServerConfig{NodeID: ServerNodeID, Limits: DefaultLimits()}),注册ServiceOptions{Concurrency: 4, QueueSize: 1024, MaxQueueBytes: 8 << 20},ListenAndServe("127.0.0.1:0")随机端口; - 客户端:
transport.NewClient(ClientConfig{NodeID: ClientNodeID, Discovery: StaticDiscovery{...}, PoolSize: 4, Limits: DefaultLimits()}); StaticDiscovery是测试用的固定路由表实现,Resolve直接返回注册的地址(harness.go)。
这印证了设计中的"真实路径优先"原则:压测走的是与生产一致的 Server、Client、frame 编解码与 RPC 路径,而不是 mock。
6. 延迟测量方案
6.1 raft send latency(主指标)
从客户端准备调用 Send 前记录 sentAt,在服务端普通消息 handler 收到消息时计算 time.Since(sentAt)。
这样得到的延迟包含:
- 客户端进入 writer 队列的等待;
- 实际写 socket 的时间;
- 服务端读 frame 与 dispatch 的时间。
但不包含服务端 handler 中额外的业务处理逻辑,因为该 handler 仅做解码与采样上报。这样更能反映 transport 库本身的优先级调度表现。
6.2 rpc latency(辅助指标)
客户端 RPC 调用开始到收到响应的往返耗时。其目的主要是:
- 验证压力确实建立起来了;
- 为日志输出提供负载背景;
- 观察混部时 RPC 自身延迟的变化。
rpc latency 不是首版的硬门槛,但会纳入统计输出。
6.3 统计方法
测试结束后统一计算:
countp50p95p99max
首版直接保留全量 time.Duration 样本,原因:
- 默认时长仅数秒;
- 逻辑清晰,易读易校验;
- 首版重点是建立护栏,不需要先引入 reservoir sampling 等复杂度。
如果后续样本规模显著增大,再演进为限长采样或分桶统计。
7. 环境变量与默认值:让压测可调、可复现
压力测试默认关闭,全部行为通过环境变量显式开启和调参。设计文档建议的环境变量如下:
| 环境变量 | 含义 | 默认值 |
|---|---|---|
WK_TRANSPORT_STRESS |
是否开启压力测试 | 关闭 |
WK_TRANSPORT_STRESS_DURATION |
压测时长 | 5s |
WK_TRANSPORT_STRESS_RAFT_WORKERS |
PriorityRaft worker 数 |
max(2, GOMAXPROCS/2) |
WK_TRANSPORT_STRESS_RPC_WORKERS |
PriorityRPC worker 数 |
max(2, GOMAXPROCS) |
WK_TRANSPORT_STRESS_RPC_DELAY |
服务端 RPC handler 的固定延迟 | 2ms |
WK_TRANSPORT_STRESS_SEED |
固定随机种子 | 一个稳定常量,便于复现 |
WK_TRANSPORT_STRESS_P99_BUDGET |
raft send 的 p99 预算 |
20ms |
参数校验要求:
duration > 0raft workers > 0rpc workers > 0rpc delay >= 0p99 budget > 0
在仓库当前的落地实现中,开关为 WK_TRANSPORT_STRESS=1(同时兼容 WK_TRANSPORTV2_STRESS=1),未设置时 t.Skip(pkg/transport/stress_test.go)。其余细分调参项可参考设计文档逐步补齐。
8. 通过/失败判定:p99 硬门槛 + 最小样本量
测试必须同时满足以下条件才算通过:
raft send无错误;rpc无错误;raft send样本数达到最小阈值;rpc样本数达到最小阈值;raft send p99 <= WK_TRANSPORT_STRESS_P99_BUDGET。
关于最小样本量,首版建议使用固定下限:
raft count >= 1000rpc count >= 1000
选择 p99 作为硬门槛的理由:
p50对优先级退化不敏感;max波动过大,不适合作为稳定断言;p99最能反映"少数慢请求是否被混部显著拖慢"。
如果样本量不足,则直接失败并打印当前配置,避免"压力没打起来也算通过"。
9. harness 细节:消息格式、handler 约束与并发控制
9.1 消息格式
普通消息体仅携带最小必要字段:
sentAtUnixNanosequence
首版可直接采用定长字节编码(例如 16 字节:8 字节时间戳 + 8 字节序号),避免额外引入 JSON 或其他编码开销。
RPC payload 无需复杂结构,保持小体积即可,只需保证:
- 能持续驱动服务端
RPChandler; - 可在响应中带回简单确认字段,避免测试误判。
9.2 服务端 handler 约束
普通消息 handler:
- 读取消息体;
- 计算
latency; - 记录统计;
- 不执行任何额外慢逻辑。
RPC handler:
- 按
rpc delay配置执行time.Sleep; - 返回小响应体;
- 不额外引入不可控阻塞。
9.3 并发控制
主测试使用:
context.WithTimeout:控制整体压测时长;sync.WaitGroup:等待所有 worker 退出;- 原子计数 / 轻量锁:汇总错误数与样本。
如果任一 worker 发生非预期错误:
- 记录首个错误;
- 允许其他 goroutine 在
ctx.Done()后自然退出; - 最终统一
Fatal。
仓库实际实现中正是这样做的:worker 出错时 t.Errorf 并 cancel() 提前终止(pkg/transport/stress_test.go),最后用 received.Load() == 0 兜底判断"handler 一个请求都没收到"。
9.4 资源清理
transportStressHarness.Close() 负责统一清理:
raftClient.Stop()或raftPool.Close();rpcClient.Stop()或rpcPool.Close();server.Stop()。
测试退出前确保 listener、连接与 goroutine 均可收敛,避免压力测试污染后续用例。
对应到源码:Client.Stop() 释放 peer 连接管理(pkg/transport/client.go),Server.Stop() 幂等关闭 listener、active 连接、服务与 executor(pkg/transport/server.go),Harness.Close() 依次停止 client 与 server(testkit/harness.go)。
10. 日志输出:可解释、可对比的汇总格式
测试结束时输出一条可读的汇总日志,至少包含:
seeddurationraft_workersrpc_workersrpc_delayraft_countraft_p50/p95/p99/maxrpc_countrpc_p50/p95/p99/max
输出目标:
- 方便本地调参;
- 方便后续版本间手工对比;
- 当断言失败时能快速定位是样本不足、整体压力太低,还是高优先级延迟真的退化。
11. 验证方式:如何在本仓库显式运行
开发时至少验证:
go test ./pkg/transport/...
显式开启压力测试后执行:
go test -run TestTransportStressRaftSendUnderRPCLoad ./pkg/transport -count=1
在手工压测场景下可使用环境变量,例如:
WK_TRANSPORT_STRESS=1 \
WK_TRANSPORT_STRESS_DURATION=5s \
WK_TRANSPORT_STRESS_RPC_DELAY=2ms \
WK_TRANSPORT_STRESS_P99_BUDGET=20ms \
go test -run TestTransportStressRaftSendUnderRPCLoad ./pkg/transport -count=1
对应仓库当前落地测试的开关:
WK_TRANSPORT_STRESS=1 go test -run TestTransportStressMixedRPCAndSend ./pkg/transport -count=1
12. TDD 落地顺序与配套基准
12.1 TDD 落地顺序
实现阶段遵循 test-first:
- 先写配置加载与默认 skip 行为的测试(如需要拆 helper);
- 先写延迟统计 helper 的单元测试;
- 再写主压力测试骨架,并先验证其在未实现完整 helper 时失败;
- 最后补齐 harness、统计、断言与日志输出。
注意:压力测试本身默认 skip,因此实现时应尽量把可确定的逻辑拆成普通单元测试 helper,避免所有逻辑都只能依赖慢测试验证。
12.2 仓库中已有的配套基准测试
pkg/transport 还提供了大量 Benchmark* 用例(pkg/transport/benchmark_test.go),可作为压力测试之外的性能观察手段:
BenchmarkTransportRPC/BenchmarkTransportRPCOwned:64B 小 payload 的 RPC 往返;BenchmarkTransportRPCPayloadSizes:64B / 1KiB / 64KiB 三种 payload 尺寸;BenchmarkTransportRPCParallel:并行 RPC 并发吞吐;BenchmarkTransportRPCPoolSizes:Pool1 / Pool4 / Pool8 连接池规模对比;BenchmarkTransportSendWithBackpressure/SendParallelWithBackpressure:背压下的单向发送(遇到ErrQueueFull时runtime.Gosched()重试,见 benchmark_test.go)。
这些基准测试与压力测试互补:benchmark 测吞吐与分配,stress 测混合负载下的延迟护栏。
13. 后续演进方向
本设计落地后,可按需要继续补充:
pkg/transport/benchmark_test.go:测SendQPS、RPC RTT、alloc/op;- 多 server / 多 node 压测场景;
- 更严格的优先级隔离测试,例如放大 RPC handler 阻塞或增加 bulk 流量;
- 长时间 soak test 与关闭收敛测试。
这些后续工作不影响本次目标:先为 pkg/transport 建立一条可靠的混合负载延迟护栏。
14. 总结
pkg/transport 的混合负载压力测试是优先级调度重构(docs/raw/transport-pipeline-priority-refactor.md)的验收护栏:它用真实 transport 组件、默认关闭的可选运行方式、以 PriorityRaft 的 p99 为硬门槛、以最小样本量与零错误为辅证,验证"Raft 流量在 RPC 压力下不被明显拖慢"这一核心承诺。结合 pkg/transport/internal/sched/scheduler.go 的四车道权重调度、pkg/transport/testkit/harness.go 的本地 Server/Client 配对,以及 pkg/transport/stress_test.go 的落地实现,开发者在本地一条命令即可复现、调参并长期追踪这条延迟护栏,防止未来任何改动悄悄破坏节点间通信的优先级隔离。