先把事故时间线还原出来#

这次出问题的是 8 月 17 日的 Gemini 3.7 Flash 文章，对应 GitHub PR #40。

GitHub 记录里的关键时间如下（北京时间）：

中间有大约 4 小时 29 分钟。

这 4 个多小时里发生了一件很有迷惑性的事情：

1
文章文件存在        ✅
2
PR 存在             ✅
3
Biome               ✅
4
Tests               ✅
5
Type Check          ✅
6
Build               ✅
7
Playwright E2E      ✅
8
生产 master 有文章   ❌

如果只看 GitHub Actions 页面，很容易产生“已经通过了，应该上线了”的错觉。

但 GitHub Actions 的绿色勾，只能证明工作流定义的那些检查成功执行。

它并不会自动替你完成一个没有配置自动合并的 Pull Request。

CI 到底证明了什么？#

我的博客 PR 工作流目前有五个 Job：

1
Biome Check
2
Tests
3
Type Check
4
Build
5
Playwright E2E

其中包括：

• Biome 做代码与格式检查；
• Node 测试跑已有回归；
• Astro Check 检查内容与类型；
• Production Build 验证站点能完整构建；
• Playwright 用真实浏览器跑 UI 回归。

这套检查很有价值。

如果它们全部通过，我们可以得到一个相当强的结论：

“这一个 PR 对应的提交，在当前 CI 环境中满足了仓库定义的合并前质量门槛。”

但这句话里有一个非常关键的词：

合并前。

GitHub 官方对 Status Checks 的描述也是类似的：状态检查用于判断提交是否满足仓库条件、帮助维护者判断 PR 是否已经 ready to merge；如果分支规则要求某些检查，它们需要通过之后 PR 才能合并。

所以：

1
CI = 验证器

而不是：

1
CI = 自动发布按钮

除非你另外配置了 Auto-merge、Merge Queue、部署 Action，或者其他自动化机制。

Pull Request 也是一个独立状态#

Git 的分支模型决定了：

1
content/gemini-37-flash-2026-08-17

和：

1
master

是两条不同的引用。

文章即使已经存在于 content branch，只要没有发生 merge，master 指向的提交树就不会凭空发生变化。

这就是这次问题的真正断点：

1
content branch
2
      ↓
3
Pull Request
4
      ↓
5
五项 CI 全绿
6
      ↓
7
  [停在这里]
8
      ✕
9
merge → master

当时不是构建失败，也不是部署失败。

部署链根本还没有获得新的生产提交。

所以从系统视角看，后面的 Cloudflare、DogeCloud、浏览器缓存全都没有做错任何事。

它们只是在忠实地继续提供旧的 master。

为什么 Cloudflare Pages 也救不了这个问题？#

这个博客使用 Cloudflare Pages Git Integration。

Cloudflare Pages 会区分 Production branch 和其他 Preview branch。官方文档也明确说明：生产分支用于生产版本，其余分支通常用于 Preview Deployment。

我的仓库生产源是 master。

因此逻辑可以简化成：

1
push 到普通内容分支
2
    ↓
3
可以产生 Preview
4
    ↓
5
不会替换生产 master
6

7
merge / push 到 master
8
    ↓
9
Cloudflare Pages Production Build
10
    ↓
11
生产站更新

于是，当 PR #40 没有 merge 时，即使内容分支上的文件完全正确，生产域名也没有理由切换到那一个 commit。

这也是为什么“Preview 能打开”与“生产已经上线”是两个完全不同的事实。

我的真实发布链其实比想象中还多一层#

现在这个博客真正的生产链不是简单的：

1
GitHub → Cloudflare

而更接近：

1
Content Branch
2
      ↓
3
Pull Request
4
      ↓
5
GitHub Actions
6
      ↓
7
Squash Merge
8
      ↓
9
master
10
      ↓
11
Cloudflare Pages Production Deployment
12
      ↓
13
确认 production deployment 的 commit SHA
14
      ↓
15
DogeCloud CDN 精确刷新
16
      ↓
17
用户访问 blog.katelya.top

仓库里还有一条 Refresh DogeCloud CDN 工作流。

它只监听：

