WuKongIM wk-sim 有界并发流量调度:从 `WK_SIM_TRAFFIC_CONCURRENCY` 到 1000 通道压测的完整链路

原创2026-10-15 11:12:371,688 阅读
文章标签:即时通讯后端

WuKongIM wk-sim 有界并发流量调度:从 WK_SIM_TRAFFIC_CONCURRENCY 到 1000 通道压测的完整链路

导读

本文围绕 WuKongIM 仓库中的实现计划文档 2026-05-18-wk-sim-traffic-concurrency.md,深入剖析 wk-sim 开发仿真器如何通过一个可选的有界并发旋钮,让 Docker Compose 下 1000 通道(500 单聊 + 500 群聊)的仿真流量在服务端 CPU pprof 优化之前就能稳定到达预设的 ingress 速率。读完本文,你将掌握 WK_SIM_TRAFFIC_CONCURRENCY 的完整传递链路、runScheduledMessagesByKey 有界调度器的内部原理、顺序/并发双路径的兼容设计,以及如何用 /status 与 pprof 验证压测效果并调整本地压测参数。


一、背景:顺序发送为什么到不了目标速率

wk-sim 是 WuKongIM 的可选本地开发仿真器,它通过 wkcli bench dev-sim 运行,让一批确定性用户保持在线,并持续向三个节点的集群发送单聊/群聊消息。在并发旋钮加入之前,person/group 工作负载采用顺序发送:每个 send 请求必须等上一次 send+sendack 往返完成,才能发出下一条消息。

这种模型在低通道数、低速率下没有问题,但当 Docker Compose 配置扩展到 500 个单聊通道 + 500 个群聊通道、目标是每秒数百条 ingress 消息时,问题就暴露了:

  • 每次发送都依赖一次完整的 send+sendack 网络往返(RTT);
  • 本地开发环境的 RTT 一旦偏高,顺序发送的吞吐就被 RTT 上限封死;
  • 结果是在服务端 CPU 尚未成为瓶颈之前,压测端自己先“供不上货”,/status 观察到的实际发送速率明显低于配置目标,也就无法为 CPU pprof 采样提供足够的压力。

计划文档给出的目标非常明确:让 wk-sim 生成有界的并发流量(bounded concurrent traffic),使 1000 通道的 Docker Compose 运行能在服务端 CPU pprof 优化之前达到预期 ingress 速率。

二、架构总览:一个旋钮贯穿四层

计划的架构设计可以用一句话概括:增加一个可选的 per-traffic 并发旋钮,默认保持现有的顺序行为,从而不影响普通 wkbench 场景。

WK_SIM_TRAFFIC_CONCURRENCY (环境变量)
        │
        ▼
internal/bench/devsim/config.go  TrafficConfig.Concurrency
        │  BuildBenchInputs()
        ▼
model.TrafficConfig.Concurrency  (派生到 person/group 流量流)
        │
        ▼
worker/person_runner.go / group_runner.go
        │  bundle.traffic.Concurrency → PersonConfig.MaxConcurrency / GroupConfig.MaxConcurrency
        ▼
workload runFor() → runScheduledMessagesByKeyUntilWithStats()
        │
        ▼
scheduler.go 有界调度器(保持速率节拍 + 限制在途 send+sendack)

整条链路的技术栈为 Go,涉及 internal/bench 下的 model/devsim/worker/workload 包,以及 Docker Compose 的 dev-sim profile。下面是每一层的落地细节。

三、核心:internal/bench/workload/scheduler.go 有界调度器

计划 Task 1 要求先写失败测试、再实现 runScheduledMessages。最终实现落在 scheduler.go,它实际上提供了一族函数,围绕一个有界调度核心展开。

3.1 函数家族与顺序兼容路径

入口函数:

func runScheduledMessages(ctx context.Context, totalMessages int, interval time.Duration, maxConcurrency int, send func(context.Context, int) error) error {
	return runScheduledMessagesByKey(ctx, totalMessages, interval, maxConcurrency, nil, send)
}

