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. 它怎么更新自己
- 启动时(
MarketViewModel.init→refresh)和设置页「检查更新」都会check(relhub-market, android, BuildConfig.VERSION_CODE); - 清单验签通过、
versionCode比自己大,才算有更新(Decisions.selfUpdate);minVersionCode高于自己时为强制更新; - 点更新 →
stageSelf:下载(续传)→ 校验大小/SHA-256 → 额外校验包名必须是dev.relhub.market、证书必须是当前已安装应用的证书; 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(Gocrypto/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 + 包名记忆 + 证书一致性 |