93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# 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. 定期与官方版本对齐，避免长期“漂移”导致的隐藏问题。
|
||
|
||
---
|
||
|
||
> 若有新的场景/问题，请在这里补充，保持流程可演进。
|
||
|
||
|