1
on:
2
  push:
3
    branches: [master]

也就是说，如果 PR 还没 merge：

连 CDN 刷新工作流本身都不会因为这个 PR 而进入生产刷新阶段。

这比“刷新失败”更靠前——根本没有生产 push 事件。

我为什么没有简单地“merge 后直接清 CDN”#

这里还有一个容易踩的坑。

假设一 merge 就立刻提交 CDN purge，但 Cloudflare Pages 还在构建新版本，会发生什么？

可能出现这种竞态：

1
master 更新
2
   ↓
3
CDN 立刻刷新
4
   ↓
5
CDN 回源
6
   ↓
7
Cloudflare Pages 生产版本仍然是旧提交
8
   ↓
9
旧内容重新进入边缘缓存
10
   ↓
11
几秒后 Pages 才完成新部署

这会产生非常难排查的“我明明 purge 过了，为什么还是旧页面”。

所以我现在的刷新脚本没有简单 sleep 几秒，而是会查询 Cloudflare Pages Deployment API。

只有找到同时满足下面两个条件的部署：

1
environment == production
2
commit_hash == 当前 GITHUB_SHA

并且：

1
latest_stage.status == success

才继续提交 DogeCloud 刷新任务。

换句话说，CDN 刷新前有一道 commit-level barrier：

1
GitHub merge SHA
2
       ==
3
Cloudflare Production SHA

这个设计比“等 30 秒然后 purge”稳很多，因为等待时间不是事实，提交一致性才是事实。

一次发布至少有六种不同的“成功”#

这次之后，我更愿意把静态站发布拆成下面六个状态。

1
CONTENT_READY

1
CONTENT_READY
2
    ↓
3
VALIDATED

1
VALIDATED
2
    ↓
3
INTEGRATED

1
master

1
INTEGRATED
2
    ↓
3
ORIGIN_DEPLOYED

1
ORIGIN_DEPLOYED
2
    ↓
3
EDGE_REFRESHED

1
EDGE_REFRESHED
2
    ↓
3
USER_VISIBLE

1
CONTENT_READY
2
      ↓
3
VALIDATED
4
      ↓
5
INTEGRATED
6
      ↓
7
ORIGIN_DEPLOYED
8
      ↓
9
EDGE_REFRESHED
10
      ↓
11
USER_VISIBLE

1
VALIDATED != USER_VISIBLE

为什么 Ctrl + F5 当时注定无效？#

浏览器强制刷新能解决的是最末端的问题。

比如：

1
生产源站已经是新版本
2
CDN 也已经是新版本
3
只有本地浏览器仍然缓存旧资源

此时强刷有意义。

但这次实际情况是：

1
master 仍然没有新文章

那么从源头开始就是旧状态：

1
浏览器
2
  ↓
3
CDN
4
  ↓
5
Cloudflare Pages Production
6
  ↓
7
master
8
  ↓
9
旧提交

你无论刷新多少次，都只是在更加努力地请求一个本来就没有新文章的生产版本。

这也是排障时非常值得坚持的一点：

从 source of truth 往外查，而不是从浏览器往里猜。

我现在会怎样确认一篇文章真的上线了？#

以后再遇到类似发布，我不会只看一个绿色勾。

第一层先看 PR：

1
gh pr view 40 \
2
  --json state,mergedAt,mergeCommit,statusCheckRollup

需要同时确认：

1
checks = success
2
state = MERGED
3
mergedAt != null
4
mergeCommit != null

第二层确认生产分支真的包含文件：

1
git fetch origin master
2

3
git show \
4
  origin/master:src/content/posts/gemini-37-flash-agent-coding.md \
5
  | head -n 20

这里能直接回答最重要的问题：

“生产 Git 源头到底有没有这篇文章？”

第三层再检查部署：

1
Cloudflare Pages production deployment
2
commit == merge commit
3
status == success

第四层才检查 CDN 刷新任务。

最后，再访问公开站点确认文章进入列表和正文路由。

一个更实用的发布核对表#

我现在会把上线判断写成下面这种布尔条件：

1
Published =
2
    CI_Green
3
 && PR_Merged
