常见问题
汇总接入与运维中最常见的问题。若未找到答案，请查阅对应功能页或提交 Issue。
连接与消息
连接失败 / 一直 CONNECTING 怎么办？
先检查 Token 是否有效（错误码 1002）、AppKey 是否匹配、服务端地址是否可达；再看服务端日志与客户端错误回调。
为什么收不到离线消息？
确认对方会话已有历史、离线队列未超上限（默认 500 条/会话）；聊天室不补发离线消息。
消息会重复吗？
投递语义为 at-least-once，客户端必须按 messageId 去重；同一用户 clientMsgId 10 分钟内幂等。
seq 有什么用？
同一会话内 seq 单调递增，用于补拉、排序与已读游标推进；跨会话没有全局顺序。
多端同时在线会怎样？
同一账号所有在线端都会收到消息副本；发送方其他端 direction=SEND。当前为端级游标，多端已读一致性见缺口清单 P0。
能力与限制
群组和超级群怎么选？
成员 ≤ 3000 用群组；更大规模或需要频道语义用超级群。
聊天室消息为什么查不到？
聊天室消息不持久化、不补发，仅在线广播；需要留存请用群组或通过回调归档。
回调没收到？
检查回调 URL 可达性、签名校验与投递日志；失败会按退避重试。
401 / 签名错误？
检查 App-Key/Nonce/Timestamp/Signature 四个头；时间戳允许 ±5 分钟，Nonce 5 分钟内不可重复。
如何限频？
见「限频与限制」；客户端发送默认 120 条/分钟，Open API 按接口限频。
如何迁移历史消息？
参考「迁入融云」的五个阶段与数据映射，保留旧消息 ID 到扩展字段。
接入与运维
支持哪些消息类型？
内置文本/图片/文件/语音/位置 + 自定义 objectName；单条上限 5120 字节。
本地存储能关吗？
可以清理本地会话与消息；关闭后每次进入会话需从服务端拉取历史。
如何做消息审核？
使用敏感词 + message.routed 回调先审后发；审核结果写入消息扩展。
SDK 支持哪些平台？
Android / Web / Electron / Flutter / Native 已交付；iOS / HarmonyOS 为契约预留。