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

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

原文: https://fdetimes.net/zh/guides/debug-integration-customer-network-dns-proxy-cors/

到客户现场的第一周，一个在你笔记本上跑得好好的集成，先返回 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 请求头：

```bash
# 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 请求头，控制台里不能有红色报错。

**要点:** curl 调用成功只能说明网络通路是通的。CORS 由浏览器执行，必须在浏览器里再检查一遍。

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

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

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

```js
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”时，面试前准备好这样一个故事。

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

**本周动手试试:**

- 在工作机上，通过内部代理（如果有）用 curl -v 访问一个外部 HTTPS API，找到 CONNECT 那一行以及代理返回的状态码。
- 对你负责的某个 API，用 curl -X OPTIONS 加上 Origin、Access-Control-Request-Method 和 Access-Control-Request-Headers 请求头模拟预检，检查响应是否包含所需的全部 Access-Control-Allow-* 头。
- 在嵌有 iframe 的页面上打开 DevTools，进入 Application &gt; Cookies，记下每个会话 Cookie 的 SameSite、Secure 和 Domain 属性。

## 信源

- [Overview of HTTP - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)

- [Proxy servers and tunneling - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling)

- [X-Forwarded-For header (MDN Web Docs, HTTP Reference)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For)

- [Cross-Origin Resource Sharing (CORS) - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)

- [Using HTTP cookies - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies)

- [HTTP response status codes - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)

- [List of HTTP status codes - Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)

- [HTTP/3 From A To Z: Core Concepts](https://www.smashingmagazine.com/2021/08/http3-core-concepts-part1/)

- [DNS - Glossary | MDN](https://developer.mozilla.org/en-US/docs/Glossary/DNS)
