故障排查
从现象开始，按成本逐步收集可信证据，并在状态未知时停止变更。
排障的目标是把“系统异常”缩小为一个有时间范围、影响范围和证据链的问题。先做只读检查，再临时增加采样；只有权威状态新鲜且一致时，才进入对应的运维流程。
未知状态必须失败关闭
缺失、过期或互相矛盾的 Controller、Slot、Channel、任务或节点证据不能解释成健康。不要根据单条日志、单个平均值或一次成功请求自动重启、迁移 Leader、删除数据或推进缩容。
前十分钟
- 冻结变化：暂停发布、扩缩容、备份恢复和并发拓扑操作，记录正在执行的任务。
- 界定影响：记录开始时间、受影响的节点、用户、频道、协议入口和请求类型。
- 分开检查存活与就绪：保存
/healthz、/readyz的状态码与完整响应体；只有/readyz用于业务流量准入。 - 核对集群投影：在 Manager 查看节点、Controller、Slot、Channel 和任务状态，标记缺失或过期字段。
- 关联低成本信号：对齐指标、错误日志和部署/配置变更的时间线，再用 Top 查看节点本地压力。
- 限定复现：只在受控环境或小范围流量上复现；设置时限、停止条件和负责人。
curl -sS -i http://127.0.0.1:5001/healthz
curl -sS -i http://127.0.0.1:5001/readyz
go run ./cmd/wkcli top --server http://127.0.0.1:5001 --once --json地址必须替换为实际 API 地址。不要把监听地址 0.0.0.0 当作节点、客户端或负载均衡器可访问的发布地址。
证据阶梯
| 顺序 | 能力 | 回答的问题 | 主要成本或边界 |
|---|---|---|---|
| 1 | /readyz 与 Manager | 节点是否可接流量，哪个控制面证据异常 | 状态可能缺失或过期，必须保留原始原因 |
| 2 | Prometheus 与告警 | 问题从何时开始、是否持续、是否节点偏斜 | 平均值会隐藏热点，阈值依赖当前版本与负载 |
| 3 | 应用/错误日志 | 同一时间窗口发生了什么错误 | 日志内容不可信且可能包含敏感信息 |
| 4 | Top / wkcli top | 某节点当前的资源、队列和短期历史如何 | 节点本地快照，不是全局真相 |
| 5 | 保留诊断与只读 Operations MCP | 精确节点、Slot、Channel 或任务有哪些有界证据 | 独立凭据、固定查询、限流与结果上限 |
| 6 | pprof | CPU、堆或 Goroutine 热点是什么 | 高成本、限时、受控网络；完成后立即关闭 |
| 7 | wkbench | 假设能否在隔离集群的代表性负载下复现 | 会产生真实流量和数据，不应指向生产集群 |
一层证据已经能解释问题时不要继续提高诊断成本。需要各能力的选择规则见诊断能力。
按现象定位
节点存活但未就绪
- 保存
/readyz的 503 响应和reason，不要只记录探针失败。 - 在 Manager 核对节点运行时、Controller、Slot、维护状态与正在执行的恢复或控制任务。
- 比较其他节点的就绪、时间、版本和配置快照；单节点集群仍必须保留集群语义。
- 若证据指向恢复、扩缩容或升级，回到对应操作页面，不要跳过其确认与验证门槛。
客户端无法连接或频繁重连
- 区分 TCP、WebSocket、HTTP 和 Manager 入口，核对监听地址与发布地址、DNS、负载均衡、TLS 和防火墙。
- 按节点比较连接数、会话错误、路由失败、FD、内存和网络，而不是只看总量。
- 关联同一客户端与同一时间窗的网关日志；不要在证据不足时批量断开连接或重启所有节点。
发送失败、延迟升高或出现积压
- 先分开观察请求接入、SEND/SENDACK、Channel 追加、复制持久化和投递阶段；消息发送链路给出了这些边界的完整路径。
- 查看错误率、分位延迟、有界队列的深度/拒绝/丢弃，以及节点偏斜和单频道热点。
- 已知精确频道时使用点查；不要枚举频道目录。十万成员群组和高消息率下，平均延迟不能代表尾部或扇出成本。
- 只有指标与日志已把问题缩小到 CPU、堆或 Goroutine 时，才在有界窗口抓取 pprof。
Controller、Slot 或节点生命周期异常
go run ./cmd/wkcli node ls --context production
go run ./cmd/wkcli node diagnose 4 --context production --json保存健康新鲜度、控制修订、blocked_reasons、任务与 Slot 证据。不要因为诊断给出建议就强制迁移 Leader 或删除节点；缩容仍必须等待权威状态报告 safe_to_remove=true。先用 Controller 与 Slot 的权威边界解释观测，再按扩容与缩容执行完整流程。
磁盘、存储或数据差异
- 先记录磁盘容量、IO 延迟、错误日志、节点身份、路径和配置，不要删除日志或存储文件腾空间。
wkdb只适合停止的节点、文件系统快照或复制出的数据目录。它看到的是一个节点的本地文件，不是在线一致的全局视图。- 先使用只读
query、diff或export。import是唯一写存储的命令，只能用于明确的离线目标，不能替代 Manager 备份恢复。
备份、恢复或升级窗口异常
保留 Manager 任务、审计、归档清单、所有 256 个物理哈希槽的验证结果、制品摘要和版本兼容声明。恢复期间不要因为 /healthz 成功就恢复业务流量；升级失败也不要假设任意版本可混跑。分别回到备份与恢复和升级与迁移。
升级支持前的证据包
- 事件时间线、影响和最近变更；
- 节点清单、版本、集群身份和脱敏后的相关配置；
/healthz、/readyz原始响应与 Manager 状态；- 同一时间范围的指标快照、日志游标或有界日志片段；
- 精确的节点、Slot、频道类型/ID、任务或追踪标识；
- 已执行检查、结果、停止条件以及尚未执行的写操作；
- 若使用 pprof 或基准测试，记录授权、开始/结束时间、目标、配置和制品位置。
凭据、完整 Token、任意用户消息内容和未审查的配置文件不得进入共享证据包。
排障结束条件
只有根因或规避措施已有可重复证据、监控恢复、积压受控、所有节点重新满足预期就绪条件，并且临时 Debug、采样、凭据和负载已经关闭，事件才算结束。把新阈值和回归负载记录为版本与环境相关的基线，而不是全局容量承诺。