平滑迁移

更新时间：2022 年 7 月 22 日

环信多年来一直在致力于提供稳定，安全的即时通讯服务，在开发者中积累了良好的口碑。如果您希望接入环信的IM服务，但正在使用自研或友商提供的即时通讯服务，这篇文档正是针对这一场景，介绍了一套迁移方案，这套方案已经成功为多家客户实现了平滑迁移。

用户也可以通过环信提供的存量迁移工具、平滑迁移 Relay-server 来完成迁移。这两个工具已经完成了绝大部分迁移工作，用户只需要关注感兴趣部分即可。

• 应用服务器：客户方自有，服务于客户应用业务功能的服务器。
• 环信 IM 服务器：环信提供的即时通讯服务器。
• 原 IM 服务器：用户原先实现 IM 功能的服务器，可以是自有服务器或友商提供的云服务。
• 老应用：与原 IM 服务器连接的老版本 app。
• 新应用：迁移后与环信服务器连接的新版本 app。

进行 IM 平滑迁移，需要提前进行以下准备：

注册环信账号，创建应用并开通 IM 功能。

如果新应用上架，可以强制所有的老应用升级至新应用，可以使用强制迁移方式。此方式下不存在新老应用的兼容问题。 主要工作如下：

用户体系包含两部分内容：

一是用户在环信的 ID 和密码；

二是用户之间的好友关系。如果你的应用服务器保存了用户的好友关系，则不需要在环信服务器中保存该部分。

环信只是即时通讯的消息通道。环信本身不提供除用户 ID 和密码外的其他资料。比如说，你的 APP 是一个婚恋交友 APP，那么你的 APP 用户的头像、昵称、身高、体重、三围、电话号码等信息是保存在你自己的 APP 业务服务器上，这些信息不需要告诉环信。

用户管理 REST API 提供了一个创建环信账号的 REST 方法。这个方法很简单，只需要提供账号 ID 和密码 2 个参数，就可以创建一个环信账号。对一个已经上线，已经有很多现有用户的 APP 来说，要集成环信，只需要写一个脚本，循环调用创建环信用户的 REST 方法。

需要将客户业务中的单聊和群聊信息从旧的 IM 服务器中导入环信服务器，例如群建对应的群组，并加入对应的用户至群组中。

对应的 REST API 如下：

REST 导入单聊消息

REST 导入群聊消息

环信为了用户更好的迁移数据（用户体系、群组），提供了存量迁移工具。用户只需要在此基础上简单二次开发，向工具中集成需要迁移的数据，即可使用。如有需要，请联系销售。

在新版本 App 中集成环信 IM SDK 后，如果需要继续使用用户设备上的旧消息，可以使用导入消息的 API，构建环信消息结构，导入环信 SDK 中的消息数据库。

具体可以参考：

Android 导入消息至本地数据库

iOS 导入消息至本地数据库

新老兼容迁移的方式，是指在迁移过程中，环信 IM 服务器和原IM服务器同时提供服务，新应用和旧应用并存，支持新旧应用互通。待用户逐步更新至新应用，旧应用逐步无人使用后，原 IM 服务器停止服务。

平滑迁移需要原服务支持并开通服务端消息路由功能(用户 A 给用户 B 发消息的过程中，服务器支持通过消息回调（也经常称为：callback，WebHook 或者消息抄送服务）的模式将消息转发给开发者提供的服务器 URL 地址)。

平滑迁移的主要内容如下：

与强制升级的步骤相同，请参考强制升级中的说明。

如果需要老用户和新用户互相通信，老用户（需要注册一个环信的 ID 和老用户关联）可以发消息到自己的服务端，服务端来调环信的 REST 发送消息接口给新用户发送消息，新用户收到对方的消息，回复消息给老用户，先走到环信服务器，环信服务器调用旁路接口（自己服务器提供的一个接口）到自己服务器上，再由自己服务器的聊天系统发消息给客户端。

注：在这里需要注意的是，新老用户之间发送文字容易处理，但是如果发送的消息里面带有附件情况，需要 User Server 提供可以上传下载附件的旁路接口，并且需要音视频转换的方法，目前环信客户端这边音频格式统一为 AMR 格式。

消息回调为增值服务，需要联系商务开通，具体步骤可以参考如下文档：

消息回调

环信 IM 服务的消息可能与旧的 IM 服务的消息格式稍有差别，需要用户自己实现格式的转换。 环信的消息支持文本消息，图片消息，语音消息，视频消息，位置消息等不同的类型，具体请参考：

消息数据格式

用户也可以参考 Relay-server 此部分的实现。

环信的移动端语音消息为 amr 格式，其中 iOS 端是录制后转换为 amr 格式，web 端是由服务器端在下载语音消息时转换为 mp3 格式。如果旧的 IM 服务器支持的格式不符，需要适当的进行转换。

用户也可以参考 Relay-server 此部分的实现。

环信为了更好帮助客户从云信、融云平台迁移到环信，环信开发平滑迁移服务（Relay-server），来完成 “利用消息路由功能完成新旧版本之间的消息互通”。 Relay-server 提供了大多数的消息转换，如：文字、语音、视频、图片、文件、位置等消息。 客户只需要进行简单开发即可高度适配客户特有需求，如客户的自定义消息转换等。 如有需要，请联系销售。

为保证消息的到达率，环信 IM 服务支持各平台的推送通道，同时支持免打扰功能（即设定时间不收推送时，或者不接收某个群组的推送），如果旧的 IM 服务中有类似功能需要迁移的话，可以使用服务器的 API 提前设置，也可以使用 SDK 的 API 根据需要设置。

免打扰设置

聊天室一般是临时使用的场景中加入退出，因此建议在迁移时通过后台 API 创建聊天室，用户在需要时加入退出即可。

音视频功能涉及到信令和媒体流协议的不同，暂无法平滑迁移，建议一次性迁移至环信服务器。