迁入融云
本页说明如何从其它 IM 服务（包括融云、环信或自建 IM）迁移到 NI PaaS IM。迁移分为评估、数据映射、双跑、切换与回滚五个阶段。
说明
页面标题沿用对标栏目“迁入融云”，实际内容是“迁入 NI PaaS”的迁移指南；对标仅用于 IA 对齐。
迁移阶段
- 评估与盘点
盘点现有会话形态、消息类型、扩展字段、回调与推送通道；确认目标平台与 SDK 版本。
- 账号与 Token 迁移
保持 userId 不变；由业务服务调用
/user/register同步用户并签发 Token。 - 历史数据迁移
导出旧服务消息，按目标 objectName 映射后经服务端批量导入；保留原时间戳与顺序。
- 双跑与灰度
新旧 IM 并行，客户端按用户灰度切换；通过回调比对消息量与在线状态。
- 切换与回滚
全量切换后保留旧服务只读 30 天；异常时回滚客户端配置并恢复旧 Token。
数据映射
| 旧概念 / 字段 | NI PaaS 对应 | 说明 |
|---|---|---|
| userId / username | userId | 保持稳定，不强制迁移昵称与头像 |
| token | Token（/user/register 返回） | 由业务服务签发，HTTP 有效期可配置 |
| 会话类型 | conversationType（1-5） | 单聊 / 群组 / 聊天室 / 超级群 / 系统 |
| 消息 ID | messageId | 服务端生成；迁移时保留旧 ID 到扩展字段 |
| 消息序号 | seq | 按会话重新分配，保证单调递增 |
| 自定义消息 | objectName + 自定义 JSON | 透传不解析，单条上限 5,120 字节 |
| 离线推送 | 推送接口 + 厂商通道 | 推送 token 需重新注册 |
接口兼容策略
- 对外暴露的 REST 路径与字段以 IDL 为准，迁移期间不破坏既有语义；
- 新增字段保持向后兼容，客户端可忽略未知字段；
- 错误码不复用旧值：统一使用 状态码表。
切换检查清单
| 检查项 | 通过标准 |
|---|---|
| 消息收发 | 单聊/群组/聊天室各 100 条消息顺序正确、无重复 |
| 离线补发 | 断网 5 分钟后重连可收到离线消息并触发 CONNECTED |
| 多端同步 | 两端同时在线，消息双向同步且已读状态一致 |
| 回调 | message.routed 投递成功率 100%，签名校验通过 |
| 监控 | 控制台消息量与错误码曲线与旧服务对齐 |
需要帮助
迁移过程中可通过控制台的「消息查询」与「回调投递日志」定位问题；如需定制迁移脚本，请参考 示例工程。