release-publish

Relhub Market(Android 应用市场)

release-publish 的安卓客户端:把服务器上托管的发行包做成一个可浏览、可安装、能更新自己的应用市场。

  • Kotlin + Jetpack Compose(Material 3),minSdk 26、compileSdk 35、JDK 17,工程在 android/。
  • 只读:服务器的读接口本来就开放,所以这个应用里没有任何 token。
  • 每个清单都用钉住的 Ed25519 公钥验签(纯 Kotlin 实现,API 26+ 可用),每个包都按清单核对大小和 SHA-256,之后才交给系统安装器。
  • 自更新走同一条管线:relhub-market 这个 app id 在同一个服务器上,检出、验签、下载、校验、安装。

本文件是协议与实现的权威说明;工程内的英文简版见 android/README.md。


1. 它解决什么

服务器(README.md)负责托管和签名,Go/C# SDK 负责让应用自己更新。手机上没有控制台,装一个包还得先找到链接。这个市场补上最后一环:

场景 做法
想看看服务器上都有什么 列表页读 GET /v1/apps,显示每个应用在当前渠道提供的版本、大小、发布日期
想在手机上装一个新应用 详情页读签名清单 → 下载(断点续传)→ 校验 → 系统安装确认
想回退到一个旧版本 版本历史列出全部记录(含已撤回),点「安装」下载那个 versionCode 的包
服务器要求必须升级(minVersionCode) 列表和详情都标成「强制更新」,市场自己被要求时直接阻断界面
应用市场自己该更新了 启动时和手动检查都会问自己;有新版本就在顶部提示,强制更新则不可关闭

服务器端没有任何改动:市场只用已有的公开读接口。

2. 集成契约摘要

2.1 用到的接口

方法 路径 用途
GET /v1/info 服务器名、apiVersion、信任的公钥(首次信任用)
GET /v1/apps 应用列表,含各平台各渠道的当前版本
GET /v1/apps/{app} 单个应用
GET /v1/apps/{app}/check?platform=&channel=&versionCode=N 检查更新,返回签名清单(市场自己重算结论)
GET /v1/apps/{app}/{platform}/latest?channel= 某渠道当前的签名清单
GET /v1/apps/{app}/{platform}/releases?limit=&before=&includeYanked=1 版本历史
GET /v1/apps/{app}/{platform}/releases/{code}/download 下载(Range / If-Range / ETag=SHA-256)
GET /healthz 连通性

平台固定为 android(BuildConfig.ANDROID_PLATFORM);渠道默认 stable,设置页可切 beta 或列表里出现的任意渠道。

2.2 关键字段

Manifest(只有这些字段被签名覆盖,keyId 与 signature 除外):

app platform channel versionCode versionName file size sha256
minVersionCode notes(经 hash) publishedAt

签名串逐字节复刻 relproto.Manifest.signingPayload:

relhub-release-v1
app=<app>
platform=<platform>
channel=<channel>
versionCode=<n>
versionName=<...>
file=<...>
size=<n>
sha256=<64 hex>
minVersionCode=<n>
publishedAt=<RFC3339>
notesSha256=<notes 的 UTF-8 字节的 sha256>

每一行以 \n 结尾,包括最后一行。notes 以 hash 入签名,所以说明里的换行、引号、反斜杠都不影响安全性(ManifestTest 用 Go 生成的签名验证这一点:Kotlin 侧只要有一个字节不同就验签失败)。

客户端自己算结论,不信服务器返回的布尔值(与 Go SDK 的 settle 一致):

updateAvailable = manifest.versionCode > installedVersionCode
mandatory       = updateAvailable && manifest.minVersionCode > installedVersionCode

2.3 错误码

{"error":{"code","message"}};HTTP 状态与 relproto 一致(400/401/403/404/409/413/503)。客户端另外有本地码:

码 来源 含义
invalid_argument 服务端 / 本地 参数不合法,或验签失败
not_found 服务端 应用 / 版本 / 渠道不存在
conflict 服务端 发布时 versionCode 不够大
unavailable 服务端 503、502、504(可重试)
checksum_mismatch 本地 下载的包与清单不符(会删除文件)
network 本地 连不上、超时(可重试)
protocol 本地 服务器答了另一个应用/渠道的清单、JSON 不可读

2.4 下载语义(与 Go SDK 的 fetch 对齐)

  • 目标文件旁写 .part,完成后校验大小 + SHA-256,通过才 rename 成正式文件 —— 半截包永远不会被安装。
  • 续传:Range: bytes=N- + If-Range: "<sha256>";206 且 Content-Range 起点匹配才续写,200 从头覆盖,416/错位的 206 删除重下(最多 2 次),5xx/429 重试(3 次,退避)。
  • 早期拒绝:响应头 X-Content-SHA256 与清单不符时,不读 body 直接失败。
  • 已存在且校验通过的文件不会重新下载。