4
 && Master_Contains_Content
5
 && Pages_Production_SHA_Matches
6
 && Pages_Production_Success
7
 && CDN_Refresh_OK
8
 && Public_URL_Visible

少任何一项，都不应该轻易说“已经发布”。

如果想让它更像机器可执行的状态：

1
const published =
2
  checksPassed &&
3
  prMerged &&
4
  masterContainsPost &&
5
  pagesCommit === mergeCommit &&
6
  pagesStatus === "success" &&
7
  cdnReady &&
8
  publicSmokeTestPassed;

这里最重要的不是 JavaScript。

而是把模糊的“应该上线了”变成一组可观测条件。

CI/CD 里的 C 和 D，真的不是同一件事#

CI，Continuous Integration，关注的是：

• 新改动能不能与代码库安全整合；
• 测试是否通过；
• 构建是否成功；
• 是否满足合并门槛。

CD 则更接近：

• 什么提交进入哪个环境；
• 什么时候部署；
• 发布目标是否成功；
• 流量现在到底服务哪个版本；
• 失败如何回滚。

实际工程里，这两部分可以由同一个平台实现，也可以完全分开。

我的博客就是一个很直观的例子：

1
GitHub Actions
2
负责主要的验证
3

4
GitHub Merge
5
负责集成到 master
6

7
Cloudflare Pages
8
负责生产构建和部署
9

10
DogeCloud Workflow
11
负责边缘缓存刷新

一个界面上的绿色状态，很难代表整个跨平台链路。

这次事故之后，我反而更喜欢“分层”#

看起来发布环节多了，好像复杂。

但层与层之间只要有明确的不变量，系统反而更容易排查。

比如：

1
PR 层的不变量：
2
五项检查必须全绿
3

4
Git 层的不变量：
5
生产文章必须存在于 master
6

7
Pages 层的不变量：
8
production commit 必须等于 merge SHA
9

10
CDN 层的不变量：
11
只有 origin ready 后才能刷新
12

13
用户层的不变量：
14
最终 URL 必须可见

以后如果文章没出现，只需要问：

1
第一个不满足的不变量在哪里？

而不是一上来同时怀疑 GitHub、Cloudflare、CDN、浏览器、DNS。

这其实就是我越来越喜欢的一种工程排障方式：

不要从症状随机试修复，而要沿状态转移逐层寻找第一个断点。

还可以进一步自动化什么？#

这次最直接的改进方向其实不是“让缓存刷新得更猛”，而是让发布状态更机器化。

例如后续可以考虑：

1. CI 全绿后，如果满足策略，启用 Auto-merge；
2. merge 后记录唯一 production SHA；
3. Pages Deployment API 必须确认同 SHA 成功；
4. CDN 刷新完成后执行站点 smoke test；
5. smoke test 检查目标文章 URL 是否返回 200；
6. 再检查首页 / RSS / Sitemap 是否包含目标文章；
7. 最后才把发布任务标记为完成。

最终发布流水线更像：

1
VALIDATE
2
   ↓
3
MERGE
4
   ↓
5
DEPLOY
6
   ↓
7
REFRESH
8
   ↓
9
VERIFY

而不是：

1
跑完 CI
2
   ↓
3
感觉应该好了

结语#

这次没有什么复杂的框架 Bug。

没有 Cloudflare 神秘缓存。

也没有 Astro 排序失效。

真正的问题只是：

我把“代码已经通过检查”误认为了“代码已经进入生产”。

但也正因为问题简单，它特别值得记录。

随着部署链从一个 Git 仓库扩展到 GitHub Actions、Cloudflare Pages、CDN、DNS 和客户端缓存，“上线”已经不再是一个动作，而是一系列状态迁移。

所以以后当我再看到：

1
✅ Build
2
✅ Tests
3
✅ Type Check
4
✅ Biome
5
✅ Playwright

我不会直接说：

“发布成功。”

我会继续问：

1
Merge 了吗？
2
Production SHA 对吗？
3
源站部署完成了吗？
4
CDN 刷了吗？
5
公开 URL 真能看到吗？

CI 全绿是一张合格证，不是一张生产环境的到货签收单。