复制项目

docs/troubleshooting.md

@@ -0,0 +1,92 @@
+# OpenIM ACK 排障流程（标准化指南）
+
+> **目标**：在 ACK/Kubernetes 环境下定位“消息不同步/推送缓慢”时，有一套可复用的排障步骤，避免因为主观猜测去改底层逻辑。
+
+---
+
+## 1. 明确现象与影响范围
+- **收集信息**：受影响的用户、群组、时间段、终端类型（iOS/Android/H5）。
+- **区分场景**：登录拉取历史 vs. 实时推送，是否所有人都不行、还是个别用户/群。
+- **保存日志与报错**：客户端/服务端的时间点，便于与服务端日志对应。
+
+> 不要在未复现/未收集信息的情况下就进行代码改动。
+
+---
+
+## 2. 逐层排查流程
+
+### 2.1 API 层（openim-api）
+1. 查看 `kubectl logs deploy/openim-api`，确认登录/发消息请求是否返回 200。
+2. 如出现 `token invalid`、`rpc timeout` 等明确错误，先排除配置、网络等问题。
+
+### 2.2 RPC 层（openim-rpc-xxx）
+1. 针对消息问题，重点查看 `openim-rpc-msg`、`openim-rpc-group` 等服务日志。
+2. 出现 `MsgToMongoMQ error`、`redis set failed` 等，说明生产端异常，需要先修复 RPC/存储配置。
+
+### 2.3 Kafka & 消费端
+1. 使用 `kubectl logs deploy/openim-msgtransfer`、`deploy/push-rpc-server`，查看是否有：
+   - `xxxConsumer err, will retry in 5 seconds`（真正的连不上 Kafka）；
+   - `Subscribe returned normally...`（**正常现象**，新版 SDK 每条消息都会返回一次）。
+2. 如怀疑 Kafka 累计延迟，可登录 Kafka 集群或使用 `kafka-consumer-groups.sh --describe` 查看 Lag。
+
+### 2.4 持久化（Mongo / Redis）
+1. 抽取异常消息的 conversationId & seq，直接在 Mongo/Redis 中查询是否存在。
+2. 若 Redis 缺失最新 seq，说明 msgtransfer 未写入；继续回头查消费日志。
+
+### 2.5 推送服务（push）与网关（msggateway）
+1. `kubectl logs deploy/push-rpc-server`：关注推送 RPC 的失败/超时日志；
+2. `kubectl logs deploy/messagegateway-rpc-server`：观察是否大量 `write: broken pipe`（通常是客户端断线，非服务异常）；
+3. 确认 `openim-push` 是否因为配置（厂商证书、推送速率限制）导致卡住。
+
+### 2.6 客户端侧验证
+- 使用不同终端（iOS/Android/H5）交叉验证；
+- 检查客户端本地缓存/seq 是否有延迟；必要时抓包或查看客户端日志。
+
+---
+
+## 3. 变更前的对照与验证
+- **先查证**：如果怀疑配置/逻辑问题，先在官方仓库（`upstream/main`）对比差异，确认是否确实存在 bug。
+- **最小化修改**：优先通过配置/运维手段解决（如重启 Pod、更新镜像、修复 Kafka 集群）；代码层改动需：
+  1. 写清楚“问题现象 → 复现步骤 → 根因分析 → 预期影响”；
+  2. 在测试环境复盘，多人同行评审；
+  3. 修改后 `mage build` + `kubectl rollout` 验证，确保上下游联调通过。
+- **禁止“先改再说”**：避免仅凭几行日志或猜测就改动核心组件（如 discovery、在线推送、MQ 消费），否则容易引入新的系统风险。
+
+---
+
+## 4. 常见误区与经验
+- **“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`。
+
+---
+
+## 5. 工具清单
+- `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` 等目录，确认是否存在异常增长。
+
+---
+
+## 6. 复盘与持续改进
+1. 每次重大故障后，输出“故障记录 + 根因 + 修复方案 + 预防措施”。
+2. 同步更新此文档或内部 Wiki，确保新同学也能快速掌握流程。
+3. 定期与官方版本对齐，避免长期“漂移”导致的隐藏问题。
+
+---
+
+> 若有新的场景/问题，请在这里补充，保持流程可演进。
+
+