3. 工程结构

android/
  settings.gradle.kts / build.gradle.kts / gradle.properties   AGP 8.7.3、Kotlin 2.0.21、Compose BOM 2024.12.01
  app/build.gradle.kts       minSdk 26;BuildConfig 注入服务器地址、公钥、自身 app id、版本号
  test.sh                    单元测试 + 对临时 relhub 的联测
  publish.sh                 构建签名 release APK 并发布(版本号 -> versionCode 自动推导)
  tools/genvectors/main.go   用 Go crypto/ed25519 + 真实 relproto 类型生成测试向量
  app/src/main/java/dev/relhub/market/
    core/      没有任何 Android API,全部可在 JVM 上测
      Crypto.kt sha256/sha512、文件哈希
      Ed25519.kt RFC 8032 验签(BigInteger,扩展坐标,S<L,非规范编码拒绝)
      Manifest.kt 签名串、校验规则、验签、downloadPath
      Models.kt  DTO(org.json 解析,字段与 relproto 一致)
      Errors.kt  错误码与 HTTP 状态映射
      Transport.kt HttpURLConnection(可注入)
      Client.kt  info/apps/check/latest/releases/download(含续传)
      Decisions.kt 未安装/已最新/可更新/强制 的判定,自更新判定,暂存路径
    data/      Settings(服务器、渠道、钉住的公钥、包名记忆)、MarketRepository(编排)
    install/   ApkVerifier(安装前校验)、ApkInstaller(PackageInstaller 会话)
    ui/        Theme、MarketViewModel、MarketScreen/Home/Detail/Settings、Components
  app/src/test/java/...     46 个测试(含 7 个被环境变量门控的联测)

4. 构建、测试、发布

cd android
./gradlew assembleDebug            # app/build/outputs/apk/debug/app-debug.apk
./gradlew testDebugUnitTest        # 纯 JVM 测试(39 个)
./gradlew lintDebug                # 只有 warning,没有 error
android/test.sh                     # 单元测试 + 对临时 relhub 的联测(46 个)
android/test.sh --no-live           # 只跑单元测试
go run ./android/tools/genvectors > android/app/src/test/resources/relhub-vectors.json   # 重新生成向量(在仓库根目录执行)

构建参数(都进 BuildConfig,改不了运行时值):

参数 默认 说明
relhubServerUrl https://tony-ai-pc-1.tail9f7f1f.ts.net/release 服务器地址
relhubPublicKeys 空 逗号分隔的 base64 公钥;空 = 首次信任(TOFU)
relhubMarketAppId relhub-market 自己在服务器上的 app id
relhubVersionName / relhubVersionCode 0.1.0 / 100 必须是已发布的那个版本

发布一个市场新版本(签名密钥必须始终相同):

export RELHUB_MARKET_KEYSTORE=... RELHUB_MARKET_STORE_PASSWORD=...
export RELHUB_URL=https://host/release RELHUB_TOKEN=...
android/publish.sh 0.2.0 --channel beta

publish.sh 会拒绝未签名的 release 构建,因为那种包装上去也更新不了自己。

5. 它怎么更新自己

  1. 启动时(MarketViewModel.init → refresh)和设置页「检查更新」都会 check(relhub-market, android, BuildConfig.VERSION_CODE);
  2. 清单验签通过、versionCode 比自己大,才算有更新(Decisions.selfUpdate);minVersionCode 高于自己时为强制更新;
  3. 点更新 → stageSelf:下载(续传)→ 校验大小/SHA-256 → 额外校验包名必须是 dev.relhub.market、证书必须是当前已安装应用的证书;
  4. PackageInstaller 全屏确认,用户点一次「安装」;装完进程重启,新版本继续用同一套逻辑。

能,但有两个安卓层面的硬限制,必须说清楚:

  • 不能静默安装。 普通应用只能通过 PackageInstaller 让用户点一次确认;真正静默需要设备所有者/系统权限。这是平台规则,不是实现缺陷。
  • 签名密钥不能换。 换了密钥,系统安装器会拒绝升级;市场在安装前还会比对证书,失败会给出可读的错误而不是安装器报错。

其余都是自动的:检查、验签、下载、校验、拉起安装确认。检查失败是静默的(quiet = true),不会用网络错误打断使用;强制更新时会阻断界面直到更新完成。

