把 Nginx 装在应用前面做反向代理,是它最常见的用法,也是最容易「配出来能跑、跑起来不对」的用法。请求能通不等于配置是对的:后端收到的路径可能多了一截、拿到的客户端 IP 可能是 Nginx 自己的、WebSocket 握手可能莫名失败、SSE 推送可能被缓冲拖成一坨——这些问题全都藏在反向代理的几个细节里。这篇就把反代的五条主线一次讲透:proxy_pass 的斜杠规则、请求头的传递、WebSocket 的升级、缓冲的取舍、上游长连接与超时。搞懂这五条,反代配置才算真正受控。如果暂时不想手写配置,也可以先用面板方案顶着,见Nginx Proxy Manager 实战。
proxy_pass 的斜杠:一条斜杠,两种转发结果
反代配置里最容易踩的坑,就是 proxy_pass 后面那个不起眼的 URI 部分。先看官方文档给出的规则:proxy_pass 带 URI 时,请求 URI 里与 location 匹配的那部分会被替换成指令里的 URI;不带 URI 时,原始 URI 原样转发。这句话值得逐字读三遍,因为它决定了后端最终收到什么路径。location 匹配本身的优先级规则,见本系列第 1 篇Nginx 架构深挖:进程模型、配置结构与 location 匹配顺序。
location /api/ { proxy_pass http://127.0.0.1:8080;}
location /api/ { proxy_pass http://127.0.0.1:8080/;}
location /api/ { proxy_pass http://127.0.0.1:8080/v1/;}三段配置看起来只差一个斜杠,转发结果完全不同。假设请求是 GET /api/users/42,后端收到的分别是:
| 配置写法 | 后端收到的 URI |
|---|---|
proxy_pass http://127.0.0.1:8080; | /api/users/42 |
proxy_pass http://127.0.0.1:8080/; | /users/42 |
proxy_pass http://127.0.0.1:8080/v1/; | /v1/users/42 |
第一种不带 URI,原始 URI 原样送过去,后端必须自己处理 /api 前缀;第二种带一个斜杠,location 匹配到的 /api/ 部分被替换成 /,相当于把前缀剥掉;第三种则把 /api/ 换成 /v1/,等于在转发时顺手改写了路径前缀。日常最常见的需求是「剥掉前缀」,写法就是第二种:proxy_pass 末尾加一个斜杠。
这里有两点要特别注意。第一,只有前缀 location 才有「替换匹配部分」这个说法。如果 location 是用正则写的,Nginx 无法确定要替换请求 URI 的哪一段,这时 proxy_pass 带 URI 会把整个请求 URI 直接换成指令里写的 URI,行为和直觉完全不同。正则 location 下想改写路径,老老实实用 rewrite 再转发,别指望斜杠帮你干活。
location ~ ^/api/v([0-9]+)/(.*)$ { rewrite ^/api/v[0-9]+/(.*)$ /$1 break; proxy_pass http://127.0.0.1:8080;}第二,proxy_pass 的 URI 里可以带变量,但带变量之后行为会变:Nginx 不再按上面的替换规则处理,而是把 URI 重新解析——具体表现是请求 URI 不再做替换、直接拼到变量解析出的地址后面。想用变量做动态上游时,路径处理要自己用 rewrite 兜底,不要把变量和斜杠替换混在同一条指令里指望它按直觉工作。
WARNING
proxy_pass后面写http://127.0.0.1:8080和http://127.0.0.1:8080/是两回事,前者转发原 URI、后者剥掉 location 前缀。线上很多「后端报 404 但直连后端是好的」问题,根子就是这里多写或少写了一个斜杠。改完务必用curl对照直连和经 Nginx 的两次返回,确认后端收到的路径是你想要的。
proxy_pass 还有一个容易被忽略的搭档:proxy_redirect。后端返回的重定向 Location 头里往往带着它自己的内网地址或端口,比如 Location: http://127.0.0.1:8080/login,直接透传给浏览器就断了。默认的 proxy_redirect default 会按 proxy_pass 的地址做替换,把内网地址换成对外地址;如果后端返回的地址格式特殊,默认替换覆盖不到,就得显式写 proxy_redirect 做映射。
location /app/ { proxy_pass http://127.0.0.1:8080/; proxy_redirect http://127.0.0.1:8080/ /app/; proxy_redirect http://internal.example.com/ /app/;}头传递:后端看到的 IP 和协议,别让 Nginx 吞了
反代一接进来,后端眼里的世界就变了:连接是 Nginx 发起的,源 IP 是 Nginx 的内网地址,协议是 Nginx 与后端之间的 HTTP。应用要拿到真实的客户端信息,全靠 Nginx 显式把头传过去。不传,后端日志里所有请求都来自同一个 IP,限流、风控、审计全都会错。
location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;}这四行是反代的标配,每一行的含义都不一样:
| 请求头 | 值 | 后端拿到的是什么 |
|---|---|---|
Host | $host | 客户端请求里的域名,不带端口 |
X-Real-IP | $remote_addr | 直连 Nginx 的那个客户端 IP |
X-Forwarded-For | $proxy_add_x_forwarded_for | 客户端 IP 追加到已有链路末尾 |
X-Forwarded-Proto | $scheme | 客户端到 Nginx 用的是 http 还是 https |
Host 最值得单独说一句。proxy_pass 的默认行为是把 Host 设成上游地址里的主机名,也就是写 proxy_pass http://127.0.0.1:8080 时,后端收到的 Host 是 127.0.0.1。后端如果按域名做虚拟主机路由、或者按 Host 拼绝对地址,就会直接走错。显式写 proxy_set_header Host $host 是在告诉 Nginx:把客户端带来的域名原样交给后端。注意 $host 是小写域名且不带端口;如果后端需要带端口的原始 Host,用 $http_host,它保留客户端发来的完整值。
X-Forwarded-For 的值 $proxy_add_x_forwarded_for 是个变量:它等于客户端 IP 加上请求里已有的 X-Forwarded-For。链路经过多层代理时,这个头会自然攒成一条 IP1, IP2 的链,后端取第一个就是真实客户端。但这也意味着这个头是客户端可以伪造的,后端拿它做风控之前,必须先确认请求确实经过了你自己的 Nginx,而不是客户端直连后端绕过了代理。正确的做法是后端只信任来自 Nginx 内网地址的请求里的这个头,其余一律按直连 IP 处理。
X-Forwarded-Proto 管的是协议。浏览器到 Nginx 是 HTTPS,Nginx 到后端是 HTTP,后端如果只看连接协议,会以为请求是明文的,进而生成 http:// 的跳转链接、或者反复触发「强制 HTTPS」的重定向循环。把 $scheme 传过去,后端框架大多能认这个头并据此判断原始协议,循环就断了。对应的,后端应用也要配置成信任这个头,光 Nginx 传了、后端不认,等于白传。
WebSocket:升级握手要过两道关
普通 HTTP 请求是「一问一答」,WebSocket 是「一次握手、长期双向」。Nginx 默认按 HTTP/1.0 转发上游请求、且默认不转发 Upgrade 这类逐跳头,两件事都撞在 WebSocket 的握手上,所以反代 WebSocket 必须显式做三件事:
location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";}proxy_http_version 1.1 是因为 WebSocket 握手要求 HTTP/1.1,而 Nginx 默认用 HTTP/1.0 连上游;Upgrade 头告诉后端「客户端想把这个连接升级成 WebSocket」,Connection: upgrade 则是升级握手本身的信号。缺了任何一行,握手都会失败,浏览器控制台一般会看到 101 没回来、或者连接直接断掉。
还有一个超时细节:WebSocket 连接建立后可能长时间没有数据,Nginx 的 proxy_read_timeout 默认 60 秒,60 秒没收到上游数据就把连接掐了。对长连接应用,这个值要按业务调大,否则聊天室、实时推送这类连接会每分钟断一次、再重连一次。
location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 86400; proxy_send_timeout 86400;}Connection 头这里有个小坑:Nginx 的 proxy_set_header 里写 Connection "upgrade" 是固定写法,但如果有的客户端发来的不是升级请求,这个 location 又同时处理普通 HTTP 请求,硬写 upgrade 会把普通请求的 Connection 也改掉。更严谨的写法是用 map 按 $http_upgrade 的值动态决定:
map $http_upgrade $connection_upgrade { default upgrade; "" close;}
location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;}proxy_buffering:开与关,都是取舍
proxy_buffering 默认是开的。开着的时候,Nginx 会把上游的响应先读进自己的缓冲区(内存,不够用时落到磁盘临时文件),读完再慢慢发给客户端。关掉的时候,Nginx 收到多少就立刻发给客户端多少,中间不做停留。两种模式没有对错,只有场景合不合适:
| 维度 | proxy_buffering on(默认) | proxy_buffering off |
|---|---|---|
| 上游连接占用 | 响应读完即释放,慢客户端不占上游 | 客户端收完才释放,慢客户端一直占着上游 |
| 客户端体验 | 首字节稍慢,整体吞吐稳定 | 首字节快,流式内容实时到达 |
| 内存与磁盘 | 大响应会占缓冲内存、甚至写临时文件 | 几乎不占缓冲 |
| 适用场景 | 普通 API、页面、文件下载 | SSE、流式输出、超大文件直传 |
开着的好处是保护上游:上游应用把响应交出去就能立刻去处理下一个请求,不用陪着一个慢速客户端慢慢发数据。这是反代默认开缓冲的根本原因。代价是响应要先经过 Nginx 的缓冲,首字节会慢一点,而且大响应的缓冲可能落盘,磁盘 I/O 反而成了瓶颈。相关参数可以按需调:
location / { proxy_pass http://127.0.0.1:8080; proxy_buffering on; proxy_buffer_size 8k; proxy_buffers 8 16k; proxy_busy_buffers_size 32k; proxy_temp_file_write_size 32k;}proxy_buffer_size 是放响应头的第一块缓冲,proxy_buffers 是放响应体的缓冲池,proxy_busy_buffers_size 控制可以同时发给客户端的缓冲上限。这几个值不用死记,记住原则就行:响应头特别大的应用(Cookie 多、头多)先调 proxy_buffer_size;大文件下载场景关注 proxy_temp_file_write_size,它决定每次往临时文件写多少。
关掉缓冲的场景很明确:服务端推送事件(SSE)、大模型流式输出、长轮询。这些场景要求上游吐一个字节、客户端立刻看到一个字节,中间插一层缓冲就等于把「实时」变成了「攒够一波再发」,用户看到的就是一卡一卡的输出。关缓冲就是一行配置,但要接受代价:上游连接会被慢客户端长时间占用,上游的并发能力要按这个重新估算。
location /stream/ { proxy_pass http://127.0.0.1:8080; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600;}注意这里顺手关了 proxy_cache:流式接口本来就不该进缓存,两个开关一起关才干净。顺带一提,proxy_buffering off 的时候 proxy_cache 也就没意义了,因为缓存本身依赖缓冲。
upstream keepalive:别让每次请求都重新握手
没有长连接的时候,Nginx 每转发一个请求,就要和上游重新建一次 TCP 连接(HTTPS 上游还要重新握手),高并发下这笔开销非常可观。upstream 块里的 keepalive 就是让 Nginx 和上游之间维持一池复用的空闲连接:
upstream backend { server 127.0.0.1:8080; server 127.0.0.1:8081; keepalive 32;}
server { listen 80; server_name example.com;
location / { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ""; }}三个点必须同时满足,缺一不可。第一,keepalive 32 写在 upstream 块里,数字是每个 worker 进程保留的空闲连接数,不是总数;第二,proxy_http_version 1.1,因为 HTTP/1.0 默认连接用完即关;第三,proxy_set_header Connection "";,把默认的 Connection: close 清掉,否则 Nginx 还是会告诉上游「用完就关」。三行少一行,长连接都建不起来。
keepalive 的数字不用贪大:32 对大多数单机后端绰绰有余,设得太大反而让上游维持一堆基本不用的空闲连接。上游应用如果自己有空闲连接超时(比如 Go 的 IdleTimeout、Node 的 keepAliveTimeout),两边的超时要对得上,Nginx 这边保留的空闲连接不能比上游的超时时间还长,否则 Nginx 复用了一条上游已经关掉的连接,请求会失败一次再重试,用户看到的就是偶发的 502。
三个超时:connect、send、read 各管一段
proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout 是三个不同的超时,管的是请求转发链路上的三段,默认值都是 60 秒:
location / { proxy_pass http://127.0.0.1:8080; proxy_connect_timeout 5s; proxy_send_timeout 60s; proxy_read_timeout 60s;}proxy_connect_timeout 是 Nginx 与上游建立连接的等待上限。上游挂了、端口没监听、网络不通,都会在这里超时。这个值可以设得很短,5 秒足够——内网里连不上就是连不上,等 60 秒没有意义,只会拖慢失败重试。proxy_send_timeout 是 Nginx 把请求体发给上游的时限,上传大文件、客户端网络慢的时候会撞到它。proxy_read_timeout 是两次从上游读到数据之间的间隔上限,不是整个响应的总时长;上游处理慢、每隔一段时间吐一点数据,只要间隔不超过这个值就不会断。
三者调参的思路也不一样:connect 按「内网建连应该多快」设短一点;send 按「上传场景」设;read 按「上游最慢接口的响应时间」设。反代 SSE、WebSocket、大文件上传这类长耗时场景,read 和 send 要按业务单独放宽,别在全局一刀切——全局放宽等于把所有接口的故障发现时间都拉长了。
排障:反代出问题,先按这个顺序查
后端报 404,但直连后端是好的。 先查 proxy_pass 的斜杠。直连用的路径和经 Nginx 的路径不一致,九成是斜杠规则理解反了:想剥前缀却没加斜杠,或者加了斜杠却不知道它剥掉了 location 前缀。用 curl 分别请求直连地址和经 Nginx 的地址,对照后端日志里收到的实际 URI,差的那一段就是斜杠吃掉或多带的部分。
WebSocket 连不上,普通接口正常。 按顺序查三行:proxy_http_version 1.1 写了没有、Upgrade 头传了没有、Connection 是不是 upgrade。三行都在还失败,看浏览器开发者工具的网络面板:握手请求返回的不是 101 Switching Protocols,而是 400 或 502,说明后端根本没认出这是升级请求,多半是头没传过去。长连接每分钟断一次则是 proxy_read_timeout 没放宽。
后端日志里所有请求的 IP 都是 Nginx 的地址。 proxy_set_header X-Real-IP 或 X-Forwarded-For 没配,或者配了但后端应用没开启「信任代理头」的选项。两边要同时对上:Nginx 传头、后端认头。还要确认请求确实经过了 Nginx——客户端如果能直连后端,绕过代理的请求自然没有任何代理头。
SSE 或流式输出一卡一卡、半天才吐一段。 proxy_buffering 还开着。流式接口的 location 里显式写 proxy_buffering off,同时确认没有缓存配置在起作用。改完用 curl -N 直接看流式输出是不是逐行到达,别只看浏览器表现,浏览器自己的缓冲也会干扰判断。
偶发 502,刷新一下又好了。 先看错误日志里 502 那一刻的 upstream_status 和 upstream_response_time:如果是上游连接被重置,大概率是 keepalive 空闲连接超时没对齐——Nginx 复用了上游已经关闭的连接。把 Nginx 的 keepalive 空闲时间调得比上游的短,或者把 keepalive 数字调小,都能缓解;根治是两边超时对齐。
响应特别慢,但上游处理其实很快。 用 $request_time 和 $upstream_response_time 对照(这两变量的用法本系列第 8 篇日志篇会细讲):如果 request_time 远大于 upstream_response_time,慢在 Nginx 到客户端这一段,查缓冲和客户端网络;如果两者都大,慢在上游本身。这两个时间戳是定位反代性能问题的第一手证据,别凭感觉猜。
小结
反向代理的配置量不大,但每个指令背后都是一条明确的行为规则:proxy_pass 的斜杠决定后端收到什么路径,四个头决定后端看到谁在访问、WebSocket 的三行决定握手能不能升级、proxy_buffering 的开关决定响应是先攒后发还是随到随发、keepalive 的三行决定上游连接复不复用、三个超时决定每一阶段等多久。配反代的时候别凭「看起来差不多」下手,改完用 curl 对照直连和经代理的两端表现,再看一眼错误日志——这套验证习惯,比多背十条配置更管用。下一篇讲负载均衡:多个上游时 Nginx 怎么调度、怎么把挂掉的节点摘出去。
WARNING本文涉及的
proxy_read_timeout、proxy_buffering等参数都是按 location 生效的,调参只动对应的 location,别在http块里全局放宽超时——全局放宽会让所有接口的故障发现时间一起变长,慢接口的问题会被掩盖成「偶尔慢」,排障更难。