OpenIM ACK 排障流程（标准化指南）

目标：在 ACK/Kubernetes 环境下定位“消息不同步/推送缓慢”时，有一套可复用的排障步骤，避免因为主观猜测去改底层逻辑。

1. 明确现象与影响范围

不要在未复现/未收集信息的情况下就进行代码改动。

使用 kubectl logs deploy/openim-msgtransfer、deploy/push-rpc-server，查看是否有：
- xxxConsumer err, will retry in 5 seconds（真正的连不上 Kafka）；
- Subscribe returned normally...（正常现象，新版 SDK 每条消息都会返回一次）。
如怀疑 Kafka 累计延迟，可登录 Kafka 集群或使用 kafka-consumer-groups.sh --describe 查看 Lag。

kubectl logs deploy/push-rpc-server：关注推送 RPC 的失败/超时日志；
kubectl logs deploy/messagegateway-rpc-server：观察是否大量 write: broken pipe（通常是客户端断线，非服务异常）；
确认 openim-push 是否因为配置（厂商证书、推送速率限制）导致卡住。

先查证：如果怀疑配置/逻辑问题，先在官方仓库（upstream/main）对比差异，确认是否确实存在 bug。
最小化修改：优先通过配置/运维手段解决（如重启 Pod、更新镜像、修复 Kafka 集群）；代码层改动需：
1. 写清楚“问题现象 → 复现步骤 → 根因分析 → 预期影响”；
2. 在测试环境复盘，多人同行评审；
3. 修改后 mage build + kubectl rollout 验证，确保上下游联调通过。
禁止“先改再说”：避免仅凭几行日志或猜测就改动核心组件（如 discovery、在线推送、MQ 消费），否则容易引入新的系统风险。

“Subscribe returned normally” ≠ 错误：新版本 NewMConsumerGroupV2 每处理一条消息就会返回，外层循环需要继续 Subscribe。
ACK Pod 重建是常态：官方推荐使用 Service DNS/Headless Service + readiness/liveness，不要擅自关闭连接。
推送失败不等于刷新连接：先确认网关/客户端状态，只有在明确连接池崩溃时才考虑 ForceRefresh。
go mod tidy 的影响：在本地执行 go mod tidy 可能引入上游依赖，CI/build 失败时先恢复 go.mod/go.sum。

kubectl logs/get/describe：查看 Pod/Deployment 状态；
- kubectl top pods -n <ns>：实时查看 Pod CPU / MEM；
- kubectl top nodes：评估集群整体资源是否紧张；
- kubectl top node <name>：关注某台节点是否 CPU / MEM / LOAD 异常；
kubectl rollout status deployment/<name>：确认升级完成；
mage build：本地编译检查；
Kafka CLI 或监控平台：定位消费滞后；
Prometheus/Grafana：查看服务 CPU、内存、QPS、错误率、延迟等指标；
日志聚合（ELK / Loki 等）：快速检索关键字；
SSH 到节点（需要权限）：
- top / htop：查看 CPU、内存占用；
- free -h：系统整体内存状况；
- df -h：磁盘容量，防止磁盘打满影响容器；
- du -sh /var/lib/docker, /var/log 等目录，确认是否存在异常增长。

若有新的场景/问题，请在这里补充，保持流程可演进。