在Nginx作为反向代理服务器的场景中，准确区分客户端收到的响应和后端服务实际返回的状态，是运维和开发排查故障的基本功。Nginx内置的$upstream_status变量专门用于记录每一次请求中后端上游服务（upstream）所返回的HTTP状态码，它和面向客户端的$status变量有着本质区别。理解这个变量的生成机制，能够帮我们在复杂调用链中迅速锁定问题发生在代理层还是业务层。
一、$upstream_status变量的底层赋值逻辑
Nginx在处理反向代理请求时，会先根据配置的upstream块选择一台后端节点，建立或复用连接，然后向后端发送请求并等待响应。当后端返回响应状态行（如HTTP/1.1 404 Not Found）且Nginx成功解析后，就会将该状态码写入$upstream_status。如果一次请求过程中尝试了多个后端（例如第一个节点连接超时后重试第二个），该变量可能包含多个以冒号分隔的状态码，比如502:200，表示第一次失败第二次成功。
与$status不同，后者是Nginx最终发送给客户端的状态码，可能因为Nginx自身的错误拦截、rewrite规则或limit模块而发生变化。例如后端返回500，但Nginx配置了error_page 500 /custom.html并返回200页面，此时$status是200，而$upstream_status依旧是500。这种差异正是我们判断“是不是后端真挂了”的核心依据。
还有一个容易忽略的点：当使用keepalive保持后端长连接时，如果连接从连接池取出后并未真正发出请求（例如被某些访问控制提前终止），$upstream_status可能为空。此时不能简单认为后端正常，而要结合$upstream_connect_time和$upstream_response_time综合判断。在下面的配置示例中，我们同时记录了多个上游相关变量：
log_format proxy_detail '$remote_addr - $upstream_addr $upstream_status $status '
'rt=$request_time urt=$upstream_response_time '
'uct=$upstream_connect_time';
server {
listen 80;
access_log /var/log/nginx/access_proxy.log proxy_detail;
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
}
}
二、在日志与监控中实践后端状态码分析
把$upstream_status写进访问日志只是第一步，更重要的是建立基于它的监控视角。很多团队只监控$status的5xx比例，结果后端大面积异常却被Nginx的自定义错误页掩盖成200，监控毫无波动。正确的做法是在日志采集系统（如ELK或Loki）中单独提取该字段，并对非空格且非2xx/3xx的值进行告警。
我们还可以通过Nginx的map指令，将后端异常转化为可观测指标。例如当$upstream_status为502或504时，打一个内部计数变量，再借助stub_status或向StatsD推送。下面的代码片段演示了如何用map做分类，并在响应头中回显后端状态方便调试：
map $upstream_status $is_upstream_bad {
default 0;
"502" 1;
"504" 1;
"~^5" 1;
}
server {
location /api/ {
proxy_pass http://backend;
add_header X-Upstream-Status $upstream_status always;
proxy_intercept_errors on;
error_page 502 504 = @badgw;
}
location @badgw {
return 503 "upstream error: $upstream_status";
}
}
上述配置中，proxy_intercept_errors on让Nginx能够捕获后端错误并内部跳转，而add_header把真实后端码透传给前端开发。这样在联调时，前端看到503响应体里明确写了upstream error: 502，就不会再误以为是Nginx配置问题。此外，对于灰度环境，可以对比不同upstream组的$upstream_status分布，快速发现某个节点池的健康度下降。
三、常见误区与连接复用下的特殊场景
不少初学者认为$upstream_status一定等于后端应用的返回码，其实它记录的是Nginx与upstream交互收到的状态行。如果后端是FastCGI或uWSGI这类非HTTP协议，Nginx也提供了类似的$upstream_status但含义映射不同；而对于HTTP upstream，若后端直接断连（如进程崩溃），Nginx可能记成502，并非后端主动发出。因此看到502要优先排查网络与后端存活，而非业务逻辑。
另一个高频误区出现在keepalive连接池。当proxy_http_version 1.1且proxy_set_header Connection ""开启长连接时，如果某次请求在选连接阶段就被限流模块拦截，$upstream_status为空字符串，而$upstream_addr可能显示已选中的节点。此时若在日志里用条件判断空值当成正常，就会漏报。建议对空值也单独标记，如下面示例用map将空转为特定标识：
map $upstream_status $upstream_status_log {
default $upstream_status;
"" "NONE";
}
log_format trace '$remote_addr $upstream_addr $upstream_status_log $status';
最后需要强调，在多层代理架构中（CDN到Nginx再到后端），每一层都有自己的upstream概念。边缘Nginx的$upstream_status指的是它直接调用的上一层，而非最源站。若要端到端追踪，必须在每一跳都传递并透传类似X-Upstream-Status的头部，避免将中间层状态误读为业务后端状态。只有厘清了变量边界与协议差异，才能让$upstream_status真正服务于稳定性建设。
Nginxupstream_status后端状态码修改时间：2026-08-16 13:04:30