nginx proxy_pass语法

<think>我们正在讨论nginx的proxy_pass指令，该指令在反向代理配置中至关重要。根据用户提供的引用和问题，我将详细解释proxy_pass的语法、使用场景和配置示例，特别关注其在反向代理和负载均衡中的应用。首先，引用[1]和[2]提供了两个关键点：1.在proxy_pass中设置代理头部信息（如Host,X-Real-IP等）以传递额外信息给后端服务器。2.proxy_pass后是否加斜杠会影响URL的传递方式。现在，我将系统性地解释proxy_pass：###1.proxy_pass基本语法```location匹配路径{proxy_pass目标地址;}```-目标地址可以是：域名、IP地址（可带端口）、upstream组名（用于负载均衡）。-示例：```nginxlocation/{proxy_passhttp://backend_server;}```###2.URL传递规则（重点）根据目标地址末尾**是否带斜杠**，Nginx处理原始请求URI的方式不同：-**情况1：目标地址末尾无斜杠**Nginx将`location`匹配后的**完整路径**追加到目标地址后。示例：```nginxlocation/app/{proxy_passhttp://backend;}```请求`/app/user`→代理到`http://backend/app/user`-**情况2：目标地址末尾有斜杠**Nginx用目标地址**替换location匹配的路径部分**。示例：```nginxlocation/app/{proxy_passhttp://backend/;}```请求`/app/user`→代理到`http://backend/user`###3.反向代理常用配置项引用[1]中的示例展示了常用的头部设置：```nginxproxy_set_headerHost$host;#传递原始请求的主机名proxy_set_headerX-Real-IP$remote_addr;#传递客户端真实IPproxy_set_headerX-Forwarded-For$proxy_add_x_forwarded_for;#追加代理链IPproxy_set_headerX-Forwarded-Proto$scheme;#传递协议（http/https）```###4.负载均衡场景示例结合upstream模块实现负载均衡：```nginx#定义后端服务器组upstreambackend_servers{server192.168.1.10:80weight=2;server192.168.1.11:80;server192.168.1.12:80backup;}server{listen80;server_nameportal.example.com;location/{proxy_passhttp://backend_servers;#指向upstream组proxy_set_headerX-Real-IP$remote_addr;}}```###5.路径重写高级技巧使用正则匹配location时，可通过捕获组动态重写路径：```nginxlocation~^/user/([0-9]+){proxy_passhttp://user_service/$1;#$1引用正则捕获的用户ID}```请求`/user/123`→代理到`http://user_service/123`###6.关键注意事项-**协议一致性**：若后端是HTTPS服务，proxy_pass地址需写为`https://`-**代理超时控制**：建议设置`proxy_connect_timeout`、`proxy_read_timeout`-**缓冲区管理**：大文件传输需调整`proxy_buffers`等参数###完整配置示例```nginxhttp{upstreambackend{serverapp1.example.com;serverapp2.example.com;}server{listen80;server_namenginx-proxy.example.com;#静态文件直接处理location~\.(jpg|png|css)${root/data/static;}#动态请求代理到后端location/api/{proxy_passhttp://backend/;#注意尾部斜杠移除/api前缀proxy_set_headerHost$host;proxy_set_headerX-Forwarded-For$remote_addr;proxy_connect_timeout5s;}#特殊路径重定向location/legacy{return301/api/legacy$request_uri;}}}```###常见问题排查1.**502BadGateway**：检查后端服务是否存活，防火墙是否开放2.**404NotFound**：确认proxy_pass的URL拼接规则（斜杠问题）3.**请求头丢失**：确保正确配置`proxy_set_header`通过以上配置，Nginx即可作为高效的反向代理网关，实现请求分发和负载均衡。§§相关问题§§1.如何解决Nginx反向代理中的502错误？2.Nginx的`upstream`模块支持哪些负载均衡算法？3.如何在Nginx中配置WebSocket反向代理？</think>### Nginx `proxy_pass` 语法详解与配置示例 `proxy_pass` 是 Nginx 实现反向代理和负载均衡的核心指令，用于将请求转发到后端服务器。以下是详细语法规则和配置示例： --- #### 一、基础语法 ```nginx location /匹配路径 { proxy_pass 目标地址; } ``` - **目标地址格式**： - `http://ip:port`（直接指定后端） - `http://upstream_name`（指向负载均衡组） - `https://`（支持 HTTPS 后端） - `unix:/path/to/socket`（Unix 域套接字） --- #### 二、关键行为规则（斜杠差异） | 配置方式 | 请求路径 | 实际转发路径 | 说明 | |------------------------------|------------------|----------------------|------| | `proxy_pass http://backend;` | `/api/user` | `http://backend/api/user` | 保留原始路径 | | `proxy_pass http://backend/;` | `/api/user` | `http://backend/user` | **移除 location 匹配前缀** | > **重要**：尾部斜杠决定是否保留 `location` 匹配的路径前缀[^2]。 --- #### 三、完整反向代理配置示例 ```nginx http { # 负载均衡组定义 upstream backend_servers { server 192.168.1.10:8080 weight=3; # 权重 server 192.168.1.11:8080 max_fails=2; # 健康检查 keepalive 32; # 连接复用优化 } server { listen 80; server_name proxy.example.com; # 示例1：基础代理（保留路径） location /app1/ { proxy_pass http://backend_servers; # 无斜杠 proxy_set_header Host $host; # 传递原始域名 proxy_set_header X-Real-IP $remote_addr; # 传递客户端IP[^1] } # 示例2：路径重写（移除前缀） location /api/ { proxy_pass http://backend_servers/v1/; # 带斜杠 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 代理链信息[^1] } # 示例3：正则匹配动态转发 location ~ ^/user/(\d+) { proxy_pass http://user_service/$1; # $1 捕获正则参数 } } } ``` --- #### 四、关键配置指令说明 | 指令 | 作用 | 示例值 | |------|------|--------| | `proxy_set_header` | 修改请求头 | `Host $host` | | `proxy_connect_timeout` | 连接超时 | `3s` | | `proxy_read_timeout` | 响应超时 | `30s` | | `proxy_buffering` | 缓冲区开关 | `off`（实时流） | | `proxy_redirect` | 重定向处理 | `default` | --- #### 五、常见场景解决方案 1. **路径重写** ```nginx location /legacy/ { proxy_pass http://new-service/current/; # /legacy/user → /current/user } ``` 2. **HTTPS 后端** ```nginx location /secure/ { proxy_pass https://backend; proxy_ssl_verify off; # 跳过证书验证（测试用） } ``` 3. **WebSocket 代理** ```nginx location /ws/ { proxy_pass http://websocket_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } ``` > **验证命令**： > `nginx -t` 测试配置 > `curl -v http://proxy.example.com/app1/test` 观察转发路径