★ FEATURED ARTICLE 即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载本文是一份面向 WuKongIM 内部 v2 动态数据节点 Stage 9 生产就绪验证的实操手册核心场景是在真实 WKProto 流量持续运行的同时通过 Manager 依次完成节点 4 的种子加入seed join、激活、Slot 上移onboarding、标记离开、网关排空drain、缩容迁移与安全移除并全程采集状态与指标证据。读完本文你将掌握wkcli sim压测命令的参数语义与运行机制、动态节点生命周期 8 步操作顺序、健康上报相关配置以及如何用低基数指标验证“节点在 joining 阶段不可调度、激活且健康新鲜后才可调度”这一关键约束。背景这份手册要验证什么这份可选人工冒烟手册是对test/e2e/cluster/dynamic_node_readiness自动化测试的补充。e2e 测试包在其 AGENTS.md 中明确了 Stage 9 的场景契约启动一个静态三节点集群在真实 WKProtoSEND - SENDACK流量持续运行期间完成节点 4 的加入、激活、上移、缩容与移除并用公开的 Manager HTTP 接口、公开的/metrics接口和 WKProto 客户端证明健康新鲜度与生命周期阻塞项全过程可解释。冒烟手册与 e2e 测试共同遵守一条黑盒原则只使用公开的 v2 bench、Manager、Metrics 和 WKProto 接口面绝不导入服务端内部实现不引用internal/app、internal/usecase、存储内部、Controller 内部或集群内部。这让冒烟结果能真实反映生产可观察性而不是依赖内部函数。集群形态健康上报参数怎么配冒烟要求按接近生产的形态启动一个 Stage 9 集群Manager HTTP、bench API、Metrics、网关监听器与健康上报设置全部开启。其中最关键的是节点健康上报的两个参数通过环境变量注入WK_CLUSTER_NODE_HEALTH_REPORT_INTERVAL5s WK_CLUSTER_NODE_HEALTH_REPORT_TTL30s这两个变量在 internal/config/schema.go 中有明确的 TOML 路径映射等价于wukongim.toml中[cluster]段的配置[cluster] node_health_report_interval 5s node_health_report_ttl 30s示例配置见仓库根目录 wukongim.toml.example。含义拆解node_health_report_interval每个数据节点向集群上报一次健康状态的周期默认5s。上报越频繁健康新鲜度判定越敏感。node_health_report_ttl一次健康上报被视为“新鲜”的有效期默认30s。超过 TTL 未刷新节点健康会被判定为stale过期从而触发调度与缩容阻塞。在自动化 e2e 测试中为了让验证时间可控readinessOverrides()见 test/e2e/cluster/dynamic_node_readiness/lifecycle_helpers_test.go把上报间隔缩短到了500msWK_CLUSTER_NODE_HEALTH_REPORT_INTERVAL: 500ms, WK_CLUSTER_NODE_HEALTH_REPORT_TTL: 30s,手册建议本地短冒烟时先把集群保持在 3 个活跃数据节点上再通过种子加入引入节点 4避免一开始就形成不完整的拓扑。压测流量wkcli sim 的参数与运行机制在生命周期变更进行期间通过公开的wkcli sim持续跑真实流量。手册给出的基准命令go run ./cmd/wkcli sim --server http://127.0.0.1:5001 --users 200 --groups 40 --group-members 20 --rate 2/s --status-listen 127.0.0.1:19091 --max-runtime 5m命令定义在 cmd/wkcli/internal/sim/command.go参数默认值与校验逻辑在 cmd/wkcli/internal/sim/config.go。逐项解读参数本冒烟取值默认值说明--serverhttp://127.0.0.1:5001必填或--gateway/--contextWuKongIM HTTP API 服务地址可重复或逗号分隔传入多个--users200100模拟用户数--groups4020模拟群组频道数--group-members2010每个群组的成员数--rate2/s0.2/s每个群组的消息发送速率格式如2/s--status-listen127.0.0.1:19091127.0.0.1:19091本地状态端点监听地址--max-runtime5m0不限时模拟总运行时长上限0 表示不限制其余常用参数还包括--gatewayWKProto TCP 网关地址覆盖 preflight 探测到的网关、--payload-size默认128B支持1KB、1MiB等、--connect-rate默认 20每秒最大建连数、--concurrency默认 64最大并发模拟操作数、--ack-timeout默认 5sSENDACK 等待超时、--heartbeat-interval默认 30s模拟客户端 PING 间隔、--jsonJSON 输出。注意--rate是每个群组的速率总发送速率 rate × groups。压测期间不要让 sim 结束手册明确要求“Keep the simulator running while the operator performs the lifecycle flow”因为通过标准的每一条都需要在流量不中断的前提下验证。sim 内部如何工作wkcli sim的运行时实现位于 cmd/wkcli/internal/sim/runtime.go其执行脉络可以概括为preflight先向 bench API 探测目标能力并解析网关地址runtime.gosetup通过 v2 bench API 准备拓扑数据用户、群组、成员connect按--connect-rate限速批量建立 WKProto 客户端连接frame.APP设备标记runTraffic按总速率调度发送每个模拟用户最多 32 条在途 SENDsimClientMaxInflight发送结果以ReasonSuccess计为messages_sent失败或缺失 SENDACK 计为send_errors重试运行时状态机依次经历starting → preflighting → setting_up → connecting → running → retrying → stopped出错后以 2s 固定退避自动重连重跑见 runtime.go因此单次网络抖动不会终止整个冒烟。sim 的实时快照通过本地状态端点暴露。状态服务器实现在 cmd/wkcli/internal/sim/server.go提供两个 GET 端点/healthz返回{status:ok}的存活探针/status返回完整 JSON 快照结构定义见 cmd/wkcli/internal/sim/status.go字段包括state、run_id、target_servers、gateway_tcp_addrs、users、active_users、groups、group_members、messages_sent、send_errors、recv_messages、recv_dropped、reconnects、last_error、last_transition_at。这正是手册“Evidence To Keep”中curl http://127.0.0.1:19091/status的数据来源只要send_errors不持续增长、messages_sent持续增加就说明生命周期操作期间流量一直在正常推进。生命周期流程8 步操作顺序通过 Manager HTTP 接口或 Manager UI按以下顺序执行对应 e2e 测试 production_readiness_test.go 中逐步验证的同一流程种子加入节点 4通过 seed join 把新节点接入现有 3 节点集群JoinToken 校验通过后节点进入成员清单等待节点 4 进入joining且健康alive新鲜此时 Manager 能列出节点健康上报保持新鲜但节点不可调度——这是关键约束激活节点 4激活后等待 join state 变为active节点变为可调度启动一个有界boundedSlot 上移任务到节点 4把少量 Slot 副本迁往新节点验证新增容量落地标记节点 4leaving进入缩容准备阶段开启节点 4 的网关排空gateway drain停止新连接接入并排空存量连接推进一个有界的 Slot 缩容迁移移离节点 4把 Slot 数据迁往其他存活节点仅在safe_to_removetrue后移除节点 4最终移除前必须确认所有阻塞项已清空。e2e 测试中对应的断言顺序值得参考manager.EventuallyNodeJoinState(t, 4, joining, ...)→eventuallyNodeSchedulable前的requireNodeNotSchedulable→ 激活后EventuallyNodeJoinState(..., active)→ onboarding 计划与执行 →leaving→ 缩容排空 →EventuallyScaleInSafeToRemove→removed见 production_readiness_test.go。整个流程中每个阶段结束后都调用requireTrafficProgress确认发送仍在推进。关于safe_to_remove的语义可以在源码中找到精确定义缩容目标“没有已知的 control、Slot、Channel 或 runtime 排空阻塞项”时才为真见 internal/usecase/management/scale_in.go并通过 Manager 诊断接口以 JSON 字段safe_to_remove暴露见 internal/access/manager/dynamic_node_diagnostics.go。证据收集要保留哪些数据手册要求冒烟全程保留以下证据供事后审计与复现curl http://127.0.0.1:19091/statussim 运行快照证明流量持续推进Manager 节点列表 JSON每个生命周期转换前后各一份对比 join state 与健康状态Manager 缩容状态 JSON最终移除前获取确认safe_to_remove/metrics片段重点采集以下 5 个指标。这 5 个指标的完整定义与标签约束在 pkg/metrics/node_lifecycle.go 中实现指标类型标签含义wukongim_node_lifecycle_nodesGaugeVecjoin_state,status按持久化 join 状态与健康状态分组的当前节点数wukongim_node_health_freshness_nodesGaugeVecfreshness,status按健康新鲜度fresh/stale/missing与状态分组的节点数wukongim_node_lifecycle_attempts_totalCounterVecoperation,result生命周期操作尝试次数join/activate/mark_leaving/onboarding/scale_in等 ×ok/fail/conflict等wukongim_node_scale_in_blockers_totalCounterVecreason缩容阻塞原因计数如target_health_missing、target_health_stale、target_runtime_not_ready等 9 种有界原因wukongim_discovery_membership_revisionGauge无本地可见的成员版本号用于确认成员变更已收敛除此之外同一文件还暴露了wukongim_node_health_report_age_seconds健康上报最大年龄、wukongim_node_onboarding_tasks上移任务数以及wukongim_slot_replica_move_*系列Slot 副本迁移时长/失败/阶段观测可用于更细粒度地审计上移与缩容迁移过程。低基数设计是这套指标的核心原则所有标签值都经过normalizeBoundedMetricLabel归一化node_lifecycle.go不在白名单内的值统一折叠为other/unknown。例如 join state 只允许active/joining/leaving/removed健康状态只允许alive/suspect/down操作只允许固定的 9 种。这避免了高基数标签拖垮 Prometheus也让仪表盘聚合稳定可靠。e2e 测试的指标断言metrics_helpers_test.go会轮询直到目标标签组合出现并校验最小值例如wukongim_node_lifecycle_nodes{join_stateactive,statusalive} 3。通过标准如何判定冒烟成功逐条对照手册的 Pass Criteriawkcli sim在 join、激活、上移、缩容与移除全程持续报告发送成功——用/status的messages_sent增量与send_errors收敛来判定节点 4 仅在joining时绝不可调度——通过 Manager 节点列表或调度相关状态确认节点 4 仅在激活且健康alive新鲜后才可调度——健康新鲜度需同时满足fresh true、freshness fresh、status alive、RuntimeReady见 lifecycle_helpers_test.go 的健康轮询条件最终移除仅在 Slot、Channel、健康与网关排空阻塞项全部清空后才尝试——对应safe_to_removetrue并由wukongim_node_scale_in_blockers_total的各个 reason 标签给出可解释证据指标以低基数标签暴露生命周期与健康证据——即上述全部指标均遵守有界标签白名单。一键脚本与自动化对照除了手工冒烟仓库还提供了可直接运行的冒烟脚本 scripts/smoke-wkcli-sim-wukongim-three-nodes.sh它启动本地三节点集群、跑一轮真实wkcli sim流量并采集证据。其中与动态节点生命周期相关的关键选项--auto-join-node在 sim 发送阶段启动一个 seed join 数据节点默认节点 4配合--auto-join-after、--auto-join-seeds、--auto-join-token使用--auto-promote-controller-voter新节点就绪后通过 Manager APIPOST /manager/nodes/{id}/activate、/controller-voter/promote激活并提升为 Controller voter--fault-kill-node在发送阶段杀掉一个静态节点配合--fault-health-report-interval/--fault-health-report-ttl覆盖健康上报参数用于故障演练对照。自动化 e2e 版本可在仓库根目录按 AGENTS.md 的说明串行运行GOWORKoff go test -tagse2e ./test/e2e/cluster/dynamic_node_readiness -count1 -timeout 12m -p1该包必须用-p1串行执行任务扇出保持有界通常max_slot_moves1并优先轮询公开状态而不是固定 sleep这些约束同样适用于手工冒烟一次只做一个有界迁移让证据链每一步都可解释。小结这份 Stage 9 冒烟手册的核心价值在于用公开接口把“动态节点加入/缩容不影响在线业务”这一生产要求变成可重复、可取证、可观测的流程。实操要点可归纳为四件事把健康上报间隔与 TTL 配成可观测的节奏5s/30se2e 用 500ms 加速、让wkcli sim流量贯穿全程并通过/status持续观察、严格按 8 步顺序执行生命周期操作并在每个转换点留证、最后用 5 个低基数指标外加 Slot 迁移与上移任务系列作为通过判据。如需深入底层实现可继续阅读 pkg/metrics/node_lifecycle.go指标与标签约束、cmd/wkcli/internal/sim/runtime.gosim 运行时与重试机制、test/e2e/cluster/dynamic_node_readiness/production_readiness_test.go完整生命周期断言。赞分享即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载相关推荐WuKongIM 动态节点缩容收尾Stage 5E 黑盒 e2e 冒烟验证 removed 墓碑路径WuKongIM 动态节点缩容收尾Stage 5E 黑盒 e2e 冒烟验证 removed 墓碑路径 本篇基于 WuKongIM 仓库中的动态节点生命周期实施即时通讯后端WuKongIM 动态数据节点加入与激活Stage 2 以 ControllerV2 为唯一持久成员源的生命周期写入路径WuKongIM 动态数据节点加入与激活Stage 2 以 ControllerV2 为唯一持久成员源的生命周期写入路径 本文围绕 WuKongIM 的 in即时通讯后端WuKongIM 动态节点生命周期 Stage 4MarkNodeLeaving、Fail-Closed 安全报告与有界 Slot 缩容排空实战WuKongIM 动态节点生命周期 Stage 4MarkNodeLeaving、Fail Closed 安全报告与有界 Slot 缩容排空实战 本篇基于 W即时通讯后端上一篇突破分布式瓶颈Apache ZooKeeper队列性能极限测试与调优指南下一篇ChatAgent 深度指南用 openJiuwen 最简对话智能体打通提示词调优链路创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
