FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

客户网络上演示崩了,问题不在代码

407、504 和一行红色 CORS 报错分属不同层,按 DNS、代理、状态码、浏览器的顺序排查最快。

分享微博

要点速览

  • 按顺序问四个问题:域名解析到哪里?连接能否出网?HTTP 状态码由谁返回?浏览器是否放行?
  • 407 来自代理,401 来自应用。502 或 504 表示中间某个网关收到了错误响应,或没能及时收到响应。
  • CORS 由浏览器执行,curl 调用成功说明不了 CORS 的问题。OPTIONS 预检请求不带 Cookie,要求 Cookie 的安全层可能会把它拦下。
流程式信息图:请求从访客网络中的一台机器发往你的 API,依次经过四层。第 1 层 DNS:域名是否正确解析,在访客网络的机器上用 nslookup 检查。第 2 层代理与防火墙:CONNECT 被拒或基于 UDP 的 HTTP/3 被拦,检查 443 端口和白名单。第 3 层 HTTP 状态码:407 来自正向代理,502、504 和 520 来自网关或反向代理,对比网关超时与 API 响应时间。第 4 层浏览器(高亮显示):CORS 错误、Cookie 未发送,在 DevTools 中检查预检请求、Cookie 请求头和 SameSite。注:curl 能通只说明网络是通的,CORS 由浏览器执行。
四层,四个问题:先确定故障出在 DNS、代理与防火墙、HTTP 状态码还是浏览器,再动手修复,并把证据交给对应的团队。

到客户现场的第一周,一个在你笔记本上跑得好好的集成,先返回 407,又返回 504,接着控制台里冒出一行红色的“CORS”。代码一行没改,变的是网络。

前线部署工程师(FDE)经常碰到这种情况,因为你不是部署到一个自己掌控的干净云环境,而是部署进别人的网络。这张网络里有企业代理、防火墙、反向代理和 SSO Cookie,每一样都归不同的团队管。最快打通阻塞的,往往不是技巧最多的人。

而是能在动手修之前,先说清楚故障出在哪一层的人。

一个请求要经过多少方之手?

HTTP 是客户端-服务器协议:请求由用户代理发出,或由代表它的代理发出。MDN 指出,客户端与服务器之间有许多机器,统称为代理,充当网关或缓存。请求在发出之前,还得先由 DNS 这一分层、去中心化的命名系统把域名转换成地址。

读客户的网络拓扑图时,先把两类代理分开。正向代理位于客户端一侧,隐藏客户端身份,银行员工上网走的就是这种代理。反向代理位于服务器一侧,隐藏服务器身份,也就是挡在你的 API 或客户自家 API 前面的那一层。

由此得到一个四层模型,对应四个必须严格按顺序提出的问题。从客户网络内部看,域名是否解析到正确的地方?连接能否出网,还是被代理和防火墙拦住?返回的是什么 HTTP 状态码,由谁发出?

最后一个问题留给浏览器:它是否允许页面读取响应、发送 Cookie?

状态码告诉你谁在应答

最常见的错误,是以为所有错误码都是后端发的。407 看着像 401,但它的意思是需要向代理进行认证。看到 407,说明企业代理要凭据,工单应该交给网络团队,而不是应用团队。

502 和 504 同样指向中间层。应答你的机器充当网关或代理,它从上游收到了错误响应,或者没能及时收到响应。Cloudflare 还多出一个 520,这个码不在标准里。

看到 504 时,先测出网关的超时时间和 API 的耗时,再考虑优化查询。

对 HTTPS 来说,位于 HTTP 代理之后的客户端必须用 CONNECT 方法建立隧道。并非所有代理都支持 CONNECT,有些只放行 443 端口。

连接层还有一个坑。防火墙和各类中间设备普遍难以升级,有些会被配置成拦截任何带陌生扩展的流量。QUIC 和 HTTP/3 跑在 UDP 上,在客户网络上可能被拦。客户端必须始终能回退到基于 TCP 的 HTTP。

症状 可疑层 首先检查
域名无法解析,或指向错误 IP 第 1 层:DNS 在客户网络内部的机器上运行 nslookup
CONNECT 被拒绝 第 2 层:经代理、防火墙的连接 目标端口是否为 443,主机是否在白名单中?
407 第 3 层:HTTP 状态码,由正向代理返回 向网络团队询问如何向代理认证
502、504、520 第 3 层:HTTP 状态码,由网关或反向代理返回 对比网关超时与 API 处理时间
CORS 错误,Cookie 未发送 第 4 层:浏览器 DevTools 的控制台和 Network 面板:预检响应、Cookie 请求头、Cookie 属性(curl 无法复现这一层)

示例:嵌在银行门户里的小组件

假设这样一个场景。客户是一家银行,内部门户位于 portal.customer.vn。你从 app.yourcompany.com 嵌入一个小组件,组件用会话 Cookie 调用 api.yourcompany.com 上的 API。在你的笔记本上一切正常,到了银行员工的机器上,组件一片空白。

