CI Webhook 投递三平面:托管 NETWORK ERROR ≠ 本端不可达

Hello,我是小兔大白糖。 合并主干后自动 CI 没动静,托管控制台一排 NETWORK ERROR,本机对同一 URL 却稳拿 202——下一秒会议室里有人开始改 WAF、改 token、改分支过滤。写成这篇,给要做 CI Webhook 投递可靠性调研 的初中级后端 / 平台同学:不是某次故障工单,而是可复述的投递三平面心智模型。
说明:文中「托管平台」「监听器」「手动旁路」泛指云代码托管出站 webhook、集群或网关侧入口、以及控制台 / 脚本手动触发流水线。
NETWORK ERROR、202、伪流程均为教学脱敏示意,不绑定某一家控制台文案或某套 Triggers 实现。不声称任何厂商「官方内部就是这样」。
估计阅读时间:8 分钟
目录
为什么现在要关心
Webhook 自动 CI「通了」要三条平面同时绿:托管出站投递、边缘入站可达、流水线消费成功——本机 curl 通只覆盖中间那一段。
现场里常见误伤,几乎都来自把三件事揉成「网络有问题 / 没问题」一句:
| 你看到的现象 | 常见真相 |
|---|---|
托管侧大量 NETWORK ERROR,无 HTTP 状态 | 托管出口到你入口这一段没走完;不等于你监听器一定挂了 |
本机 curl 同 URL 得 202 | 只证明入站路径此刻可达;证伪不了托管出口故障 |
| 监听 Pod / 进程健康 | 本端健康 ≠ 托管出站成功 |
| 一上来改 WAF / token / 分支过滤 | 若本端已证明可达,假设层级可能错了 |
| 合并后干等自动触发 | 自动路径缺手动旁路,研发直接阻塞 |
三条硬规则先钉死——删掉门铃比喻也能复述给同事:
- Webhook 是第三条平面:源站出站 ≠ 本机入站可达 ≠ 流水线监听器健康。
- 本端
202+ 本机可达,不能证伪厂商出口故障。 - 自动路径必须配手动旁路,且演练过;旁路勿绕过必要门禁。
问题空间:三条平面,不是一条「网络」
云代码托管向你的 webhook 入口打 repo:push 一类事件;故障期常见「托管投递失败」与「本端入站成功」同时成立。
典型排障陷阱:控制台红、本机绿、监听健康——于是人在本端配置上打转。若本端已用对照实验证明「同 URL 可入站且返回接受态」,下一步应把假设升到托管出口到你入口的路径,并先打开手动触发,别把发版卡死在「等自动门铃」。
后端类比:连接池「本机能连上」不等于「对端出站链路今天通」;线程池「worker 还活着」不等于「上游任务已经投进来」。类比局限:池子解释「分段可达」;解释不了各托管商投递重试窗口、出口 IP 段与边缘 ACL 的具体字段名——那些按厂商公开文档另开合同。
心智模型:门铃 vs 自己按门铃
Webhook 像邮差按门铃;本机 curl 像你自己走到门口按一下。门铃坏了不代表屋子没人;屋子有人也不证明邮差今天能到门口。
- 自己按门铃(curl / 内网探测):验证「门、铃、屋里的人」这一段——边缘入口、监听器、鉴权是否当场接得住。
- 邮差按门铃(托管出站 webhook):还多一段「邮差从邮局走到你家门口」——托管出口、公网路径、对方出口策略。
- 屋里开工(流水线消费):铃响了还要有人按合同开工;Trigger / 过滤器 / 模板缺失是另一类故障,别和投递平面混成一根因。
类比局限:门铃解释「分段证明」;解释不了 WAF 规则语法、签名算法细节,以及「手动旁路」是否仍要过同样的分支保护与审批——旁路解决的是触发通道,不是门禁合同本身。
精确定义:投递三平面
硬规则:三条平面合同不同;只绿一条,不能宣称「自动 CI 通了」。
| 平面 | 职责 | 典型形态 | 成功标准 |
|---|---|---|---|
| 托管出站(Host egress) | 源站主动投递事件 | 云代码托管 webhook 投递日志 | 投递记录出现 HTTP 状态,而非仅 NETWORK ERROR / 超时无状态 |
| 边缘入站(Edge ingress) | 请求进入你的边界 | DNS、LB、WAF、API 网关、Ingress | 同 URL 从可信路径拿到接受态(如 2xx / 202) |
| 流水线消费(Pipeline consume) | 事件变成一次构建 / 部署 | webhook 监听器、过滤器、流水线触发 | 出现预期 Pipeline / Workflow;失败可归因到消费合同 |
三平面可以协作,但证据链不同:
- 出站回答:「托管有没有把请求送出去、对方有没有 HTTP 层响应。」
- 入站回答:「请求打到你的 URL 时,边界与监听器接不接得住。」
- 消费回答:「接住之后,有没有按分支 / 事件类型开工。」
把「自动 CI 静默」只当成 WAF 或 token 问题,等于用「屋里有没有人」解释「邮差有没有出门」。
业界常见模式对照
自动 webhook 省运维感,但厂商出口一抖就会静默停;分享向推荐「Webhook + 已演练的手动旁路」,并在观测上拆开本端 5xx 与托管侧无状态错误。
| 模式 | 做法 | 代价 |
|---|---|---|
| A. 只靠托管 webhook | 合并即触发,零手动感 | 托管出口或投递通道抖动时,CI 静默停;排障易误伤本端配置 |
| B. Webhook + 只测本端健康 | 探针打监听器 / 本机 URL | 发现本端挂;发现不了托管出口故障 |
| C. Webhook + 手动 / 脚本旁路 | 控制台「重投 / 测试投递」、脚本模拟 payload、或直接手动跑流水线 | 故障期可继续发版;要纪律——旁路勿绕过必要门禁(审查、环境保护、密钥范围) |
| D. 轮询托管 API 代替 webhook | 定时拉新提交 / 用 API 触发 | 不依赖托管出站;换来延迟、配额与鉴权面 |
分享向默认组合:A + C。观测上至少能区分:
- 本端 4xx / 5xx:优先查鉴权、过滤器、监听器与消费合同。
- 托管侧
NETWORK ERROR/ 无 HTTP 状态:在本端入站证据已绿时,优先升假设到出站路径,而不是继续拧本端旋钮。
长期可评估 D 或「webhook + 轮询」双通道;双通道的代价是重复触发与去重合同——要写清幂等键(commit SHA、delivery id),否则一次合并跑两遍。
排障对照:本端 202 证不了什么
本端可达只能证伪「屋子没人」;证伪不了「邮差今天没到门口」。改基础设施前先做对照实验。
教学向对照顺序(脱敏示意,不是某厂 runbook):
1. 看托管投递日志:有 HTTP 状态,还是仅 NETWORK ERROR / 超时?
2. 本机或可信探测机 curl 同 webhook URL(教学:期望接受态如 202)
3. 若 2 绿而 1 无状态 → 假设升到托管出口路径;启用手动旁路
4. 若要动 WAF / 防火墙:改前改后用「托管重投」对照;仍 ERROR 则回滚该假设
5. 恢复后做一次「只合并不手动」验收,确认自动路径真的回来了| 证据组合 | 更可能落在 | 先做什么 |
|---|---|---|
托管有 5xx,本机也 5xx | 入站 / 监听器 | 修本端,再谈出口 |
托管 NETWORK ERROR,本机 202,监听健康 | 出站路径 | 旁路发版 + 升假设到托管出口 |
托管 2xx,但无流水线 | 消费合同 | 查过滤、模板、权限——别当网络问题 |
| 什么证据都没有就改 WAF | 假设失控 | 先补对照,再动边界 |
代价要当着写:手动旁路能救发版,也会变成「大家再也不修自动路径」的温床——所以恢复验收是合同的一部分,不是可选彩蛋。
反模式
下面几条会把「分段故障」修成「全场乱改」。
-
本机 curl 通就断言「不是网络问题」
忽略了托管出口。你只证明了入站段。 -
故障期大改 WAF / 权限却无对照实验
改了仍NETWORK ERROR也不回滚假设,边界越改越脏。 -
无手动触发合同,合并后干等
自动门铃一坏,整条发布链停摆。 -
把无关的触发模板 / 过滤器缺失当成同一根因
投递平面绿了,消费合同红,是另一张工单;揉在一起会修错层。 -
旁路绕过分支保护与审批
为了「先发出去」拆掉门禁,故障期债务变成日常通道。 -
健康探针只打本端,却当成端到端 SLO
探针绿掩盖托管出站红——看板撒谎。
选型结论
- 先画清三平面:托管出站 / 边缘入站 / 流水线消费;成功标准分开写。
- 本端可达证据与托管投递日志对照,再动 WAF、token、过滤器;别用本机
202证伪出口故障。 - 默认 A+C:Webhook 自动 + 已演练的手动 / 脚本旁路;旁路仍走必要门禁。
- 观测拆开:本端
4xx/5xxvs 托管侧无状态NETWORK ERROR;恢复后做一次「只合并不手动」验收。 - 长期可评估轮询或双通道;接受延迟、配额与去重代价,不把双通道当成零成本保险。
系列导航
- 上一篇:/blog/avatar_upload_architecture/(seriesOrder 8)— 小图上传的通道与对象合同
- 本篇(seriesOrder 9):CI Webhook 投递三平面与手动旁路选型