当 maxConcurrency <= 1 时走顺序兼容路径,由 runSequentialMessagesUntil 实现(scheduler.go)。它保留原有行为的同时还多了一层窗口防护:

  • 若 duration(窗口)已到,不再准入新的操作;
  • 已准入的那一次操作允许跑到终态,作为阶段尾部交给随后的有界 drain;
  • 每条消息之间按 interval 睡眠,保持原有速率节拍。

计划中“默认保持当前顺序行为”的要求,正是由这一路径保证的:worker 只有在 MaxConcurrency > 1 时才切到并发路径。

3.2 有界并发路径:runScheduledMessagesByKey

并发核心是 runScheduledMessagesByKeyLimitUntilWithStats(scheduler.go),它同时承担两个约束:

  1. 全局在途上限:maxConcurrency 限制整个流量流中同时进行的 send 操作数量;
  2. 同 key 串行化:maxInFlightPerKey(默认 1)保证共享同一个 key 的发送不会流水线化。

第二个约束非常关键——计划文档明确写道,这样做是为了“keep one simulated client from pipelining sendacks”,即防止同一个模拟客户端在收到 sendack 之前就堆积多条发送,从而让一个客户端永远只有一个在途往返,这与真实 IM 客户端行为一致,不会人为制造出服务器端根本不可能遇到的并发形态。

调度核心 scheduledMessageScheduler.run(scheduler.go)是一个事件循环,维护以下数据结构:

type scheduledMessageScheduler struct {
	totalMessages  int
	maxConcurrency int
	keyForOffset   func(int) string
	send           func(context.Context, int) error
	startAt        time.Time
	stopAt         time.Time
	interval       time.Duration

	nextOffset     int
	active         int
	keyLimit       int
	pendingNoKey   scheduledMessageTaskQueue   // 无 key 任务 FIFO
	pendingByKey   map[string]*scheduledMessageTaskQueue
	readyKeys      []string                    // 就绪 key 轮转队列
	busyKeys       map[string]int              // 每个 key 当前在途数
	windowClosed   bool
}

循环每轮做四件事:消化完成结果(doneCh)、按节拍准入到期任务(enqueueDue)、在 active < maxConcurrency 前提下分派任务(dispatch)、记录统计(observeStats),然后根据下一次到期时间或窗口截止时间设置 timer 等待。

3.3 速率节拍与窗口语义

enqueueDue 严格按原始到达时钟计算到期时间:

if s.interval > 0 {
	dueAt := s.startAt.Add(s.interval * time.Duration(s.nextOffset))
	if now.Before(dueAt) {
		return
	}
}

这意味着并发只叠加在延迟上,不改变发送节奏:第 N 条消息仍在 startAt + N×interval 时刻才允许准入,与顺序路径的节拍完全一致。interval 由上游计算(见第五节),例如窗口 10s、总消息数 2500,则 interval ≈ 4ms。

窗口语义体现在 stopAt 与 windowExpired/closeWindow:

  • stopAt 由调用方传入的 admissionDeadline 或按 interval × totalMessages 推导的截止时间决定;
  • 一旦窗口过期,closeWindow 立即丢弃所有尚未准入/未分派的任务(并分别记录 DroppedPendingWindowExpired 与 DroppedUnstartedWindowExpired),只允许已准入的在途操作收尾;
  • nextTimer 在窗口关闭后不再设置任何过期 timer,只等已准入操作完成或上下文取消。

这套语义保证:压测窗口的起止时刻是确定的,不会因为并发排队而把流量“拖”出窗口边界,这对后续按时间窗计算实测速率至关重要。

3.4 调度器统计指标

