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

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 / 分支过滤若本端已证明可达,假设层级可能错了
合并后干等自动触发自动路径缺手动旁路,研发直接阻塞

三条硬规则先钉死——删掉门铃比喻也能复述给同事:

  1. Webhook 是第三条平面:源站出站 ≠ 本机入站可达 ≠ 流水线监听器健康。
  2. 本端 202 + 本机可达,不能证伪厂商出口故障。
  3. 自动路径必须配手动旁路,且演练过;旁路勿绕过必要门禁。

问题空间:三条平面,不是一条「网络」

云代码托管向你的 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 经边缘入口到监听器再消费;本机 curl 只覆盖入站段
三平面:托管出站 webhook 经边缘入口到监听器再消费;本机 curl 只覆盖入站段 · 点击查看 SVG 原图

业界常见模式对照

自动 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假设失控先补对照,再动边界
排障分流:托管无状态且本机 202 时升假设到出口并启用手动旁路
排障分流:托管无状态且本机 202 时升假设到出口并启用手动旁路 · 点击查看 SVG 原图

代价要当着写:手动旁路能救发版,也会变成「大家再也不修自动路径」的温床——所以恢复验收是合同的一部分,不是可选彩蛋。


反模式

下面几条会把「分段故障」修成「全场乱改」。

  1. 本机 curl 通就断言「不是网络问题」
    忽略了托管出口。你只证明了入站段。

  2. 故障期大改 WAF / 权限却无对照实验
    改了仍 NETWORK ERROR 也不回滚假设,边界越改越脏。

  3. 无手动触发合同,合并后干等
    自动门铃一坏,整条发布链停摆。

  4. 把无关的触发模板 / 过滤器缺失当成同一根因
    投递平面绿了,消费合同红,是另一张工单;揉在一起会修错层。

  5. 旁路绕过分支保护与审批
    为了「先发出去」拆掉门禁,故障期债务变成日常通道。

  6. 健康探针只打本端,却当成端到端 SLO
    探针绿掩盖托管出站红——看板撒谎。


选型结论

  1. 先画清三平面:托管出站 / 边缘入站 / 流水线消费;成功标准分开写。
  2. 本端可达证据与托管投递日志对照,再动 WAF、token、过滤器;别用本机 202 证伪出口故障。
  3. 默认 A+C:Webhook 自动 + 已演练的手动 / 脚本旁路;旁路仍走必要门禁。
  4. 观测拆开:本端 4xx/5xx vs 托管侧无状态 NETWORK ERROR;恢复后做一次「只合并不手动」验收。
  5. 长期可评估轮询或双通道;接受延迟、配额与去重代价,不把双通道当成零成本保险。

系列导航

  • 上一篇:/blog/avatar_upload_architecture/(seriesOrder 8)— 小图上传的通道与对象合同
  • 本篇(seriesOrder 9):CI Webhook 投递三平面与手动旁路选型