Shorebird 的国内版来了？FlutterPatch 基于 Shorebird fork 的自建 Flutter

基于 Shorebird fork 的自建 Flutter 热更方案。设备端 updater 和补丁格式跟 Shorebird 兼容，服务器、CLI、桌面端全换成自建的，可以部署在国内服务器或者内网里。

因为Shorebird 的管理后台全在海外，国内团队接起来存在很多问题——补丁包不在自己服务器、API 慢、收费贵、内网用不了。FlutterPatch 就是把这部分换成自己的。

架构

国内或内网
  ├─ 手机 App（Shorebird updater）──► 自建 control_api
  └─ 研发机：Desktop ──► flutterpatch CLI ──上传──► 自建 /admin/v1

三个组件：

手机端查补丁的流程跟 Shorebird 官方一样的，就改个地址：

App → /api/v1/patches/check → 签名下载地址 → 冷启动生效 → /api/v1/patches/events

base_url 在 shorebird.yaml 里进行配置，指到自己的域名或内网地址。制品存本地盘或者 MinIO/S3，也能挂国内对象存储，走 CDN 下载。

下载链接用 HMAC 签名，服务端生成带过期时间的 URL，客户端拿这个 URL 直接下补丁。登录不走 Shorebird 官方 OAuth，CLI 用 FLUTTERPATCH_TOKEN会更加方便管理，管理后台用会话。

部署是 Docker compose，从单机到集群几档配置。Dart + Shelf，SQLite 起步，数据量大了换 Postgres。

补丁查包是按 app_id + release_version + build_number + platform 查的，命中了就返回最新的 patch。设备上报事件也是这几个字段，后面做灰度和放量的时候可以用。

check-ota 是发版前在本地跑的，扫工程里哪些文件不允许热更——比如改了原生层、改了 pubspec 里的依赖版本，这些不能打补丁可以提前检测出来。

设备白名单是可选的，配了之后只有白名单里的设备才会收到补丁推送。force_update 是强更标记，如果补丁想做强更提醒用户也可以基于这个字段进行自己实现逻辑。

从 Shorebird fork 出来的，命令叫 flutterpatch。本地打 release/patch 跟上游用法一样，改的是请求地址和鉴权——只打自建的 /admin/v1。

工程里还是 shorebird.yaml，因为更新库写了这个也懒得改了，但 base_url 必须自己填，没有官方默认值。装在 ~/.flutterpatch，用 FLUTTERPATCH_TOKEN 鉴权。记得一定要关闭自动更新，不然就没办法做白名单逻辑。

下载Flutter引擎还是得用 Shorebird 自定义引擎，这里开发需要开启代理，不然会很慢。

加了几个实用功能：check-ota 预检、资源扫描上传、--whitelist、--tags、JSON 输出，方便接 CI。部分报错是中文。

macOS / Windows / Linux 都有。本机改配置、跑 CLI、看自建服上的应用和补丁。给发版的人用的，不是运营后台。

多套环境分开存（测试、生产、内网），base_url 和 Token 各记各的。发补丁前跑 check-ota，哪些文件挡热更直接看，ignore / unsupported 写回工程。线上按应用 → 版本 → Build 往下翻，补丁、资源、快照都在。

回滚、放量还是去 Web 管理后台。桌面端就是个发版辅助工具。