6. 安全模型

威胁 对策
服务器被入侵,返回恶意清单 清单必须由钉住的公钥签名;BuildConfig.PUBLIC_KEYS 来自构建参数,设置页只能清除/重新信任,不能任意新增
服务器改包 下载后核对 size 与 sha256(来自签名清单);不符即删
换掉 APK 冒充某应用 APK 的 versionCode 必须与清单一致;同一 app id 的包名会被记住,变了就拒绝;已安装的同包名应用证书不同则拒绝
冒充应用市场自己 自更新要求包名 = dev.relhub.market、证书 = 已安装应用的证书
中间人 只用 HTTPS(network_security_config 只对回环/10.0.2.2 放行明文,方便本机调试)
篡改签名(延展性) 验签要求 S < L 且 R 逐字节一致,与 Go 的 crypto/ed25519 行为一致

首次信任(TOFU)是唯一弱点:构建时没带公钥时,市场会信任第一次 /v1/info 给出的密钥,并在设置页用红字标注。要严格就带上 -PrelhubPublicKeys。

7. 已验证与未验证

已验证

  • Ed25519 验签:RFC 8032 前三组向量、真实清单载荷、翻转任意签名字节、换公钥/换消息、长度错误、S+L 可延展签名、非规范 y≥p 公钥、不在曲线上的点 —— 全部拒绝;[L]B 为单位元。向量由 android/tools/genvectors(Go crypto/ed25519)确定性生成。
  • 清单签名串:Kotlin 重算的字节与 Go 完全一致(Go 生成的签名在 Kotlin 里验得过;改任一字段即失败)。
  • 下载:全新下载、.part 续传(Range/If-Range)、错位 206 回退重下、校验失败清理、X-Content-SHA256 不符提前拒绝、已存在文件不重复下载、4xx 不重试。
  • 与真实服务器联测(android/test.sh):临时 relhub serve + 随机回环端口 + 真实发布 → /v1/info 公钥、应用列表、签名清单验签、check 结论、历史、真实包下载并核对 SHA-256、错误公钥被拒、未知应用 404。
  • 构建:assembleDebug、assembleRelease(未签名时 publish.sh 会拒绝)、lintDebug 无 error;APK 清单确认为 minSdk 26、targetSdk 35、含 INTERNET 与 REQUEST_INSTALL_PACKAGES。

未验证(诚实记录)

  • 真机/模拟器上的安装流程:这台机器没有 /dev/kvm,无法跑加速的模拟器。PackageInstaller 会话、系统确认对话框、安装结果回传、安装后重启,只在编译层面验证过。
  • 装完另一个 APK 之后的市场表现(PackageManager 缓存刷新、列表里「已安装」状态更新)。
  • 深色主题与不同 DPI 的视觉细节(只有 Compose 编译与逻辑测试)。
  • 主机的 tailnet 地址在手机上的可达性(需要设备在同一 tailnet,或经反向代理)。

8. 排障

现象 处理
列表空的,顶部显示服务器地址 拉一下刷新;确认手机能打开 https://host/release/healthz(tailnet 内)
「校验失败:signature is not from a trusted release key」 服务器换过签名密钥,或钉住的公钥不是这台服务器的。设置页核对公钥,必要时「忘记公钥」重新信任
「服务器上没有这个应用或版本」 该 app id 在这台服务器上没有发布 android 平台,或渠道不对(切 stable/beta 试试)
点安装没反应,弹「需要安装权限」 系统设置 → 应用 → Relhub Market → 允许安装未知应用
提示「… is installed and signed by another key」 手机上那个包是别的密钥签的(例如先装过 debug 版)。卸载旧包再装,或统一签名密钥
应用市场自己的更新装不上 检查是否换了签名密钥;publish.sh 用固定 keystore 构建
下载中断 再点一次即可续传,.part 会被复用
想看服务器给了什么 设置页显示了服务器名与钉住的公钥;协议细节见 REST-API

9. 与 Go / C# SDK 的差异

能力 Go SDK C# SDK Android 市场
验签 crypto/ed25519 自实现 自实现(Kotlin,API 26+)
检查/监听新版本 Check / Watch / WatchLoop Check / 长轮询 仅 Check(前台手动/启动)
备用服务器故障转移 WithFallbackURLs 未实现 未实现(只连一个地址)
发布 / 管理 有 有 只读,没有 token
安装 不涉及 不涉及 PackageInstaller 全屏确认
包校验 大小 + SHA-256 大小 + SHA-256 大小 + SHA-256 + 包名记忆 + 证书一致性