WuKongIM 原生 Linux RPC 重复性门槛：从可复现探针、固定六窗校准到云上执行纪律

• 即时通讯
• 后端

本文是 WuKongIM 仓库内一次完整的技术准备记录：为了在判断 transport 小幅性能改动前获得可信依据，项目把临时探针整理为可重复使用的诊断工具，并预先冻结了一套「原生 Linux 双机六窗校准」方案。读者将掌握该探针工具链的构建纪律、测量协议、fail-closed 验收判据，以及云上执行时必须遵守的租约与授权边界——同时明确：本地冒烟、容器功能测试与合成数据测试都不能当作稳定性通过的证据。

背景：为什么要给 transport 改动设置重复性门槛

WuKongIM 的 transport 层承载节点间 RPC 与消息投递。当开发者想评估某个小幅性能优化（例如连接池、队列或批写调整）是否值得合入时，最大的干扰不是「快了还是慢了」，而是测量本身是否可重复：CPU 型号、容器标记、CPU 亲和性、GOMAXPROCS、GC 参数、运行时覆盖变量、样本截断、服务器中途重启、混合二进制……任何一项不一致，都会让两次测量之间的差异无法归因。

为此，本轮工作将前几轮的临时探针整理为仓库内可重复使用的工具，集中放在 scripts/transport-perf 目录，使用说明见 scripts/transport-perf/README.md。需要特别强调本轮报告的三条结论：

• 原生 Linux 实测结果仍为空：工具已准备好，但尚未在真实云主机上执行六窗校准；
• 不能把本地功能冒烟或合成数据测试当成稳定性通过；
• 产品 transport 运行时未做任何修改，本轮只交付工具与验证。

构建纪律：只允许从干净、已提交的源码构建

重复性测量的前提是「每次跑的都是同一个二进制」。报告记录的工具提交为9511a2b41（完整 SHA 为9511a2b4138d04d738069064c1378b2b457f7ebd，见 结构化准备证据），构建器对此做了严格约束：

• 只接受干净、已提交的源码工作区，脏源码直接拒绝；
• 固定临时导入路径，避免源码路径影响构建产物；
• 固定 Go 工具链Go1.25.11、CGO 关闭、-trimpath、-buildvcs=false；
• 输出独立的源码 SHA256 与二进制 SHA256 清单（wkrpc-probe-build/v1）；
• 拒绝覆盖既有产物；构建结束后清理自己的临时源目录。

按 scripts/transport-perf/README.md 的说明，在干净检出、输出目录位于仓库之外的前提下，构建命令形如：

python3 scripts/transport-perf/build.py \ --source "$PWD" --output /tmp/wkrpc-native/base

报告中 Linux/amd64 与 Darwin/arm64 两个平台的构建均成功，且已验证「脏源码拒绝构建」「覆盖既有产物拒绝构建」「临时源目录清理完成」三项负面检查（对应证据文件build-negative-checks.json）。

构建产物中嵌入sourceRevision，探针运行时还会采集并输出完整身份信息，供验收器比对：

• 操作系统、进程架构、内核架构、CPU 型号；
• 二进制 SHA256、源码 SHA、Go 工具链版本；
• CPU 亲和性（Cpus_allowed_list）、GOMAXPROCS、CPU 数量；
• GOMEMLIMIT/GODEBUG等运行时覆盖参数（debug.SetMemoryLimit(-1)与os.Getenv("GODEBUG")，见 探针主程序）；
• BootID、PID、StartTicks（防止加入另一次启动或复用 PID）；
• 容器标记检测（/.dockerenv、/run/.containerenv、cgroup 中的 docker/kubepods/containerd/libpod 标记）。

需要特别说明：宿主身份只保存摘要（/etc/machine-id或 hostname 的 SHA256），不保存机器 ID 原文；探针不能证明物理宿主机隔离——KVM 虚拟机是受支持的运行形态，但实际云上部署边界仍需用精确租约库存确认，不能仅凭「没有常见容器标记」就断定独占宿主机。

