Go SDK 使用文档(relclient)
2026-11-06 起 egg 不再是镜像。 egg 上的 release-publish 改成了独立分发服务器:签名密钥仍是同一把
f5faa9f9858b789f(固定密钥的客户端照样信任),但relhub mirror已停用,两台的发布互不同步。egg 同时挂在公网https://release.521985.xyz(只读,GET/HEAD;发布只走 egg 本机 127.0.0.1:18790),tailnet 路径https://egg.tail9f7f1f.ts.net/release照旧。所以别再把 egg 当作本机的 fallback 地址:它上面没有本机的新发布。下文关于 mirror 的部分是历史记录。
relhub/pkg/relclient 是 release-publish 的官方 Go 客户端:让一个应用用几行代码接入「检查更新 → 下载 → 校验」,也让 CI 和脚本用同一个包发布、管理发行版本。
- 只依赖 Go 标准库,没有第三方依赖,
CGO_ENABLED=0即可构建。 (服务端从 2026-11 起用 gin;pkg/relclient、pkg/relproto仍只用标准库。用replace relhub => …引入时,go.mod里会出现 gin 的间接要求,第一次需要go mod tidy补齐go.sum,编译出的程序不含 gin。) - 已验证可为
windows/amd64、windows/arm64、linux/arm64、android/arm64交叉编译。 Client并发安全,一个进程里建一个、到处共用即可。- 协议细节(REST 路径、JSON-RPC、签名载荷)见 REST-API;服务端的安装、发布流程和运维见 USAGE.md。C# 应用请用 C# SDK;其他语言(Kotlin、shell)按 REST-API 页的协议自行接入。
目录
- 五分钟上手
- 把 SDK 引入你的项目
- 必须先懂的五个概念
- 创建客户端
- 检查更新
Check - 下载
Download - 等待新版本
Watch/WatchLoop - 查询
- 发布
Publish - 管理接口
- JSON-RPC
Call - 错误处理
- 集成方案
- 测试你的集成
- 排障
- API 速查
1. 五分钟上手
一个完整的「检查并下载更新」程序,已放在仓库里并实测通过:examples/selfupdate/main.go。核心就这些:
package main
import (
"context"
"fmt"
"log"
"relhub/pkg/relclient"
)
// 发行服务的公钥(relhub keys 可查看),编译进应用。
const pinnedKey = "k4thZR+OVYSGAT/9j5F39csgGqTL0t3X6GYdNCmuRI8="
func main() {
keys, err := relclient.ParseTrustedKeys(pinnedKey)
if err != nil {
log.Fatal(err)
}
c, err := relclient.New("https://tony-ai-pc-1.tail9f7f1f.ts.net/release",
relclient.WithTrustedKeys(keys...))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
const installed = 10601 // 当前运行版本的 versionCode
u, err := c.Check(ctx, relclient.Target{App: "nightdesk", Platform: "win-x64"}, installed)
if err != nil {
log.Fatal(err)
}
if !u.UpdateAvailable {
fmt.Println("已是最新")
return
}
fmt.Printf("新版本 %s,强制更新: %v\n", u.Manifest.VersionName, u.Mandatory)
// 续传、校验大小和 SHA-256,通过后才改名到位。
if err := c.Download(ctx, *u.Manifest, "update.zip", nil); err != nil {
log.Fatal(err)
}
fmt.Println("update.zip 已下载并校验")
}
命令行直接试用参考实现(把 <公钥> 换成 relhub keys 输出的那一行):
go run ./examples/selfupdate \
-url https://tony-ai-pc-1.tail9f7f1f.ts.net/release -keys <公钥> \
-app nightdesk -platform win-x64 -code 10601 -out update.zip
# -watch:不立即回答,等到下一个新版本发布再下载
2. 把 SDK 引入你的项目
模块名是 relhub(没有域名,不能 go get)。有三种引入方式,第一种最省事:
方式 A:replace 指向本机源码(同一台机器开发)
在你的应用的 go.mod 里:
module example.com/nightdesk
go 1.24
require relhub v0.0.0
replace relhub => /home/tony/dev/release-publish
然后 import "relhub/pkg/relclient" 和 import "relhub/pkg/relproto" 即可。go build、go mod tidy、go vet 以及 Windows / Android 的交叉编译都已实测通过。
只有 pkg/ 下的两个包可以被外部引用;internal/ 是服务端实现,Go 不允许外部导入。
方式 B:go mod vendor(CI 或别的机器构建)
先按方式 A 配好,再在你的应用目录执行:
go mod vendor # 把 relhub/pkg/... 复制进 vendor/,提交 vendor/
go build -mod=vendor ./...
之后构建不再依赖 /home/tony/dev/release-publish 这个路径。
方式 C:直接复制
把 pkg/relclient 和 pkg/relproto 两个目录复制进你的仓库,把里面的 relhub/pkg/... 导入路径改成你自己的模块路径。适合不想碰 replace 的小项目。升级 SDK 时需要手动同步。
relproto是服务端、SDK、CLI 共用的协议包(Manifest 签名/验签、错误码、类型)。你的应用会用到其中的relproto.CheckResult、relproto.Error、relproto.Manifest等类型。
3. 必须先懂的五个概念
| 概念 | 一句话 |
|---|---|
| Target | 要更新什么:App(应用 id)+ Platform(android、win-x64…)+ Channel(默认 stable)。 |
| versionCode | 整数版本号,越大越新,每个 platform 内严格递增。Android 必须等于 APK 的 versionCode。检查更新时传「当前安装版本」的 versionCode。versionName(如 1.6.1)只用于展示。 |
| channel | 渠道。stable 是默认;可以有 beta 等。渠道只是指向某个 release 的指针,外加一个强制更新下限 minVersionCode。 |
| manifest | 服务端对「某渠道当前提供什么」的签名描述(应用、平台、渠道、版本、文件名、大小、SHA-256、下限、说明的哈希)。 |
| 公钥固定 | 把服务端的 Ed25519 公钥编译进应用,用 WithTrustedKeys 传给 SDK。这样即使服务端或网络被冒充,伪造的清单也过不了验签。 |
SDK 的安全约定:
- 响应里的
updateAvailable、mandatory没有签名,SDK 不采信,而是用签名过的 manifest 在本地重新计算:UpdateAvailable = manifest.versionCode > 已安装,Mandatory = UpdateAvailable && manifest.minVersionCode > 已安装。 - SDK 会核对 manifest 里的 app/platform/channel 与你请求的一致(防止拿别的应用的合法签名来冒充)。
- 下载 URL 一律用「你配置的 base URL + manifest 推出的路径」,不使用服务端发来的任意 URL。
4. 创建客户端
c, err := relclient.New(baseURL, opts...)
baseURL 是服务地址加上反向代理的路径前缀,本机部署为 https://tony-ai-pc-1.tail9f7f1f.ts.net/release。末尾斜杠会被去掉;非 http(s) 地址返回错误。
| 选项 | 作用 |
|---|---|
WithTrustedKeys(keys ...ed25519.PublicKey) |
固定签名公钥。设置后,SDK 交出的每个 manifest 都已验签。强烈建议。 不设置则只校验清单格式和包的 SHA-256,只能防损坏,防不了被冒充的服务端。可传多个,用于密钥轮换期间。 |
WithToken(token) |
写操作(发布、promote、yank、管理)用的 Bearer token。纯更新检查的应用不要带 token。 |
WithHTTPClient(h) |
自定义 http.Client(代理、TLS 根证书、Transport)。不要设置 Client.Timeout:下载和长轮询的耗时不固定,用 context 控制超时。 |
WithUserAgent(ua) |
设置 User-Agent,默认 relclient/1,建议填「应用名/版本」,便于看日志。 |
WithFallbackURLs(urls ...string) |
备用服务器(持有同样的发布、用同一把密钥签名,见 CONTAINER.md 的高可用一节)。读请求连不上、或遇到 5xx / 429 时换下一台;4xx 是最终答案,不换;写请求永远只发给主地址。有备用地址时默认 HTTP 客户端的连接超时是 5 秒。 |
WithFailbackAfter(d) |
切到备用地址后多久再试主地址,默认 5 分钟。 |
WithRetryPause(initial, max) |
WatchLoop 网络出错后的重试间隔:从 initial 起翻倍到 max,默认 1 秒到 1 分钟。 |
辅助函数:
relclient.ParseTrustedKeys(b64 ...string) ([]ed25519.PublicKey, error):把 base64 文本公钥解码成 SDK 要的格式。c.BaseURL():返回规范化后的主服务地址。c.ActiveURL():下一次读请求最先访问的服务器:主地址,或上次应答的备用地址。
c, _ := relclient.New("https://tony-ai-pc-1.tail9f7f1f.ts.net/release",
relclient.WithFallbackURLs("https://egg.tail9f7f1f.ts.net/release"),
relclient.WithTrustedKeys(pinned...)) // 公钥只钉一把:两台服务器用同一把密钥
怎么拿到公钥
relhub keys
# KEY ID ACTIVE PUBLIC KEY (base64 Ed25519)
# f5faa9f9858b789f true k4thZR+OVYSGAT/9j5F39csgGqTL0t3X6GYdNCmuRI8=
本机这个实例的公钥就是上面这一行。把它写进应用的代码或配置里。不要在运行时从同一台服务器取公钥(GET /v1/info 能取到,但那样等于没验证)。
5. 检查更新 Check
func (c *Client) Check(ctx context.Context, t Target, have int64) (*relproto.CheckResult, error)
have 是当前已安装版本的 versionCode,未知时传 0。返回的 CheckResult:
| 字段 | 含义 |
|---|---|
UpdateAvailable |
渠道提供的版本比 have 新(本地重算)。 |
Mandatory |
必须更新:UpdateAvailable 且渠道的 minVersionCode > have(本地重算)。 |
Manifest |
已验签的清单:VersionCode、VersionName、File、Size、SHA256、MinVersionCode、Notes、PublishedAt、KeyID。 |
CurrentVersionCode |
即你传入的 have。 |
DownloadPath |
相对下载路径;Download 内部自己推导,一般不用。 |
要点:
- 即使没有更新(
UpdateAvailable == false),Manifest也在,可以用来显示「当前最新是 x.y.z」。 - 服务端会按「已安装版本」统计每次检查,所以每次启动检查一次就能在
relhub stats里看到各版本的分布。 - 渠道上还没有发布过任何版本、或应用不存在,返回
not_found。
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
u, err := c.Check(ctx, relclient.Target{App: "nightdesk", Platform: "android"}, installed)
var apiErr *relproto.Error
switch {
case errors.As(err, &apiErr) && apiErr.Code == relproto.CodeNotFound:
// 还没发布过
case err != nil:
// 离线、服务不可用、验签失败……不要打断用户,记录日志,下次再查
case !u.UpdateAvailable:
// 已是最新
case u.Mandatory:
// 强制更新:阻塞界面,必须更新后才能继续使用
default:
// 可选更新:展示 u.Manifest.Notes,让用户决定
}
建议:检查更新是「尽力而为」,失败不要弹错误给用户;只有 Mandatory 时才需要持续重试。
6. 下载 Download
func (c *Client) Download(ctx context.Context, m relproto.Manifest, dest string, opt *DownloadOptions) error
把 manifest 描述的安装包下载到 dest。行为:
- 先校验 manifest(格式,以及设置了公钥时的签名)。
- 如果
dest已经存在且大小、SHA-256 都与 manifest 一致,什么也不做直接成功(会调一次Progress(size, size))。 - 下载到
dest + ".part"。若上次中断留下了.part,用Range+If-Range: "<sha256>"续传;如果这期间服务端文件换了,会从头下载,不会把两个不同的构建拼在一起。 - 下载完成后检查大小和 SHA-256;通过才
rename到dest。因此dest要么不存在/是旧文件,要么是完整且已校验的新包,不会出现半个文件。 - 校验失败:删除
.part,返回relclient.ErrChecksum(可用errors.Is判断)。
DownloadOptions(可传 nil):
| 字段 | 含义 |
|---|---|
Progress func(done, total int64) |
每收到一块数据回调一次:磁盘上已有的字节数和总大小。续传时 done 从非 0 开始。回调里不要做耗时操作。 |
Retries int |
遇到网络错误、5xx、429 时,从断点自动重试的次数。0 表示默认 3 次,负数表示不重试。 |
RetryWait time.Duration |
第一次重试前的等待,之后每次翻倍,默认 1 秒。 |
注意:
- 4xx(例如包已被撤回返回的 404)不会重试,直接返回错误。
dest所在目录必须已存在且可写,SDK 不会帮你创建目录。- 不要对同一个
dest并发调用Download。 .part在失败后会保留,下一次调用自动续传;想放弃就自己删掉它。- 可以随时用
ctx取消,取消后.part保留。
err := c.Download(ctx, *u.Manifest, filepath.Join(os.TempDir(), "update.zip"), &relclient.DownloadOptions{
Progress: func(done, total int64) { bar.Set(float64(done) / float64(total)) },
})
switch {
case errors.Is(err, relclient.ErrChecksum):
// 包与签名清单不符,已丢弃;可以提示「下载文件损坏」,也可以重新 Check 后重试
case err != nil:
// 网络问题等;.part 保留,稍后重试会续传
}
7. 等待新版本 Watch / WatchLoop
长轮询:服务端把请求挂住,一发布新版本就立刻返回,不需要客户端定时轮询。适合常驻后台的程序(托盘应用、常驻服务)。
func (c *Client) Watch(ctx context.Context, t Target, have int64, wait time.Duration) (*relproto.CheckResult, error)
- 有比
have更新的版本:立即返回(已验签,字段同Check)。 - 等满
wait(最长 50 秒,0表示取最大值)仍没有:返回nil, nil,请再调用一次。每次返回后服务端不保留连接。 - 渠道上还没有发布过任何版本时,不报错,继续等;应用不存在则返回
not_found。 - 服务端同时最多挂 64 个等待者,超出返回
unavailable(WatchLoop会自动退避重试)。
func (c *Client) WatchLoop(ctx context.Context, t Target, have int64, fn func(*relproto.CheckResult) error) error
循环调用 Watch,每出现一个更新的版本就调一次 fn,然后把基准版本推进到该版本继续等。
- 网络错误、
unavailable:按WithRetryPause退避后自动重试。 - 协议错误(应用不存在、验签失败等):结束循环并返回该错误。
fn返回非 nil 错误:结束循环并原样返回这个错误。ctx取消:返回ctx.Err()。
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
err := c.WatchLoop(ctx, relclient.Target{App: "nightdesk", Platform: "win-x64"}, installed,
func(u *relproto.CheckResult) error {
notifyUser(u.Manifest.VersionName, u.Mandatory) // 弹出「有新版本」
return nil // 继续等下一个;返回错误则退出循环
})
只想等一次的写法(例子里用一个哨兵错误跳出循环)见 examples/selfupdate 的 nextRelease。
反向代理的空闲超时通常是 60 秒,所以服务端把等待上限定为 50 秒,
WatchLoop每次请求 45 秒。
8. 查询
func (c *Client) Info(ctx) (relproto.Info, error) // 服务名、API 版本、公钥列表
func (c *Client) Latest(ctx, t Target) (*relproto.Manifest, error) // 渠道当前版本的已验签清单(不计入「检查」统计)
func (c *Client) Apps(ctx) ([]relproto.App, error) // 所有应用及各平台各渠道的当前版本
func (c *Client) App(ctx, id string) (relproto.App, error)
func (c *Client) Releases(ctx, app, platform string, limit int, before int64, includeYanked bool) (list []relproto.Release, next int64, err error)
Releases 按 versionCode 倒序分页,next != 0 时把它作为下一页的 before:
var before int64
for {
list, next, err := c.Releases(ctx, "nightdesk", "android", 50, before, false)
if err != nil {
return err
}
for _, r := range list {
fmt.Println(r.VersionCode, r.VersionName, r.Size)
}
if next == 0 {
break
}
before = next
}
Info返回的公钥只取决于网络连接是否可信,不能用来代替内置的固定公钥。
9. 发布 Publish
需要 token:管理员 token,或者限定到该应用的 token(relhub token create -app nightdesk,CI 推荐用后者)。
func (c *Client) Publish(ctx context.Context, req PublishRequest) (*relproto.PublishResult, error)
c, _ := relclient.New(baseURL, relclient.WithToken(os.Getenv("RELHUB_TOKEN")))
res, err := c.Publish(ctx, relclient.PublishRequest{
App: "nightdesk",
Platform: "android",
VersionCode: 11,
VersionName: "1.4.0",
Notes: "修复鼠标问题",
Path: "app-release.apk",
Progress: func(sent int64) { fmt.Printf("\r已上传 %d 字节", sent) },
})
PublishRequest 字段:
| 字段 | 含义 |
|---|---|
App、Platform |
必填。应用必须已创建(relhub app create)。 |
VersionCode |
必填,必须大于该 platform 上已有的最大 versionCode,否则 conflict(即使不上线到任何渠道也一样)。 |
VersionName |
必填,展示用,如 1.4.0。 |
Notes |
更新说明,最长 8192 字节。 |
Channel |
发布到哪个渠道,空表示 stable。渠道不存在会自动创建。 |
NoChannel |
true:只上传,不上线到任何渠道(之后用 Promote 上线)。 |
MinVersionCode |
大于 0:同时把渠道的强制更新下限设为该值(低于它的客户端必须更新)。必须不大于本次的 VersionCode。 |
Force |
true:把本次发布设为下限,等价于 MinVersionCode = VersionCode。 |
Path |
安装包路径。SDK 先算 SHA-256 并随请求发送,服务端收完后核对,不一致则拒绝。 |
File + FileName |
不是磁盘文件时的替代(例如内存流、管道)。没有 FileName 时记为 package.bin。 |
StoredName |
在服务端保存和下载时使用的文件名,默认就是上传的文件名。需匹配 ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$。 |
SHA256 |
期望的摘要(小写十六进制);用 Path 时留空即可自动计算。 |
Progress |
已发送的字节数回调。 |
SkipPreflight |
关闭上传前的预检(见下)。 |
行为:
- 流式上传,包不会整个读进内存,几个 GB 也行(受服务端
-max-size限制,本机默认 2 GiB,超了返回too_large)。 - 预检:上传前先做几个很小的请求(确认 token 能操作该应用、versionCode 是否已被占用),把「token 错、应用不存在、版本号没递增」这类问题在传输前就报出来,而不是传到一半被服务端掐断变成含糊的「连接被重置」。同时请求头带
Expect: 100-continue。 - 返回的
res.Release是入库的记录,res.Manifest是已签名清单(NoChannel时为nil);设置了公钥时会验签。 - 发布是原子的:上传先写入临时目录,完整、校验通过才出现;失败不会留下半成品。
- 已发布的 release 不可修改。发错了:
Yank撤回,再发一个更高 versionCode 的修复版。
其他例子:
// 灰度:先发 beta,验证后再把 stable 指过去(只移动指针,不复制文件)
c.Publish(ctx, relclient.PublishRequest{App: "nightdesk", Platform: "win-x64",
VersionCode: 10700, VersionName: "1.7.0-rc1", Channel: "beta", Path: "nightdesk.zip"})
m, err := c.Promote(ctx, relproto.PromoteParams{App: "nightdesk", Platform: "win-x64",
Channel: "stable", VersionCode: 10700})
// 强制更新:低于 10700 的客户端都必须升级
c.Publish(ctx, relclient.PublishRequest{App: "nightdesk", Platform: "win-x64",
VersionCode: 10700, VersionName: "1.7.0", Path: "nightdesk.zip", Force: true})
10. 管理接口
| 方法 | 作用 | 需要的 token |
|---|---|---|
CreateApp(ctx, relproto.CreateAppParams{ID, Name, Description}) |
创建应用 | 管理员 |
UpdateApp(ctx, relproto.UpdateAppParams{App, Name *string, Description *string}) |
改名称/描述(nil 字段不变) | 管理员 |
Promote(ctx, relproto.PromoteParams{App, Platform, Channel, VersionCode, MinVersionCode *int64, Force}) |
让渠道指向某个已有 release;指向更低的版本即为回退。若下限高于新版本会被自动降到新版本 | 应用或管理员 |
SetMin(ctx, relproto.SetMinParams{App, Platform, Channel, MinVersionCode}) |
修改强制更新下限(0 表示取消) | 应用或管理员 |
Yank(ctx, relproto.YankParams{App, Platform, VersionCode, Reason}) |
撤回 release:之后不能被渠道提供,也不能下载。若某渠道正在提供它,返回 conflict,需先 Promote 到别的版本 |
应用或管理员 |
Unyank(ctx, relproto.YankParams{...}) |
恢复被撤回的 release | 应用或管理员 |
Stats(ctx, app string) |
下载次数、各已安装版本的检查次数;app 为空表示所有应用 |
带 app 时为应用或管理员;不带为管理员 |
CreateToken(ctx, relproto.CreateTokenParams{Name, Apps []string, Admin bool}) |
签发 token,明文只在返回值里出现一次 | 管理员 |
Tokens(ctx) / RevokeToken(ctx, id) |
列出 / 吊销 token | 管理员 |
回滚的完整例子(线上 10700 有严重问题,退回 10601 并撤回 10700):
if _, err := c.Promote(ctx, relproto.PromoteParams{App: "nightdesk", Platform: "win-x64", Channel: "stable", VersionCode: 10601}); err != nil {
return err
}
_, err := c.Yank(ctx, relproto.YankParams{App: "nightdesk", Platform: "win-x64", VersionCode: 10700, Reason: "启动崩溃"})
已经升级到 10700 的客户端不会被降级:回滚只影响「之后检查更新」的客户端。要让这些客户端换到修复版,需要发布一个 versionCode 更高的新版本。
11. JSON-RPC Call
REST 能做的操作,JSON-RPC(POST /v1/rpc)都能做。Call 是通用入口:
func (c *Client) Call(ctx context.Context, method string, params, result any) error
var res relproto.CheckResult
err := c.Call(ctx, "update.check", relproto.CheckParams{App: "nightdesk", Platform: "android", VersionCode: 8}, &res)
// 列出所有方法、鉴权级别和参数类型
var methods []relproto.MethodInfo
err = c.Call(ctx, "rpc.discover", nil, &methods)
- 失败时返回
*relproto.Error,Code与 REST 一致(来自 JSON-RPC 的error.data.code)。 params必须是 JSON 对象(struct 或 map);没有参数传nil。Call返回的是服务端原话,不验签、不重算UpdateAvailable。 更新流程请用Check/Watch/Latest/Download。- 一次只发一个调用;批量和 notification 请直接 POST(见 REST-API)。
- 不能用来上传安装包:RPC 请求体上限 1 MiB,包只能走
Publish(REST)。
12. 错误处理
SDK 返回的服务端错误都是 *relproto.Error{Code, Message};error.Error() 形如 conflict: versionCode 11 is not higher than the published 11。
var apiErr *relproto.Error
if errors.As(err, &apiErr) {
switch apiErr.Code {
case relproto.CodeNotFound: // 应用、平台、渠道或版本不存在;还没有发布
case relproto.CodeUnauthorized: // 没带 token 或 token 无效
case relproto.CodeForbidden: // token 无权操作这个应用 / 需要管理员
case relproto.CodeConflict: // versionCode 没递增;撤回了仍被渠道提供的版本
case relproto.CodeTooLarge: // 超过服务端 -max-size
case relproto.CodeUnavailable: // 等待者过多、包文件缺失、反向代理 502/503/504
case relproto.CodeInvalid: // 参数不合法;验签失败也是这个 code
}
}
| code | HTTP | 常见原因 |
|---|---|---|
invalid_argument |
400 | 参数不合法;签名不是来自受信任的公钥;manifest 不是你请求的 app/platform/channel |
unauthorized |
401 | 缺少或无效的 token |
forbidden |
403 | token 不能操作这个应用,或该操作需要管理员 |
app_delisted |
403 | 应用已被管理员下架;匿名的检查、下载都会被拒(按字符串 "app_delisted" 判断,见 错误码) |
not_found |
404 | 应用/平台/渠道/版本不存在,或还没发布 |
conflict |
409 | versionCode 没有比已发布的更大;撤回仍在被渠道提供的版本 |
too_large |
413 | 安装包超过服务端限制 |
unavailable |
503 | 太多客户端在等待;服务端暂时不可用(含代理返回的 502/504) |
internal |
500 | 服务端错误 |
其他你可能遇到的错误:
relclient.ErrChecksum:下载的包与 manifest 的大小/SHA-256 不符(errors.Is判断)。context.Canceled/context.DeadlineExceeded:你自己的ctx结束了。- 网络错误(
*url.Error、net.Error、io.ErrUnexpectedEOF):Download和WatchLoop会自动重试,Check等单次调用不会,由你决定是否重试。
注意:relproto.AsError(nil) 返回 nil,不要直接写 relproto.AsError(err).Code,先判断 err != nil,或者像上面那样用 errors.As。
13. 集成方案
13.1 Windows 桌面应用(Go)
推荐流程:启动后在后台常驻 WatchLoop(或每隔数小时 Check 一次);有更新时下载到临时目录,用户确认(强制更新则直接)后替换并重启。下面是片段,pinnedKey、releaseURL、versionName、offerRestart 是你的应用自己的常量和函数:
func startUpdater(ctx context.Context, installed int64) {
keys, _ := relclient.ParseTrustedKeys(pinnedKey)
c, _ := relclient.New(releaseURL, relclient.WithTrustedKeys(keys...), relclient.WithUserAgent("nightdesk/"+versionName))
t := relclient.Target{App: "nightdesk", Platform: "win-x64"}
go func() {
err := c.WatchLoop(ctx, t, installed, func(u *relproto.CheckResult) error {
zip := filepath.Join(os.TempDir(), u.Manifest.File)
if err := c.Download(ctx, *u.Manifest, zip, nil); err != nil {
return nil // 这次失败,保留 .part,下一个版本或重启后再试
}
offerRestart(zip, u.Manifest.VersionName, u.Mandatory)
return nil
})
log.Printf("updater stopped: %v", err)
}()
}
替换自身文件的通用做法(此段为通用做法的示意,未在 Windows 实机验证):运行中的 app.exe 不能被删除或覆盖,但可以被改名。所以先把正在运行的 app.exe 改名为 app.exe.old,把新版本的文件放到位,再启动新进程并退出旧进程;下次启动时清理 *.old。下载到的 zip 应先解压到临时目录并整体就位,避免半更新。
13.2 强制更新的界面处理
u.Mandatory == true 时:
- 展示「必须更新」界面,不允许进入主功能。
- 下载失败不要让用户困在无出口的界面:显示重试按钮和错误原因,
Download会自动续传。 - 离线时
Check会失败,此时是否放行由你的产品决定。SDK 无法知道「这个客户端是否已经过期」,因为强制更新信息只来自服务端。
13.3 Android
- Go 核心(gomobile/静态库)的应用:直接用
relclient,SDK 已验证可为android/arm64交叉编译(CGO_ENABLED=0)。把下载好的 APK 交给 Kotlin 层,用PackageInstaller安装。 - 纯 Kotlin 应用:按 REST-API 的协议实现:
GET v1/apps/{app}/check、验签(需要一个 Ed25519 实现,使用前在你支持的最低 Android 版本上验证平台是否自带,否则引入库)、带Range的下载、校验 SHA-256,再交给PackageInstaller。 - Android 的
versionCode必须等于 APK 里的versionCode,否则「检查更新」会拿服务端的号和本机的号比出错误的结果。系统安装器还会强制要求新旧 APK 的签名证书一致,这是对服务器之外的另一层保护。
13.4 命令行工具 / 后台服务
和桌面应用类似。若只是想在脚本里判断,可以直接用 CLI:
relhub check -url https://tony-ai-pc-1.tail9f7f1f.ts.net/release -keys <公钥> -app nightdesk -platform linux-arm64 -code 10601
echo $? # 0 已是最新,10 有可选更新,20 有强制更新
relhub download -url ... -keys <公钥> -app nightdesk -platform linux-arm64 -out nightdesk.tar.gz
13.5 CI 自动发布
// ci-publish:在流水线最后一步运行
c, _ := relclient.New(os.Getenv("RELHUB_URL"), relclient.WithToken(os.Getenv("RELHUB_TOKEN")))
res, err := c.Publish(ctx, relclient.PublishRequest{
App: "nightdesk", Platform: "win-x64",
VersionCode: buildNumber, VersionName: version, Notes: changelog, Path: "dist/nightdesk.zip",
})
给 CI 单独签发只能操作该应用的 token(relhub token create -name ci -app nightdesk),不要把管理员 token 放进 CI。不想写 Go 的话,一条 curl 同样可以发布,见 CI 自动发布。
14. 测试你的集成
不要对线上实例做测试发布:发布不可修改,versionCode 也只能递增,测试数据删不掉。用一个一次性的本地实例,数据放在临时目录,端口选一个空闲的回环端口:
W=$(mktemp -d); PORT=18999
relhub serve -addr 127.0.0.1:$PORT -data $W/data & # 临时实例有自己的密钥,和线上实例互不相干
export RELHUB_URL=http://127.0.0.1:$PORT RELHUB_DATA=$W/data
KEY=$(relhub keys | awk 'NR==2{print $3}') # 这个临时实例的公钥
relhub app create -id demo -name Demo
relhub publish -app demo -platform win-x64 -file demo-1.0.0.zip -version 1.0.0
relhub publish -app demo -platform win-x64 -file demo-1.1.0.zip -version 1.1.0
# 让你的应用指向 $RELHUB_URL,并把 $KEY 作为固定公钥,就能完整走一遍检查 → 下载 → 验证。
# 也可以直接试参考实现:
go run ./examples/selfupdate -url $RELHUB_URL -keys $KEY -app demo -platform win-x64 -code 10000 -out $W/u.zip
kill %1; rm -rf $W
仓库自带的测试同样可以参考:
pkg/relclient/client_test.go:用httptest起真实的服务端处理器,覆盖检查、续传、验签失败、watch、发布。scripts/e2e.sh:用真实二进制、临时目录、随机回环端口,把「建应用 → 发布 → 检查 → 下载 → watch → 渠道 → 撤回 → 鉴权」整条链路跑一遍。
15. 排障
| 现象 | 原因与处理 |
|---|---|
invalid_argument: signature is not from a trusted release key |
内置的公钥与服务端当前/历史密钥都对不上。确认用的是 relhub keys 里的公钥;若做过密钥轮换,应用里要同时带新旧公钥(见 USAGE.md)。 |
not_found |
应用 id、platform 或 channel 拼写不对;或还没发布过。用 relhub list -app <id> 看实际有什么。 |
所有请求都 not_found,连 Info 都失败 |
baseURL 写错了。应是 https://tony-ai-pc-1.tail9f7f1f.ts.net/release,末尾不要带 /v1,也不要少了 /release。 |
conflict: versionCode N is not higher than the published M |
发布时 versionCode 必须大于该平台已有的最大值(包括已撤回的)。 |
发布时 unauthorized / forbidden |
token 缺失、已吊销,或是限定了别的应用的 token。 |
发布大文件失败,提示 too_large |
超过服务端 -max-size(本机默认 2G)。需要调大 ~/.config/release-publish/env 里的 RELHUB_MAX_SIZE 后重启服务。 |
Download 报 ErrChecksum |
包与签名清单不符,可能是传输损坏或服务端文件被动过;relhub verify 可在服务端离线检查数据目录。 |
unavailable |
等待者超过 64、反向代理 502/503/504,或服务暂时不可用。WatchLoop 会自动退避重试。 |
Check 在浏览器能通,在应用里很慢/超时 |
不要给 http.Client 设置 Timeout(会掐断下载和长轮询);用 context.WithTimeout 控制单次调用。 |
| 更新提示反复出现 | 传给 Check 的 have 不是当前真实安装版本的 versionCode(例如写死了常量)。 |
16. API 速查
// 创建
func New(baseURL string, opts ...Option) (*Client, error)
func ParseTrustedKeys(b64 ...string) ([]ed25519.PublicKey, error)
func WithTrustedKeys(keys ...ed25519.PublicKey) Option
func WithToken(token string) Option
func WithHTTPClient(h *http.Client) Option
func WithUserAgent(ua string) Option
func WithRetryPause(initial, max time.Duration) Option
func (c *Client) BaseURL() string
type Target struct{ App, Platform, Channel string } // Channel 为空即 stable
// 读(无需 token)
func (c *Client) Info(ctx) (relproto.Info, error)
func (c *Client) Check(ctx, t Target, have int64) (*relproto.CheckResult, error)
func (c *Client) Watch(ctx, t Target, have int64, wait time.Duration) (*relproto.CheckResult, error) // 超时返回 nil, nil
func (c *Client) WatchLoop(ctx, t Target, have int64, fn func(*relproto.CheckResult) error) error
func (c *Client) Latest(ctx, t Target) (*relproto.Manifest, error)
func (c *Client) Apps(ctx) ([]relproto.App, error)
func (c *Client) App(ctx, id string) (relproto.App, error)
func (c *Client) Releases(ctx, app, platform string, limit int, before int64, includeYanked bool) ([]relproto.Release, int64, error)
func (c *Client) Download(ctx, m relproto.Manifest, dest string, opt *DownloadOptions) error
// 写(需要 token)
func (c *Client) Publish(ctx, req PublishRequest) (*relproto.PublishResult, error)
func (c *Client) CreateApp / UpdateApp / Promote / SetMin / Yank / Unyank / Stats
func (c *Client) CreateToken / Tokens / RevokeToken
// 通用
func (c *Client) Call(ctx, method string, params, result any) error
var ErrChecksum error
relproto 常用:
relproto.DefaultChannel // "stable"
relproto.VersionCodeFromName("1.6.1") // 10601 = major*10000 + minor*100 + patch
relproto.ValidAppID / ValidPlatform / ValidChannel
(*relproto.Manifest).Verify(keys) / Mandatory(have) / DownloadPath()
relproto.Error / AsError / CodeNotFound ... // 见第 12 节
可运行、已通过编译检查的示例见 pkg/relclient/example_test.go(go doc relhub/pkg/relclient 或 go test -run Example ./pkg/relclient)以及 examples/selfupdate。