WuKongIM 三节点真实发送链路压测实施指南:WKProto 到 SendAck 的全链路设计与持久化校验
WuKongIM 三节点真实发送链路压测实施指南:WKProto 到 SendAck 的全链路设计与持久化校验
本文完整解读 WuKongIM 仓库中 发送压力测试实施计划(
2026-04-08-send-stress-implementation.md)及其配套 设计文档(2026-04-08-send-stress-design.md),面向 v3.1 引入一条 env-gated 的三节点真实发送链路压测。读者可据此掌握:如何用WK_SEND_STRESS系列环境变量开关并调参压测入口、压测 worker 的发送循环与成功契约、压测结束后如何对全部成功消息做持久化提交回读校验,以及压测暴露生产缺陷时的"先补回归、再修代码"处置流程。
一、为什么要做真实发送链路压测
WuKongIM 的发送主路径横跨协议层、网关层、消息用例层与存储层。设计文档给出的链路覆盖为:
WKProto/TCP(客户端协议接入)internal/gateway与internal/access/gateway(网关会话与帧分发)internal/usecase/message(发送用例)pkg/storage/channellog/ 集群提交(durable 落盘)SendAck(发送回执)
压测只压 person 单聊发送,不把收件端实时投递、RecvPacket、RecvAck 纳入成功条件。设计上确立两条不可动摇的原则:
- 压测走真实装配,不退化成 mock usecase 或只压
message.App.Send; - 如果压测暴露程序缺陷,先修生产代码,不为了让测试通过而放宽断言或删除真实校验。
设计文档明确了 Goals 与 Non-Goals:目标是为真实发送入口建立稳定长压测试,让三节点稳定集群经受高并发 SendPacket -> SendAck 压力,对每条成功发送建立可追踪记录并做全量持久化校验,输出吞吐、错误率、延迟分位数与校验结果;明确不在本次范围内做群聊压测、收件端投递校验、leader 切换/节点重启/网络扰动,也不把长压纳入默认 go test ./...。
说明:本文解读的是一份面向 agentic worker 的实施计划文档。计划中新建的目标文件(如
internal/app/send_stress_test.go、docs/distributed-cluster-test-matrix.md)在当前仓库中尚未落地;仓库现存的真实三节点装配测试(见文末"与仓库源码的印证"一节)是这套计划复用的基座与既有事实依据。
二、整体架构与执行约束
计划的核心决策是:实现集中落在单一文件 internal/app/send_stress_test.go,复用现有 threeNodeAppHarness、WKProto 编解码 helper 和三节点 channel meta 刷新逻辑,不引入第二套压力测试基座。测试先用纯 helper/config 测试锁定 env 配置与统计逻辑,再落真实三节点压力场景。
技术栈:Go 1.23、testing、testify、net、internal/app 三节点 harness、internal/usecase/message、pkg/protocol/wkframe(仓库中实际位于 pkg/protocol/frame 与 pkg/protocol/codec)、pkg/storage/channellog、pkg/storage/metadb。
计划为执行过程规定的硬性约束:
- 每个任务都遵循 TDD:先写失败测试,再写最小实现,再跑测试确认通过;
- 新测试默认必须跳过,只有
WK_SEND_STRESS=1时才运行真实长压; - 发送链路只覆盖
person单聊,不把RecvPacket/RecvAck纳入成功条件; - 每条成功发送都必须同时验证
SendAck成功和最终 durable 可读,禁止只看其中一边; - 如果压力测试暴露的是真实程序 bug,先在缺陷所属包补 focused failing regression,再修生产代码,不降低压力测试标准;
- 最终交付前运行
@superpowers/verification-before-completion。
文件映射
| 路径 | 责任 |
|---|---|
internal/app/send_stress_test.go |
新增发送压力测试入口、env 配置、统计、预热、发送 worker、SendAck 校验、持久化回读校验 |
internal/app/multinode_integration_test.go |
复用 threeNodeAppHarness、readAppWKProtoFrameWithin、waitForAppCommittedMessage 等三节点真实 helper;仅在实现确实缺少必要 helper 时才补最小抽取 |
internal/app/integration_test.go |
复用 sendAppWKProtoFrame 编码写帧 helper;除非缺 helper,否则不改 |
internal/usecase/message/send_test.go |
若 stress red phase 暴露 send usecase 缺陷,补最小回归测试 |
internal/usecase/message/send.go |
仅当 stress 暴露 durable send 缺陷时修生产代码 |
internal/access/gateway/handler_test.go |
若 stress 暴露 gateway send/ack 协议缺陷,补最小回归测试 |
internal/access/gateway/handler.go |
仅当 stress 暴露 gateway 缺陷时修生产代码 |
三、Task 1:锁定配置、统计与纯 helper 骨架
Task 1 不启动任何节点,只通过纯测试把压测的配置加载语义与统计口径钉死。
3.1 配置与统计的失败测试
在 internal/app/send_stress_test.go 先写三个失败测试:
func TestSendStressConfigDefaultsAndOverrides(t *testing.T) {
t.Setenv("WK_SEND_STRESS", "1")
t.Setenv("WK_SEND_STRESS_DURATION", "1500ms")
t.Setenv("WK_SEND_STRESS_WORKERS", "7")
t.Setenv("WK_SEND_STRESS_SENDERS", "11")
t.Setenv("WK_SEND_STRESS_MESSAGES_PER_WORKER", "13")
t.Setenv("WK_SEND_STRESS_DIAL_TIMEOUT", "2s")
t.Setenv("WK_SEND_STRESS_ACK_TIMEOUT", "1800ms")
t.Setenv("WK_SEND_STRESS_SEED", "42")
cfg := loadSendStressConfig(t)
require.True(t, cfg.Enabled)
require.Equal(t, 1500*time.Millisecond, cfg.Duration)
require.Equal(t, 7, cfg.Workers)
require.Equal(t, 11, cfg.Senders)
require.Equal(t, 13, cfg.MessagesPerWorker)
require.Equal(t, 2*time.Second, cfg.DialTimeout)
require.Equal(t, 1800*time.Millisecond, cfg.AckTimeout)
require.EqualValues(t, 42, cfg.Seed)
}
func TestSendStressLatencySummaryPercentiles(t *testing.T) {
summary := summarizeSendStressLatencies([]time.Duration{
90 * time.Millisecond,
10 * time.Millisecond,
70 * time.Millisecond,
30 * time.Millisecond,
50 * time.Millisecond,
})
require.Equal(t, 5, summary.Count)
require.Equal(t, 50*time.Millisecond, summary.P50)
require.Equal(t, 90*time.Millisecond, summary.P95)
require.Equal(t, 90*time.Millisecond, summary.P99)
require.Equal(t, 90*time.Millisecond, summary.Max)
}
func TestSendStressOutcomeErrorRate(t *testing.T) {
outcome := sendStressOutcome{Total: 10, Success: 8, Failed: 2}
require.InDelta(t, 20.0, outcome.ErrorRate(), 0.001)
}
聚焦运行(此时应 FAIL,因为类型与 helper 尚不存在):
go test ./internal/app -run 'TestSendStress(ConfigDefaultsAndOverrides|LatencySummaryPercentiles|OutcomeErrorRate)' -count=1
3.2 最小实现:三个核心类型
type sendStressConfig struct {
Enabled bool
Duration time.Duration
Workers int
Senders int
MessagesPerWorker int
DialTimeout time.Duration
AckTimeout time.Duration
Seed int64
}
type sendStressLatencySummary struct {
Count int
P50 time.Duration
P95 time.Duration
P99 time.Duration
Max time.Duration
}
type sendStressOutcome struct {
Total uint64
Success uint64
Failed uint64
}
配套实现四个函数:(o sendStressOutcome) ErrorRate() float64、loadSendStressConfig(t *testing.T) sendStressConfig、requireSendStressEnabled(t *testing.T, cfg sendStressConfig)、summarizeSendStressLatencies(latencies []time.Duration) sendStressLatencySummary。
3.3 配置默认值与约束(务必遵守)
| env 变量 | 默认值 | 说明 |
|---|---|---|
WK_SEND_STRESS |
关闭 | 压测总开关,非 1 则跳过 |
WK_SEND_STRESS_DURATION |
5s |
压测时长上限 |
WK_SEND_STRESS_WORKERS |
max(4, runtime.GOMAXPROCS(0)) |
并发 worker 数 |
WK_SEND_STRESS_SENDERS |
max(8, Workers) |
发送者身份数 |
WK_SEND_STRESS_MESSAGES_PER_WORKER |
50 |
每 worker 目标消息数 |
WK_SEND_STRESS_DIAL_TIMEOUT |
3s |
建连超时 |
WK_SEND_STRESS_ACK_TIMEOUT |
5s |
等 ack 超时 |
WK_SEND_STRESS_SEED |
无 | 确定性随机种子 |
关键约束:
Senders >= Workers:显式配置不满足时loadSendStressConfig直接t.Fatalf;- worker 到 sender 的映射固定为
worker i -> sender i,一个 worker 只持有一个 sender 和一条长连接,不做 sender 复用或连接共享; - 若
Senders > Workers,多出的 sender 仅作为预热数据集保留,不参与活跃 worker 发流; - 非法参数一律
t.Fatalf。
重新跑聚焦测试,应 PASS,随后提交:
git add internal/app/send_stress_test.go
git commit -m "test(app): scaffold send stress config"
四、Task 2:真实三节点发送压力测试与全量 durable 校验
Task 2 落地 TestSendStressThreeNode,是全计划的核心。
4.1 记录与目标结构体
type sendStressTarget struct {
SenderUID string
RecipientUID string
ChannelID string
ChannelType uint8
OwnerNodeID uint64
ConnectNodeID uint64
}
type sendStressRecord struct {
Worker int
SenderUID string
RecipientUID string
ChannelID string
ChannelType uint8
ClientSeq uint64
ClientMsgNo string
Payload []byte
MessageID int64
MessageSeq uint64
AckLatency time.Duration
OwnerNodeID uint64
ConnectNodeID uint64
}
4.2 主测试骨架
func TestSendStressThreeNode(t *testing.T) {
cfg := loadSendStressConfig(t)
requireSendStressEnabled(t, cfg)
harness := newThreeNodeAppHarness(t)
leaderID := harness.waitForStableLeader(t, 1)
leader := harness.apps[leaderID]
targets := preloadSendStressChannels(t, harness, leader, cfg)
outcome, records, failures := runSendStressWorkers(t, harness, targets, cfg)
verifySendStressCommittedRecords(t, harness, records)
t.Logf("send stress results: total=%d success=%d failed=%d error_rate=%.2f%%", outcome.Total, outcome.Success, outcome.Failed, outcome.ErrorRate())
if len(failures) > 0 {
t.Logf("send stress failures: %s", strings.Join(failures, " | "))
}
require.NotZero(t, outcome.Total)
require.Equal(t, outcome.Total, outcome.Success)
require.Zero(t, outcome.Failed)
require.Len(t, records, int(outcome.Success))
}
需要的最小 helper 集合:
func preloadSendStressChannels(t *testing.T, harness *threeNodeAppHarness, leader *App, cfg sendStressConfig) []sendStressTarget
func runSendStressWorkers(t *testing.T, harness *threeNodeAppHarness, targets []sendStressTarget, cfg sendStressConfig) (sendStressOutcome, []sendStressRecord, []string)
func verifySendStressCommittedRecords(t *testing.T, harness *threeNodeAppHarness, records []sendStressRecord)
func runSendStressClient(t *testing.T, app *App, senderUID string, cfg sendStressConfig) net.Conn
4.3 预热:channel runtime meta 预载
preloadSendStressChannels 负责:
- 生成发送者/接收者 UID:
stress-sender-%03d/stress-recipient-%03d; - 为每对 sender/recipient 写入
metadb.ChannelRuntimeMeta,字段必须完整镜像现有 person send seed 形状,至少包含:ChannelEpoch、LeaderEpoch、Replicas、ISR、Leader、MinISR、Status、Features、LeaseUntilMS; - 取值约定:
Replicas/ISR固定[1,2,3];Leader使用当前稳定 leader;MinISR固定3;Status固定channellog.ChannelStatusActive;Features固定channellog.MessageSeqFormatLegacyU32;LeaseUntilMS使用time.Now().Add(time.Minute).UnixMilli(); - 返回完整
sendStressTarget,显式携带OwnerNodeID(该单聊 channel 的 durable owner)与ConnectNodeID(sender 实际连入的 gateway 节点); - 对
harness.appsWithLeaderFirst(leaderID)全量RefreshChannelMeta。
设计文档特别强调:预热不预发消息,本压测只关心发送实时写入与 ack 闭环。
4.4 worker 发送循环与成功契约
runSendStressClient 建立真实 TCP WKProto 连接,发送 ConnectPacket 并等待成功 Connack。runSendStressWorkers 的发送循环语义固定为:
- 每个 worker 绑定一个 sender/client connection(固定映射
worker i -> sender i); - 最多发送
MessagesPerWorker条;若Duration先到则提前停止,并记录已完成的部分; - 总目标发送量上限是
Workers * MessagesPerWorker; - 每条消息发送一个真实
wkframe.SendPacket,每发一条立即阻塞读取一个SendackPacket; - 校验
ReasonSuccess、MessageID != 0、MessageSeq != 0; ClientMsgNo必须使用确定性唯一格式,例如send-stress-%02d-%s-%03d-%d,至少包含worker、senderUID、iteration、seed;- 记录
ClientMsgNo/Payload/MessageSeq/MessageID/AckLatency,并在sendStressRecord中同时写入OwnerNodeID与ConnectNodeID; - 统计
Total/Success/Failed,收集有限数量失败样本。
消息负载用固定前缀加递增序号,便于持久化回读校验;worker 使用固定 sender 身份,避免每条消息都建连。
4.5 全量持久化提交校验
verifySendStressCommittedRecords 遍历全部成功记录:
- 用
record.OwnerNodeID先定位 owner 节点,再用waitForAppCommittedMessage(...)读回; - 核对
Payload、FromUID、ClientMsgNo、ChannelID、ChannelType; - 再在
harness.orderedApps()上确认同一MessageSeq最终可读(副本侧复核)。
为避免时序误判,读取阶段允许用 require.Eventually 在有限窗口内等待提交可见。任一记录 SendAck 成功但持久化校验失败,测试直接失败——这正是执行约束里"禁止只看其中一边"的落地。
4.6 显式 env 跑真实压测
WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=2s WK_SEND_STRESS_WORKERS=3 WK_SEND_STRESS_SENDERS=6 WK_SEND_STRESS_MESSAGES_PER_WORKER=8 go test ./internal/app -run 'TestSendStressThreeNode' -count=1 -v -timeout 10m
默认关闭与显式开启的双重验证:
go test ./internal/app -run 'TestSendStressThreeNode' -count=1
WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=2s WK_SEND_STRESS_WORKERS=3 WK_SEND_STRESS_SENDERS=6 WK_SEND_STRESS_MESSAGES_PER_WORKER=8 go test ./internal/app -run 'TestSendStressThreeNode' -count=1 -v -timeout 10m
预期:第一条 PASS 且输出 set WK_SEND_STRESS=1 to enable send stress test;第二条 PASS,日志中 failed=0,并完成全量 durable 校验。
4.7 测试日志输出指标
压测结束后日志至少包含:duration、workers、senders、total、success、failed、qps、p50/p95/p99/max、verification_count、verification_failures,并额外输出有限数量失败样本便于定位。
4.8 暴露生产缺陷时的处置流程
执行规则按缺陷归属分三类:
- 失败点在
messagedurable send:先在internal/usecase/message/send_test.go写 focused failing test,再改internal/usecase/message/send.go; - 失败点在 gateway send/ack:先在
internal/access/gateway/handler_test.go写 focused failing test,再改internal/access/gateway/handler.go; - 失败点落在其他所有权包(如
pkg/storage/channellog、internal/app/channelmeta.go等发送链路依赖):先在该缺陷所属包写最小 focused failing regression,再改对应生产文件。
修复后必须先跑该 focused regression,随后回跑:
go test ./internal/usecase/message ./internal/access/gateway -run 'Test.*Send.*' -count=1
WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=2s WK_SEND_STRESS_WORKERS=3 WK_SEND_STRESS_SENDERS=6 WK_SEND_STRESS_MESSAGES_PER_WORKER=8 go test ./internal/app -run 'TestSendStressThreeNode' -count=1 -v -timeout 10m
不得通过改弱压力测试断言来"修复"失败。提交时按是否含生产修复区分两条提交路径(后者把 send.go、send_test.go、handler.go、handler_test.go 一并纳入 git add),提交信息统一为 test(app): add real send stress coverage。
五、Task 3:文档化入口
在测试矩阵文档(计划目标文件 docs/distributed-cluster-test-matrix.md)的"压力与稳定性"区域补充新条目:internal/app 发送压力测试、推荐命令、关键 env 变量,以及适用场景(手动验证 / nightly / 发布前 soak)。建议文案:
- app 真实发送链路压测:
`WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=10s WK_SEND_STRESS_WORKERS=8 WK_SEND_STRESS_SENDERS=16 WK_SEND_STRESS_MESSAGES_PER_WORKER=100 go test ./internal/app -run 'TestSendStressThreeNode' -count=1 -v -timeout 15m`
落地后用最小回归验证文档命令仍可执行:
WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=1s WK_SEND_STRESS_WORKERS=2 WK_SEND_STRESS_SENDERS=4 WK_SEND_STRESS_MESSAGES_PER_WORKER=4 go test ./internal/app -run 'TestSendStressThreeNode' -count=1 -timeout 10m
六、错误处理清单与验收标准
设计文档把以下任一情况都计为失败并保留失败样本:
- TCP 连接失败;
ConnectPacket后未收到成功Connack;SendPacket写失败;- 读取超时;
- 返回的不是
SendAck; SendAck.ReasonCode != ReasonSuccess;message_id == 0;message_seq == 0;- 持久化回读不到消息;
- 回读消息字段与发送记录不一致。
错误处理原则:发送阶段失败直接计数,不伪造成功;测试结尾 require.Zero(failed),不允许"有失败但整体还能接受";测试先暴露生产缺陷则优先修生产代码。
设计文档给出的最终验收标准(Acceptance)共七条:测试走真实 WKProto -> Gateway -> SendAck;只覆盖 person 单聊;默认关闭、显式 env 开启;压测期间不混入故障扰动;每条发送都要求成功 SendAck;压测结束后对全部成功消息做持久化提交校验;发现程序 bug 时先修生产代码而不是改测试降低标准。
七、与仓库源码的印证
计划中压测校验的 SendAck 字段定义可在仓库中直接对应:SendackPacket 携带 MessageID(全局唯一消息 ID)、MessageSeq(用户唯一有序序列号)、ClientSeq(服务端原样返回)、ClientMsgNo 与 ReasonCode,见 pkg/protocol/frame/sendack.go(编码实现见 pkg/protocol/codec/sendack.go)。这与压测"校验 ReasonSuccess、MessageID != 0、MessageSeq != 0"的契约一一对应。
发送用例层面,internal/usecase/message/send.go 定义了 channelTypePerson = 1 等渠道类型常量(person 单聊、group 群聊、customerService、info、visitors、agent),并实现了批量发送的权限快照、分组与提交器流水线(permission -> pre_append -> submitter -> ok/error),即压测走真实 message.Send 时经历的底层链路;其回归测试位于 internal/usecase/message/send_test.go。
三节点真实装配基座方面,计划描述复用的 threeNodeAppHarness 在计划文件中为既有基座;从当前仓库源码结构看,与之等效的真实集群装配测试已存在于 internal/app/app_cluster_integration_test.go(启动三个 voter 节点的静态集群、等待 waitAppClusterSnapshotsConverge、发送默认 meta 冒烟包并校验 ReasonSuccess 与 MessageSeq)。单节点/集群的 SendPacket -> SendAck 闭环冒烟测试见 internal/app/sendack_smoke_integration_test.go:通过 app.Handler().OnFrame 注入真实 frame.SendPacket,断言回执 ReasonCode == ReasonSuccess、MessageID 由对应节点生成、MessageSeq 为通道首个提交序号。这些既有测试正是计划"复用真实装配、不退化为 mock"的仓库事实基础。
八、滚动策略(Rollout)
该测试以 env-gated 长压测试形态存在:PR 默认不跑;开发者手动验证时显式开启;nightly / 发布前 soak 可按更大参数放大(例如 DURATION=10s、WORKERS=8、SENDERS=16、MESSAGES_PER_WORKER=100)。设计文档建议的快速验证命令组合为:
go test ./internal/app -run TestSendStressThreeNode -count=1
WK_SEND_STRESS=1 WK_SEND_STRESS_DURATION=3s WK_SEND_STRESS_WORKERS=4 WK_SEND_STRESS_SENDERS=8 WK_SEND_STRESS_MESSAGES_PER_WORKER=25 go test ./internal/app -run TestSendStressThreeNode -count=1 -v
实施这套压测计划的价值在于:把"发送成功"从单一的 SendAck 回执扩展为"回执 + durable 可读"双重证据,为三节点稳定集群的高并发单聊发送建立可量化、可回归的吞吐(qps)、错误率与延迟分位数基线,并让发送链路中的任何真实缺陷都能在合入前被显式暴露、以 focused regression 的方式收敛到所属包修复。