• 即时通讯
• 后端

本篇技术指南以仓库内 docs/reports/2026-10-01-permission-main-integration.md 为主体，系统还原 WuKongIM 针对 Issue #977「SEND 权限/热 Channel 追加等待」修复在合并主分支（main）后的完整验证过程：如何通过 12 组并发 burst 对比证明修复有效，如何通过 9 组顺序控制对比暴露仍未达标的事实，以及如何用"首次尝试即通过"的 Linux 500 SEND/s CI 门禁做独立交叉验证。读完本文，你将掌握 WuKongIM 在热 Channel 追加路径上的修复原理、一套可复现的"老→新"性能取证实验设计，以及这套项目在"非回归判定"上的严谨证据边界。

一、背景：Issue #977 与"不急于下结论"的修复路径

WuKongIM 是一个面向高并发场景的开源即时通讯内核。Issue #977 追踪的是一个发生在消息发送链路中的热点问题：当大量独立调用方并发向同一 Channel（或同属一个物理 Slot 的 Channel）发送 SEND 时，权限（permission）评估与 Channel 追加（append）准入阶段会产生大量重复的权限信封（envelope）与按 Slot 的 barrier 调用，进而把 SENDACK 尾延迟拖到数百毫秒级。

在 2026-10-01-permission-request-timeline.md 中，源绑定（source-bound）诊断已经给出了慢速边界证据：

诊断结论明确：主导的等待是 admitted-append waiting（已准入后的追加等待），即瓶颈不在权限计算本身，而在于准入与追加之间的排队调度。围绕这一结论，修复实现了两个关键改动：

1. 有界同 Channel 队列前缀合并（queue-prefix repair）——允许OrderedSubmitter在满足严格条件时合并已就绪的同一 Channel 前缀，减少重复路由与追加批次；
2. 独立 deadline 修复（deadline repair）——权限（authority）解析不再借用首个 item 的上下文，而是复用每个 Channel 的全量 items 生命周期，终止 watcher 注册并保留每个过期 item 自身的 deadline 结果。

修复源码收敛在干净提交5b8379497f1127c2e298d27925888fb701167f58（时间线报告），其后的主分支集成候选为a991974f8d34423b5e59a12bd24e15de21b1a723（本文报告）。注意：这两份报告都没有声称 Issue #977 已完结——在顺序控制样本全部达标之前，"整体非回归"始终是未验证状态。

二、主分支集成的边界与溯源：合并了什么、改了什么

2.1 合并预览与内容冲突

在639b7c35f的 CI 尚未开始时，main 已经继续前移，产生了"合并预览冲突"。为此，验证工作区将 main 的精确提交623091def1951fea6746bd9ac3b63a8a9ba30208作为a991974f8的 second parent 进行合并。合并过程中只有 CHANGELOG 与自动生成的 FLOW_INDEX 需要内容解决：

• 两个父分支的 CHANGELOG 条目都被保留；
• FLOW_INDEX 重新生成；
• 传入的流事件组合（stream-event composition）原样保留；
• SEND 权限/追踪、Router 与 OrderedSubmitter 的实现与639b7c35f完全一致；
• 受保护的.github/.agents文件与 main 一致，未修改任何策略文件。

也就是说，这是一次"只做集成、不夹带实现变更"的干净合并，为后续所有性能数据提供了可溯源的基线。

2.2 构建身份与 CI 预览校验

干净构建显式把 Git 绑定到本次任务工作区，并验证：

• vcs.revision=a991974f8d34423b5e59a12bd24e15de21b1a723
• vcs.modified=false
• 二进制 SHA-256：63ecbcd167f5aef4eacf493cb616558e6c3e2fbe1609faa5edb6b43e2120f6ad

首次尝试的 CI 使用合并预览ec392bd9845ec89e36ff892e0a67328f40a1b01d，其父提交已验证、整棵目录树与受测候选树一致。而本报告/bundle 的追加内容属于纯文档更新，需要自己独立的 final-head CI 状态；下述所有源码级结论仍绑定在a991上。这种"提交身份—二进制哈希—CI 预览—受测树"四者互锁的做法，正是 WuKongIM 性能取证体系里防止"用错误源码冒充结论"的核心机制。