调度器通过 scheduledMessageStats 与 scheduler_metrics.go 暴露可观测指标:

  • workload_scheduler_planned_total:准入前先发布的计划总数(计划文档要求“在第一个 SEND 可能阻塞之前发布不可变分母”,让生命周期观测者在窗口仍活跃时就能看到配置的计划量);
  • workload_scheduler_enqueued_total / workload_scheduler_dispatched_total:已入队/已分派数;
  • workload_scheduler_busy_key_stall_total:因 key 忙而暂停分派的次数;
  • workload_scheduler_dropped_total{reason="pending_window_expired"|"unstarted_window_expired"}:窗口过期丢弃数;
  • workload_scheduler_max_pending / workload_scheduler_max_active / workload_scheduler_max_busy_keys:排队深度、在途峰值、忙 key 数的观测值;
  • workload_dispatch_lag_seconds:准入迟到程度相对原始到达时钟的延迟分布。

这些指标让“并发是否真正追上了目标速率”可以被量化验证,而不是靠猜。

四、调度器的测试防线:scheduler_test.go

计划 Task 1 的核心测试用例(total=6, concurrency=3 + 阻塞发送函数)已在仓库落地为 TestRunScheduledMessagesBoundsInFlight:断言前 3 条(offset 0/1/2)启动后,在释放一个槽位之前第 4 条绝不能启动,释放后第 3 号 offset 才被调度。这与计划文档描述的验收标准逐字吻合。

仓库还额外覆盖了计划之外的边界,反映调度器的演进深度:

测试 验证点
TestRunScheduledMessagesByKeySerializesSameKey 同一个 sender key 上,下一条必须等上一条 sendack 完成
TestRunScheduledMessagesByKeyLimitAllowsTwoInFlightPerKey maxInFlightPerKey=2 时同 key 允许 2 个在途
TestRunScheduledMessagesByKeySkipsBusyKeyWhenDispatching 分派时跳过忙 key,让空闲 key 继续推进
TestRunScheduledMessagesByKeyDropsBusyKeyWaitersAfterWindowExpires 窗口过期后丢弃忙 key 等待者
TestRunScheduledMessagesStopsSchedulingWhenWindowExpires 窗口过期即停止准入
TestRunScheduledMessagesByKeyDispatchesReadyKeysBehindLargeBusyPrefix 10 万级忙 key 前缀下就绪 key 仍能推进(使用 testing/synctest)

运行方式:

go test ./internal/bench/workload -run TestRunScheduledMessages -count=1
go test ./internal/bench/workload ./internal/bench/worker -count=1

五、工作负载接线:person/group 双路径切换

计划 Task 2 要求把流量并发传入 person/group 工作负载,并让 runFor 使用新调度器。落地情况如下。

5.1 配置结构

  • person.go 的 PersonConfig.MaxConcurrency int,注释明确:bounds concurrent send+sendack operations. Zero preserves sequential sends.;
  • group.go 的 GroupConfig.MaxConcurrency int,语义相同;
  • person_runner.go 与 group_runner.go 在构造 workload 时直接传入 bundle.traffic.Concurrency。

5.2 person 负载的调度切换

person.go 的 runFor 逻辑:

  1. 计算 totalMessages 与 interval:
func scheduledMessageCount(duration time.Duration, perSecond float64, channelCount int) int {
	// count = duration.Seconds() * perSecond * channelCount
}
func scheduledMessageInterval(duration time.Duration, totalMessages int) time.Duration {
	// interval = duration / totalMessages
}
  1. 若 MaxConcurrency > 1:走 runScheduledMessagesByKeyUntilWithStats,并以 pair.SenderUID 作为 key(person.go),从而天然保证同一发送者串行、不同发送者可并行;
  2. 否则:走 runSequentialMessagesUntil 顺序路径,并保留 warmup 特殊处理(warmup 窗口时长视为 0,只控制准入停止时刻)。

5.3 group 负载的调度切换

group.go 的 runFor 在 MaxConcurrency > 1 时更进一步:

  • 当 sender pick 策略为 round_robin 时,走专门的 runExactGroupWindow(见 exact_group_window.go),保证每个群通道在一个窗口内精确收到预期消息数;
  • 其他策略下走 runScheduledMessagesByKeyUntilWithStats,以 senderUID(channel, messageIndex) 作为 key。

这意味着群聊场景下,并发调度还叠加了“精确群窗口”与“确定性发送者选择”两层语义,确保群聊 fanout 的可验证性不被并发破坏。

