WuKongIM 集群空闲 CPU 代码级优化实战:从 5%~6% 压向 1% 的三板斧

原创2026-10-15 10:52:281,418 阅读
文章标签:即时通讯后端

WuKongIM 集群空闲 CPU 代码级优化实战:从 5%~6% 压向 1% 的三板斧

导读

本文基于 WuKongIM 仓库内《Cluster Idle CPU Code Optimization Implementation Plan》及其配套设计文档《2026-04-27-cluster-idle-cpu-code-optimization-design.md》,完整还原一次针对三节点集群空闲态 CPU 的代码级优化:用 RawNode.BasicStatus() 替代高成本的 RawNode.Status() 状态刷新、为 Slot Raft 引入按目标节点聚合的批量传输帧、为传输层字节指标加装计数器缓存。读完本文,你将掌握 WuKongIM 集群在空闲流量下 CPU 居高不下的根因分析方法、三项优化各自的设计与落地形态(含当前仓库实现与计划文档的差异对照)、对应的单元测试与 pprof/docker stats 验证手段,以及"不以放慢 Raft 时钟为代价换 CPU"的优化边界意识。

一、问题背景:业务近空闲,CPU 却稳定在 5%~6%

设计文档给出了明确的量化场景:一个三节点本地集群,托管 10 个 managed Slot,业务流量接近空闲时,每个 wk-node 的 CPU 仍稳定维持在 约 5%~6%。这不是应用消息造成的,而是"常开"的 Raft 心跳与传输层工作——通过 pprof 与指标定位到的热点函数如下:

  • pkg/transport.(*MuxConn).readLoop(连接读循环)
  • pkg/transport.(*priorityWriter).loop(优先级写循环)
  • pkg/slot/multiraft.(*Runtime).processSlot(Slot 调度处理)
  • pkg/slot/multiraft.(*slot).processReady(Ready 处理)
  • go.etcd.io/raft/v3.(*RawNode).Status(全量状态克隆)
  • pkg/slot/multiraft.(*slot).refreshStatus(状态刷新)
  • pkg/cluster.(*raftTransport).Send(Raft 消息发送)

归纳下来,空闲路径上有三个可避免的成本源:

  1. 状态刷新过度"重":每个 Slot 反复调用 RawNode.Status(),该方法会克隆完整的 Progress map 与配置追踪器(tracker.Config.Clone),而运行时其实只需要 leader id、term、commit index、applied index、raft role 这几个基础字段;
  2. 传输帧粒度过细:一个 Ready 批次里每个 Slot 的 Raft 心跳各自成帧发往对端,空闲稳态下产生大量小帧,放大 readFrame、priorityWriter.loop、WriteTo 与系统调用样本;
  3. 指标查找在热路径上:每个帧的收发都要对 CounterVec.WithLabelValues 做标签查找,累积成可观测开销。

优化目标明确写为:将每节点空闲 CPU 向 <1% 收敛,同时不改变 Raft tick/election 时序、不改变任何运维配置。

二、优化总纲:目标、非目标与"绝不降速"的边界

计划文档与设计文档共同划定了这次优化的红线:

维度 内容
核心目标 空闲 CPU 每 wk-node 趋近或低于 1%;RawNode.Status 不再是显著 pprof 热点;MuxConn.readLoop 与 priorityWriter.loop 样本显著下降;聚焦单测通过;不引入请求延迟回归
必须保留 现有 Raft tick/election 语义、公共 API、部署形态、单节点集群语义、既有指标名与标签
明确不做 不降低 WK_CLUSTER_TICK_INTERVAL、不抬高 election timeout、不依赖更慢的配置;不改 Raft 选举与 CheckQuorum 行为;不改应用发送/路由语义;不为 RPC 流量全局更换传输协议;不删除或重命名现有指标标签
兜底路线 若第一阶段未达空闲 CPU 目标,下一步是 pkg/slot/multiraft 内的调度器级批量(scheduler-level batching),而不是配置降速

"不改变 operator configuration"是整个方案的关键约束——这意味着所有收益都必须来自代码级优化,而非把心跳调慢、把选举拉长来"看起来省 CPU"。

三、优化一:让 Slot 状态刷新"分配友好"

3.1 为什么 RawNode.Status() 是热点

etcd raft 的 RawNode.Status() 会构造完整的 raft.Status,其中包含每个 peer 的 Progress 表与 tracker.Config 的克隆。在 WuKongIM 的 Slot 运行时里,状态刷新是每轮 processSlot/processReady 都可能执行的常规动作,空闲稳态下这些克隆与分配就成了纯浪费。

