企业官网建设流程全解析

BBPlayer 是一款简约好用的 BiliBili 音乐播放器，其热更新系统基于自托管的 Expo Updates 服务搭建，通过 bsdiff 增量补丁与 Cloudflare R2 对象存储配合，让 JS 代码更新无需等待应用商店审核即可触达用户。本文将带你完整拆解这套开源热更新方案的架构、补丁原理与部署实战。

为什么自托管：音乐播放器的双层更新机制

BBPlayer 把"更新"拆成了两层，各司其职：

• 原生大版本：APK / 原生能力升级走应用市场，客户端从远程 update.json 拉取版本号、更新日志与强制更新标记，由 apps/mobile/src/lib/services/updateService.ts 中的checkForAppUpdate做 semver 比较后提示下载；
• JS 热更新（OTA）：绝大多数 Bug 修复与界面调整只涉及 JS bundle，通过 Expo Updates v1 协议直接下发，分钟级生效。

自托管 Expo Updates 的核心收益在于：分发状态、溯源与遥测数据全部落在自己的 PostgreSQL 里，不可变的 bundle 全部落在 R2，既没有按请求计费的依赖，也拿到了完整的分发观测能力（补丁命中率、节省字节数、启动成功率）。

架构总览：一个镜像、三个进程、两种存储

整个更新服务端由 apps/update-server/docker-compose.yml 编排，共 5 个服务：

网络设计上只有两个 docker 网络：internal（内网隔离，不对外暴露任何端口）与egress（仅供 api/worker 访问 R2 的 S3 endpoint）。唯一的宿主机入口是 nginx 的127.0.0.1:8080，再套一层你自己的 HTTPS 反向代理。

⚙️ 关键决策：bsdiff 的 CPU / 内存开销很高，所以补丁计算被刻意拆成独立的worker进程，绝不拖慢 manifest 响应。

bsdiff 增量补丁：下载量最少能省 90%

每次新发布后，服务端会为"上一个可见的 channel head → 新 head"创建异步 bsdiff 任务，核心逻辑在 apps/update-server/internal/patchworker/worker.go：

1. 从 R2 读取新旧两个完整 Hermes bundle，写入临时目录；
2. 执行bsdiff --format=bsdiff40生成增量补丁，再用bspatch把旧包还原出来，逐字节比对还原结果与目标 bundle，不一致直接判失败；
3. 补丁必须携带BSDIFF40魔数头，且尺寸至少要比目标 bundle 小 10%（minimumSaving = 0.10），否则标记为not_beneficial——客户端此时会继续收到完整 bundle，绝不拿"假增量"浪费请求；
4. 校验通过才上传到 R2 的patches/<from>/<to>.bsdiff，并记录 sha256 与节省比例。

两个工程细节值得注意：

• 补丁认领有 10 分钟租约：worker 被中断时 channel 不会永久卡在processing，新 worker 可以接管；任务未就绪期间，客户端持续收到完整 bundle，可用性不受影响；
• 构建期自检：Docker 构建固定住 Expo 的 bsdiff 源码，若产出的补丁无法被配套 bspatch 逐字节还原，构建直接失败，把问题拦在部署之前。

移动端接入：expo-updates 的 manifest 请求

客户端侧只需在 apps/mobile/app.config.ts 中声明updates配置：manifest 地址指向自托管的/api/manifest，并通过requestHeaders预置expo-channel-name（渠道）与x-bbplayer-installation-id（安装级匿名 ID，启动时由 updateTelemetry.ts 写入真实 UUID）两个请求头。

服务端的 manifest 处理器（api_manifest.go）按 Expo 协议工作：

• 根据expo-platform/expo-runtime-version/expo-channel-name查 channel head，命中则返回 manifest，无更新返回带expo-protocol-version的 204；
• head 为embedded模式时下发rollBackToEmbedded指令，一键回滚到内嵌版本；
• 只有启动用的 Hermes bundle 走 API URL——因为 expo-updates 仅在此时携带A-IM: bsdiff头做 HTTP 内容协商，由服务端在"完整对象"与"补丁对象"之间二选一；其余普通资源直接由 R2 自定义域名提供，完全绕过 Go 进程，静态资源零 API 压力；
• 每次 manifest 请求还会顺带记录启动/崩溃观测（updateTelemetry.ts 的launch_succeeded/launch_failed事件最终上报到/api/events），构成回滚决策的数据基础。