测量协议：有界样本、预热与计数守恒

客户端与服务端使用独立进程，通过真实 transport echo 调用测量。协议要点如下：

• 客户端预分配有界样本（默认每 worker 上限 100 万），正式计时后才进行复制与排序，避免排序干扰资源快照；
• 记录每个调用者的调用数与错误、每秒窗口的调用数与分位数、整窗调用数，以及独立计数的预热调用；
• 服务端 echo 计数差必须与客户端测量完成数完全一致：ServerAfter.EchoCalls - ServerBefore.EchoCalls == Summary.Calls，不一致即视为其他客户端活动或服务器计数不符（见 探针主程序）；
• 元数据控制 RPC 的少量边界工作包含在服务端资源差中，不把它当作精确 handler 成本；
• 纯计时模式下不启用 pprof；
• 服务端有硬生命周期（默认 30 分钟）并支持SIGTERM优雅退出——但报告明确提示：进程退出不等于云资源释放，付费主机必须按精确租约选择器释放并取得认证零库存证明。

客户端测量时序（源码可核）：并发预热（默认 10 秒）→runtime.GC()强制一次客户端 GC → 边界快照（ClientBefore/ServerBefore）→ 正式测量（默认 20 秒，按调用开始时间划入每秒桶）→ 边界快照（ClientAfter/ServerAfter）→ 校验。整窗分位数从完整样本排序得出，采用历史固定的floor((n-1)*p)秩，绝不用各秒 P99 平均冒充整窗 P99。

验收器：fail-closed 的同版本重复性判据

验收器实现于 analyze.py，其设计原则是遇到无效证据一律拒绝（fail-closed），绝不输出候选优化通过或生产容量通过。它会拒绝：

• 错误、样本截断（SampleCapHit）、计数不守恒、窗口内服务器重启（Instance变化）；
• 混合二进制/主机（HostID、BinarySHA256、Source、GoVersion、CPUModel、AllowedCPUs 必须完全一致）；
• 重复或重叠窗口（按StartedUTC排序校验间隔）；
• 隐藏运行时参数（GODEBUG非空、GOMEMLIMIT被设置、TelemetryTail非零）；
• 不支持的环境（非原生 Linux amd64/x86_64、容器、CPU 不足、GOMAXPROCS≠4、缺少 CPU 身份等）。

对全部提供的窗口，判据为跨完整批次的(max-min)/median：吞吐 ≤ 3%、P99 ≤ 10%。这是预先声明的工程判据，不是统计显著性或置信区间。对应单元测试见 test_analyze.py，覆盖「稳定批次通过」「P99 不稳不通过」「14 类无效证据变体全部判 invalid」以及「不足六窗判 invalid」。

固定首轮计划：六窗校准的完整参数

首轮校准场景被刻意收窄：只覆盖64B、无预算写请求、单连接、16 调用者、Observer 关闭。它不是业务容量或固定到达率 SLO 测试。完整固定参数如下：

服务端参数与 ServiceOptions 定义 一一对应：Concurrency=64、QueueSize=4096、MaxQueueBytes=64<<20、MaxRetainedBytes=128<<20、Timeout=30s、QueueTimeout=5s、MaxPayload=65537、CancelRunning=false——验收器会逐项校验这些选项在测量前后保持一致。

失败处理纪律：不通过就终止该轮、保存全部证据并释放租约，绝不挑有利重跑。通过也仅说明该基线在既定条件下可重复，本轮不据此重新接受已拒绝的监听候选；后续 AB/BA 对照需要独立预先声明完整矩阵（覆盖两种连接数、预算/读控制、大负载与被拒绝的准入场景），并在其后另跑一次同版本门槛。

本地验证与功能冒烟：全部命令与结果

报告记录的本地验证命令（全部通过）：

GOWORK=off GOTOOLCHAIN=go1.25.11 go test ./scripts/transport-perf/probe -count=1 GOWORK=off GOTOOLCHAIN=go1.25.11 go test -race -tags=integration ./scripts/transport-perf/probe -count=1 -timeout=1m GOWORK=off GOTOOLCHAIN=go1.25.11 go vet ./scripts/transport-perf/probe PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s scripts/transport-perf -p test_analyze.py -v