而 RawNode.BasicStatus() 恰好提供状态刷新真正需要的五个字段:Lead(leader id)、Term、Commit、Applied、RaftState(角色),且不克隆 Progress map。

3.2 计划中的实现形状

计划文档给出的核心改造落在 pkg/slot/multiraft/slot.go:

func (g *slot) refreshStatus() {
    st := g.rawNode.BasicStatus()
    g.mu.Lock()
    defer g.mu.Unlock()
    prevRole := g.status.Role
    g.status.LeaderID = NodeID(st.Lead)
    g.status.Term = st.Term
    g.status.CommitIndex = st.Commit
    g.status.AppliedIndex = st.Applied
    g.status.Role = mapRole(st.RaftState)
    if prevRole == RoleLeader && g.status.Role != RoleLeader {
        g.failLeadershipDependentLocked(ErrNotLeader)
    }
}

同时计划要求删除 processSlot 中 processReady 返回 true 之后的那次重复刷新(processReady 内部已刷新状态),只保留 processReady 内部的刷新以保证 Ready 处理后的 commit/apply 状态新鲜:

if g.processReady(context.Background(), r.opts.Transport) {
    return true
}
g.refreshStatus()
return false

计划还配套了一个"AST 守卫"同包测试 pkg/slot/multiraft/status_refresh_test.go:直接解析 slot.go 的语法树,断言 refreshStatus 函数体内不得出现对 .Status 的选择器调用,从源头锁死性能契约——防止未来有人无意间把 BasicStatus 改回 Status。该测试同时要求 refreshStatus 函数必须存在(找不到即失败)。

3.3 当前仓库的实际落地形态

从当前仓库源码看,这项优化已进一步演进为"按需二选一"的刷新策略(slot.go):

func (g *slot) refreshStatus() {
    if g.needsFullStatusRefresh() {
        g.refreshFullStatus()
        return
    }
    g.refreshBasicStatus()
}
  • refreshBasicStatus() 调用 g.rawNode.BasicStatus(),更新 leader/term/commit/applied/role,并累加 basicStatusRefreshCount 供回归测试断言;
  • refreshFullStatus() 仅在 !votersInitialized || votersDirty || needsLearnerProgressRefreshLocked() 时才调用 g.rawNode.Status(),用于补齐 CurrentVoters、CurrentLearners、ConfState 与 Progress 等"冷"数据,累加 fullStatusRefreshCount;
  • 两者共用 applyBasicStatusLocked(slot.go),其中保留了"本地 leader 变为非 leader 时触发 failLeadershipDependentLocked(ErrNotLeader)"的语义,且 Role 继续通过 mapRole 从 raft.StateType 映射(StateLeader → RoleLeader、StateCandidate → RoleCandidate、其余 → RoleFollower,见 slot.go)。

调度入口 Runtime.processSlot(runtime.go)也落实了计划"避免重复刷新"的要求:每轮最多在请求/Ready/Tick/控制动作处理完毕后,在 worked && !readyWorked 条件下补一次 g.refreshStatus(),而 processReady 内部在 Advance(ready) 后已刷新过。

与状态刷新配套的公共 API 语义同样得到保留(api.go):Runtime.Status(slotID) 返回缓存快照,Runtime.FreshStatus(ctx, slotID) 则通过 controlFreshStatus 控制动作在 Slot worker 上强制执行一次全量刷新——正是"普通 tick 走轻量 BasicStatus、需要完整视图时再走全量 Status"的分层设计。对应的行为契约测试见 fresh_status_test.go,例如 TestRuntimeFreshStatusReadsLeaderProgressAfterBasicOnlyElectionTicks 验证了"纯 BasicStatus 刷新后 Progress 为空、FreshStatus 后拿到完整 3 行 voter 进度"。

预期收益(设计文档口径):go.etcd.io/raft/v3.getStatus、tracker.Config.Clone 及相关分配成本从空闲 profile 中消失。

四、优化二:按目标节点聚合的 Raft 批量传输帧

4.1 设计动机

空闲稳态下,一个 Ready 批次内会有多个 Slot 的 Raft 心跳,如果每个心跳独立成帧,对端 readLoop/priorityWriter.loop/WriteTo 与系统调用都会被放大。方案是引入集群专属的批量帧:发送端按 Message.To 把信封分组,每个目标节点在一个批次内只收到一帧。

4.2 帧类型与线格式(计划定义)

