快速接入
本页用最短的路径走完一遍:管理员建应用 → 签发应用 token → 发布第一个版本 → 客户端检查更新、下载并校验。概念解释见 首页。
下文中:
$RELHUB_URL是服务器的基础地址,包括反向代理加的路径前缀,例如https://host/release;- 示例应用 id 是
nightdesk,平台是win-x64和android。
1. 管理员:创建应用
只做一次。在服务器本机上,relhub 命令默认连 http://127.0.0.1:18790 并自动读取数据目录里的管理员 token:
relhub app create -id nightdesk -name "NightDesk" -desc "远程桌面"
# created app nightdesk (NightDesk)
用 curl(需要管理员 token):
curl -fsS -X POST "$RELHUB_URL/v1/apps" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"id":"nightdesk","name":"NightDesk","description":"远程桌面"}'
2. 管理员:签发应用专用 token
不要把管理员 token 交给开发者或 CI。给每个应用签发一个只能操作它的 token:
relhub token create -name ci-nightdesk -app nightdesk
# rl_… <- 明文只显示这一次,立刻存进密钥库
# token d763bd18aeab (ci-nightdesk) created; the secret above is shown only once
服务端只保存 token 的哈希,丢了只能重新签发;泄露时用 relhub token revoke -id <ID> 吊销。-app a,b 可以一次授权多个应用。
同时把服务端的签名公钥交给客户端开发者,他们要把它内置进应用:
relhub keys
# KEY ID ACTIVE PUBLIC KEY (base64 Ed25519)
# <key id> true <公钥>
也可以匿名访问 GET $RELHUB_URL/v1/info 查看。
3. 发布一个版本
用 CLI
在任意一台能访问服务器的机器上:
export RELHUB_URL=https://host/release
export RELHUB_TOKEN=rl_… # 第 2 步得到的应用 token
# Windows:versionCode 可以省略,按 主×10000+次×100+补丁 推导(1.6.1 -> 10601)
relhub publish -app nightdesk -platform win-x64 -file nightdesk.zip -version 1.6.1 -notes "首个版本"
# Android:必须显式给 versionCode,且等于 APK 自身的 versionCode
relhub publish -app nightdesk -platform android -file app-release.apk -version 1.3.1 -code 10 -notes "修复鼠标问题"
常用参数:-channel beta 发到 beta 渠道;-no-channel 只上传不上线;-force 把本次版本设为强制更新下限;-notes-file CHANGELOG.md 从文件读更新说明。
用 curl
curl -fsS -X POST "$RELHUB_URL/v1/apps/nightdesk/android/releases" \
-H "Authorization: Bearer $RELHUB_TOKEN" \
-F versionCode=10 -F versionName=1.3.1 -F notes='修复鼠标问题' \
-F file=@app-release.apk
file 必须是最后一个表单字段,这样版本号过低之类的错误能在传输安装包之前就被拒绝。成功返回 201 和 {"release":…,"manifest":…}。
验证
relhub check -app nightdesk -platform android -code 8; echo $?
# update available: nightdesk (8) -> 1.3.1 (10)
# 退出码:0 已是最新,10 有可选更新,20 有强制更新
4. 客户端:检查更新
应用每次启动、以及之后每隔几小时调用一次:
GET /v1/apps/{app}/check?platform=<平台>&versionCode=<已安装的 versionCode>&channel=<渠道>
versionCode:当前安装版本的 versionCode,不知道时传0;channel:可省略,默认stable。
curl -fsS "$RELHUB_URL/v1/apps/nightdesk/check?platform=android&versionCode=8&channel=stable"
{"app":"nightdesk","platform":"android","channel":"stable","currentVersionCode":8,
"updateAvailable":true,"mandatory":false,
"manifest":{"app":"nightdesk","platform":"android","channel":"stable","versionCode":10,
"versionName":"1.3.1","file":"nightdesk-1.3.1-android.apk","size":55076236,
"sha256":"…","minVersionCode":0,"notes":"…","publishedAt":"…",
"keyId":"…","signature":"…"},
"downloadPath":"v1/apps/nightdesk/android/releases/10/download"}
渠道上还没有任何发布时返回 404 not_found;应用被下架时返回 403 app_delisted。各错误的处理方式见 错误码。
想在新版本发布的那一刻就收到通知,用长轮询 GET /v1/apps/{app}/watch?…&wait=50:有更新立即返回同样的结果,否则最多挂起 50 秒后返回 204,然后再调一次。
5. 客户端:下载并校验
- 验签:用内置公钥验证
manifest.signature,并确认manifest.app/platform/channel是你请求的那几个值。 - 自己判断:
manifest.versionCode > 已安装才更新;manifest.minVersionCode > 已安装时为强制更新。不要依赖未签名的updateAvailable/mandatory。 - 下载:
GET $RELHUB_URL/{downloadPath},下载地址用你自己配置的基础地址拼出来;中断后用Range续传(建议同时带If-Range: "<sha256>")。 - 校验:文件大小等于
manifest.size,SHA-256 等于manifest.sha256,否则丢弃。 - 安装:Android 交给
PackageInstaller(系统还会检查签名证书一致),桌面端替换文件后重启。
用 SDK 时以上步骤都是一两行代码:
keys, _ := relclient.ParseTrustedKeys("<base64 公钥>")
c, _ := relclient.New("https://host/release", relclient.WithTrustedKeys(keys...))
u, err := c.Check(ctx, relclient.Target{App: "nightdesk", Platform: "win-x64"}, installed)
if err == nil && u.UpdateAvailable {
err = c.Download(ctx, *u.Manifest, "update.zip", nil) // 续传 + 校验大小和 SHA-256
}
using var client = new RelhubClient("https://host/release", new RelhubClientOptions().TrustKey("<base64 公钥>"));
var update = await client.CheckAsync(new Target("nightdesk", "win-x64"), installedVersionCode);
if (update.UpdateAvailable)
await client.DownloadAsync(update.Manifest!, "update.zip");
详细用法见 Go SDK 和 C# SDK;其他语言按 REST API 与 JSON-RPC 实现。
下一步
- 把发布放进流水线:CI 自动发布
- 灰度(先 beta 后 stable)、强制更新、回滚:
relhub channel promote/relhub channel min/relhub yank,见docs/USAGE.md第 4、5 节