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