C# SDK 使用文档(Relhub.Client)
Relhub.Client 是 release-publish 的 C# 客户端:让 .NET 应用(WPF、WinForms、Avalonia、控制台、后台服务)用几行代码接入「检查更新 → 下载 → 校验」,也让 CI 和工具用同一个包发布、管理发行版本。它和 Go SDK 功能对等、行为一致。
- 零依赖:只用 .NET 基础类库(
System.Net.Http、System.Text.Json、System.Numerics、System.Security.Cryptography)。.nupkg里没有任何包依赖。 - 自带 Ed25519 验签:.NET 基础类库没有 Ed25519,所以 SDK 内置了一个只做验签的托管实现。它用 Go 标准库(也就是服务端签名所用的实现)生成的测试向量验证过,实测约 6 ms 一次。
- 目标框架
net8.0和net10.0(同一份.nupkg含两套)。 RelhubClient线程安全,一个进程里建一个、到处共用即可。- 源码在
sdk/csharp/。协议细节见 REST-API,服务端运维见 USAGE.md。
目录
- 五分钟上手
- 把 SDK 引入你的项目
- 必须先懂的概念
- 创建客户端
- 检查更新
CheckAsync - 下载
DownloadAsync - 等待新版本
WatchAsync/WatchLoopAsync - 查询
- 发布
PublishAsync - 管理接口
- JSON-RPC
CallAsync - 错误处理
- 集成方案
- 测试与验证
- 排障
- API 速查与 Go 对照
- 实现说明与限制
1. 五分钟上手
一个完整的「检查并下载更新」程序已放在仓库里并实测通过:sdk/csharp/samples/SelfUpdate。核心就这些:
using System;
using Relhub;
// 发行服务的公钥(relhub keys 可查看),编译进应用。
const string PinnedKey = "k4thZR+OVYSGAT/9j5F39csgGqTL0t3X6GYdNCmuRI8=";
using var client = new RelhubClient(
"https://tony-ai-pc-1.tail9f7f1f.ts.net/release",
new RelhubClientOptions().TrustKey(PinnedKey));
const long installed = 10601; // 当前运行版本的 versionCode
var update = await client.CheckAsync(new Target("nightdesk", "win-x64"), installed);
if (!update.UpdateAvailable)
{
Console.WriteLine("已是最新");
return;
}
Console.WriteLine($"新版本 {update.Manifest!.VersionName},强制更新: {update.Mandatory}");
// 续传、校验大小和 SHA-256,通过后才改名到位。
await client.DownloadAsync(update.Manifest, "update.zip");
命令行直接试用参考实现(把 <公钥> 换成 relhub keys 输出的那一行):
dotnet run --project sdk/csharp/samples/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 引入你的项目
三种方式,前两种都已在本仓库的 test.sh 里实测。
方式 A:ProjectReference 指向源码(同一台机器开发)
在你的应用的 .csproj 里:
<ItemGroup>
<ProjectReference Include="/home/tony/dev/release-publish/sdk/csharp/src/Relhub.Client/Relhub.Client.csproj" />
</ItemGroup>
Windows 上的路径按实际位置写(可以用相对路径)。应用的目标框架是 net8.0、net10.0 或它们的 -windows 变体都能引用,例如 NightDesk 的 net10.0-windows。
方式 B:本地 NuGet 源(CI 或别的机器构建)
dotnet pack sdk/csharp/src/Relhub.Client -c Release -o ./nupkgs # 产出 Relhub.Client.1.0.0.nupkg
把 ./nupkgs 当作一个文件夹源,在你的应用旁放一个 nuget.config:
<configuration>
<packageSources>
<add key="local" value="./nupkgs" />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
</configuration>
<ItemGroup>
<PackageReference Include="Relhub.Client" Version="1.0.0" />
</ItemGroup>
升级 SDK 时改 Version(在 Relhub.Client.csproj 里改 <Version>)并重新 dotnet pack。
方式 C:直接复制源码
把 sdk/csharp/src/Relhub.Client/*.cs 复制进你的项目即可(文件之间只互相引用,没有外部依赖)。需要 C# 10 以上(我用 C# 10、11、12 和最新版都编译通过了),建议开启 <Nullable>enable</Nullable>。适合只有一个小项目、不想碰 NuGet 的情况。升级时手动同步。
公开的类型都在命名空间
Relhub下:RelhubClient、RelhubClientOptions、Target、Manifest、CheckResult、DownloadOptions、PublishRequest、RelhubException、ChecksumException、ErrorCodes、RelhubKeys、Identifiers等。
3. 必须先懂的概念
| 概念 | 一句话 |
|---|---|
| Target | 要更新什么:App(应用 id)+ Platform(android、win-x64…)+ Channel(默认 stable)。 |
| versionCode | 整数版本号,越大越新,每个 platform 内严格递增。检查更新时传「当前安装版本」的 versionCode。versionName(如 1.6.1)只用于展示。 |
| channel | 渠道。stable 是默认;可以有 beta 等。渠道只是指向某个 release 的指针,外加一个强制更新下限 minVersionCode。 |
| manifest | 服务端对「某渠道当前提供什么」的签名描述(应用、平台、渠道、版本、文件名、大小、SHA-256、下限、说明的哈希)。 |
| 公钥固定 | 把服务端的 Ed25519 公钥编译进应用,用 RelhubClientOptions.TrustKey 传给 SDK。这样即使服务端或网络被冒充,伪造的清单也过不了验签。 |
SDK 的安全约定(和 Go SDK 完全一致):
- 响应里的
updateAvailable、mandatory没有签名,SDK 不采信,而是用签名过的 manifest 在本地重新计算:UpdateAvailable = manifest.VersionCode > 已安装,Mandatory = UpdateAvailable && manifest.MinVersionCode > 已安装。 - SDK 会核对 manifest 里的 app/platform/channel 与你请求的一致,防止拿别的应用的合法签名来冒充。
- 下载 URL 一律用「你配置的 base URL + manifest 推出的路径」,不使用服务端发来的任意 URL。
怎么得到「当前安装版本的 versionCode」
在 Windows 等非 Android 平台,发布时只写版本名(relhub publish -version 1.6.1,不写 -code),服务端会按 主×10000 + 次×100 + 补丁 推导 versionCode。应用端用同一个规则从自己的程序集版本算出来:
var v = System.Reflection.Assembly.GetEntryAssembly()!.GetName().Version!;
long installed = Identifiers.VersionCodeFromName($"{v.Major}.{v.Minor}.{v.Build}"); // 1.6.1.0 -> 10601
NightDesk 的 <Version>1.3.1</Version> 就会得到 10301。版本号的次版本和补丁都必须小于 100。
4. 创建客户端
var options = new RelhubClientOptions { UserAgent = "NightDesk/1.3.1" }.TrustKey(PinnedKey);
using var client = new RelhubClient("https://tony-ai-pc-1.tail9f7f1f.ts.net/release", options);
baseUrl 是服务地址加上反向代理的路径前缀;末尾斜杠会被去掉;不是 http(s) 的绝对地址抛 ArgumentException。
RelhubClientOptions 属性 |
作用 |
|---|---|
TrustKey(string base64) / TrustedKeys |
固定签名公钥。设置后,SDK 交出的每个 manifest 都已验签。强烈建议。 不设置则只校验清单格式和包的 SHA-256,只能防损坏,防不了被冒充的服务端。可固定多个,用于密钥轮换期间。 |
Token |
写操作(发布、promote、yank、管理)用的 Bearer token。纯更新检查的应用不要带 token。 |
HttpClient |
自定义 HttpClient(代理、TLS、IHttpClientFactory)。SDK 不会 Dispose 它。见下面的超时说明。 |
UserAgent |
默认 relhub-csharp/1,建议填「应用名/版本」,便于看服务端日志。 |
RetryPauseMin / RetryPauseMax |
WatchLoopAsync 网络出错后的重试间隔:从 Min 起翻倍到 Max,默认 1 秒到 1 分钟。 |
辅助函数:
RelhubKeys.Parse(string base64):把文本公钥解码成 32 字节;格式不对抛FormatException。RelhubKeys.KeyId(byte[] publicKey):算出keyId(SHA-256 前 8 字节的十六进制),可与 manifest 的KeyId对照。client.BaseUrl:规范化后的服务地址。
怎么拿到公钥
relhub keys
# KEY ID ACTIVE PUBLIC KEY (base64 Ed25519)
# f5faa9f9858b789f true k4thZR+OVYSGAT/9j5F39csgGqTL0t3X6GYdNCmuRI8=
本机这个实例的公钥就是上面这一行。把它写进应用的代码里。不要在运行时从同一台服务器取公钥(GetInfoAsync() 能取到,但那样等于没验证)。
关于 HttpClient 与超时
- 不传
HttpClient时,SDK 自己创建一个,Timeout为无限:下载和长轮询的耗时不固定,靠各方法的CancellationToken控制。 - 传入你自己的
HttpClient(例如来自IHttpClientFactory,默认Timeout是 100 秒)时:SDK 的所有请求都用ResponseHeadersRead,此时Timeout只约束到「收到响应头」为止(我实测过:Timeout为 1 秒时,响应头立即返回、响应体花 2.5 秒读完,不会超时)。所以只要Timeout大于 50 秒(长轮询最长等 50 秒),检查、长轮询和任意大小的下载都不受影响;但发布会把整个上传算在内,大包上传请使用没有短超时的HttpClient。 - 在依赖注入里把
RelhubClient注册成单例即可(它线程安全)。
5. 检查更新 CheckAsync
Task<CheckResult> CheckAsync(Target target, long haveVersionCode, CancellationToken ct = default)
haveVersionCode 是当前已安装版本的 versionCode,未知时传 0。返回的 CheckResult:
| 属性 | 含义 |
|---|---|
UpdateAvailable |
渠道提供的版本比已安装的新(本地重算)。 |
Mandatory |
必须更新:UpdateAvailable 且渠道的 MinVersionCode > 已安装(本地重算)。 |
Manifest |
已验签的清单:VersionCode、VersionName、File、Size、Sha256、MinVersionCode、Notes、PublishedAt、KeyId。 |
CurrentVersionCode |
即你传入的值。 |
要点:
- 即使没有更新,
Manifest也在,可以用来显示「当前最新是 x.y.z」。 - 服务端会按「已安装版本」统计每次检查,所以每次启动检查一次就能在
relhub stats里看到各版本的分布。 - 渠道上还没有发布过任何版本、或应用不存在,抛
RelhubException(ErrorCodes.NotFound)。 CheckAsync不会自动重试;检查更新是「尽力而为」,失败就记录日志、下次再查,不要弹错误打断用户。只有Mandatory时才需要持续重试。
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));
try
{
var update = await client.CheckAsync(new Target("nightdesk", "android"), installed, cts.Token);
if (!update.UpdateAvailable)
{
return; // 已是最新
}
if (update.Mandatory)
{
// 强制更新:阻塞界面,必须更新后才能继续使用
}
else
{
// 可选更新:展示 update.Manifest.Notes,让用户决定
}
}
catch (RelhubException e) when (e.Code == ErrorCodes.NotFound)
{
// 还没发布过
}
catch (Exception e) when (e is RelhubException or HttpRequestException or OperationCanceledException)
{
// 离线、服务不可用、验签失败……记录日志,下次再查
}
6. 下载 DownloadAsync
Task DownloadAsync(Manifest manifest, string destination, DownloadOptions? options = null, CancellationToken ct = default)
把 manifest 描述的安装包下载到 destination。行为:
- 先校验 manifest(格式,以及设置了公钥时的签名),不通过就不发任何请求。
- 如果
destination已经存在且大小、SHA-256 都与 manifest 一致,什么也不做直接成功(会调一次Progress(size, size))。 - 下载到
destination + ".part"。若上次中断留下了.part,用Range+If-Range: "<sha256>"续传;如果这期间服务端文件换了,会从头下载,不会把两个不同的构建拼在一起。 - 下载完成后检查大小和 SHA-256;通过才改名到
destination(覆盖旧文件)。因此destination要么不存在/是旧文件,要么是完整且已校验的新包,不会出现半个文件。 - 校验失败:删除
.part,抛ChecksumException。
DownloadOptions(可不传):
| 属性 | 含义 |
|---|---|
Progress |
Action<long, long>:每收到一块数据回调一次(磁盘上已有的字节数, 总大小)。续传时从非 0 开始。 |
Retries |
遇到网络错误、5xx、429 时,从断点自动重试的次数。0 表示默认 3 次,负数表示不重试。 |
RetryWait |
第一次重试前的等待,之后每次翻倍,默认 1 秒。 |
注意:
Progress在线程池线程上执行,不是 UI 线程。 更新 UI 请自己切回去(WPF:Dispatcher.InvokeAsync;Avalonia:Dispatcher.UIThread.Post;或在 UI 线程创建Progress<T>后传入它的Report)。回调里不要做耗时操作。- 4xx(例如包已被撤回返回的 404)不会重试,抛
RelhubException。 destination所在目录必须已存在且可写。- 不要对同一个
destination并发调用。 - 失败或取消后
.part保留,下一次调用自动续传;想放弃就自己删掉它。
try
{
await client.DownloadAsync(manifest, Path.Combine(Path.GetTempPath(), manifest.File), new DownloadOptions
{
Progress = (done, total) => Console.Write($"\r{done * 100 / total,3}%"),
});
}
catch (ChecksumException)
{
// 包与签名清单不符,已丢弃;可以提示「下载文件损坏」,或重新 CheckAsync 后重试
}
catch (Exception e) when (e is HttpRequestException or IOException)
{
// 网络问题;.part 保留,稍后重试会续传
}
7. 等待新版本 WatchAsync / WatchLoopAsync
长轮询:服务端把请求挂住,一发布新版本就立刻返回,不需要客户端定时轮询。适合常驻后台的程序(托盘应用、后台服务)。
Task<CheckResult?> WatchAsync(Target target, long haveVersionCode, TimeSpan wait, CancellationToken ct = default)
- 有比已安装更新的版本:立即返回(已验签,字段同
CheckAsync)。 - 等满
wait(最长 50 秒,TimeSpan.Zero表示取最大值)仍没有:返回null,请再调用一次。 - 渠道上还没有发布过任何版本时,不报错,继续等;应用不存在则抛
NotFound。 - 服务端同时最多挂 64 个等待者,超出返回
unavailable。
IAsyncEnumerable<CheckResult> WatchLoopAsync(Target target, long haveVersionCode, CancellationToken ct = default)
循环调用 WatchAsync,每出现一个更新的版本就产出一项,并把基准版本推进到该版本继续等。用 await foreach 消费:
await foreach (var update in client.WatchLoopAsync(new Target("nightdesk", "win-x64", "beta"), installed, ct))
{
Console.WriteLine($"{update.Manifest!.VersionName} 刚发布(强制: {update.Mandatory})");
// break; 即可离开循环
}
- 网络错误、
unavailable:按RetryPauseMin/Max退避后自动重试,不会抛出。 - 协议错误(应用不存在、验签失败等):抛
RelhubException,循环结束。 - 取消
ct(或break):以OperationCanceledException结束,即使取消时恰好发生网络错误也是如此。
一个不依赖 UI 框架的后台更新器
文档里的所有代码都放在 DocumentationExamples.cs 里随库一起编译,下面这个更新器还对着真实服务端测试过(发布后触发事件、DisposeAsync 不用等长轮询结束):
public sealed class BackgroundUpdater : IAsyncDisposable
{
private readonly RelhubClient _client;
private readonly Target _target;
private readonly long _installed;
private readonly CancellationTokenSource _stop = new();
private Task _loop = Task.CompletedTask;
public BackgroundUpdater(string baseUrl, string publicKey, Target target, long installedVersionCode, string userAgent)
{
_client = new RelhubClient(baseUrl, new RelhubClientOptions { UserAgent = userAgent }.TrustKey(publicKey));
_target = target;
_installed = installedVersionCode;
}
public event Action<CheckResult>? UpdateFound; // 在线程池线程上触发
public event Action<RelhubException>? Failed; // 协议错误导致循环结束
public void Start() => _loop = Task.Run(RunAsync);
private async Task RunAsync()
{
try
{
await foreach (var update in _client.WatchLoopAsync(_target, _installed, _stop.Token))
{
UpdateFound?.Invoke(update);
}
}
catch (OperationCanceledException) { }
catch (RelhubException e) { Failed?.Invoke(e); }
}
public Task DownloadAsync(CheckResult update, string destination, Action<long, long>? progress = null, CancellationToken ct = default)
=> _client.DownloadAsync(update.Manifest!, destination, new DownloadOptions { Progress = progress }, ct);
public async ValueTask DisposeAsync()
{
_stop.Cancel();
await _loop.ConfigureAwait(false);
_stop.Dispose();
_client.Dispose();
}
}
8. 查询
Task<ServerInfo> GetInfoAsync(ct) // 服务名、API 版本、公钥列表
Task<Manifest> GetLatestAsync(Target, ct) // 渠道当前版本的已验签清单(不计入「检查」统计)
Task<IReadOnlyList<App>> GetAppsAsync(ct) // 所有应用及各平台各渠道的当前版本
Task<App> GetAppAsync(string app, ct)
Task<ReleasePage> ListReleasesAsync(string app, string platform, int limit = 0, long before = 0, bool includeYanked = false, ct)
ListReleasesAsync 按 versionCode 倒序分页,Next != 0 时把它作为下一页的 before:
long before = 0;
do
{
var page = await client.ListReleasesAsync("nightdesk", "android", limit: 50, before: before);
foreach (var r in page.Releases)
{
Console.WriteLine($"{r.VersionCode} {r.VersionName} {r.Size}");
}
before = page.Next;
} while (before != 0);
GetInfoAsync返回的公钥只取决于网络连接是否可信,不能用来代替内置的固定公钥。
9. 发布 PublishAsync
需要 token:管理员 token,或者限定到该应用的 token(relhub token create -app nightdesk,CI 推荐用后者)。
using var client = new RelhubClient(baseUrl, new RelhubClientOptions { Token = Environment.GetEnvironmentVariable("RELHUB_TOKEN") }.TrustKey(PinnedKey));
var result = await client.PublishAsync(new PublishRequest
{
App = "nightdesk",
Platform = "win-x64",
VersionCode = Identifiers.VersionCodeFromName("1.7.0"), // 10700
VersionName = "1.7.0",
Notes = "修复鼠标问题",
Path = "dist/nightdesk.zip",
Progress = sent => Console.Write($"\r已上传 {sent} 字节"),
});
PublishRequest 属性:
| 属性 | 含义 |
|---|---|
App、Platform |
必填。应用必须已创建(relhub app create)。 |
VersionCode |
必填,必须大于该 platform 上已有的最大 versionCode(包括已撤回的),否则 conflict。Android 必须等于 APK 的 versionCode。 |
VersionName |
必填,展示用。 |
Notes |
更新说明,最长 8192 字节(UTF-8)。 |
Channel |
发布到哪个渠道,空表示 stable。渠道不存在会自动创建。 |
NoChannel |
true:只上传,不上线到任何渠道(之后用 PromoteAsync 上线)。 |
MinVersionCode |
大于 0:同时把渠道的强制更新下限设为该值,必须不大于本次的 VersionCode。 |
Force |
true:把本次发布设为下限,等价于 MinVersionCode = VersionCode。 |
Path |
安装包路径。SDK 先算 SHA-256 并随请求发送,服务端收完后核对,不一致则拒绝。 |
Content + FileName |
不是磁盘文件时的替代(内存流、管道)。流读到结尾,不会被 Dispose。没有 FileName 时记为 package.bin。 |
StoredName |
在服务端保存和下载时使用的文件名,默认是上传的文件名。需匹配 ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$。 |
Sha256 |
期望的摘要(小写十六进制);用 Path 时留空即可自动计算。 |
Progress |
Action<long>:已发送的字节数。 |
SkipPreflight |
关闭上传前的预检。 |
行为:
- 流式上传,包不会整个读进内存(受服务端
-max-size限制,本机默认 2 GiB,超了返回too_large)。 - 预检:上传前先做几个很小的请求(确认 token 能操作该应用、versionCode 是否已被占用),把「token 错、应用不存在、版本号没递增」这类问题在传输前就报出来。同时请求头带
Expect: 100-continue,服务端拒绝时包体根本不会发出。 - 上传失败后会查明原因:如果服务端在上传中途拒绝并断开连接(客户端只会看到
Broken pipe之类),SDK 会再做一次预检;能查到明确原因(版本号已被占用、token 无效等)就抛对应的RelhubException,查不到才保留原始的网络异常。这条路径对着真实 Go 服务端测过(8 MB 的包、SkipPreflight = true)。 - 返回的
Release是入库的记录,Manifest是已签名清单(NoChannel时为null);设置了公钥时会验签。 - 发布是原子的,且不可修改。发错了:
YankAsync撤回,再发一个更高 versionCode 的修复版。 - 上传期间
HttpClient.Timeout会计入(见第 4 节)。
catch (RelhubException e) when (e.Code == ErrorCodes.Conflict)
{
// versionCode 没有比已发布的更大
}
catch (RelhubException e) when (e.Code is ErrorCodes.Unauthorized or ErrorCodes.Forbidden)
{
// token 缺失、已吊销,或没有权限操作这个应用
}
灰度与回滚:
// 先发 beta:stable 用户看不到
await admin.PublishAsync(new PublishRequest { App = "nightdesk", Platform = "win-x64", VersionCode = 10700, VersionName = "1.7.0-rc1", Channel = "beta", Path = "nightdesk.zip" });
// 验证后把 stable 指过去(只移动指针,不复制文件)
var manifest = await admin.PromoteAsync(new PromoteParams { App = "nightdesk", Platform = "win-x64", Channel = "stable", VersionCode = 10700 });
// 回滚:允许指向更低的版本;再撤回有问题的版本
await admin.PromoteAsync(new PromoteParams { App = "nightdesk", Platform = "win-x64", Channel = "stable", VersionCode = 10601 });
await admin.YankAsync(new YankParams { App = "nightdesk", Platform = "win-x64", VersionCode = 10700, Reason = "启动崩溃" });
10. 管理接口
| 方法 | 作用 | 需要的 token |
|---|---|---|
CreateAppAsync(new CreateAppParams { Id, Name, Description }) |
创建应用 | 管理员 |
UpdateAppAsync(new UpdateAppParams { App, Name, Description }) |
改名称/描述(null 的字段不变) |
管理员 |
PromoteAsync(new PromoteParams { App, Platform, Channel, VersionCode, MinVersionCode, Force }) |
让渠道指向某个已有 release;指向更低的版本即为回退。若下限高于新版本会被自动降到新版本 | 应用或管理员 |
SetMinAsync(new SetMinParams { App, Platform, Channel, MinVersionCode }) |
修改强制更新下限(0 表示取消) | 应用或管理员 |
YankAsync(new YankParams { App, Platform, VersionCode, Reason }) |
撤回 release:之后不能被渠道提供,也不能下载。若某渠道正在提供它,抛 conflict,需先 PromoteAsync 到别的版本 |
应用或管理员 |
UnyankAsync(new YankParams { ... }) |
恢复被撤回的 release | 应用或管理员 |
GetStatsAsync(string? app) |
下载次数、各已安装版本的检查次数;app 为空表示所有应用 |
带 app 时为应用或管理员;不带为管理员 |
CreateTokenAsync(new CreateTokenParams { Name, Apps, Admin }) |
签发 token,明文只在返回值的 Token 里出现一次 |
管理员 |
ListTokensAsync() / RevokeTokenAsync(id) |
列出 / 吊销 token | 管理员 |
已经升级到有问题版本的客户端不会被降级:回滚只影响「之后检查更新」的客户端。要让它们换到修复版,需要发布一个 versionCode 更高的新版本。
11. JSON-RPC CallAsync
REST 能做的操作,JSON-RPC(POST /v1/rpc)都能做。CallAsync 是通用入口:
var check = await client.CallAsync<CheckResult>("update.check", new CheckParams { App = "nightdesk", Platform = "android", VersionCode = 8 });
var methods = await client.CallAsync<List<MethodInfo>>("rpc.discover"); // 所有方法、鉴权级别、参数类型
-
失败时抛
RelhubException,Code与 REST 一致(来自 JSON-RPC 的error.data.code)。 -
参数必须是 JSON 对象(record、匿名对象、字典都行);
null的属性不会发送;没有参数就不传。 -
CallAsync返回的是服务端原话,不验签、不重算UpdateAvailable。 更新流程请用CheckAsync/WatchAsync/GetLatestAsync/DownloadAsync。上面例子里拿到的check.Manifest需要你自己Verify:check!.Manifest!.Verify(new[] { RelhubKeys.Parse(PinnedKey) }); -
一次只发一个调用;批量和 notification 请直接 POST(见 REST-API)。
-
不能用来上传安装包:RPC 请求体上限 1 MiB,包只能走
PublishAsync。
12. 错误处理
服务端报告的错误都是 RelhubException:
| 属性 | 含义 |
|---|---|
Code |
ErrorCodes 里的一个常量 |
ServerMessage |
不带前缀的消息 |
Message |
"code: message" |
HttpStatus |
HTTP 状态码(本地产生的错误为 null) |
ErrorCodes |
HTTP | 常见原因 |
|---|---|---|
InvalidArgument |
400 | 参数不合法;签名不是来自受信任的公钥;manifest 不是你请求的 app/platform/channel;manifest 格式不对 |
Unauthorized |
401 | 缺少或无效的 token |
Forbidden |
403 | token 不能操作这个应用,或该操作需要管理员 |
"app_delisted" |
403 | 应用已被管理员下架;匿名的检查、下载都会被拒(用 e.Code == "app_delisted" 判断,见 错误码) |
NotFound |
404 | 应用/平台/渠道/版本不存在,或还没发布;下载的包已被撤回 |
Conflict |
409 | versionCode 没有比已发布的更大;撤回仍被渠道提供的版本;promote 已撤回的版本 |
TooLarge |
413 | 安装包超过服务端限制 |
Unavailable |
503 | 太多客户端在等待;服务端暂时不可用(含代理返回的 502/504) |
Internal |
500 | 服务端错误;或收到了读不懂的响应(例如被登录页拦截) |
其他异常:
ChecksumException:下载的包与 manifest 的大小/SHA-256 不符,或服务端提供的是另一个构建。OperationCanceledException:你的CancellationToken取消了。HttpRequestException/IOException:网络问题。DownloadAsync和WatchLoopAsync会自动重试,CheckAsync等单次调用不会,由你决定。
13. 集成方案
13.1 WPF / WinForms 桌面应用
推荐流程:启动后在后台常驻上面的 BackgroundUpdater(或每隔数小时 CheckAsync 一次);发现更新后切回 UI 线程提示用户;用户确认(强制更新则直接)后下载、替换、重启。
// WPF 片段(依赖 WPF,未在本仓库编译)
var updater = new BackgroundUpdater(ReleaseUrl, PinnedKey, new Target("nightdesk", "win-x64"), installed, "NightDesk/" + Version);
updater.UpdateFound += update => Application.Current.Dispatcher.InvokeAsync(async () =>
{
if (!update.Mandatory && MessageBox.Show($"发现新版本 {update.Manifest!.VersionName},现在更新?", "更新", MessageBoxButton.YesNo) != MessageBoxResult.Yes)
{
return;
}
var zip = Path.Combine(Path.GetTempPath(), update.Manifest!.File);
await updater.DownloadAsync(update, zip, (done, total) => Application.Current.Dispatcher.InvokeAsync(() => progress.Value = done * 100.0 / total));
ApplyUpdateAndRestart(zip);
});
updater.Start();
替换自身文件的通用做法(这段代码能编译,但没有在 Windows 实机运行过):运行中的 exe 不能被删除或覆盖,但可以被改名。先把正在运行的 app.exe 改名为 app.exe.old,把新文件放到位,再启动新进程并退出旧进程;下次启动时清理 *.old。
public static void ReplaceRunningExecutable(string runningExe, string newExe)
{
var old = runningExe + ".old";
if (File.Exists(old))
{
File.Delete(old); // 上一次更新留下的
}
File.Move(runningExe, old);
File.Move(newExe, runningExe);
System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(runningExe) { UseShellExecute = true });
Environment.Exit(0);
}
下载到的是 zip 时,应先解压到临时目录并整体就位,避免更新到一半。
13.2 强制更新的界面处理
update.Mandatory == true 时:
- 展示「必须更新」界面,不允许进入主功能。
- 下载失败不要让用户困在无出口的界面:显示重试按钮和错误原因,
DownloadAsync会自动续传。 - 离线时
CheckAsync会失败,此时是否放行由你的产品决定:强制更新信息只来自服务端,SDK 无法知道「这个客户端是否已经过期」。
13.3 Avalonia、MAUI、Android
- Avalonia(桌面):和 WPF 相同,把 UI 线程切换换成
Dispatcher.UIThread.Post。库只依赖基础类库,不依赖任何 UI 框架。 - .NET MAUI / Android:库本身只用基础类库,面向
net8.0;我没有在 Android 目标上编译或运行过它,使用前请自行验证。Android 的versionCode必须等于 APK 里的versionCode,下载后交给PackageInstaller安装,系统安装器还会强制要求新旧 APK 的签名证书一致,这是服务器之外的另一层保护。 - 纯 Go 或 Kotlin 的 Android 应用请看 Go-SDK 13.3。
13.4 控制台工具 / 后台服务
和桌面应用类似,把 BackgroundUpdater 放进你的 BackgroundService(Microsoft.Extensions.Hosting)或常驻循环。只想在脚本里判断有没有更新,可以用 CLI:
relhub check -url https://tony-ai-pc-1.tail9f7f1f.ts.net/release -keys <公钥> -app nightdesk -platform win-x64 -code 10601
echo $? # 0 已是最新,10 有可选更新,20 有强制更新
13.5 CI 自动发布
在流水线最后一步调用 PublishAsync(见第 9 节),或者不写 C# 直接用一条 curl / relhub publish(见 CI 自动发布)。给 CI 单独签发只能操作该应用的 token(relhub token create -name ci -app nightdesk),不要把管理员 token 放进 CI。
14. 测试与验证
所有检查一条命令:
sdk/csharp/test.sh
它会:
- 为
net8.0和net10.0构建库(警告即错误)。 - 运行 190 个测试(见下)。
- 起一个一次性的
relhub(随机回环端口、临时数据目录),用samples/SelfUpdate走一遍「已最新、有更新、错误公钥被拒、--watch等到强制更新」。 - 打包
.nupkg,从本地文件夹源还原并运行一个消费者项目。
整个过程不联网:测试框架取自本机 ~/.nuget/packages 缓存(xunit 2.9.3、Microsoft.NET.Test.Sdk 18.0.1、xunit.runner.visualstudio 3.1.5,本机都已有),不安装任何东西,也不会碰线上服务。在没有这些缓存的机器上,第一次还原会从 nuget.org 下载它们。
测试分三层:
| 层 | 内容 |
|---|---|
| Ed25519 向量 | 用 Go 的 crypto/ed25519 生成的签名(含 RFC 8032 的 1–3 号向量,其中第 1 号的公钥生成时与 RFC 对照过):全部通过;改任意一个签名字节、改消息、换公钥、S+L 可延展签名、错误长度、非点/非规范公钥都被拒绝。向量由 sdk/csharp/tools/genvectors 确定性生成。 |
| 客户端逻辑 | 假的 HTTP 传输:不信服务端布尔值、篡改的清单、别的应用的合法签名、续传(Range/If-Range)、断线重试、损坏包丢弃、错误体映射、watch 循环的重试与取消(含 200 轮取消竞态压力测试)、发布的表单字段顺序等。 |
| 与真实服务端互通 | 起 Go 的 relhub:发布、检查、下载、Unicode 说明和版本名的签名、超过 32 位的 versionCode、渠道、promote/回滚/强制更新、撤回、令牌权限、watch、JSON-RPC、统计、上传中途被拒时的错误诊断。 |
单独运行测试:
cd sdk/csharp
dotnet test tests/Relhub.Client.Tests # 需要 go(自动构建 relhub),或设置 RELHUB_BIN 指向 relhub 二进制
RELHUB_BIN=$HOME/.local/bin/relhub dotnet test tests/Relhub.Client.Tests
互通测试只用临时目录和随机回环端口启动自己的
relhub,不会对线上实例发布任何东西。测试你自己的集成时也请这样做:发布不可修改,versionCode 只能递增(见 Go-SDK 第 14 节)。
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,连 GetInfoAsync 都失败 |
baseUrl 写错了。应是 https://tony-ai-pc-1.tail9f7f1f.ts.net/release,末尾不要带 /v1,也不要少了 /release。 |
internal: unreadable answer |
响应不是 JSON:多半是 baseUrl 指到了别的服务,或被代理/登录页拦截。 |
conflict: versionCode N is not higher than the published M |
发布时 versionCode 必须大于该平台已有的最大值(包括已撤回的)。 |
发布时 unauthorized / forbidden |
token 缺失、已吊销,或是限定了别的应用的 token。 |
发布大文件时 HttpRequestException/TaskCanceledException |
你传入的 HttpClient 有较短的 Timeout(IHttpClientFactory 默认 100 秒),上传耗时超过了它;改用不限时的 HttpClient。 |
ChecksumException |
包与签名清单不符,可能是传输损坏或服务端文件被动过;relhub verify 可在服务端离线检查数据目录。 |
| 一直提示有更新 | 传给 CheckAsync 的已安装 versionCode 不对(例如写死了常量,或没按第 3 节的规则从程序集版本算)。 |
| UI 更新进度时报「跨线程操作」 | Progress 在线程池线程上执行,需要切回 UI 线程。 |
dotnet test 报找不到 relhub |
没有 go 也没有设置 RELHUB_BIN;见第 14 节。 |
16. API 速查与 Go 对照
// 创建
new RelhubClient(string baseUrl, RelhubClientOptions? options = null) // IDisposable,线程安全
new RelhubClientOptions { Token, HttpClient, UserAgent, RetryPauseMin, RetryPauseMax }.TrustKey(base64)
readonly record struct Target(string App, string Platform, string? Channel = null)
// 读(无需 token)
Task<ServerInfo> GetInfoAsync(ct)
Task<CheckResult> CheckAsync(Target, long have, ct)
Task<CheckResult?> WatchAsync(Target, long have, TimeSpan wait, ct) // 超时返回 null
IAsyncEnumerable<CheckResult> WatchLoopAsync(Target, long have, ct)
Task<Manifest> GetLatestAsync(Target, ct)
Task<IReadOnlyList<App>> GetAppsAsync(ct)
Task<App> GetAppAsync(string app, ct)
Task<ReleasePage> ListReleasesAsync(string app, string platform, int limit = 0, long before = 0, bool includeYanked = false, ct)
Task DownloadAsync(Manifest, string destination, DownloadOptions? = null, ct)
// 写(需要 token)
Task<PublishResult> PublishAsync(PublishRequest, ct)
Task<App> CreateAppAsync / UpdateAppAsync
Task<Manifest> PromoteAsync / SetMinAsync
Task<Release> YankAsync / UnyankAsync
Task<StatsResult> GetStatsAsync(string? app = null, ct)
Task<CreateTokenResult> CreateTokenAsync; Task<IReadOnlyList<TokenInfo>> ListTokensAsync; Task RevokeTokenAsync(string id)
// 通用
Task<TResult?> CallAsync<TResult>(string method, object? parameters = null, ct)
// 辅助
RelhubKeys.Parse(base64) / KeyId(publicKey)
Identifiers.VersionCodeFromName("1.6.1") // 10601
Manifest.Verify(IEnumerable<byte[]>) / Validate() / IsMandatoryFor(long) / DownloadPath
与 Go SDK(relclient)的对照:
| Go | C# | 差异 |
|---|---|---|
relclient.New(url, opts...) |
new RelhubClient(url, options) |
选项集中在 RelhubClientOptions |
WithTrustedKeys / ParseTrustedKeys |
TrustKey / RelhubKeys.Parse |
|
Check / Watch / Latest |
CheckAsync / WatchAsync / GetLatestAsync |
全部异步,带 CancellationToken |
WatchLoop(ctx, t, have, fn) |
WatchLoopAsync(...) 返回 IAsyncEnumerable |
用 await foreach,break 即停止,不需要回调和哨兵错误 |
Download(ctx, m, dest, *DownloadOptions) |
DownloadAsync(m, dest, DownloadOptions?) |
校验失败抛 ChecksumException(Go 是 ErrChecksum) |
Publish |
PublishAsync |
C# 额外:上传中途失败后会重新预检以查明原因 |
返回 *relproto.Error |
抛 RelhubException |
Code 常量相同 |
Call(ctx, method, params, &result) |
CallAsync<T>(method, params) |
17. 实现说明与限制
- Ed25519 验签是自己实现的(RFC 8032 §5.1.7,
BigInteger上的扩展坐标算术)。它只验签,不签名,处理的都是公开数据,所以不是常数时间。行为与 Go 的crypto/ed25519对齐:S必须小于群的阶、重算出的R必须与签名里的R逐字节一致;非规范编码的公钥会被拒绝(比 Go 更严,对服务端生成的密钥没有影响)。一次验签约 6 ms(Release,预热后)。 - 标识符校验用
\A…\z而不是^…$:在 .NET 里$还会匹配结尾换行之前的位置,会让"nightdesk\n"通过校验并污染签名载荷。测试里专门覆盖了这一点,也覆盖了\d会匹配其他文字的数字。版本名和说明的长度按 UTF-8 字节计,与服务端一致。 - JSON 用
System.Text.Json的反射序列化;服务端新增的字段会被忽略,不会让旧应用出错。没有验证过裁剪(trimming)或 NativeAOT,需要的话请自行测试。 - 目标框架是
net8.0与net10.0;没有为 .NET Framework 或netstandard2.0构建。运行时验证只在 .NET 10 上做过(本机只有 .NET 10 运行时),net8.0目标做了完整编译(零警告)。 - 请求都用
ResponseHeadersRead,响应体在读完前不会被整个缓冲(错误体最多读 64 KiB,JSON 答复最多 32 MiB)。