cmhub/docs/client-release-api-integration.md

桌面端版本检查接口对接文档

面向桌面端客户端和其他项目 agent。本文只说明「获取当前软件最新版本」接口如何调用，不涉及 API Key、点数、生成接口或用户账本。

接口用途

桌面端启动时或用户点击「检查更新」时，请求 cmhub 获取当前平台的最新客户端版本、下载地址、SHA256 校验值和发布说明。

该接口是公开只读接口：

• 不需要 Authorization。
• 不需要登录态 cookie。
• 不读取用户信息。
• 不扣点。
• 不占用生成接口限流。
• 不返回后台 ID、本地文件系统路径、用户信息、API Key、模型配置或密钥。

请求地址

生产环境：

GET https://cm.833729.com/api/v1/client/releases/latest?platform=windows

本地开发：

GET http://127.0.0.1:8000/api/v1/client/releases/latest?platform=windows

请求参数

参数	必填	默认值	可选值	说明
platform	否	windows	windows / macos / linux	客户端运行平台。当前桌面端 Windows 客户端传 windows 即可。

建议桌面端显式传 platform=windows，不要依赖默认值。

请求 Demo

curl

curl -s "https://cm.833729.com/api/v1/client/releases/latest?platform=windows"

Windows PowerShell

Invoke-RestMethod `
  -Method Get `
  -Uri "https://cm.833729.com/api/v1/client/releases/latest?platform=windows" `
  -TimeoutSec 10

Python

import requests

url = "https://cm.833729.com/api/v1/client/releases/latest"
response = requests.get(url, params={"platform": "windows"}, timeout=10)
response.raise_for_status()
data = response.json()

release = data.get("release")
if release is None:
    print("暂未发布")
else:
    print(release["version"], release["download_url"])

JavaScript / TypeScript

const response = await fetch(
  "https://cm.833729.com/api/v1/client/releases/latest?platform=windows",
  { method: "GET" },
);

if (!response.ok) {
  throw new Error(`version check failed: ${response.status}`);
}

const data = await response.json();
if (data.release) {
  console.log(data.release.version, data.release.download_url);
}

成功响应：有当前版本

HTTP 状态码：200

{
  "platform": "windows",
  "release": {
    "version": "1.0.0",
    "download_url": "https://cm.833729.com/media/downloads/cmhub-desktop-1.0.0.exe",
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "release_notes": "本次更新说明",
    "published_at": "2026-07-07T10:30:00+08:00"
  }
}

字段说明：

字段	类型	说明
platform	string	服务端实际查询的平台。
release.version	string	最新客户端版本号。
release.download_url	string	下载地址。可能是本站 /media/downloads/... 的绝对 URL，也可能是后台配置的外部 CDN / 对象存储 URL。
release.sha256	string	安装包 SHA256。桌面端下载后应计算本地文件 SHA256 并比对。
release.release_notes	string	发布说明，可能为空字符串。
release.published_at	string	ISO 8601 时间；当前实现使用发布记录更新时间。

成功响应：暂未发布

HTTP 状态码：200

{
  "platform": "windows",
  "release": null,
  "message": "暂未发布"
}

客户端处理建议：

• 把 release === null 视为「没有可下载版本」。
• 不要弹错误框。
• 可在日志中记录，也可在「检查更新」按钮下显示「暂未发布」。

错误响应：非法平台

HTTP 状态码：400

{
  "error": {
    "code": "bad_request",
    "message": "参数错误"
  }
}

常见原因：platform=android 或其他未支持的平台。

客户端对接要求

1. 调用版本检查接口时不要带 API Key。
2. 不要解析首页 HTML 获取版本号，必须使用本 JSON 接口。
3. 网络超时建议 5 到 10 秒；失败时不影响主程序启动。
4. 客户端应把本地版本号与 release.version 比较，只有远端版本更新时才提示用户下载。
5. 下载完成后按 release.sha256 校验安装包；校验失败必须删除文件并提示重新下载。
6. 不要假设下载地址一定在 cmhub 域名下，后续可能切到 CDN 或对象存储。
7. 不要依赖 message 做业务判断；是否有版本以 release 是否为 null 为准。

版本比较建议

版本号建议采用语义化版本格式，例如：

1.0.0
1.1.0
1.1.1
2.0.0

客户端比较时不要做普通字符串比较。例如 "1.10.0" 应大于 "1.9.0"。

简化 Python 示例：

def parse_version(version: str) -> tuple[int, ...]:
    return tuple(int(part) for part in version.split("."))

if parse_version(remote_version) > parse_version(local_version):
    print("发现新版本")

如果未来版本号包含 beta / rc 等预发布标记，客户端需要使用更完整的语义化版本解析器。

下载校验建议

Python 计算 SHA256 示例：

import hashlib
from pathlib import Path

def sha256_file(path: str) -> str:
    digest = hashlib.sha256()
    with Path(path).open("rb") as file:
        for chunk in iter(lambda: file.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()

比对时建议统一转小写：

if sha256_file(downloaded_path).lower() != release["sha256"].lower():
    raise RuntimeError("安装包 SHA256 校验失败")

服务端发布前置条件

运营在 django-admin 的「客户端下载版本」里维护发布记录：

• platform：选择 windows。
• version：填写客户端版本号。
• file 或 external_url：至少填写一个。
• sha256：填写安装包 SHA256。
• is_current：勾选当前版本。
• release_notes：填写发布说明。

同一平台只能有一个当前版本；保存新的当前版本时，旧当前版本会自动取消当前状态。

如果使用本地上传文件，生产环境必须确保 Nginx 正确服务 MEDIA_ROOT/downloads/，否则接口会返回下载 URL，但客户端下载可能 404。

排查清单

现象	优先检查
返回 release:null	django-admin 是否有该 platform 的 is_current=True 发布记录；发布记录是否有 external_url 或上传文件。
返回 400 bad_request	platform 是否为 windows / macos / linux。
download_url 访问 404	Nginx media 配置是否正确；本地上传文件是否存在；若使用 external_url，外部地址是否可访问。
SHA256 校验失败	后台填写的 SHA256 是否对应当前安装包；安装包是否被重新打包但未更新 SHA256。
客户端每次都提示更新	客户端版本比较逻辑是否按数字段比较，而不是字符串比较。