proxy_pass 是 Nginx 实现反向代理最核心的指令，决定请求转发目标；其路径结尾是否带斜杠直接影响 URI 重写行为，需配合 proxy_set_header 等指令传递真实客户端信息，并针对重定向、WebSocket、超时等场景做必要配置。
proxy_pass 是 Nginx 实现反向代理最核心的指令，它直接决定请求被转发到哪个后端地址。配置本身不难，但细节容易出错，尤其在路径重写、协议兼容和 header 传递方面。
基础 proxy_pass 配置写法
最简形式是在 location 块中指定后端服务地址：
- 后端是 HTTP 服务（如 Node.js、Python Flask）：
proxy_pass http://127.0.0.1:3000; - 后端是 HTTPS 服务（需确保 Nginx 编译时启用了 SSL 支持）：
proxy_pass https://backend.example.com; - 使用 upstream 定义多个节点实现负载均衡：
upstream app_servers { server 10.0.1.10:8000; server 10.0.1.11:8000; } location /api/ { proxy_pass http://app_servers; }
路径处理的关键细节
proxy_pass 后是否带 URI 路径，会显著影响请求路径的转发行为：
-
proxy_pass http://127.0.0.1:8000;（结尾无斜杠）→ Nginx 会把原始 location 匹配的路径完整拼接过去。例如访问/api/v1/user，实际发给后端的是/api/v1/user。 -
proxy_pass http://127.0.0.1:8000/;（结尾有斜杠）→ Nginx 会**截掉 location 的匹配前缀**，再拼接。例如：location /api/ { proxy_pass http://127.0.0.1:8000/; }，访问/api/v1/user会转发为/v1/user。
这个区别常导致 404，务必根据后端路由规则选择是否加末尾斜杠。
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
必须配套设置的常用代理头
默认情况下，Nginx 不会转发原始客户端的真实 IP 和协议信息，后端可能拿到的是 Nginx 本机地址或错误的 scheme。需手动补充：
-
proxy_set_header Host $host;—— 保持原始 Host 头 -
proxy_set_header X-Real-IP $remote_addr;—— 传真实客户端 IP -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 支持多层代理链 -
proxy_set_header X-Forwarded-Proto $scheme;—— 标明是 http 还是 https，便于后端做跳转判断 -
proxy_set_header X-Forwarded-Host $host;—— 保留原始域名
常见问题与应对建议
实际部署中高频踩坑点：
- 后端返回 302 重定向时跳转地址错误 → 加上
proxy_redirect off;或显式重写跳转地址，例如proxy_redirect http://127.0.0.1:8000/ /; - WebSocket 连接失败 → 需额外添加升级头：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; - 大文件上传超时 → 设置超时参数：
proxy_connect_timeout 60; proxy_send_timeout 120; proxy_read_timeout 120; - 后端响应体过大被截断 → 检查并调大
proxy_buffer_size和proxy_buffers
