SDK 升级与回滚

本页面向需要升级 XHIM SDK 的 App 开发者和服务端运维人员。普通业务开发只需使用 正式交付包，不需要修改本地数据库或执行内核迁移命令。

客户端升级

1. 阅读 Changelog，确认是否有需要调整的公开方法；
2. 在一个空白工程中安装新的正式 SDK 包；
3. 用测试账号验证登录、会话、发送消息、联系人、群组、退出和重新登录；
4. 用旧版 App 生成一份测试账号数据，再由新版 App 打开并验证历史消息；
5. 先发布给内部账号，再逐步扩大用户范围；
6. 观察登录失败、崩溃、消息积压和数据库打开错误。

升级时 Core、平台 SDK 和 UI Kit 应来自同一次发布。不要混用仓库临时构建、旧版 Wrapper 和新版 Core。

服务端升级

推荐顺序：

备份数据库并验证可以恢复
  -> 执行一次受控迁移
  -> 部署少量新 Server 实例
  -> 检查健康状态和关键接口
  -> 逐步替换其余实例
  -> 再开始发布新版客户端

迁移只能由一个受控任务执行。不要让所有服务实例同时修改数据库结构。

发布前检查

• SDK 和 Server 版本来自同一发布说明；
• 安装包的 Hash 与交付清单一致；
• 空白工程可以正常安装和编译；
• 新 Server 仍支持约定范围内的旧客户端；
• 数据库备份已验证可恢复；
• 测试账号的登录、收发消息和离线恢复正常；
• 监控和回滚负责人已经明确。

什么时候停止灰度

出现以下情况应停止扩大范围：

• 登录成功率明显下降；
• WebSocket 频繁断开或无法恢复；
• 消息发送、Push 或媒体任务持续积压；
• 数据库迁移或打开失败；
• App 崩溃率明显上升；
• 新旧版本之间出现无法解释的数据差异。

回滚说明

应用回滚和数据库回滚不是一回事。服务程序通常可以切回上一版本，但已经完成的数据库 升级不应通过删列、降低版本号或清空数据来“伪装回滚”。如果数据库已经写入新结构， 优先发布向前修复；只有在确认数据影响后，才从已验证的备份恢复到独立环境并切换。

客户端数据库被新版 SDK 打开后，也不保证旧版 SDK 可以再次打开。因此灰度前必须使用 测试账号验证升级路径，而不是拿真实用户数据反复切换版本。

完整上线步骤见 发布检查清单，服务端备份、迁移和健康检查见 Server 使用说明。