外观
15 - 反向代理与网关错误
前置阅读:05 - connect与应用完成、12 - HTTP协议、14 - 每跳TLS。整体预算见17。
状态码语义采用 RFC9110;Nginx、Envoy、Ingress 控制器与云负载均衡的错误触发和重写规则,取决于部署版本与配置。
error_page是 Nginx 的错误页处理配置;它、重试规则以及无可用端点时的处理都属于产品行为,不能当作 HTTP 的统一规定。
摘要
反向代理代表后端服务接收客户端请求,再将请求转发给上游服务。502、503、504 描述的是生成响应的节点遇到了什么问题,不能直接指出业务根因。排障需要先理解代理两侧的独立连接,再确定错误由谁生成、发生在哪次尝试、耗尽了哪段预算。
1. 现象:客户端504,应用却说早已200
应用打印“200”与客户端收到响应是两个不同事件。业务可能已经完成,但响应还没写出,或网关已经停止等待;应用开始处理得太晚,也会留下更少的响应时间。
还要确认日志是否对应同一次尝试。Request ID(请求标识)用于关联请求,Attempt(尝试)表示一次具体的上游调用。网关重试时,同一个请求标识可能对应多次尝试,只看到最后一次的 200 无法解释前一次失败。客户端自身的预算也可能更早耗尽,此时应区分收到 HTTP 504 与发生本地超时。
状态码还可能由上游直接返回、代理拦截重写或缓存。先定位生成节点与对应Attempt,再决定查连接、响应语法、资源还是业务。
2. 原理:至少两跳,不共享同一连接状态
text
Client ←→ Gateway:下游连接、TLS、HTTP版本和资源
Gateway ←→ Upstream:独立连接、TLS、协议、池与预算
Upstream ←→ Dependency:再一层独立调用下游是请求发起方,上游是网关转发请求的目标服务。本文讨论终止客户端连接、再向上游建立或复用连接的代理:网关对下游是服务端,对上游则是客户端。
两侧连接独立,所以客户端使用 HTTP/2,不证明上游也使用 HTTP/2(H2)。客户端验证网关证书成功,也不证明上游 TLS 正确;若上游使用 mTLS(双向 TLS 认证),还需检查网关提供的客户端证书。NAT(网络地址转换)可以改写地址、端口,但 TCP 代理两侧有独立的序列号空间,不能直接用相同序列号关联两侧报文。
数据也不一定立刻穿过网关。连接池保存可复用的连接;请求或响应缓冲暂存数据;流式转发在数据陆续到达时推进。下游消费速度变慢时,背压会限制继续读取或发送,避免数据无限积压。这些机制会影响内存、临时文件、首字节到达时间和取消后的资源释放。
3. 状态码:语义、来源与产品映射
| 状态 | HTTP语义主线 | 产品候选映射,不是唯一根因 |
|---|---|---|
| 502 | 网关/代理从上游得到无效响应 | 某实现可将连接重置(RST)、TLS 失败、无效响应头(Header)等映射为 502 |
| 503 | 服务器暂时不能处理请求,如过载/维护 | 无可用端点(Endpoint,即后端地址)、资源不足或策略拒绝;也可由源站直接返回 |
| 504 | 网关/代理未及时从相应上游获得响应 | 建连/响应阶段预算,具体映射依实现 |
503 也可以由业务服务器产生。429 与 503 用于限流时,仍需符合各自语义和产品规则,不能任意互换。Retry-After 响应头提示再次尝试的时间,但不要求客户端一定重试,还需考虑幂等、预算和策略。幂等指重复执行不会产生额外的业务效果,例如不能因重试而重复扣款。客户端自行超时可能根本没有 HTTP 响应,本地 TimeoutException 不等于“收到 504”。
Server/Via/自定义错误页可作为来源线索,但可能隐藏或改写,需代理和上游日志证实。日志缺失可能采样、路径不匹配或采集故障,不能无条件推出请求没到达。
4. 实现:阶段超时不等于总Deadline
Deadline 是整个操作必须结束的截止时间;阶段超时只限制某个环节。Nginx 的 proxy_connect_timeout 约束与上游建立连接,proxy_send_timeout 约束向上游发送请求时相邻写操作的等待,proxy_read_timeout 约束读取上游响应时相邻读操作的等待。后两者不能直接当作整个请求或响应的总时长限制。
例如,上游每次都在读超时到期前发送少量数据,响应仍可能持续很久并占用资源。因此,还需要独立考虑总截止时间。
Nginx 的 upstream_connect_time 记录相应上游连接建立耗时,SSL/TLS 上游还涉及握手时间。响应头与响应耗时字段、空值和多次尝试的分隔规则,需要按部署版本的模块文档解释。网关耗时可能已经包含应用处理时间,不能再与应用处理跨度直接相加,否则会重复计算。
示意预算:入口剩余1000ms,扣本地与回传预留后给本次尝试700ms;尝试耗时650ms后,不能重新给重试700ms。各层按剩余预算执行,connect、读取间隔、写入和总操作保护各自定义,见分布式11。
| 机制 | 收益 | 风险与边界 |
|---|---|---|
| 请求缓冲 | 暂存请求数据,便于控制向上游发送的过程 | 内存/磁盘、延迟、取消和重试条件 |
| 响应缓冲 | 吸收上下游速度差 | 排队、首字节、流式接口延迟 |
| 上游重试 | 某些暂时故障恢复 | 执行结果未知、重复写、多层放大 |
| 连接复用 | 减少建立成本 | 失效连接、旧地址、池等待 |
能否重试还取决于请求体(Body)是否能再次发送,以及响应是否已向下游提交。即使代理配置允许重试,业务也可能已经执行;重新发送写请求可能造成重复写入,因此还需业务幂等保障,见分布式13。
5. 教学时序:200日志为什么不是反证
text
以下仅推演,非生产日志:
0ms:入口收到请求,预算1000ms
150ms:网关开始尝试1,上游连接和排队消费预算
900ms:应用完成业务,打印“200”,但Body尚未完成回写
1000ms:网关总预算耗尽,若尚未提交下游Header可生成错误响应
1100ms:应用继续写,可能发现连接已关闭;业务可能已经提交这个推演假设网关具有 1000ms 的总预算,不表示单个 Nginx 读超时就能实现该预算。应用的 200 日志不证明网关及时取得完整响应。
若下游响应头已经发送,状态码就已提交,代理通常无法再将同一个响应改成另一个状态码。这时可能只能终止连接,或终止 HTTP/2 的流(Stream,即连接内承载请求与响应的逻辑通道)。所以超时不一定表现为带有可读响应体的 504。
验证网关错误需要让请求实际经过代理,再观察代理如何处理上游故障。让源站直接返回固定状态码,只能验证客户端收到这些状态码后的行为;12的本地HttpServer也不能替代网关实验。
6. 可执行验证计划:一次改一个故障条件
在已获授权的测试代理与上游环境中,先保存版本、完整有效配置、路由、证书和日志采样策略,再记录低流量正常请求的基线。Nginx 可用 nginx -v 查看版本、nginx -t 检查配置;展开配置可能包含秘密,需要控制访问和留存。云平台或其他代理应使用各自的诊断字段。
| 注入条件 | 预期线索 | 验收/恢复 |
|---|---|---|
| 测试上游停止监听 | connect失败及目标地址 | 实际状态码按实现记录;恢复监听和同路径请求 |
| 测试上游证书名称不匹配 | 上游TLS原因链 | 不关闭证书验证,恢复正确的 SAN(证书主体备用名称)与访问名称 |
| 测试上游延迟首响应 | header等待与预算耗尽 | 控制延迟、恢复基线,不改生产超时 |
| 测试路由没有健康端点 | endpoint/选择日志 | 记录生成节点,恢复测试端点 |
| 测试响应慢消费/流式 | 缓冲、读取间隔、取消 | 区分间隔超时和整体截止,验证资源释放 |
使用受控 GET 请求与测试数据,限制次数和总时长,并确认 GET 对应的业务适合重复执行。非幂等操作只在隔离业务模型中验证,不重复真实订单。每次只注入一个故障条件,记录准确配置、预期线索和能够否定假设的证据。恢复前确认测试对象归属,恢复后以同路径请求检查基线,方法见A。
以下是 Bash 环境下的客户端探测示例,需要安装支持这些参数的 curl,并将 gateway.example.test 替换为授权测试服务:
bash
curl --connect-timeout 2 --max-time 5 -sS -D - -o /dev/null -w 'code=%{http_code} connect=%{time_connect} first=%{time_starttransfer} total=%{time_total}\n' https://gateway.example.test/health预期输出包括响应头,以及 code、connect、first、total 字段;具体状态码和耗时取决于测试环境。--connect-timeout 2 限制连接阶段,--max-time 5 限制整体操作。
时间字段是从操作开始计算的累计时间点:connect 对应连接建立,first 对应首字节,total 对应操作结束,不能直接相加作为互不重叠的阶段耗时。http_code 为 000 等情况不是标准 HTTP 状态码,还需结合退出码和错误信息判断。客户端测量只能展示它看到的过程,与每一跳日志对齐后才能定位原因。
7. 排障:三层日志加每次尝试
| 层次 | 最低记录 | 解释限制 |
|---|---|---|
| 客户端 | 请求ID、Attempt、目标、连接复用、错误、预算 | 最终成功掩盖前次失败 |
| 网关 | 路由、选中上游、每次状态/阶段耗时、生成原因 | 字段按产品,可能多个上游值 |
| 应用 | 到达时间、排队与执行耗时、依赖调用、业务提交与响应回写、取消 | “处理完成”不证明响应送达 |
客户端有记录但网关没有时,先检查请求路径和日志覆盖。网关有记录但应用没有时,检查上游连接、TLS 和应用日志采样,不能直接认定请求未到达。
应用业务已提交而网关失败时,客户端可能无法确认执行结果。应通过结果查询、幂等或去重机制处理,避免盲目重试造成重复操作。在两处抓包只能观察各自连接的边界,跨代理关联仍需请求标识和时序证据,见21。
重启后恢复只说明运行状态发生了变化。确认根因需要解释故障阶段与时序,并在只改变一个条件后复验。修复后还要观察连接池、线程、错误率、P99(99% 请求的耗时不超过该值)和下游负载,避免错误减少却把压力转移到其他层,综合方法见22。
8. 工程取舍、导航与依据
端口可连接、健康探针通过、服务就绪与业务执行成功,是不同层次的信号。就绪状态(Readiness)表示实例是否适合接收流量;没有可用端点时,应检查服务注册与就绪状态。将探针改成昂贵的全依赖调用会增加检查本身的负载,需要权衡。
Kubernetes 中的 Ingress 是描述外部 HTTP 路由的资源,具体转发由 Ingress 控制器实现。控制器版本与资源状态的排查见云原生14 - Ingress,这里的通用代理模型仍然适用。
- 控制面对照:分布式07;多层重试:分布式12。
- RFC9110:状态码语义,不规定全部产品错误映射。
- Nginx proxy模块:缓冲、超时和重试语义;不把网页当前默认值当现场配置。
验收点:定位状态码生成者与对应尝试,对齐连接、业务提交和回写边界,不以错误码直接宣判根因。