release-publish

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 页的协议自行接入。

目录

  1. 五分钟上手
  2. 把 SDK 引入你的项目
  3. 必须先懂的五个概念
  4. 创建客户端
  5. 检查更新 Check
  6. 下载 Download
  7. 等待新版本 Watch / WatchLoop
  8. 查询
  9. 发布 Publish
  10. 管理接口
  11. JSON-RPC Call
  12. 错误处理
  13. 集成方案
  14. 测试你的集成
  15. 排障
  16. 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。行为:

  1. 先校验 manifest(格式,以及设置了公钥时的签名)。
  2. 如果 dest 已经存在且大小、SHA-256 都与 manifest 一致,什么也不做直接成功(会调一次 Progress(size, size))。
  3. 下载到 dest + ".part"。若上次中断留下了 .part,用 Range + If-Range: "<sha256>" 续传;如果这期间服务端文件换了,会从头下载,不会把两个不同的构建拼在一起。
  4. 下载完成后检查大小和 SHA-256;通过才 rename 到 dest。因此 dest 要么不存在/是旧文件,要么是完整且已校验的新包,不会出现半个文件。
  5. 校验失败:删除 .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 时:

  1. 展示「必须更新」界面,不允许进入主功能。
  2. 下载失败不要让用户困在无出口的界面:显示重试按钮和错误原因,Download 会自动续传。
  3. 离线时 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。