计划在集群 codec 中新增消息类型:

const (
    msgTypeRaft            uint8 = 1   // 保留:单条 Slot Raft 消息(兼容与测试)
    msgTypeObservationHint uint8 = 2
    msgTypeRaftBatch       uint8 = 4   // 新增:批量 Slot Raft 消息
)

批量帧 body 采用大端定长头部 + 原始 raft 消息字节的布局:

[count:uint32]
repeated count times:
  [slot_id:uint64]
  [message_len:uint32]
  [message_bytes:message_len]

编码器先把每个 Envelope.Message 用 raftpb.Message.Marshal() 序列化,再统一拼装;解码器逐条校验:len(body) < 4 报"body too short"、每条记录头部不足 12 字节报"record header too short"、messageLen 越界报"message too short"、解码完还有残留字节报"trailing bytes"——任何畸形输入都返回错误而非 panic。

4.3 发送路径:按目标分组,一次一帧

计划给出的 raftTransport.Send 实现要点:

func (t *raftTransport) Send(ctx context.Context, batch []multiraft.Envelope) error {
    grouped := make(map[uint64][]multiraft.Envelope)
    order := make([]uint64, 0)
    for _, env := range batch {
        if err := ctx.Err(); err != nil {
            return err
        }
        target := uint64(env.Message.To)
        if target == 0 {
            continue
        }
        if _, ok := grouped[target]; !ok {
            order = append(order, target)
        }
        grouped[target] = append(grouped[target], env)
    }
    for _, target := range order {
        envelopes := grouped[target]
        body, err := encodeRaftBatchBody(envelopes)
        if err != nil {
            return err
        }
        shardKey := uint64(envelopes[0].SlotID)
        if err := t.client.Send(target, shardKey, msgTypeRaftBatch, body); err != nil {
            t.logSkippedBatch(target, envelopes, err)
        }
    }
    return nil
}

注意两个细节:

  • Message.To == 0 的目标被跳过,self/invalid target 行为保持不变;
  • 单目标发送失败不阻断其他目标:依赖 Raft 自身的重传机制,仅记录 cluster.transport.raft_batch.skipped 事件(字段含源节点、目标节点、消息条数与错误),避免一个不可用 voter 拖垮同一批次内对其他存活 voter 的选举/复制消息。

分组还带来一个排序语义的明确约定:目标组内部保持信封原始顺序;跨目标顺序本就不保证、也不要求,因此无需为此引入额外复杂度。

4.4 接收路径:共享单条处理助手

计划要求接收端注册 msgTypeRaftBatch,解码后逐条路由到统一的 stepRaftMessage 助手,最终进入 runtime.Step():

func (c *Cluster) handleRaftBatchMessage(body []byte) {
    records, err := decodeRaftBatchBody(body)
    if err != nil {
        c.transportLogger().Warn("drop malformed raft batch",
            wklog.Event("cluster.transport.raft_batch.malformed"),
            wklog.Error(err))
        return
    }
    for _, record := range records {
        c.stepRaftMessage(record.SlotID, record.Message)
    }
}

同时保留 legacy 单帧路径 msgTypeRaft(handleRaftMessage → decodeRaftBody → 同一 stepRaftMessage),作为测试与混合本地工具的兼容通道。transport_glue.go 的 Start 签名相应扩展为同时接受单帧与批量两个 handler。

4.5 当前仓库的实际落地形态

当前仓库已将 Slot Raft 批量帧完整落地,但位置与线格式与计划文档存在差异——这恰是阅读源码时最值得注意的点:

  • 消息类型定义在 pkg/cluster/net/ids.go:MsgSlotRaft uint8 = 32 + iota、MsgSlotRaftBatch(即 32/33),而非计划中的 1/4;
  • 发送端为 pkg/cluster/default_slots.go 中的 networkSlotTransport(实现 multiraft.Transport 接口,见 types.go):Send 先经 groupSlotRaftEnvelopes 按 env.Message.To 分组,再逐目标 encodeSlotRaftBatch 编码、clusternet.SendOwnedPayload(ctx, sender, nodeID, MsgSlotRaftBatch, payload) 发送;单目标失败同样只 Join 错误、不阻断其他目标(default_slots.go);
  • 线格式实际采用 slotRaftBatchMagic = "WKSRB1" 魔数前缀 + uvarint 紧凑编码(count、每个记录的 slot_id、message_len、message_bytes),并带完整的畸形防护:魔数不符、计数超界、截断 varint、消息体越界、尾随字节都会返回明确错误(default_slots.go)。相比计划中的定长大端布局,uvarint 对小值更省字节,是落地时的工程取舍;
  • 接收端为 slotRaftBatchHandler(default_slots.go):解码后逐条调用 runtime.Step(ctx, env),对 ErrSlotNotFound/ErrSlotClosed 静默跳过,其余错误返回。该 handler 通过 Node.registerDefaultSlotHandlers 注册到 transportServer(default_slots.go);
  • 优先级保持 Raft 语义:MsgSlotRaft 与 MsgSlotRaftBatch 在 pkg/cluster/net/transport.go 的 servicePriority 中均映射为 transport.PriorityRaft,且 isOrderedRaftService 将二者按"每 Raft sender 固定对端连接 + 接收端串行执行"处理,以保序(Append 必须先于 Heartbeat,避免 follower 越界提交)。

