软件版本分发

站点凭 X-Api-Key 上传并发布软件版本；客户端经公开接口查询最新版本与下载（302 到 CDN）。

读写分离是设计

写面（上传 / 发布）要 X-Api-Key + releases 权限；读面（latest / 列表 / 下载）公开，按站点 slug 定位——客户端软件做更新检查不能内置 API Key。文件本体在对象存储，下载走 CDN（站点开 CDN 鉴权时为签名链接）。

① 预签名直传

POST/api/v1/releases/open/presignX-Api-Key · releases

签发版本文件直传 URL（单文件 ≤1GB）

请求 / 响应

POST https://api.rekitdev.com/api/v1/releases/open/presign
X-Api-Key: <站点 Key>

{ "content_type": "application/zip", "content_length": 12345678 }

→ { "key": "img/<slug>/releases/<uuid>.bin", "put_url": "...", "expires_in": 300, "max_bytes": 1073741824 }

客户端对 put_url 做 HTTP PUT（Content-Type 与申请一致）。content_length 必填、≤1GB；默认 content_type 为 application/octet-stream。

② 注册版本

POST/api/v1/releasesX-Api-Key · releases

上传完成后注册版本元数据（平台 HEAD 校验对象已上传且大小一致）

json

{ "version": "1.2.0", "channel": "stable", "notes": "更新说明",
  "storage_key": "<第①步返回的 key>", "size_bytes": 12345678, "sha256": "<64位hex>" }

字段	必填	说明
`version`	是	semver（`1.2.3` / `1.2.3-beta.1`）；非法 → 422；注册时规范化（剥 `v` 前缀与 build 元数据）
`channel`	否	默认 `stable`；字母数字开头，可含 `-_.`
`storage_key`	是	须在 `{path_prefix}/{slug}/releases/` 命名空间，否则 400 `storage_key_invalid`
`size_bytes`	是	与对象实际大小一致
`sha256`	是	64 位十六进制，客户端下载后校验

对象未找到 / 大小不符 → 400 storage_object_missing；同通道同版本 → 409 release_exists；站点未绑定存储 → 503 site_storage_unbound。

③ 客户端查询与下载（公开，无需 Key）

GET/api/v1/releases/{site_slug}/{channel}/latest公开

通道内 semver 最新版本元数据

GET/api/v1/releases/{site_slug}/{channel}/{version}/download公开

302 → CDN 下载链接（下载计数 +1）

响应含 version / notes / size_bytes / sha256 / published_at / download_url。无可用版本 → 404 release_not_found；运营后台「版本管理」可下架 / 恢复版本，下架后查询与下载立即 404。