三、修复的实现原理：OrderedSubmitter 的准入/完成拆分

要理解验证报告里反复出现的"并发 burst 通过、顺序控制超阈值"，必须先看懂修复载体OrderedSubmitter。它位于 internal/runtime/channelappend/ordered_submitter.go，其设计目标是：在不重排重叠 Channel 路由调用的前提下，把"准入（admission）"与"完成（completion）"分离，让独立批次可以并发执行。

3.1 有界参数

type OrderedSubmitterOptions struct { Workers int // 正在执行或发布完成的批次最大数 Capacity int // 已准入记录总数（含运行中与 callback 持有的） PayloadCapacity int // 借用的 payload 字节上限（到 callback 返回前） BatchMaxRecords int // 合并且已就绪 job 的记录数上限 BatchMaxBytes int // 合并且已就绪 job 的字节数上限 CommandChannelSuffix string // 必须匹配 Router 的 canonical key codec Goroutines *goruntimeregistry.Registry }

这些选项在应用装配点 internal/app/deferred_send.go 中被实例化：

owner, err := channelappend.NewOrderedSubmitter(channelappend.OrderedSubmitterOptions{ Workers: workers, Capacity: runtime.AsyncSendQueueCapacity, PayloadCapacity: payloadCapacity, BatchMaxRecords: session.AsyncSendBatchMaxRecords, BatchMaxBytes: session.AsyncSendBatchMaxBytes, CommandChannelSuffix: a.cfg.Message.CMDChannelSuffix, Goroutines: a.goroutines, }, router)

其中workers取网关AsyncSendWorkers与队列容量中的较小值，payloadCapacity取workers × AsyncSendBatchMaxBytes与MaxInboundBytes的较大值——保证每个执行 worker 最多持有一份最大微批次 payload，同时允许单个合法入站帧大于批次目标。如果运算溢出，装配直接返回ErrInvalidConfig。

3.2 合并的严格条件（为什么不会乱序）

Submit按每个 job 的 distinct canonical Channel 建立 FIFO 依赖链（lanes），只有blocked == 0的 job 才进入就绪队列；worker 从队头取任务时，只合并"已经就绪"的队列前缀：

• 每个 job 至少有一条未解析的 Channel 前驱时才阻塞，ready job 之间互不为前驱；
• 合并受BatchMaxRecords/BatchMaxBytes约束，绝不为了凑满批次而等待，也绝不拆分原始 job；
• 每个 callback 保留自己的 record/payload 预留直到返回，最后一个 callback 会"栅栏"（fence）后续同 Channel 路由；
• 容量（Capacity/PayloadCapacity）在 callback 返回后才释放，因此Close超时不会丢弃已准入的工作，后来的调用者只是加入同一 drain。

集成测试 internal/runtime/channelappend/ordered_coalescing_integration_test.go 中的TestOrderedSubmitterCoalescesOnlyReadyJobsWithinTargets精确验证了这一点：只有"job 1 完成后才就绪的后继"不会与正在执行的前缀合并，records/bytes两种目标下的合并批次划分与依赖顺序都被断言。

报告提到"受控 ordered-hotlane 与独立 authority-deadline 集成检查在 race 下通过"，对应的正是 ordered_submitter_integration_test.go 等测试族。修复后的一次 traced 运行（4a5f66744）中，admitted wait 降到 9.605 ms、p99 为 45.348 ms——这份数据因为 driver 含后续新增的 inactive CPU 选项、harness 哈希不同，只作为支撑性阶段证据，不冒充严格匹配的老/新性能对。

四、本地全新验证：四层检查全部通过

在跑性能对比之前，a991先通过四层本地验证：

此外，入站 public stream-online E2E 在 17.602 s 内通过，覆盖单节点/三节点的群组/单聊路由、terminal/private 事件与离线恢复；独立的 Standards 与 Spec 集成审查各报告0 个确认发现——但它们只证明静态集成安全，不重新标签旧性能证据，也不替代这些新鲜运行。

五、新鲜的老/新对比：12 组 burst 全过，9 组顺序控制全败

5.1 实验设计（取证协议）

runner 预选三对 old→new，旧版424d03eb298b972ec572261d617972eecb5523c5→ 干净候选a991974f8，六次运行全部成功、无重试、无替换。两侧使用同一份冻结 driver/native probe：

• 三节点 Darwin/arm64，GOMAXPROCS=4
• 256 Hash Slots、12 个物理 Slot、每 Slot 一个 metadata voter、三份 message replica
• 每个 placement 保留 64 个顺序控制、两波各 32 独立会话（joined）、ban/unban 控制、恰好 161 条已提交历史
• placement/配置/拓扑与 Channel runtime 元数据逐对匹配

实验窗口内不跑 profile、不跑请求 tracing、不加 histogram 族，保留原有的 20 ms ownership sampler 与 CPU-cut 开销。原始进程启动身份、Mach ticks/timebase、全部 ACK 与两次 cut 均归档；验证器独立重算全部 48 个 CPU 区间，并以最近邻（nearest-rank）方式计算 p99——64 个观测值时 p99 等于 max。

5.2 12 组并发 burst：全部在 ≤5% 阈值内

跨 12 行：p99 下降 80.61%–89.71%，整节点 CPU 下降 78.55%–89.89%，候选最高 burst p99 仅 70.813 ms。同时全部精确历史、策略控制、计数与 drained ownership 观测都通过。注意报告的限定语：这些是未限速的热 Channel burst，不能据此建立生产容量、metadata HA 或早期 4500 SEND/s 失败的恢复。

5.3 9 组顺序控制：超阈值，且是"失败的比较证据"而非被丢弃的控制

全部 12 个顺序控制都被保留在原始判定中（含 3 个在阈值内的），上表 9 行是失败的比较证据——它们构成"整体非回归"声明之前必须完成的后续项。这正是本次验证与很多"报喜不报忧"性能报告的本质区别：并发收益被确认，但顺序路径的回归被如实暴露并冻结在档案里。此前更早的观测（cohorts 报告中的 +18.95%、无 profile 阶段的 +71.44%、stage 诊断的 +16.22%）也一并保留，RPC 数量下降、短 burst 通过等事实不能擦除这些观测或早期 4500 SEND/s 失败。

六、首次尝试的 Linux PR 资格验证：500 SEND/s 三条 seam 独立通过

6.1 门禁参数

自动回归运行 36744694111 在精确合并预览ec392bd9上成功完成，全部三条新鲜 seam 保留原始设置：

• 60 秒 warmup + 三个 60 秒窗口
• 4 个可见 AMD64 CPU，Go 1.25.11
• offered/started 500 SEND/s
• 400 ms 的 scheduled-arrival-to-completion p99 预算
• 零错误、零丢包；9 个窗口各自恰好完成 30,000 个操作，无基线复用、无重试替换

6.2 三条 seam 的 p99 结果

mixed-send seam 按约定包含既有 flight recorder 与一秒采样器，收据标记 instrumentation enabled。这份绝对 Linux 门禁与前面"无 profile 的 Darwin 比较 CPU 证据"互相独立；跳过的 nightly/diagnostic job 不计为通过。Manager Chromium 与 native package-preview/lifecycle 自动检查在a991也通过，但package preview 不是发布版本。

这条 500 SEND/s 门禁的复用规则本身也有契约测试保护：脚本 scripts/ci-500qps-baseline.py 的基线选择逻辑被 scripts/ci_500qps_baseline_test.go 以纯 fixture 方式断言——只有相同head_sha、run_attempt=1、conclusion=success、祖先关系成立且未触及产品代码路径（如internal/app/app.go、go.sum、scripts/run-500qps-seam.sh）的近期 schedule 运行才允许复用，任何一个字段不匹配都拒绝复用。这套规则让"首次尝试"四个字具备可验证性。

七、交付状态与剩余范围：诚实的收尾

• PR981 仍为 Draft，依赖 Draft PR980；对 main 的 source-head diff 在本文三文件补充前为 62 个文件、补充后为 65 个，超过受保护 Review Agent 的 50 文件上限，正式派发需要依赖集成或范围拆分，限制未被修改；
• PR982/983 已独立进入 review，保持在各自原始 head；全程未调用 auto-merge review 命令、未合并、未发布、未动用付费资源、未手动重试失败 CI；
• 证据 manifest 记录 102 个文件（含六对收据、全部功能 companion、native/source 身份、本地检查、独立审查与三个原始 CI 性能工件目录），产品/native 二进制留在本地并记录哈希；
• 报告描述的 evidence bundle 解压后，用verify-reviewed-pairs.py与verify-ci-500qps.py可独立复算对比判定与 Linux 判定；先前的证据 bundle 保持不变。

八、如何复现这套取证流程

发送权限（send ban）相关 E2E 与性能取证都集中在 test/e2e/message/send_ban/，其运行契约见 test/e2e/message/send_ban/AGENTS.md。关键命令与可选环境变量如下：

# 功能级 send-ban E2E（256 Hash Slots、12 初始物理 Slot） GOWORK=off go test -tags=e2e ./test/e2e/message/send_ban -count=1 -timeout=8m -p=1 -v # Issue #977 基线（opt-in，32 个独立 UID 设备、64 顺序 SEND、两波 32 并发） WK_E2E_PERMISSION_BASELINE=1 WK_E2E_BINARY=/absolute/frozen/wukongim \ WK_E2E_PERMISSION_BASELINE_REPORT=/absolute/baseline.json \ GOWORK=off go test -tags=e2e ./test/e2e/message/send_ban \ -run '^TestPermissionCallerBaseline$' -count=1 -timeout=4m -p=1 -v # 候选 cohort 模式（低 RPC/低 envelope、独立 drain 的 ownership 指标） WK_E2E_PERMISSION_COHORTS=1 WK_E2E_BINARY=/absolute/frozen/candidate \ WK_E2E_PERMISSION_COHORT_REPORT=/absolute/cohorts.json \ GOWORK=off go test -tags=e2e ./test/e2e/message/send_ban \ -run '^TestPermissionCallerCohorts$' -count=1 -timeout=4m -p=1 -v

Darwin 上的 CPU 积分取证需要先编译原生探针并校准：

cc -O2 -Wall -Wextra -Werror fixtures/permission-cpu-darwin.c -lproc -o /absolute/permission-cpu-darwin WK_E2E_PERMISSION_CPU_PROBE=/absolute/permission-cpu-darwin go test -tags=e2e \ ./test/e2e/message/send_ban -run TestPermissionCPUProbeCalibration

其他常用取证开关：WK_E2E_PERMISSION_STAGES=1保留六组固定 histogram 族样本；WK_E2E_PERMISSION_TIMELINE=1开启 8192 事件诊断环与固定 100% 采样；WK_E2E_PERMISSION_TIMELINE_FAILURE_PROBE=1注入 post-window HTTP 503 验证失败收据完整性。所有对比都要求旧/新两侧使用同一探针与同一组开关，且 profile 或 traced 窗口永远不能替代未 profile 的 p99/CPU 门禁。

结语：这篇报告教会我们什么

WuKongIM 这份主分支集成验证的价值不在于"修好了"，而在于它的证据分层与失败保留：

1. 收益与回归分开陈述——12 组 burst 的 80%+ p99 下降是真实的，9 组顺序控制的最高 +73% p99 恶化也是真实的，两者都被归档；
2. 证据来源严格互锁——提交哈希、vcs.modified=false、二进制 SHA-256、CI 合并预览树四者一致，任何"无效 VCS 戳"的旧证据都带source_identity_valid=false存档、不参与比较；
3. 门禁不可被复用稀释——500 SEND/s 的 Linux 首次尝试通过只证明该精确源码在该门禁下的表现，与本地 Darwin 对比、早期 4500 SEND/s 失败互不抵消；
4. 结论始终收敛在"尚未完成"——Issue #977 在顺序控制达标前保持 OPEN，PR 保持 Draft，Review Agent 的文件数上限不被放宽。

对于任何关注 IM 内核性能工程、分布式取证方法或"如何诚实报告一次修复"的读者，这份报告连同 时间线报告、cohorts 报告 与 stage 诊断报告 构成一条完整的、可追溯的修复证据链。

• 即时通讯
• 后端