pro/im_server

Fork 0

Files

T

richjohnrambo 67e8c2c6f6 feat: add workbench kafka migration support

2026-09-13 22:17:02 +08:00

7.1 KiB

Raw Blame History

MeetingIM App 版本更新前后端对接文档

1. 适用范围

本文档用于 iOS、Android 客户端检查新版本，以及执行推荐更新和强制更新。

版本策略为全局配置，存储在 hotgo.im_app_releases，不区分租户。
iOS 安装包由 App Store 托管，客户端通过 store_url 跳转。
Android APK 由发布人员上传到专用 OSS 发布目录，客户端通过 package_url 下载。
客户端不直接访问数据库，也不自行拼接 OSS 地址。

2. 检查版本接口

GET https://api.118im.com/v1/im/app/releases/latest

该接口允许未登录调用。

2.1 请求 Header

Header	必填	示例	说明
`X-IM-Schema`	是	`1`	MeetingIM HTTP 协议版本
`X-Client-Platform`	建议	`ios` / `android`	客户端平台

2.2 Query 参数

参数	必填	示例	说明
`apikey`	是	`AQAAAA...`	应用 API Key
`platform`	是	`android`	仅支持 `ios`、`android`
`current_version`	是	`1.2.0`	当前版本，使用数字点分格式
`channel`	否	`stable`	发布渠道，默认 `stable`

Android 请求示例：

curl -H 'X-IM-Schema: 1' \
  -H 'X-Client-Platform: android' \
  'https://api.118im.com/v1/im/app/releases/latest?apikey=AQAAAA...&platform=android&current_version=1.2.0&channel=stable'

3. 成功响应

{
  "code": 0,
  "data": {
    "platform": "android",
    "channel": "stable",
    "current_version": "1.2.0",
    "latest_version": "1.3.0",
    "min_supported_version": "1.1.0",
    "has_update": true,
    "force_update": false,
    "update_type": "recommended",
    "release_notes": "优化消息稳定性并修复已知问题。",
    "store_url": "",
    "package_url": "https://download.example.com/app-releases/android/stable/1.3.0/meetingim-1.3.0.apk",
    "checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "remind_after_seconds": 86400,
    "published_at": "2026-09-12T08:00:00Z"
  },
  "request_id": "req_xxx",
  "server_time": "2026-09-12T08:10:00Z"
}

3.1 响应字段

字段	类型	说明
`current_version`	string	客户端传入的当前版本
`latest_version`	string	后台发布的最新版本
`min_supported_version`	string	最低可继续使用的版本
`has_update`	boolean	是否存在更高版本
`force_update`	boolean	是否必须完成更新后才能继续使用
`update_type`	string	`none`、`recommended`、`force`
`release_notes`	string	更新说明
`store_url`	string	iOS App Store 地址
`package_url`	string	Android APK 的 OSS/CDN HTTPS 下载地址
`checksum`	string	Android APK 的 SHA-256，小写十六进制
`remind_after_seconds`	number	推荐更新关闭后再次提醒的间隔
`published_at`	string	发布时间，UTC RFC 3339

4. 更新判断规则

客户端以服务端返回结果为准，不自行重新计算强制更新规则。

条件	客户端行为
`has_update=false`	不弹更新窗口；手动检查时提示已是最新版本
`has_update=true, force_update=false, update_type=recommended`	弹推荐更新窗口，允许取消或稍后更新
`has_update=true, force_update=true`	弹强制更新窗口，不允许关闭，不允许进入主业务
`update_type=none`	不主动弹窗，可展示版本信息

当 current_version < min_supported_version 时，服务端无条件返回强制更新：

{
  "has_update": true,
  "force_update": true,
  "update_type": "force"
}

5. Android APK 与 OSS

5.1 OSS 对象路径

建议使用独立于聊天附件的发布目录：

app-releases/android/{channel}/{version}/meetingim-{version}.apk

示例：

app-releases/android/stable/1.3.0/meetingim-1.3.0.apk

5.2 下载地址要求

package_url 必须使用 HTTPS。
地址必须长期稳定，至少覆盖该版本的完整支持周期。
可以使用 OSS 公共读地址，或绑定 OSS/CDN 的固定下载域名。
不得把有效期只有几分钟的 OSS 签名 URL 保存到版本表。
如果 Bucket 必须私有，应提供固定公开下载接口，由接口实时生成签名并返回 302；版本表保存该固定接口地址。
APK 响应建议设置 Content-Type: application/vnd.android.package-archive。
文件名、对象路径和 URL 必须包含版本号，禁止覆盖旧版本对象。

聊天附件接口 /v0/file/s/{file_id} 需要用户鉴权，不作为 Android 安装包的默认下载地址。

5.3 发布步骤

Android 构建正式签名 APK。
计算 APK 的 SHA-256。
上传到 OSS 的 app-releases/android/{channel}/{version}/ 目录。
使用浏览器或 curl -I 验证 HTTPS 地址可以下载。
在 Admin 的“IM 全局版本更新”中编辑 Android 策略。
填写最新版本、最低支持版本、更新类型、更新说明、package_url 和 SHA-256。
保存后由 Kafka app.release.updated 事件通知 IM Server 清理缓存。
使用旧版本号请求检查接口，确认下载地址、校验值和强更状态。

计算 SHA-256 示例：

shasum -a 256 meetingim-1.3.0.apk

6. Android 客户端处理

调用版本检查接口。
has_update=false 时结束检查。
根据 force_update 展示推荐更新或不可关闭的强更弹窗。
使用系统下载组件请求 package_url，支持进度展示和失败重试。
下载完成后计算本地文件 SHA-256，并与 checksum 比较。
校验 APK 包名和签名证书必须与已安装应用一致。
通过 Android FileProvider 发起安装，不使用 file:// URI。
未授予“安装未知应用”权限时，引导用户进入系统授权页。
强更下载或安装失败时保留重试、网络设置和退出应用入口，不能绕过进入主业务。

客户端不得在 SHA-256 或应用签名校验失败后继续安装。

7. iOS 客户端处理

iOS 只读取 store_url，忽略 package_url 和 checksum。
store_url 必须是 https://apps.apple.com/... 地址。
推荐更新允许取消；强制更新不得进入主业务。
点击更新后使用系统能力打开 App Store。

8. 错误响应

缺少或错误的 current_version：

{
  "code": 30000,
  "reason": "MALFORMED_REQUEST",
  "message": "malformed request",
  "details": {
    "field": "current_version"
  }
}

HTTP 状态	原因
400	缺少 `X-IM-Schema: 1`
400	缺少或错误的 `current_version`
400	`platform` 不是 `ios` 或 `android`
500	Admin 版本配置缺失、格式错误或内部配置接口不可用

9. 当前测试环境

Base URL: https://api.118im.com
版本接口: /v1/im/app/releases/latest
API Key: AQAAAAABAAAoeOI7tA3HsYvdzDhYhZJy
协议版本: X-IM-Schema: 1
默认渠道: stable

当前测试库已配置 iOS、Android 1.0.0 默认策略。正式验证 Android 更新前，需要先上传测试 APK，并在 Admin 填写对应 package_url 与 SHA-256。

7.1 KiB Raw Blame History Unescape Escape