接口文档

给客户端做更新检查、给脚本/CI 上传安装包。除上传外全部免登录。

Base URL

http://localhost:3000

上传令牌

UPLOAD_TOKEN（开发环境默认 dev-upload-token，生产未配置则禁用）

单文件上限

UPLOAD_MAX_MB（默认不限制）

检查更新

客户端启动时静默调用，或用户点击「检查更新」时调用，两者用同一个接口。返回的 downloadUrl 是绝对地址：优先用 PUBLIC_BASE_URL，未配置时用本次请求的 origin，客户端可直接下载。

http

GET /api/v1/check

参数	必填	说明
appKey	是	应用标识，创建应用时指定
platform	是	android / ios / windows / macos / linux
arch	否	arm64 / x64 / universal；不传时匹配该平台任意变体，传了只匹配同架构或 universal，不会串架构
versionCode	否	客户端当前的整数构建号；不传按 0 处理（首次安装）
channel	否	stable（默认）/ beta / internal
brief	否	传 1 时不返回 changelog，用于静默检查省流量

shell

curl "http://localhost:3000/api/v1/check?appKey=kiosk-player&platform=android&arch=arm64&versionCode=112&channel=stable"

响应（无更新时 hasUpdate 为 false、latest 为 null）：

json

{
  "hasUpdate": true,
  "latest": {
    "versionName": "1.13.0",
    "versionCode": 113,
    "channel": "stable",
    "forceUpdate": false,
    "fileName": "kiosk-1.13.0.apk",
    "fileSize": 22118442,
    "sha256": "9f2c1d...",
    "downloadUrl": "http://localhost:3000/dl/rel_a1b2c3d4e5f60718",
    "publishedAt": "2026-10-19 16:20",
    "changelog": "## 更新\n- 修复内存泄漏"
  }
}

上传安装包

请求体是文件原始字节，不是 multipart 表单。参数全部走 query，方便 curl --data-binary 直接调用。appKey 不存在时会自动创建应用与平台变体。文件大小默认不限制，需要护栏时用 UPLOAD_MAX_MB 设置上限。

http

POST /api/v1/upload

请求头 X-Upload-Token: <令牌> 与 Content-Type: application/octet-stream

参数	必填	说明
appKey	是	应用标识，不存在则自动创建
platform	是	android / ios / windows / macos / linux
arch	否	arm64 / x64 / universal，默认 universal
versionName	是	展示用版本号，例如 1.13.0
versionCode	是	整数构建号，必须递增；同一变体同渠道不可重复
channel	否	stable（默认）/ beta / internal
fileName	否	原始文件名，缺省读 X-File-Name 头
forceUpdate	否	true 时客户端必须更新
changelog	否	更新说明，支持 markdown，需 URL 编码
status	否	draft 存为草稿；默认 published 直接发布

bash

BASE=http://localhost:3000
TOKEN=dev-upload-token

curl -X POST "$BASE/api/v1/upload?appKey=kiosk-player&platform=android&arch=arm64&versionName=1.13.0&versionCode=113&channel=stable&fileName=kiosk-1.13.0.apk" \
  -H "X-Upload-Token: $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./kiosk-1.13.0.apk

Windows PowerShell：

powershell

$BASE = "http://localhost:3000"
$TOKEN = "dev-upload-token"

curl.exe -X POST "$BASE/api/v1/upload?appKey=kiosk-player&platform=android&arch=arm64&versionName=1.13.0&versionCode=113&channel=stable&fileName=kiosk-1.13.0.apk" `
  -H "X-Upload-Token: $TOKEN" `
  -H "Content-Type: application/octet-stream" `
  --data-binary "@.\kiosk-1.13.0.apk"

响应：

json

{
  "ok": true,
  "releaseId": "rel_a1b2c3d4e5f60718",
  "appKey": "kiosk-player",
  "platform": "android",
  "arch": "arm64",
  "versionName": "1.13.0",
  "versionCode": 113,
  "status": "published",
  "fileSize": 22118442,
  "sha256": "9f2c1d...",
  "downloadUrl": "/dl/rel_a1b2c3d4e5f60718",
  "createdApp": false,
  "createdArtifact": false
}

下载安装包

支持 Range 请求头，返回 206 与 Content-Range，客户端可断点续传或分块下载。只有 status=published 的版本可下载，草稿与已归档返回 403。

http

GET /dl/{releaseId}

bash

curl -L -C - -o kiosk.apk "http://localhost:3000/dl/rel_a1b2c3d4e5f60718"

接入约定

这几条是最容易出错的地方，接入前先读一遍。

版本比较只认整数 versionCode。Android 用 BuildConfig.VERSION_CODE，Windows/Tauri 用构建号， macOS 用 Info.plist 的 CFBundleVersion。 versionName 只用于展示，不要拿来比大小。
下载完校验 sha256 再安装。响应里的 sha256 是上传时算好的，客户端比对后再执行。
静默检查要带超时并吞掉失败。后端不可达时不弹错误框，避免拖慢启动。
同一变体同渠道的 build 号不能重复。重复上传返回 409，请递增 build 号。
桌面端签名不在本系统处理。macOS 未公证的 DMG 会被 Gatekeeper 拦截，Windows 未签名会触发 SmartScreen，发布前自行确认。