反向代理本质是Nginx进程、HTTP协议栈、内核socket与后端服务的协同机制，核心避坑点包括：一、proxy_pass末尾斜杠决定URI路径拼接方式；二、502/504源于socket层连接、发送或响应阶段断层；三、Header透传失效因worker进程上下文丢失，须显式设置X-Real-IP等头；四、文件上传与大响应受缓冲区内存映射限制，需合理配置buffer及临时文件大小。
反向代理不是“配个 proxy_pass 就完事”的功能，而是 Nginx 进程模型、HTTP 协议栈、内核 socket 层与后端服务之间的一整套协同机制。真正踩坑的根源，往往不在语法写错，而在底层通信链路被隐式切断或扭曲。以下从进程通信最底层出发，直击反向代理架构中 4 类关键避坑点，每一条都对应真实线上故障场景。
一、proxy_pass 斜杠：URI 重写本质是内核级路径拼接
Nginx 在转发请求前会重构请求 URI，而末尾斜杠决定的是 路径合并方式，这直接影响系统调用层面的 path resolution（路径解析）行为：
- proxy_pass http://backend; → Nginx 把 location 匹配到的完整 URI（如 /api/v1/user）原样拼接到 backend 地址后，发起新请求：http://backend/api/v1/user
- proxy_pass http://backend/; → Nginx 先剥离 location 前缀（如 location /api/），再把剩余路径（v1/user）拼到 backend 后：http://backend/v1/user
- 不加斜杠且后端地址含路径（如 proxy_pass http://b.com/app）→ 等价于 proxy_pass http://b.com/app/，但易引发 404（因后端常依赖 /app 为根路径）
建议统一使用带尾部斜杠形式，并配合 rewrite 显式控制路径，避免依赖隐式行为。
二、502/504 不是网络不通，而是进程间通信断层
502 Bad Gateway 和 504 Gateway Timeout 的根本原因，是 Nginx worker 进程在与后端建立连接、发送请求、读取响应三个阶段中某一个环节失败。排查必须下沉到 socket 层：
- 检查 upstream 是否可连：
telnet 192.168.1.100 8080或curl -v http://192.168.1.100:8080/health—— 验证 TCP 层通路 - 确认后端是否接受长连接：
netstat -antp | grep :8080查看 ESTABLISHED 连接数是否快速归零，若无 keepalive，Nginx 默认复用连接失败即报 502 - 检查超时设置是否匹配后端实际处理耗时：
proxy_connect_timeout 5s;（建连）、proxy_send_timeout 30s;（发包）、proxy_read_timeout 60s;（收响应）—— 三者需大于后端最长接口耗时
三、Header 透传失效：不是没写 proxy_set_header，而是进程上下文丢失
Nginx worker 进程在构造反向代理请求时，会重建 HTTP 请求头。若未显式设置，$host、$remote_addr 等变量将取自当前请求上下文，而非原始客户端上下文：
-
X-Real-IP 必须用
proxy_set_header X-Real-IP $remote_addr;，否则后端拿到的是 Nginx 本机 IP -
X-Forwarded-For 要用
$proxy_add_x_forwarded_for（自动追加，保留原有链路），而非简单写$remote_addr，否则多层代理时会丢掉原始 IP -
Host 头 若后端依赖 Host 路由（如多租户 SaaS），必须显式设为
proxy_set_header Host $host;，否则默认发的是 upstream 名称（如 backend_server），导致 404
四、文件上传与大响应：缓冲区不是配置项，而是内存映射边界
Nginx 默认启用 proxy_buffering，所有响应先写入内存 buffer 再返回客户端。当后端返回大文件或流式响应（如 SSE、视频分片），buffer 溢出直接触发 502 或截断：
- 上传限制由
client_max_body_size 100m;控制，该值作用于 Nginx 接收阶段，必须大于前端表单最大文件尺寸 - 禁用缓冲适用于流式场景：
proxy_buffering off;+proxy_buffer_size 128k;+proxy_buffers 4 256k; - 超大响应需调大临时文件空间：
proxy_max_temp_file_size 1g;，否则 buffer 溢出后写磁盘失败仍报 502
不复杂但容易忽略
