Vela Maps 发布体系完整拆解:Stable、Nightly、Canary 三通道与内置更新器设计
Vela Maps 发布体系完整拆解:Stable、Nightly、Canary 三通道与内置更新器设计
为什么 Vela Maps 需要三通道发布
[
] 先交代背景:Vela Maps 是一款不依赖 Google Play 服务的 Android 地图与逐路口导航应用(turn-by-turn navigation),运行在去 Google 化的手机上。没有 Google Play 就意味着没有官方商店帮你分发和推送更新,Vela 的答案是三通道发布(Stable、Nightly、Canary)加一套自建内置更新器——所有构建都来自同一个 CI 流水线,所有渠道共用同一把签名密钥。
对普通用户来说,记住三句话就够:
- Stable:每周提升一次,日常使用选它;
- Nightly:每天构建,尝鲜新特性选它;
- Canary:开发中的滚动构建,给愿意陪跑的硬核玩家。
三个发布通道各是什么
完整规则写在 SPEC.md 第 15 节,官方手册见 docs/book/12-releases.md。一张表看清楚:
| 通道 | 发布节奏 | Tag 规则 | 适合谁 |
|---|---|---|---|
| Canary | 每次向 canary 分支 push 即替换 |
固定为 canary,永不改变 |
想第一时间踩新代码的人 |
| Nightly | 每天 10:30 UTC(main 有变动时) |
v0.5.<run> 预发布版 |
想要每日新鲜构建的人 |
| Stable | 每周一 16:00 UTC 提升 | 沿用对应 Nightly 的 tag | 绝大多数用户 |
几个容易忽略的细节:
- Canary 是一个"滚动 tag":每次 push 都删掉旧的
canaryrelease 再重建,所以它的下载 URL 永远不变,版本号只写在 release 说明里; - Stable 不重新编译:它就是最新 Nightly 被"就地改标题、去掉 prerelease 标记、重新生成更新日志"后的样子,同一个签名 APK;
- Stable 永不过期删除,它们是变更日志和二分定位(bisect)的基准;Nightly 则滚动保留最新 30 个。
版本号设计:run 号是灵魂
版本号是整个发布体系的"排序货币",由 CI 的工作流计数器 github.run_number 统一派生:
tag = v0.<minor>.<run>
versionName = 0.5.<run> (Canary 为 0.5.<run>-canary)
versionCode = (2000 + run) × 10 + 芯片位
关键设计点:
- run 号全局单调递增。
0.4时代的构建和0.5时代的构建共享同一条递增序列,所以任何一个新构建对旧构建都是"升级"——无论你在哪个通道,切换通道永远是升级,安装器不会拒绝; - 绝不发布
v0.5.0。更新器从 tag 里取 run 号,v0.5.0会被读成 2000,永远推送不出来(SPEC.md 明确写死了这条纪律); - 本地构建的 versionCode 必须低于 1000,保证自己改出来的包永远不会"领先"于官方发布线。
内置更新器:不搭更新服务器的更新器
这是 Vela 发布体系里最精巧的部分。源码集中在 app/src/main/java/app/vela/update/,核心是 SelfUpdater.kt:它不查任何自建更新服务器,而是直接读 GitHub Releases API。
三个通道各查哪里
- Stable:读
releases/latest。因为数据发布(地图、POI 包等)都是 prerelease,Latest 永远指向最新 Stable,一次请求(约 15 KB)就完成检查; - Nightly:先取
git/matching-refs/tags/v0.标签列表(约 200 KB、不含正文和附件),再对最新 3 个 tag 逐个拉取 release,取代码最大的非草稿版本; - Canary:读滚动 tag
canary的说明文字里的versionCode:行,同时兜底跑一次 Nightly 检查,两者取高——Canary 落后时用户会自动收到 Nightly,谁也不会被"套牢"。
源码里有一段注释解释了一个关键决策(SelfUpdater.kt):永远不拉取完整 release 列表。因为地图数据 release 每个带约 450 个附件,一次列表请求要下载 4~9 MB——这正是"检查更新为什么慢"的根因。改走标签端点后,Stable 检查只需 1 次请求,Nightly/Canary 也只要 2~4 次。
更新如何被提供、下载、验证
整条链路可以概括为"只升不降、双重验签、交给系统安装器":
- 只升不降:候选版本 code 大于本机 code 才提示;"Not now" 会把被拒版本存进
update_dismissed_code,启动检查从此安静,直到出现更高版本;手动点"Check for updates"则无视该记录; - 下载:APK 存到
filesDir/updates/,下载客户端特意去掉调用超时(共享客户端 12 秒的抓取上限会掐断百 MB 的下载体);已下载且校验通过的文件会保留复用——锁屏导致安装弹窗消失后,再点 Update 不用重新下载; - 验证:ApkCheck.kt 检查 zip 魔数
PK、文件大小、以及 GitHub 为该附件发布的 SHA-256,任何一项失败文件即删除; - 安装:通过 FileProvider 交给 Android 系统安装器,由操作系统强制校验同包名 + 同签名,用户确认后才完成。
还有一个贴心的设计:InstallSource.kt 会检查 Android 记录的"安装者"是不是 Play。Android Auto 只认从 Play 安装的导航 App,若用户借第三方工具把安装源伪装成了 Play,自更新会把这个伪装抹掉、车机随即不再显示 Vela——此时更新器会先弹警告,并给你"保存 APK 文件"(喂给那个工具)或"仍然更新"两个选择,而不是悄悄搞坏你的车机体验。
新版本的"What's new"弹窗
新构建首次启动时,WhatsNew.kt 会拉取该构建自己的 release 说明展示一次;更新卡片还会把被跳过的历史版本的更新日志(最多 8 条)一并附上,让长期没更新的人一次看全。APK 里不打包任何说明文字,弹窗显示的就是 release 当天的原文。
多路分发:同一把签名密钥
Vela 的构建同时到达四个去处,且全部用同一把 release 密钥签名(密钥在仓库之外,经 CI secrets 进入构建):
| 分发渠道 | 说明 |
|---|---|
| 内置更新器 | 上文所述,Settings → About 里可开关启动检查、切换通道 |
| Obtainium | 跟随 GitHub releases;开启 "include prereleases" 可拿 Nightly |
| 自建 F-Droid 仓库 | 服务最新 Stable + 领先时的 Nightly,指南见 FDROID.md |
| 手动侧载 | 直接从 release 页下载 APK |
因为签名一致,四个来源之间可以随意切换,永远不需要先卸载重装。F-Droid 客户端用单独的索引密钥签名索引,APK 本体仍用应用密钥——验证 APK 时应对照 README 里公布的应用证书 SHA-256,用 apksigner verify --print-certs 检查。
写在最后
Vela 的发布体系给了开源项目一个值得抄作业的范本:没有更新服务器、没有复杂后端,仅靠 GitHub Releases + 标签纪律 + 一个克制网络请求的客户端更新器,就实现了三通道滚动发布、签名一致的跨渠道升级、以及面向车机用户的降级保护。想深入看完整规则,直接读 SPEC.md 第 15 节和 docs/book/12-releases.md;想看实现细节,从 app/src/main/java/app/vela/update/SelfUpdater.kt 入手,配合 ReleaseTagsTest.kt、ApkChoiceTest.kt 等测试文件读会快很多。