即时通讯常见问题

本文汇总了网易云信即时通讯私有化部署中常见的技术问题及解决方案，帮助您快速排查和解决问题。

会话与消息问题

会话在 Redis 缓存存在，但缓存失效后无法从持久化数据库恢复。

可能原因：
- 会话缓存未正确同步到后端持久化（Kafka 消费/写库流程异常）。
- Kafka 配置或 consumer 未启动/消费失败。
- 持久化写入失败（DB 权限、连接异常或写入逻辑被禁用）。
自检步骤：
1. 检查 Redis 是否有对应 conversation 缓存（key 与过期时间）。
2. 检查 Kafka topic 是否有积压消息（消费滞后）、对应 consumer 是否在线。
3. 查看后端服务（用于消费并写库的进程）日志是否有异常和报错。
4. 验证 DB 中历史会话记录是否存在或是否最近有写入。
常见修复：
- 确保 Kafka bootstrap.servers 指向正确地址并可连通（示例配置：conversation.sync.for.db.delay.queue.consumer.bootstrap.servers=kafka://<KAFKA_HOST>:9092，producer 同理）。
- 重启/恢复 Kafka consumer 进程或修复消费异常。
- 检查并修复数据库写入权限或 SQL 错误。
- 短期缓解：延长 Redis 缓存过期并手动触发数据落盘（只在有明确风险评估后进行）。

用户端显示未读已清，但重新登录后未读数仍然出现。

可能原因：
- 未读数变更未正确同步到后端持久化，或 Redis 与 DB 同步链路（Kafka）异常（同《云端会话（conversation）过一段时间丢失》类似）。
自检步骤：
1. 确认客户端清理未读时是否向服务端发送了相应请求并返回成功。
2. 检查 Redis 和持久化 DB 中的未读计数状态。
3. 检查 Kafka 消费是否有延迟/失败。
常见修复：
- 修复 Kafka 消费与持久化写入链路，或手动触发未读数同步任务（实施方操作）。

客户端收到”撤回”通知，但历史消息未从历史记录中移除（或客户端仍展示）。

可能原因：
- 私有化默认保留历史记录，撤回只是标记；或服务端相关配置为”不删除历史”。
- 客户端没有正确处理撤回消息的回调。
自检步骤：
1. 查阅当前私有化撤回相关配置（是否设置为删除历史或仅标记）。
2. 检查服务端发送给客户端的撤回事件内容与格式（是否包含删除指令/标记）。
3. 确认客户端 SDK 是否收到并正确处理撤回回调。
常见修复：
- 若需真正删除历史：调整服务端撤回策略配置（由实施方/管理员修改），或在服务端增加历史删除任务/策略。
- 确保客户端在收到撤回事件后刷新相关消息展示。

私有化环境默认云端历史展示范围较短（例如 30 天），查询更久的历史时在默认配置下看不到。

可能原因：
- 服务端查询限制或前端查询时间窗口默认限制。
- 历史数据仍在存储中，但查询接口受限。
自检步骤：
1. 确认是否为默认展示策略（配置项或部署文档中有说明）。
2. 检查后端历史数据在 DB/存储中是否存在（直接查询存储）。
常见修复：
- 如需扩大查询范围，请联系实施方调整服务端历史查询保留/返回范围参数（例如修改历史查询天数参数）。
- 如果历史数据被归档到其他冷存储，需要启动归档查询流程或导回。

10.9.x 客户端 SDK 调整了默认登录/链路安全策略，部分老服务端可能不兼容导致登录超时。

可能原因：服务端协议/安全策略不支持 SDK 默认启用的增强链路安全特性。
自检步骤：
1. 检查客户端 SDK 版本和初始化配置。
2. 在客户端日志中查找登录阶段的错误码/超时信息。
常见修复：
- 客户端短期方案：在初始化时将 enableEnhancedLinkSecurity 字段设为 false，以回退到兼容模式。
- 长期方案：升级/兼容服务端以支持新 SDK 的安全特性，确认升级计划。

客户端使用过高或过低版本的 SDK 可能导致功能缺失或异常。

可能原因：
- SDK 版本过高，使用了服务端不支持的新特性
- SDK 版本过低，无法使用服务端新功能
- 接口协议发生变更导致兼容性问题
自检步骤：
1. 确认客户端 SDK 版本号
2. 查询当前服务端支持的 SDK 版本范围
3. 检查错误日志中的协议或接口不兼容提示
常见修复：
- 升级或降级 SDK 到与服务端兼容的版本。
- 避免使用不兼容版本的特性功能，使用新版本客户端 SDK 前与网易云信技术支持工程师沟通确认。

在群消息且未开启”强推”场景下，needpushNick 不起作用。

可能原因：对群消息，强推机制优先或服务端存在历史兼容问题。
自检步骤：
1. 验证客户端是否在群消息中设置了 needpushNick。
2. 联系网易云信私有化实施工程师查看是否开启了 teamForcePush 相关配置。