六、dev-sim 配置:Concurrency 字段与 WK_SIM_TRAFFIC_CONCURRENCY

计划 Task 3 在 devsim 侧落地为三处。

6.1 配置结构与环境覆盖

config.go 中的 TrafficConfig:

// TrafficConfig controls the simulator's low-rate message workload.
type TrafficConfig struct {
	PayloadSizeBytes int `json:"payload_size_bytes" yaml:"payload_size_bytes"`
	// PersonRatePerChannel is the per-channel rate for person traffic.
	PersonRatePerChannel model.Rate `json:"person_rate_per_channel" yaml:"person_rate_per_channel"`
	// GroupRatePerChannel is the per-channel rate for group traffic.
	GroupRatePerChannel model.Rate `json:"group_rate_per_channel" yaml:"group_rate_per_channel"`
	// Concurrency bounds in-flight send operations per traffic stream. Zero preserves sequential sends.
	Concurrency int `json:"concurrency" yaml:"concurrency"`
	VerifyRecv  string `json:"verify_recv" yaml:"verify_recv"`
	Warmup      time.Duration `json:"warmup" yaml:"warmup"`
	Window      time.Duration `json:"window" yaml:"window"`
	Cooldown    time.Duration `json:"cooldown" yaml:"cooldown"`
}

默认值在 defaultConfig() 中:Concurrency: defaultTrafficConcurrency(常量定义于 config.go,值为 64)。applyEnvOverrides 支持环境变量覆盖:

if err := applyIntEnv(env, "WK_SIM_TRAFFIC_CONCURRENCY", &cfg.Traffic.Concurrency); err != nil {
	return err
}

校验规则(validateConfig):traffic.concurrency 不允许为负;traffic.warmup、traffic.cooldown 不允许为负,traffic.window 必须大于零,person/group 每通道速率必须大于零。

6.2 派生到流量流

BuildBenchInputs(config.go)把紧凑配置展开成标准 wkbench 输入:person 与 group 两条流量流都会写入 model.TrafficConfig{..., Concurrency: cfg.Traffic.Concurrency},并通过 planner.Build 生成确定性单 worker 分片计划。测试 config_test.go 覆盖了默认值(64)、环境变量覆盖(WK_SIM_TRAFFIC_CONCURRENCY=32 生效)以及 build-input 传播(两条流量流都拿到 16)。

6.3 YAML 中的配置方式

默认样例 dev-sim.yaml 中未显式写 concurrency(使用内置默认 64),但你可以直接追加:

traffic:
  payload_size_bytes: 128
  person_rate_per_channel: 0.2/s
  group_rate_per_channel: 0.2/s
  concurrency: 64
  verify_recv: sampled
  warmup: 10s
  window: 10s
  cooldown: 1s

LoadConfig 使用 yaml.Decoder.KnownFields(true) 严格解析,未知字段会直接报错,避免拼写错误悄悄失效。

七、Compose 默认:1000 通道高吞吐 profile

docker-compose.yml 中 wk-sim 服务属于 dev-sim profile,默认环境变量如下:

wk-sim:
  profiles: ["dev-sim"]
  entrypoint: ["/usr/local/bin/wkcli"]
  command: ["bench", "dev-sim", "--config", "/etc/wkbench/dev-sim.yaml"]
  environment:
    WK_SIM_USERS: ${WK_SIM_USERS:-1000}
    WK_SIM_PERSON_CHANNELS: ${WK_SIM_PERSON_CHANNELS:-500}
    WK_SIM_GROUP_CHANNELS: ${WK_SIM_GROUP_CHANNELS:-500}
    WK_SIM_GROUP_MEMBERS: ${WK_SIM_GROUP_MEMBERS:-10}
    WK_SIM_RATE: ${WK_SIM_RATE:-0.25/s}
    WK_SIM_TRAFFIC_CONCURRENCY: ${WK_SIM_TRAFFIC_CONCURRENCY:-128}
    WK_SIM_WARMUP: ${WK_SIM_WARMUP:-10s}
    WK_SIM_VERIFY_RECV: ${WK_SIM_VERIFY_RECV:-none}
    WK_SIM_UID_PREFIX: ${WK_SIM_UID_PREFIX:-devsim-u}