• 真实子进程集成测试（process_integration_test.go）覆盖：TCP 回显、逐调用者/逐秒计数守恒、正常信号退出、以及样本耗尽必须失败（-sample-cap=1时拒绝并保留部分报告）；
• 验收器单元测试覆盖稳定/不稳定批次与无效证据拒绝，不用硬编码本机速度作为 CI 门槛；
• 功能冒烟：Darwin 完成 64,152 次、Linux amd64 容器完成 34,091 次成功回显，双端计数与哈希匹配；
• 两种冒烟随后都被原生验收检查正确拒绝（Darwin 因「requires Linux amd64 without architecture emulation」、容器因「host is not eligible for qualification」），不是云上性能证据；本轮容器和临时源目录已清理。

完整证据（测试日志、功能报告、运行/清理命令、构建清单及摘要）保存在 rpc-native-preparation-2026-09-22.json。二进制保留在构建机本地路径（如/Users/tt/.codex/visualizations/2026/09/22/rpc-native-gate）并记录 SHA256，不嵌入 Git。

云上执行的前置条件与租约纪律

报告明确了「为什么工具已就绪却不能在云上执行」——这是整篇文章最容易误解的部分：

• 用户确认没有现成测试机；本地四个历史请求均为released状态，且各有保存的认证零库存证明；
• 没有复用历史地址或凭据；
• 只读 preflight未联系云厂商，发现缺失：临时凭据/验证标记和精确生命周期授权；
• 本轮没有新报价、没有采购、没有活动租约。

若后续新增临时服务器，拟沿用仓库已验证的租约流程：3 台服务节点 + 1 台负载节点，从服务节点中选两台运行 RPC；预算上限 300 元，取得本轮新报价后才Acquire。首轮只做上述六窗校准，完成或失败后立即按精确选择器释放并取得认证零库存证明；不运行聊天生命周期长跑，不扩展业务容量测试。复用成熟采购/释放流程，避免本轮同时修改资源管理代码。

项目 云资源技能 明确规定：

“Never infer paid authority from继续,同意, deploy, run, status, diagnose, stop, an explanation,下一步建议？, or prior paid runs.”

即：单独的「同意」或历史付费记录不能推断新购授权；这条限制只作用于新增付费资源，工具实现、本地验证和交付已经完成，不受影响。

工具链的后续演进与结果闭环

本轮只是「准备」节点。仓库内后续报告形成了完整闭环，可作为本主题的延伸阅读：

• 原生双机主机诊断：六窗方案和执行材料已冻结：在门槛失败时启用 host_sample.py 与 correlate.py 进行独立的诊断通道——1 Hz 的 /proc 侧车采样（CPU/PSI、TCP 重传、网卡/softnet、线程切换与调度等待），用单调时钟对齐探针秒段，但明确「采样结果不能用于认定吞吐或延迟合格」；
• 原生 Linux RPC 六窗结果：重复性未通过，临时资源已释放：实际执行 6 窗共 10,799,412 次成功调用、零错误，但吞吐波动 8.146% > 3%、P99 波动 52.779% > 10%，门槛未通过；四台临时 ECS 与租约附属资源立即释放并取得认证零库存证明——这正是「预先声明判据、不挑重跑、失败即释放」纪律的完整示范。

总结

WuKongIM 的这套原生 Linux RPC 重复性门槛，本质上是把「性能结论的可信度」工程化了：从干净源码构建的可复现二进制，到双端身份/计数守恒的严格校验，再到fail-closed 的六窗波动判据，每一环都在回答同一个问题——「这次测量的差异，究竟是改动造成的，还是环境与测量噪声造成的？」工具已准备完毕并通过本地验证，唯一未完成的是云上执行本身，而这一步受租约与授权纪律约束，等待的是明确的付费授权，而非任何技术障碍。

• 即时通讯
• 后端