Skip to content

BiliTube(七):每周数据更新与 tag 发版,怎么避免误上线 ​

站点上线后第一次发版,我把 tag 打在了功能分支上。

工作流跑得很顺,Cloudflare 也构建成功。十分钟后,线上首页的「进入筛选的候选」变成了 0——那条分支上没有导出的数据文件,构建时读到一个空 JSON,页面照样渲染,只是所有数字都是零。

故障本身不复杂,恢复也只花了十几分钟。但它暴露了一个设计问题:发版流程默认「人不会犯错」,而人一定会犯错。 于是有了后面的两道闸门。

一、两条发布线 ​

这个项目有两种更新,节奏完全不同:

类型频率内容风险
数据周更每周web/public/data/ 下的 JSON低,纯数据覆盖
代码发版不定期Python、Next.js、样式、构建配置高,可能改坏构建或页面

如果两者共用「push 就部署」,每周的数据提交都会触发一次完整构建;更糟的是,任何一次实验性提交都可能直接上线。

所以生产分支设成 release,main 只作为集成分支:

动作结果
git push origin main只进仓库,不构建
推 vX.Y.Z tag走两道闸门,通过后推进 release
update.ps1 -Push提交数据并推 main,不部署
update.ps1 -Deploy提交数据并直接推 release,部署
update.ps1 -Deploy -Tag v0.3.1同上,并创建 tag

二、闸门一:tag 必须在 main 上 ​

工作流只监听 tag:

yaml
on:
  push:
    tags:
      - "v*"

第一步校验命名,必须是 vX.Y.Z,不接受 v0.3 或 release-0.3.1。命名统一之后,后面的判断才有稳定的前提。

第二步是闸门一:

bash
if ! git merge-base --is-ancestor HEAD origin/main; then
  echo "::error::tag $TAG 指向的提交不在 main 上(可能是在功能分支上打的),拒绝部署"
  exit 1
fi

.github/workflows/release.yml#L47-L58

merge-base --is-ancestor HEAD origin/main 判断的是「tag 指向的提交是不是 main 的祖先」。功能分支上的提交不是 main 的祖先,直接失败。

为什么不在本地拦?因为 tag 可以在任何人的机器上打,本地 hook 可以被跳过,也可以被忘记安装。能在服务端验证的规则,不要只写在本地。

三、闸门二:不能回退线上 ​

闸门一保证「这个提交合并过」,但不保证「它比线上新」。

典型的误操作:发现 v0.5.2 有个小问题,切到那个提交改了一下,顺手补了个 v0.5.2-hotfix 的 tag。这个提交在 main 上(是祖先),闸门一放行;但它比线上旧,部署上去等于把站点回退。

bash
if git rev-parse --verify origin/release >/dev/null 2>&1; then
  if ! git merge-base --is-ancestor origin/release HEAD; then
    echo "::error::tag $TAG 比线上版本旧,部署会导致回退,拒绝执行"
    exit 1
  fi
  echo "✓ 相对线上是快进"
fi

.github/workflows/release.yml#L60-L72

origin/release 必须是 HEAD 的祖先,也就是「线上版本能快进到这次 tag」。不是快进就拒绝。

首次发版时 release 还不存在,git rev-parse --verify 失败,走 else 分支放行。这个分支必须显式处理,否则第一次发版会永远失败。

两道闸门都过之后,工作流做两件事:

bash
git push origin HEAD:release   # 触发 Cloudflare 构建
gh release create "$TAG" --title "$TAG" --generate-notes --verify-tag

.github/workflows/release.yml#L74-L86

concurrency: release + cancel-in-progress: false 保证两次发版不会并发推进 release,也不会因为后一次取消前一次而留下半成品。

四、周更的 15 分钟花在哪 ​

周更脚本有四个开关,按需组合:

powershell
powershell -File scripts/update.ps1            # 只跑流水线
powershell -File scripts/update.ps1 -Build     # 跑完本地构建,检查产物
powershell -File scripts/update.ps1 -Push      # 提交数据并推 main,不部署
powershell -File scripts/update.ps1 -Deploy    # 提交 + 推 main + 推 release

一个典型的周更晚上:

  1. 跑 -Build,本地完整走一遍采集、过滤、打分、卡片、构建。这一步最久,取决于新增视频数量;大部分老视频会被断点和增量跳过。
  2. 打开 web/out 看首页和随机几个详情页,确认没有空数据、没有破图、筛选正常。
  3. 跑 -Push,把数据提交推到 main,留一份版本记录。
  4. 如果这次只是数据更新,跑 -Deploy 推 release;如果有代码改动,走 tag 流程。

