release-publish

relhub 开发者文档

relhub(release-publish)是一个自托管的发布托管 + 自动更新服务:一台服务器存放你所有应用的安装包,用 Ed25519 签名告诉客户端「有没有新版本、该不该强制更新」,客户端下载后自己校验再安装。同一套功能同时提供 REST 和 JSON-RPC 2.0 两种接口,并有 Go、C# 两个官方 SDK,以及一个 Android 应用市场客户端。

本文档内置在服务端程序里,站点上的地址是 /docs;源文件在仓库的 wiki/ 目录。

从哪里开始

你想做的事 看这页
第一次接入:建应用、发版本、让客户端检查更新 快速接入
查某个接口的路径、参数、返回值,或签名的确切字节 REST API 与 JSON-RPC
Go 应用接入 Go SDK
.NET 应用接入(WPF、Avalonia、控制台、服务) C# SDK
Android 手机上浏览、安装应用 Android 应用市场
在 CI 流水线里自动发布 CI 自动发布
收到错误时客户端该怎么做 错误码
管理员登录、下架/上架应用 管理面板

服务端的部署、备份、密钥轮换等运维内容不在 wiki 里,见仓库的 docs/USAGE.md 和 docs/CONTAINER.md。

核心概念

app(应用)

你要发布的一个产品,例如 nightdesk。id 必须匹配 ^[a-z][a-z0-9-]{1,31}$(小写字母开头,2–32 个字符)。应用由管理员显式创建,发布前必须先存在。

platform(平台)

应用的一个构建目标:android、win-x64、linux-arm64、macos-arm64 等,名字自定(^[a-z0-9][a-z0-9_-]{0,23}$)。每个平台有自己独立的版本序列,Windows 版和 Android 版的版本号互不影响。

release(发行版本)

一次上传的安装包,由 (app, platform, versionCode) 唯一确定。发布后文件不可修改;发错了只能撤回(yank)再发一个更高版本。

versionCode 与 versionName

  • versionCode:整数,同一平台内必须严格递增(比曾经发布过的任何版本都大,包括已撤回的),否则返回 conflict。客户端只靠它比较新旧。Android 上它必须等于 APK 自身的 versionCode。
  • versionName:给人看的版本名,如 1.6.1,不参与比较。

channel(渠道)

渠道是「这个渠道上的客户端会被推送哪个版本」的指针,外加一个强制更新下限 minVersionCode。默认渠道是 stable;发布或 promote 到 beta、nightly 等名字时会自动创建(^[a-z][a-z0-9-]{0,15}$)。promote 只移动指针、不复制文件,所以「先 beta 后 stable」和「回滚到旧版本」都只是一次 promote。

签名清单(signed manifest)

服务端对每个渠道当前提供的版本生成一份清单:应用、平台、渠道、versionCode、versionName、文件名、大小、SHA-256、minVersionCode、发布时间、更新说明的哈希,并用服务端的 Ed25519 私钥签名。客户端应当:

  1. 在应用里内置(pin)服务端公钥(GET /v1/info 或 relhub keys 可以看到),不要运行时从同一台服务器取公钥;
  2. 用内置公钥验证清单签名,并确认清单里的 app/platform/channel 就是自己请求的;
  3. 根据清单自己判断是否有更新、是否强制(响应里的 updateAvailable、mandatory 不在签名范围内);
  4. 下载后核对大小和 SHA-256。

Go 和 C# SDK 已经替你做完这些。签名的确切字节格式见 REST API 与 JSON-RPC。

minVersionCode 与强制更新

每个渠道有一个 minVersionCode。已安装版本低于它的客户端必须更新:检查结果里 mandatory: true,应用应当阻止用户继续使用旧版本,直到更新完成。0 表示不强制。发布时加 force=true 会把本次版本设为下限。

yank(撤回)

撤回一个 release 后,它不能再被任何渠道提供,也不能再下载。某个渠道正在提供的版本不能直接撤回(conflict),要先把渠道 promote 到别的版本。撤回不会释放它的 versionCode。已经装上坏版本的客户端不会被降级,要让它们换到修复版,必须发布一个 versionCode 更高的新版本。

delist(下架)

管理员可以把整个应用下架:它从公开列表中消失,匿名的检查更新、下载等请求都会收到 app_delisted 错误;应用自己的 token 和管理员 token 不受影响。详见 管理面板。

token(令牌)

读取(检查更新、下载、列表)不需要 token;写入(发布、promote、撤回、管理)需要 Authorization: Bearer <token>。token 分两种:

  • 管理员 token:可以做一切事情,包括建应用、签发 token、下架/上架。
  • 按应用限定的 token:只能对指定应用发布、promote、撤回、改下限、看统计。CI 里只用这种。

一次更新检查的全过程

应用启动时、以及之后每隔几小时(或用 watch 长轮询):
  GET /v1/apps/{app}/check?platform=P&channel=stable&versionCode=<已安装>
  → 用内置公钥验证 manifest 签名
  → manifest.versionCode > 已安装?  否 → 结束
                                     是 → manifest.minVersionCode > 已安装?是则强制更新
  GET {base}/{downloadPath}          (中断了就用 Range 续传)
  → 核对大小和 SHA-256
  → 交给安装器(Android:PackageInstaller;Windows:替换文件并重启)