整套数据流(设计文档口径):

Slot runtime tick
  -> rawNode.Tick()
  -> rawNode.Ready()
  -> ready.Messages
  -> wrapMessagesInto([]Envelope)
  -> raftTransport.Send()
  -> group envelopes by target node
  -> encode msgTypeRaftBatch body
  -> transport.Client.Send(target, msgTypeRaftBatch)
  -> peer transport.Server dispatch
  -> decode batch records
  -> handle one raft record
  -> runtime.Step(slotID, raftpb.Message)

状态更新仍停留在本地:

processSlot/processReady
  -> refresh cached Status from RawNode.BasicStatus()
  -> Runtime.Status(slotID) returns cached Status snapshot

另外值得对照的是 pkg/cluster/control 下的 Controller Raft 传输(control/transport.go)也已采用"按 msg.To 分组 → 一次性编码批量 → 目标分片队列 + 有界 worker"的模式,默认 4 个 worker、每 worker 队列 256,超时 200ms——可见"按节点批量"是该集群两类 Raft 传输的共同设计取向。

五、优化三:缓存传输字节指标计数器

5.1 问题:CounterVec.WithLabelValues 的每帧查找

wukongim_transport_sent_bytes_total / wukongim_transport_received_bytes_total 按 msg_type 标签区分流量。若每个帧都走 sentBytes.WithLabelValues(msgType).Add(...),Prometheus 的标签匹配(内部含正则与哈希)就会出现在最热的收发路径上。空闲场景心跳帧密集,这项开销被放大到 pprof 可见。

5.2 计划:预加载常用标签的 Counter 句柄

计划在 pkg/metrics/transport.go 中为 TransportMetrics 增加两个缓存 map,并预加载常用消息类型:

type TransportMetrics struct {
    // existing fields...
    sentBytesCache     map[string]prometheus.Counter
    receivedBytesCache map[string]prometheus.Counter
}

var commonTransportMsgTypes = []string{"1", "3", "4", "rpc_request", "rpc_response"}

初始化时一次性取出句柄:

m.sentBytesCache = make(map[string]prometheus.Counter, len(commonTransportMsgTypes))
m.receivedBytesCache = make(map[string]prometheus.Counter, len(commonTransportMsgTypes))
for _, msgType := range commonTransportMsgTypes {
    m.sentBytesCache[msgType] = m.sentBytes.WithLabelValues(msgType)
    m.receivedBytesCache[msgType] = m.receivedBytes.WithLabelValues(msgType)
}

观测方法先查缓存、命中即 counter.Add,未命中才回退向量路径:

func (m *TransportMetrics) ObserveSentBytes(msgType string, bytes int) {
    if m == nil {
        return
    }
    if counter := m.sentBytesCache[msgType]; counter != nil {
        counter.Add(float64(bytes))
        return
    }
    m.sentBytes.WithLabelValues(msgType).Add(float64(bytes))
}

关键约束:不改变指标名与标签值,缓存路径与回退路径产出的公开指标必须完全一致(计划配套测试 TestTransportMetricsPreloadsCommonByteCounters 同时断言缓存命中与 custom 标签回退的值)。

5.3 当前仓库的实际落地形态

当前仓库的实现目标一致、机制不同:不再维护"预加载数组 + map",而是用 sync.Map 做懒加载句柄缓存(pkg/metrics/transport.go 的 sentBytesHandles/receivedBytesHandles,以及 transport.go 的 sentBytesHandle/receivedBytesHandle):

