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 私钥签名。客户端应当:
- 在应用里内置(pin)服务端公钥(
GET /v1/info或relhub keys可以看到),不要运行时从同一台服务器取公钥; - 用内置公钥验证清单签名,并确认清单里的 app/platform/channel 就是自己请求的;
- 根据清单自己判断是否有更新、是否强制(响应里的
updateAvailable、mandatory不在签名范围内); - 下载后核对大小和 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:替换文件并重启)