真正需要人盯的是第 2 步。采集和卡片阶段可以挂着,构建 2–3 分钟也可以等,只有「页面看起来对不对」必须人看。

脚本里的保护也很朴素:

powershell
& $python @pipelineArgs
if ($LASTEXITCODE -ne 0) {
    Write-Host "更新中断(exit $LASTEXITCODE);已采部分已落库,重跑即可续上"
    exit $LASTEXITCODE
}

scripts/update.ps1#L38-L43

流水线失败就不提交、不部署。数据已落库,下次重跑从断点续上。失败时什么都不做,比失败时做一半更安全。

五、部署侧最常见的三个故障 ​

Cloudflare Workers Builds 的配置是:

配置项值
构建命令cd web && npm ci && npm run build
部署命令cd web && npx wrangler deploy
环境变量NODE_VERSION=20
生产分支release

三个实际踩过的坑:

第一,repo_id 指向了另一个仓库。 表现是「push 成功,但 Cloudflare 里根本没有这次构建」。查 Git 连接:

bash
curl -s ".../builds/workers/<SCRIPT_TAG>" -H "Authorization: Bearer <API_TOKEN>" \
  | jq '.result.git_repository'

repo_id 必须是本仓库。这个坑最隐蔽,因为 GitHub 侧一切正常,只有构建列表是空的。

第二,构建目录不对。 报 Could not read package.json 或找不到 lockfile,都是因为构建命令没有 cd web。不要依赖控制台里的「根目录」设置,把路径写进命令里。

第三,Node 版本太旧。 报 Node.js version ... not supported,加 NODE_VERSION=20 即可。

六、这道闸门保护不了什么 ​

闸门只保护 tag 流程。update.ps1 -Deploy 是直接 git push origin HEAD:release,不经过 GitHub Actions,也不校验快进。

这是有意的取舍:周更的数据提交发生在 main 的最新 HEAD 上,回退风险很低;每周都打 tag 又太重。但这意味着手动 -Deploy 的路径依赖操作者站在正确的分支上。

所以脚本的推荐用法是:日常只跑 -Push,让 main 保持最新;需要上线时再决定是 -Deploy 还是打 tag。两种路径的差别要写进文档,不能让人以为「有闸门就万无一失」。

踩坑:tag 打错分支,部署了空数据

第一次发版时,tag 指向功能分支。那条件分支有代码改动,但没有 web/public/data/videos.json。构建没有报错,页面正常渲染,只是所有数字都是 0。

闸门一就是为这个故障加的:功能分支的提交不是 main 的祖先,直接拒绝。恢复时把 tag 删掉、在 main 上重打,再推一次。

这件事的教训不是「打 tag 要小心」,而是部署前必须校验来源,而不是相信操作顺序。

为什么用 release 分支而不是直接部署 main

release 是一个「已验收」的指针。main 可以包含还没准备上线的提交,release 只在你决定发版时前进。

它也给了回滚一个明确的对象:线上永远等于 release 的某个提交,回滚就是把 release 指回上一个提交,再让 Cloudflare 重建。不需要在服务器上找文件、也不需要撤销已经发布的构建。

代价是多一个分支要维护、多一步推进。对这个规模的静态站,值得。

七、实测数据 ​

环节时间 / 结果
周更流水线(增量)十几分钟,取决于新增视频与卡片数量
Cloudflare 构建部署约 2–3 分钟
搜索请求(20 词 × 2 排序 × 3 页)120 个请求,0.8 req/s 下约 2.5 分钟
闸门失败工作流失败,线上保持原版本
数据无变化跳过提交,不产生空 commit

八、小结 ​

这套发布流程的核心不是自动化,而是把「什么情况下不许上线」写清楚:

  • main 不是生产分支,push 不等于部署;
  • tag 必须在 main 上,防止功能分支误发;
  • 必须相对线上快进,防止旧提交回退;
  • 流水线失败就不提交,数据留在库里等下次续跑;
  • 手动部署路径绕开闸门,这个风险要在文档里明说。

站点稳定更新之后,才有余力回头看这套系统本身的问题。最后一篇写它现在还不算什么:哪些偏差是结构性的,哪些事我试过但没做成,如果重来会先做什么。

本文阅读--次|全站访问--次|访客--人