====== 平滑迁移 ====== ---- 环信多年来一直在致力于提供稳定，安全的即时通讯服务，在开发者中积累了良好的口碑。如果您希望接入环信的IM服务，但正在使用自研或友商提供的即时通讯服务，这篇文档正是针对这一场景，介绍了一套迁移方案，这套方案已经成功为多家客户实现了平滑迁移。 用户也可以通过环信提供的存量迁移工具、平滑迁移Relay-server来完成迁移。这两个工具已经完成了绝大部分迁移工作，用户只需要关注感兴趣部分即可。 ===== 基本概念 ===== * 应用服务器：客户方自有，服务于客户应用业务功能的服务器。 * 环信IM服务器：环信提供的即时通讯服务器。 * 原IM服务器：用户原先实现 IM 功能的服务器，可以是自有服务器或友商提供的云服务。 * 老应用：与原 IM 服务器连接的老版本 app。 * 新应用：迁移后与环信服务器连接的新版本 app。 ===== 迁移准备 ===== 进行 IM 平滑迁移，需要提前进行以下准备： 注册环信账号，创建应用并开通IM功能。 ===== 强制升级迁移 ===== 如果新应用上架，可以强制所有的老应用升级至新应用，可以使用强制迁移方式。此方式下不存在新老应用的兼容问题。 主要工作如下： ==== 1. 导入用户体系至环信服务器 ==== 用户体系这里包含两部分内容： 一是用户在环信的ID和密码，二是用户之间的好友关系。 如果用户应用服务器自己保存了用户的好友关系，则不需要在环信服务器中保存该部分。 环信只是即时通讯的消息通道。环信本身不提供除用户ID和密码外的其他资料。比如说，你的 APP 是一个婚恋交友 APP，那么你的 APP 用户的头像、昵称、身高、体重、三围、电话号码等信息是保存在你自己的 APP 业务服务器上，这些信息不需要告诉环信。 [[http://docs-im.easemob.com/im/server/ready/user|用户管理REST API]] 提供了一个创建环信账号的 REST 方法。这个方法很简单，只需要提供账号 ID 和密码2个参数，就可以创建一个环信账号。对一个已经上线，已经有很多现有用户的 APP 来说，要集成环信，只需要写一个脚本，循环调用创建环信用户的 REST 方法即可。 ==== 2. 导入群组信息至环信服务器 ==== 需要将客户业务中的群组信息从旧的IM服务器中导入环信服务器，例如群建对应的群组，并加入对应的用户至群组中。 环信提供了对应的REST api可以完成这一切。 [[http://docs-im.easemob.com/im/server/basics/group|群组管理]] ==== 3. 存量迁移工具 ==== 环信为了用户更好的迁移数据（用户体系、群组），提供了存量迁移工具。用户只需要在此基础上简单二次开发，向工具中集成需要迁移的数据，即可使用。如有需要，请联系销售。 ==== 4. 导入用户设备上的历史消息 ==== 在新版本App中集成环信IM SDK后，如果需要继续使用用户设备上的旧消息，可以使用导入消息的api，构建环信消息结构，导入环信SDK中的消息数据库。 具体可以参考： [[http://docs-im.easemob.com/im/android/basics/message#%E5%AF%BC%E5%85%A5%E6%B6%88%E6%81%AF%E5%88%B0%E6%95%B0%E6%8D%AE%E5%BA%93|android导入消息至本地数据库]] [[http://docs-im.easemob.com/im/ios/basics/message#%E6%8F%92%E5%85%A5%E6%B6%88%E6%81%AF|iOS导入消息至本地数据库]] ===== 新老兼容的平滑迁移 ===== 新老兼容迁移的方式，是指在迁移过程中，环信IM服务器和原IM服务器同时提供服务，新应用和旧应用并存，支持新旧应用互通。待用户逐步更新至新应用，旧应用逐步无人使用后，原IM服务器停止服务。 平滑迁移需要原服务支持并开通服务端消息路由功能(用户 A 给用户 B 发消息的过程中，服务器支持通过消息回调（也经常称为， callback, WebHook或者消息抄送服务）的模式将消息转发给开发者提供的服务器 URL 地址)。 平滑迁移的主要内容如下： ==== 1. 导入用户体系和群组信息 ==== 与强制升级的步骤相同，请参考强制升级中的说明。 ==== 2. 利用消息路由功能完成新旧版本之间的消息互通 ==== 如果需要老用户和新用户互相通信，老用户（需要注册一个环信的 ID 和老用户关联）可以发消息到自己的服务端，服务端来调环信的REST发送消息接口给新用户发送消息，新用户收到对方的消息，回复消息给老用户，先走到环信服务器，环信服务器调用旁路接口（自己服务器提供的一个接口）到自己服务器上，再由自己服务器的聊天系统发消息给客户端。 注：在这里需要注意的是，新老用户之间发送文字容易处理，但是如果发送的消息里面带有附件情况，需要 User Server 提供可以上传下载附件的旁路接口，并且需要音视频转换的方法，目前环信客户端这边音频格式统一为 AMR 格式。 {{ :im:other:integrationcases:image018.png?nolink |新老用户通信过程}} === 消息回调的开通 === 消息回调为增值服务，需要联系商务开通，具体步骤可以参考如下文档： [[http://docs-im.easemob.com/im/extensions/value/rtmsgcallback?s[]=%E6%B6%88%E6%81%AF%E5%9B%9E%E8%B0%83|消息回调]] === 消息格式的转换 === 环信IM服务的消息可能与旧的IM服务的消息格式稍有差别，需要用户自己实现格式的转换。 环信的消息支持文本消息，图片消息，语音消息，视频消息，位置消息等不同的类型，具体请参考： [[http://docs-im.easemob.com/im/server/basics/chatrecord#%E8%81%8A%E5%A4%A9%E8%AE%B0%E5%BD%95%E6%95%B0%E6%8D%AE%E7%BB%93%E6%9E%84|消息数据格式]] 用户也可以参考Relay-server此部分的实现 === 语音消息的格式 === 环信的移动端语音消息为amr格式，其中iOS端是录制后转换为amr格式，web端是由服务器端在下载语音消息时转换为mp3格式。如果旧的IM服务器支持的格式不符，需要适当的进行转换。 用户也可以参考Relay-server此部分的实现 ==== 3. 平滑迁移Relay-server ==== 环信为了更好帮助客户从云信、融云平台迁移到环信，环信开发平滑迁移服务（Relay-server），来完成 “利用消息路由功能完成新旧版本之间的消息互通”。 Relay-server 提供了大多数的消息转换，如：文字、语音、视频、图片、文件、位置等消息。 客户只需要进行简单开发即可高度适配客户特有需求，如客户的自定义消息转换等。 如有需要，请联系销售 ==== 其他迁移问题 ==== === 推送问题 === 为保证消息的到达率，环信IM服务支持各平台的推送通道，同时支持免打扰功能（即设定时间不收推送时，或者不接收某个群组的推送），如果旧的IM服务中有类似功能需要迁移的话，可以使用服务器的api提前设置，也可以使用SDK的api根据需要设置。 [[http://docs-im.easemob.com/im/server/ready/user#%E8%AE%BE%E7%BD%AE%E5%85%8D%E6%89%93%E6%89%B0|免打扰设置]] === 聊天室迁移 === 聊天室一般是临时使用的场景中加入退出，因此建议在迁移时通过后台API创建聊天室，用户在需要时加入退出即可。 === 音视频功能迁移 === 音视频功能涉及到信令和媒体流协议的不同，暂无法平滑迁移，建议一次性迁移至环信服务器。 ---- 上一页：[[im:other:integrationcases:appchat|跨 APP 聊天]] 下一页：[[im:other:integrationcases:groupchatat|群组 @ 功能]]