func (m *TransportMetrics) sentBytesHandle(msgType string) prometheus.Counter {
    if value, ok := m.sentBytesHandles.Load(msgType); ok {
        return value.(prometheus.Counter)
    }
    handle := m.sentBytes.WithLabelValues(msgType)
    value, _ := m.sentBytesHandles.LoadOrStore(msgType, handle)
    return value.(prometheus.Counter)
}

ObserveSentBytes/ObserveReceivedBytes 经由 sentBytesHandle/receivedBytesHandle 收敛句柄(transport.go)。LoadOrStore 保证并发下每个标签只做一次 WithLabelValues,此后热路径退化为 sync.Map 读 + Counter.Add。同一思路也覆盖了 RPC 时长/总数、dial、enqueue 等句柄(rpcDurationHandles、rpcTotalHandles 等),说明"句柄缓存"已是该模块的通用模式;而公开指标输出不变这一点,由 pkg/metrics/registry_test.go 中针对 rpc_request 等标签的既有断言持续守护。

六、验证与验收:如何证明空闲 CPU 真的降下来了

6.1 单元测试关卡

聚焦测试(计划完成标准之一):

go test ./pkg/slot/multiraft ./pkg/cluster ./pkg/metrics -count=1

配套的更广回归(视本地耗时取舍,至少跑 pkg/transport):

go test ./pkg/transport ./internal/app -count=1

其中重点关卡包括:状态刷新 AST 守卫测试、raft 批量编解码 round-trip 与畸形 body 拒绝测试、TestRaftTransportBatchesMessagesByTarget 同目标批量聚合测试、legacy 单帧兼容测试,以及指标缓存路径测试。

6.2 重建三节点 dev 集群

docker compose up -d --build wk-node1 wk-node2 wk-node3

等待所有节点的 /debug/cluster 返回健康的 assignments/runtime views。

6.3 docker stats 基线对比

out=/tmp/wukongim-idle-pprof/$(date +%Y%m%d-%H%M%S)-after-code-opt
mkdir -p "$out"
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}' | tee "$out/docker-stats.txt"

验收口径:每个 wukongim-wk-node*-1 应显著低于优化前约 5%~6% 的基线,理想状态贴近或低于 1%。

6.4 pprof 热点评判

当前仓库的 compose 端口映射为 15001/15002/15003 → 5001(见 docker-compose.yml),可采集 30 秒 profile 并输出 top:

for node in 1 2 3; do
  port=$((15000+node))
  curl -fsS "http://127.0.0.1:${port}/debug/pprof/profile?seconds=30" -o "$out/node${node}.cpu.pb.gz"
  go tool pprof -top -nodecount=40 "$out/node${node}.cpu.pb.gz" > "$out/node${node}.cpu.top.txt"
done

判定标准:

  • RawNode.Status、getStatus、tracker.Config.Clone 消失或可忽略;
  • MuxConn.readLoop、priorityWriter.loop 显著下降;
  • 若单节点空闲 CPU 仍高于 1%,先审视下一个热点再动代码,而不是急着降速。

6.5 收尾

如确已运行运行时验证,把结论沉淀为报告文档(含日期、build/commit、docker stats 摘要、pprof 产物目录、剩余热点、目标达成与否),并执行一次可选的消息冒烟测试,确认网关请求不被放慢的时钟拖累。

七、风险与边界:这次优化"不碰什么"

计划文档与设计文档列出的主要风险与对策值得照单全收:

风险 缓解
批量帧引入新线格式 bug 编解码 round-trip 测试 + 畸形输入测试(截断、越界、尾随字节)
批量后丢失单消息级指标 字节指标保持帧级口径;如需消息级计数,留待后续独立变更
按目标分组改变发送顺序 组内保持信封原序;跨目标顺序本无保证且无语义要求
删除重复状态刷新延迟可见性 Ready 处理后保留一次刷新,tick/无 Ready 路径保留一次轻量刷新
指标缓存路径与公共输出不一致 缓存与回退共用同一 vector,测试断言两路径指标值一致

最后重申边界:本优化不需要运维修改任何配置——WK_CLUSTER_TICK_INTERVAL、WK_CLUSTER_ELECTION_TICK、WK_CLUSTER_HEARTBEAT_TICK 均保持不变。WuKongIM 默认的 Slot Raft 时序(pkg/cluster/FLOW.md)为 50ms 本地 tick、两 tick 心跳(即心跳约每 100ms)、40 tick 选举底线(选举至少两秒后开始),提议复制保持事件驱动。若第一轮代码优化未能达标,下一步仍是代码级手段(调度器级批量),而非牺牲集群响应速度换取 CPU 数字。

登录后查看全文
WuKongIM