Web 服务器与网关 / 系统课时
配置代理错误回退
配置代理错误回退
本课解决反向代理访问失败时的用户体验和故障隔离问题,通过 proxy_intercept_errors、命名位置和备用页面配置,让 Nginx 在合适场景接管错误响应,同时保留应用自身的业务错误处理能力。
学习目标
- 理解 Nginx 接管上游错误响应的条件。
- 掌握错误页面和备用位置的配置方法。
- 能够判断网关错误处理与应用错误处理的边界。
理解代理错误处理边界
反向代理中的错误并不都应该由 Nginx 处理。认证失败、业务校验失败等应用错误通常需要保留应用响应,而网关无法连接上游、服务不可用等基础设施错误更适合由 Nginx 提供统一回退。
proxy_intercept_errors 可以让 Nginx 拦截指定 HTTP 状态码,并按照 error_page 规则返回备用内容。
配置错误拦截与备用页面
下面示例将上游服务返回的 502、503、504 交给 Nginx 处理,并跳转到命名位置生成统一响应。
nginx
server {
listen <PORT>;
location / {
proxy_pass http://backend;
proxy_intercept_errors on;
error_page 502 503 504 = @gateway_fallback;
}
location @gateway_fallback {
default_type text/plain;
return 503 "service temporarily unavailable";
}
}预期输出
text
HTTP/1.1 503 Service Unavailable
service temporarily unavailable命名位置不会直接暴露 URL 路径,只作为内部跳转目标使用,适合集中管理网关级错误响应。
选择回退策略
错误回退应根据故障类型设计。对于短暂网络异常,可以返回统一提示并配合客户端重试;对于业务异常,应让应用返回详细错误信息,避免网关覆盖关键上下文。
实际生产环境中,还可以结合静态错误页、监控标记和请求 ID,让用户看到稳定提示,同时方便运维定位。
验证错误处理链路
测试时需要模拟不同状态码,确认只有目标错误被拦截。可以通过临时修改 upstream、关闭后端实例或使用测试接口返回错误码进行验证。
排查问题时重点检查 error_page 状态码范围、proxy_intercept_errors 是否开启,以及备用 location 是否能够正常返回内容。
按自己的节奏,确认真正理解。