WuKongIM 三节点真实发送链路压测实施指南:WKProto 到 SendAck 的全链路设计与持久化校验

原创2026-10-15 20:19:161,622 阅读
文章标签:即时通讯后端WebSocket微服务高可用前端可观测性

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 纳入成功条件。设计上确立两条不可动摇的原则:

  1. 压测走真实装配,不退化成 mock usecase 或只压 message.App.Send;
  2. 如果压测暴露程序缺陷,先修生产代码,不为了让测试通过而放宽断言或删除真实校验。

设计文档明确了 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 遍历全部成功记录:

  1. 用 record.OwnerNodeID 先定位 owner 节点,再用 waitForAppCommittedMessage(...) 读回;
  2. 核对 Payload、FromUID、ClientMsgNo、ChannelID、ChannelType;
  3. 再在 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 暴露生产缺陷时的处置流程

执行规则按缺陷归属分三类:

  • 失败点在 message durable 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 的方式收敛到所属包修复。

登录后查看全文
WuKongIM