Vela Maps 发布体系完整拆解:Stable、Nightly、Canary 三通道与内置更新器设计

原创2026-11-03 13:03:502,187 阅读

Vela Maps 发布体系完整拆解:Stable、Nightly、Canary 三通道与内置更新器设计

Vela Maps 内置更新器与离线地图资源说明

为什么 Vela Maps 需要三通道发布

[Vela 导航截图] 先交代背景:Vela Maps 是一款不依赖 Google Play 服务的 Android 地图与逐路口导航应用(turn-by-turn navigation),运行在去 Google 化的手机上。没有 Google Play 就意味着没有官方商店帮你分发和推送更新,Vela 的答案是三通道发布(Stable、Nightly、Canary)加一套自建内置更新器——所有构建都来自同一个 CI 流水线,所有渠道共用同一把签名密钥。

对普通用户来说,记住三句话就够:

  • Stable:每周提升一次,日常使用选它;
  • Nightly:每天构建,尝鲜新特性选它;
  • Canary:开发中的滚动构建,给愿意陪跑的硬核玩家。

Vela 内置更新器与三通道发布架构

三个发布通道各是什么

完整规则写在 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 绝大多数用户

Vela 三通道发布与内置更新器

几个容易忽略的细节:

  • Canary 是一个"滚动 tag":每次 push 都删掉旧的 canary release 再重建,所以它的下载 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 + 芯片位

关键设计点:

  1. run 号全局单调递增。0.4 时代的构建和 0.5 时代的构建共享同一条递增序列,所以任何一个新构建对旧构建都是"升级"——无论你在哪个通道,切换通道永远是升级,安装器不会拒绝;
  2. 绝不发布 v0.5.0。更新器从 tag 里取 run 号,v0.5.0 会被读成 2000,永远推送不出来(SPEC.md 明确写死了这条纪律);
  3. 本地构建的 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 次。

更新如何被提供、下载、验证

整条链路可以概括为"只升不降、双重验签、交给系统安装器":

  1. 只升不降:候选版本 code 大于本机 code 才提示;"Not now" 会把被拒版本存进 update_dismissed_code,启动检查从此安静,直到出现更高版本;手动点"Check for updates"则无视该记录;
  2. 下载:APK 存到 filesDir/updates/,下载客户端特意去掉调用超时(共享客户端 12 秒的抓取上限会掐断百 MB 的下载体);已下载且校验通过的文件会保留复用——锁屏导致安装弹窗消失后,再点 Update 不用重新下载;
  3. 验证:ApkCheck.kt 检查 zip 魔数 PK、文件大小、以及 GitHub 为该附件发布的 SHA-256,任何一项失败文件即删除;
  4. 安装:通过 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 三通道发布架构与内置更新器

写在最后

Vela 的发布体系给了开源项目一个值得抄作业的范本:没有更新服务器、没有复杂后端,仅靠 GitHub Releases + 标签纪律 + 一个克制网络请求的客户端更新器,就实现了三通道滚动发布、签名一致的跨渠道升级、以及面向车机用户的降级保护。想深入看完整规则,直接读 SPEC.md 第 15 节和 docs/book/12-releases.md;想看实现细节,从 app/src/main/java/app/vela/update/SelfUpdater.kt 入手,配合 ReleaseTagsTest.kt、ApkChoiceTest.kt 等测试文件读会快很多。

登录后查看全文
Vela