故障排查
从故障现象开始，用低风险检查逐步找到问题范围。
排障不是看到错误就重启，而是先回答三个问题：什么时候开始、影响了谁、哪一层先出现异常。先做只读检查，证据足够后再决定是否需要变更。
看不清状态时不要盲目操作
如果节点、Controller、Slot、Channel 或任务状态缺失、过期或互相矛盾，应先停止发布和拓扑变更。不要只凭一条日志或一次成功请求重启所有节点、迁移 Leader 或删除数据。
故障发生后的前十分钟
- 暂停其他变化：暂停发布、扩缩容、恢复和同时进行的集群操作，记录当前正在运行的任务。
- 记录影响：记下开始时间、受影响的用户、频道、节点和入口（TCP、WebSocket 或 HTTP）。
- 检查存活与就绪：保存
/healthz和/readyz的状态码与完整响应；/readyz的失败原因最重要。 - 打开 Manager：查看节点、Controller、Slot、Channel 和任务，标出异常或长时间不更新的状态。
- 对齐时间：只比较同一时间段的指标、错误日志和最近发布或配置变更。
curl -sS -i http://127.0.0.1:5001/healthz
curl -sS -i http://127.0.0.1:5001/readyz
wkcli top --server http://127.0.0.1:5001 --once --json把地址换成实际 API 地址。0.0.0.0 是监听配置，不是客户端可以访问的服务器地址。
指标名称、可复制的 PromQL 和结果解释见健康检查与监控。先检查采集是否正常，再比较同一节点、同一时间段的数据。
根据现象继续检查
/healthz 成功，但 /readyz 返回 503
- 保存
/readyz的完整响应和reason。 - 在 Manager 检查维护状态、Controller、Slot 和正在运行的恢复或控制任务。
- 比较其他节点的时间、版本、配置和就绪状态。
不要把流量接回这个节点，也不要绕过恢复、扩缩容或升级流程里的安全检查。
客户端连不上，或者反复重连
- 确认用户使用的是 TCP、WebSocket 还是 HTTP 入口，不要把 Manager 地址当作客户端地址。
- 检查发布地址、DNS、负载均衡、TLS 和防火墙。
- 按节点比较连接数、连接错误、文件句柄、内存和网络，并查看同一用户、同一时间段的网关日志。
不要在证据不足时批量断开连接或同时重启所有节点。
消息发送失败、变慢或出现积压
- 先看发送错误率和高分位延迟，再看 Channel、投递和推送队列是否持续增长。
- 比较每个节点，确认是否只有一台机器或一个大群形成热点。
- 已知频道 ID 时做精确查询，不要为了找问题枚举所有频道。
- 指标和日志已经指向 CPU、内存或 Goroutine 时，才在短时间内使用 pprof。
完整消息路径见消息发送链路。大群和高消息率下，平均值可能看起来正常，最大值和高分位却已经异常。
Controller、Slot 或节点状态异常
wkcli node ls --context production
wkcli node diagnose 4 --context production --json保存命令输出里的状态更新时间、控制版本、blocked_reasons、任务和 Slot 证据。诊断建议不是执行写操作的授权；移除节点仍必须等待 safe_to_remove=true。处理步骤见扩容与缩容。
磁盘不足或数据看起来不一致
先记录磁盘空间、IO 延迟、错误、节点 ID、数据路径和配置。不要通过删除数据文件或未知日志来腾空间。
wkcli db 只能查看已停止节点、文件系统快照或复制出的数据目录。先使用只读的 query、diff 或 export。import 会写入数据，只能指向明确离线的目标，也不能替代 Manager 的备份恢复。
备份、恢复或升级失败
保存 Manager 任务与审计、归档清单、256 个物理 Slot 的验证结果、程序版本与摘要。不要因为恢复时 /healthz 成功就接回流量，也不要假设升级失败后任意版本都能混合运行。回到备份与恢复或升级与迁移的停止条件处理。
工具应该按什么顺序使用
- 先看
/readyz和 Manager，它们成本最低。 - 再看同一时间段的 Prometheus 指标和错误日志。
- 用 Top 或
wkcli top查看一个节点的当前资源和短期历史。 - 只有问题已经缩小到精确节点、Slot、Channel 或任务时，才使用诊断能力。
- pprof 必须限时、限目标，完成后关闭 Debug 能力。
wkcli bench会产生真实流量和数据，只能在隔离的测试集群复现问题，不能对生产环境做无界压测。
前一步已经能解释问题时，就不要继续使用成本更高的工具。
请求他人协助时提供什么
- 故障开始时间、影响范围和最近的变更；
- 节点清单、版本、集群身份和脱敏后的相关配置；
/healthz、/readyz完整响应和 Manager 状态；- 同一时间段的指标截图或导出，以及少量相关日志；
- 相关节点、Slot、频道、任务或追踪 ID；
- 已做过的检查、检查结果和故意没有执行的高风险操作。
不要发送密码、完整 Token、用户消息正文或未经检查的完整配置文件。
只有业务恢复、队列受控、节点重新通过 /readyz、监控恢复，并且临时 Debug、采样和测试流量都已关闭后，排障才算结束。