Web 服务器与网关 / 系统课时

掌握 proxy_pass 路径规则

掌握 proxy_pass 路径规则

本篇解决 Nginx 反向代理中最容易出错的路径拼接问题。通过理解 proxy_pass 是否携带 URI,可以准确预测请求经过 location 后发送给上游的最终路径。

学习目标

  • 理解 proxy_pass 包含 URI 与不包含 URI 时的替换规则
  • 掌握 location 前缀和上游路径的组合方式
  • 能通过实际请求验证代理后的 URI

proxy_pass 的两种路径行为

proxy_pass 的核心差异在于配置中是否包含 URI。只写协议、地址和端口时,没有 URI;在地址后增加 / 或 /v1/ 就包含 URI。下表限定为普通前缀 location,没有 rewrite 或变量参与,请求均为 /api/user?id=1。

location proxy_pass 上游收到的请求目标
/api/ http://127.0.0.1:9091 /api/user?id=1
/api/ http://127.0.0.1:9091/ /user?id=1
/api/ http://127.0.0.1:9091/v1/ /v1/user?id=1

带 URI 时,Nginx 用目标 URI 替换规范化路径中匹配到的 location 前缀,再连接剩余部分;没有显式修改参数时,查询参数仍然跟随。这里的 / 不是装饰符号,它代表明确的替换内容。不带 URI 时,原始请求一般按原样转发;若前面已经改写 URI,则需要按改写后的规则判断。

建立能回显路径的上游

前置条件是安装 Nginx、Python 3 和 curl,使用两个本机空闲端口做实验。将以下代码保存为 echo_server.py,在一个终端运行 python3 echo_server.py 并保持它打开。服务只回显请求目标,不访问数据库,也不依赖后端框架。

python
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        # self.path 包含查询字符串,便于确认参数没有丢失。
        body = json.dumps({"path": self.path}).encode("utf-8")
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

ThreadingHTTPServer(("127.0.0.1", 9091), Handler).serve_forever()

预期结果:进程等待连接;直接请求 http://127.0.0.1:9091/api/user?id=1 时返回 200,响应体为 {"path": "/api/user?id=1"}。日志中的客户端端口和时间会变化。

对照验证保留前缀与替换前缀

在另一个终端创建独立可写实验目录和 logs 子目录,保存以下完整配置为 nginx.conf。两个 server 分别验证保留与移除前缀,这样不用反复修改配置就能比较同一请求。

nginx
worker_processes 1;
pid logs/nginx.pid;
error_log logs/error.log;
events { worker_connections 128; }
http {
    server {
        listen 127.0.0.1:8088;
        location /api/ {
            # 没有 URI,保留 /api/。
            proxy_pass http://127.0.0.1:9091;
        }
    }
    server {
        listen 127.0.0.1:8089;
        location /api/ {
            # URI 为 /,将匹配到的 /api/ 替换成 /。
            proxy_pass http://127.0.0.1:9091/;
        }
    }
}

预期结果:本机 8088 保留前缀,8089 移除前缀。实验端口固定;若被占用,同时调整对应的 listen 与 curl 地址,不改上游端口时无需改 proxy_pass。

bash
nginx -p "$PWD/" -c nginx.conf -t
nginx -p "$PWD/" -c nginx.conf
curl -sS 'http://127.0.0.1:8088/api/user?id=1'
curl -sS 'http://127.0.0.1:8089/api/user?id=1'
nginx -p "$PWD/" -c nginx.conf -s quit

预期输出:两个请求均返回 200,响应体依次如下。命令最后会关闭本次实验 Nginx,上游 Python 服务在原终端按 Ctrl+C 退出。

json
{"path": "/api/user?id=1"}
json
{"path": "/user?id=1"}

常见路径错误与适用边界

location /api 也可能匹配 /apix,不能当成严格的 API 路径边界。需要明确只接收 /api/ 下的路径时,应使用带末尾斜杠的前缀,并单独考虑 /api 本身应重定向还是返回错误。不要靠反复增删斜杠猜结果,固定检查客户端路径、实际命中的 location 和上游回显三项。

如果把目标 URI 写成 /v1,剩余的 user 可能直接连接成 /v1user;写成 /v1/ 才符合本例想要的层级。正则 location、命名 location、rewrite 和含变量的 proxy_pass 还有不同约束,本课替换口诀不能直接套用;修改这些配置前应核对 proxy_pass 官方规则,并保留同样的上游回显验证。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

掌握 proxy_pass 路径规则

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通