坐到客户网络内部的一台机器前,用三条命令逐层排查。由于组件发送的是带 JSON 请求体的 POST,模拟预检时也必须像浏览器那样声明 Content-Type 请求头:

# 1. 在客户网络内部,域名解析到哪里?
nslookup api.yourcompany.com

# 2. 经企业代理访问:查看 CONNECT 那一行以及代理返回的状态码
curl -v -x http://proxy.customer.vn:8080 https://api.yourcompany.com/health

# 3. 完全按浏览器的方式模拟预检请求
curl -v -X OPTIONS https://api.yourcompany.com/v1/data \
  -H "Origin: https://portal.customer.vn" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type"

(注释含义:1. 在客户网络内部,域名解析到哪里?2. 经企业代理访问:查看 CONNECT 那一行以及代理返回的状态码。3. 完全按浏览器的方式模拟预检请求。)

如果命令 2 返回 407,你就知道该找谁了。如果命令 2 正常,命令 3 却拿到一个来自防火墙错误页的 403,元凶就找到了。

MDN 特别强调,预检请求从不携带凭据。所以,要求每个请求都带 Cookie 的安全层也会拦下 OPTIONS 调用。浏览器随后报出 CORS 错误,而你的后端其实毫无问题。

假设诊断到此为止,Application 面板还显示会话 Cookie 没有声明 SameSite。那么根因落在代码之外的两处:防火墙因预检请求不带 Cookie 而拦截它;Cookie 被当作 Lax 处理,iframe 发出的请求不会带上它。

修复办法是请网络团队放行发往 api.yourcompany.com 的 OPTIONS 请求,不要求 Cookie;同时按下文所述,用 SameSite=None; Secure 重新设置 Cookie。

最后一步是在银行员工的机器上确认,用浏览器而不是 curl。在 Network 面板中,OPTIONS 预检必须成功并带有 Access-Control-Allow-* 响应头,真正的 POST 请求必须带 Cookie 请求头,控制台里不能有红色报错。

CORS 和 Cookie:浏览器是最后一道关

CORS 通过 HTTP 头工作,服务器用它声明哪些源可以在浏览器中读取自己的数据。HTTP 本身是无状态的,有状态的会话靠 Cookie 建立。问题在于,跨源调用 fetch 或 XHR 时,浏览器默认不发送凭据,也就是不发送 Cookie。

对示例中的小组件,客户端必须显式开启凭据:

fetch('https://api.yourcompany.com/v1/data', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});

服务器端的响应必须包含 Access-Control-Allow-Credentials: true,真正的请求才能使用 Cookie。要明确写出门户的源,而不是把门敞开:

Access-Control-Allow-Origin: https://portal.customer.vn
Access-Control-Allow-Credentials: true
Set-Cookie: session=abc123; SameSite=None; Secure; Domain=yourcompany.com

Set-Cookie 这一行最容易被忽略。没有声明 SameSite 的 Cookie 会被当作 Lax。在银行门户这样的跨站 iframe 里,会话“消失”往往正是这个原因。SameSite=None 必须同时设置 Secure 才会生效。

Domain 属性决定哪些服务器能收到 Cookie。设置为 yourcompany.com,Cookie 就会发往该服务器及其子域名,例如 api 和 app。

让你白费一周的错误

第一个是信任 X-Forwarded-For 请求头。API 位于客户的反向代理之后时,你会想从这个头里取真实 IP,用于限流或访问控制。MDN 说得很清楚:凡是与安全相关的用途,只能依赖可信代理添加的 IP。

如果天真地取第一个值,任何人伪造一个请求头就能绕过你的限制。

第二个是笼统地要求“开一下防火墙”。银行网络团队需要知道确切的主机、端口和协议,以及必须放行 OPTIONS 方法。按上面的四层表格写出的申请,比“API 坏了,能帮忙看看吗?”批得快得多。

第三个是看到 504 就去改后端。先确认是哪台机器返回的。最后一个是想当然地认为客户端能用 HTTP/3。客户的防火墙可能被配置为拦截陌生流量,跑在 UDP 上的 QUIC 很可能就在其中。

对转岗 FDE 的开发者来说,这项技能很容易展示。简历上别写“排查网络问题”这种泛泛之词,而是逐层讲清一次事故:症状是什么,你如何把范围缩小到 DNS、代理、HTTP 状态码或浏览器,又是如何修复的。

岗位描述里出现“enterprise network”“on-premise”或“customer environment”时,面试前准备好这样一个故事。

下次客户现场的小组件一片空白,别先打开代码。打开终端,按顺序走完四层,再把证据交给需要修复的团队。

这篇文章对你有帮助吗?

9 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力登录客户服务器的头几分钟,从 ssh -J 开始从笔记本经堡垒机跳转,私钥不留在客户机器上;再用短脚本先记下服务器状态。