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:
on:
push:
tags:
- "v*"第一步校验命名,必须是 vX.Y.Z,不接受 v0.3 或 release-0.3.1。命名统一之后,后面的判断才有稳定的前提。
第二步是闸门一:
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 上(是祖先),闸门一放行;但它比线上旧,部署上去等于把站点回退。
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 分支放行。这个分支必须显式处理,否则第一次发版会永远失败。
两道闸门都过之后,工作流做两件事:
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 -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一个典型的周更晚上:
- 跑
-Build,本地完整走一遍采集、过滤、打分、卡片、构建。这一步最久,取决于新增视频数量;大部分老视频会被断点和增量跳过。 - 打开
web/out看首页和随机几个详情页,确认没有空数据、没有破图、筛选正常。 - 跑
-Push,把数据提交推到 main,留一份版本记录。 - 如果这次只是数据更新,跑
-Deploy推 release;如果有代码改动,走 tag 流程。
真正需要人盯的是第 2 步。采集和卡片阶段可以挂着,构建 2–3 分钟也可以等,只有「页面看起来对不对」必须人看。
脚本里的保护也很朴素:
& $python @pipelineArgs
if ($LASTEXITCODE -ne 0) {
Write-Host "更新中断(exit $LASTEXITCODE);已采部分已落库,重跑即可续上"
exit $LASTEXITCODE
}流水线失败就不提交、不部署。数据已落库,下次重跑从断点续上。失败时什么都不做,比失败时做一半更安全。
五、部署侧最常见的三个故障
Cloudflare Workers Builds 的配置是:
| 配置项 | 值 |
|---|---|
| 构建命令 | cd web && npm ci && npm run build |
| 部署命令 | cd web && npx wrangler deploy |
| 环境变量 | NODE_VERSION=20 |
| 生产分支 | release |
三个实际踩过的坑:
第一,repo_id 指向了另一个仓库。 表现是「push 成功,但 Cloudflare 里根本没有这次构建」。查 Git 连接:
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 上,防止功能分支误发;
- 必须相对线上快进,防止旧提交回退;
- 流水线失败就不提交,数据留在库里等下次续跑;
- 手动部署路径绕开闸门,这个风险要在文档里明说。
站点稳定更新之后,才有余力回头看这套系统本身的问题。最后一篇写它现在还不算什么:哪些偏差是结构性的,哪些事我试过但没做成,如果重来会先做什么。