一键发布实战：hot-update-cli

发布侧是 TypeScript 编写的 hot-update-cli，在apps/mobile下执行：

pnpm hot-update

它会交互式询问 channel 与发布说明，并自动完成一整条流水线（见 publish.ts）：

1. git rev-parse HEAD记录 commit 溯源，脏工作区会先警告（非交互模式直接拒绝，除非--allow-dirty）；
2. 调用 Expo 的@expo/fingerprint生成 Android runtimeVersion（appVersion策略下自动取公开配置的version）；
3. 运行expo export导出 Android bundle，写入公开 Expo 配置后打包成 zip；
4. 以 multipart 形式 POST 到/admin/publish（requestJSON +archive归档），同时携带 commit 溯源与 fingerprint 报告。

首次成功后，服务器 URL 与 token 会保存到项目的.bbplayer-updates/credentials.json（目录权限 700，Git 已忽略），后续优先使用命令行参数与环境变量。CI 场景使用完全相同的命令：

pnpm hot-update -- publish --non-interactive --channel production --message "修复歌词解析"

运维还有配套管理命令：list查更新组、channel --action history看渠道变更历史、insights查看 bsdiff 命中率与节省字节数、source --action compare对比两组发布之间的源码差异。

Docker Compose + R2 四步部署

1. 构建两个镜像（运行时不编译任何东西，全部提前产出）：

   docker build -t bbplayer-updates:VERSION apps/update-server docker build -t bbplayer-updates-web:VERSION -f apps/update-server/web/Dockerfile .

2. 准备环境变量：必填项包括POSTGRES_PASSWORD、DATABASE_URL、R2 的桶名/账号/S3 凭据与R2_PUBLIC_BASE_URL（自定义域名）、PUBLIC_BASE_URL，以及相互独立的ADMIN_TOKEN与INSTALLATION_HMAC_KEY；

3. 启动栈：docker compose up -d，migrate 先行，api/worker 等待迁移成功，nginx 等待 api 健康检查通过；

4. 接入共享反向代理（生产）：叠加 docker-compose.prod.yml 移除宿主机端口、把 nginx 挂到共享proxy网络，外层 Caddy/nginx 做 TLS 终结。注意外层 nginx 需为/admin/publish放开 256 MiB 上传限制，否则会返回413 Request Entity Too Large。

本地可以用 MinIO 模拟 R2，并跑一遍端到端套件验证 Expo 协议实现：

docker compose -f docker-compose.e2e.yml up -d E2E_DATABASE_URL='postgres://updates:updates-test@127.0.0.1:55432/updates?sslmode=disable' \ go test ./internal/server -run TestE2EExpoProtocol -count=1 -v

该套件事先模拟 manifest 与资源请求、校验不可变资源的 hash，并验证事件信封的版本号与幂等性。

可观测性：结构化日志与分钟级指标

api、worker、migrate三个进程都以结构化日志写到 stderr，级别由LOG_LEVEL控制；每个补丁任务都会记录认领、耗时、补丁大小与节省百分比，格式上就是"级别 + 标签键值对"这种一目了然的样式：

指标后端刻意选用了 PostgreSQL 而非 Prometheus：请求数、5xx 与耗时按分钟聚合到service_metric_minutes，启动 bundle 与 bsdiff 分发聚合到delivery_metric_minutes（普通资源留在 R2，不计入 API 指标）。WebUI 登录页输入ADMIN_TOKEN后可直接查询/admin/metrics/service、/admin/metrics/delivery与更新组生命周期接口，窗口默认 7 天、最多 90 天。原始事件保留 35 天，worker 每天清理过期数据。

小结

BBPlayer 的自托管热更新方案给出了一个可复用的范式：PostgreSQL 管状态、R2 管不可变对象、独立 worker 算 bsdiff、内容协商在完整包与增量补丁之间自动切换、遥测闭环驱动回滚决策。配合 hot-update-cli 的一键发布与 CI 非交互模式，一个 React Native 团队就能在完全自主可控的前提下，把 JS 更新的触达时间压缩到分钟级。更多细节可参考 apps/update-server/README.md 与 apps/update-server/DESIGN.md。