按 docker/sim/README.md 的说明:500 单聊通道 + 500 群聊通道、每通道 0.25/s,目标约为 250 ingress 消息/秒;由于群聊 fanout,投递量会高于 ingress 量。默认关闭接收校验(verify_recv=none),以保证本地投递滞后时仿真器仍持续制造 ingress 压力。

八、验证与剖析:/status 与 CPU pprof

计划 Task 4 的验收包含三件事,均有对应落地:

  1. 单测回归:
go test ./internal/bench/workload ./internal/bench/worker ./internal/bench/devsim -count=1
  1. 重建并确认 /status 速率:wk-sim 暴露 19091 端口,状态 API 由 status.go 实现,Snapshot 中包含 MessagesSent、SendErrors、RecvErrors 以及 Config(含 Concurrency),通过 curl http://127.0.0.1:19091/status 在短时间窗内取两次 messages_sent 差值即可折算实测速率,与配置目标对比。

  2. 采集节点 CPU pprof:确认速率达标后,对 wk-node1/2/3 抓取 pprof 样本,用 top 查看累计函数排名,作为服务端热路径优化的输入。

九、实操:从启动到调参的完整命令

9.1 启动三节点开发集群与仿真器

docker compose --profile dev-sim up -d --build

注意:普通 docker compose up -d 不会启动 wk-sim,必须显式启用 dev-sim profile。

9.2 检查仿真器状态

curl http://127.0.0.1:19091/healthz
curl http://127.0.0.1:19091/status
docker compose logs -f wk-sim

9.3 小笔记本降载

计划文档与 README 都强调并发旋钮的“双向可调”:

WK_SIM_USERS=40 \
WK_SIM_PERSON_CHANNELS=10 \
WK_SIM_GROUP_CHANNELS=3 \
WK_SIM_GROUP_MEMBERS=12 \
WK_SIM_RATE=0.5/s \
WK_SIM_TRAFFIC_CONCURRENCY=16 \
WK_SIM_VERIFY_RECV=sampled \
WK_SIM_UID_PREFIX=dev-u \
  docker compose --profile dev-sim up -d wk-sim

9.4 何时调高/调低并发

  • 调高 WK_SIM_TRAFFIC_CONCURRENCY:当本地 RTT 使发送压力封顶、/status 实测速率低于目标时——有界调度器允许更多 send+sendack 并行在途,从而用并发抵消 RTT;
  • 调低:在小型笔记本上调试时降低开销,或希望复现接近真实客户端串行行为时。

由于调度器在 maxConcurrency <= 1 时自动回退顺序路径,且默认配置(dev-sim 内置 64、Compose 默认 128)都远大于 1,普通 wkbench 场景不受影响——这正是计划“对正常场景保持默认顺序行为”的兼容设计。

9.5 组合式验证

scripts/dev-sim-compose-smoke.sh          # 本地 Compose 冒烟:起 4 个容器、等 /status 报告 running、查 panic
GOWORK=off go test -tags=e2e ./test/e2e/bench/devsim_smoke -count=1   # 可选的 e2e 冒烟

十、小结:一次“压测端供给侧”的工程化修复

本计划表面上只加了一个并发旋钮,实际解决的是一个典型的压测陷阱:在服务端尚未饱和时,压测客户端自身的串行往返先成为瓶颈。通过 scheduler.go 的有界调度器,wk-sim 在保持速率节拍、保持同客户端串行 sendack 语义的前提下,用受控的并发把吞吐从 RTT 的束缚中解放出来;再通过 WK_SIM_TRAFFIC_CONCURRENCY 环境变量把控制权交还给运维者,配合 /status 实测速率与调度器统计指标,形成“配置 → 调度 → 可观测 → 验证”的完整闭环,为后续服务端 CPU pprof 热路径优化提供了稳定、可信的压力源。

参考文件索引

登录后查看全文
WuKongIM