release-publish

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。

目录

  1. 五分钟上手
  2. 把 SDK 引入你的项目
  3. 必须先懂的概念
  4. 创建客户端
  5. 检查更新 CheckAsync
  6. 下载 DownloadAsync
  7. 等待新版本 WatchAsync / WatchLoopAsync
  8. 查询
  9. 发布 PublishAsync
  10. 管理接口
  11. JSON-RPC CallAsync
  12. 错误处理
  13. 集成方案
  14. 测试与验证
  15. 排障
  16. API 速查与 Go 对照
  17. 实现说明与限制

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。行为:

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

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

它会:

  1. 为 net8.0 和 net10.0 构建库(警告即错误)。
  2. 运行 190 个测试(见下)。
  3. 起一个一次性的 relhub(随机回环端口、临时数据目录),用 samples/SelfUpdate 走一遍「已最新、有更新、错误公钥被拒、--watch 等到强制更新」。
  4. 打包 .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)。