跳到主要内容

Proxy Control

proxy-control 插件控制 NGINX 是否在向上游服务发送请求体前先缓冲请求体。关闭请求缓冲后,上游可以在客户端发送请求体的同时接收数据。这适用于流式上传,也适用于需要分段处理大型请求体的服务。

请求处理​

请求缓冲默认开启。NGINX 会先读取完整的请求体,再将其转发给上游。关闭请求缓冲后,NGINX 会边接收请求体边向上游转发。

关闭请求缓冲后,NGINX 一旦开始向上游发送请求体,就无法改用其他上游节点重试该请求。请在能够接受这一限制时关闭请求缓冲。

在 Apache APISIX 中,请勿将此插件与 ext-plugin-post-resp 同时使用。ext-plugin-post-resp 通过 lua-resty-http 向上游发送请求,会绕过请求缓冲控制。

示例​

此示例使用指向同一个测试上游的两条路由,对比先缓冲请求体和流式转发请求体的行为。

对比缓冲上传和流式上传​

此示例需要一个正在运行且能加入 Docker 网络的 APISIX 或 API7 网关容器。每次限速上传时,另发一个请求来检查测试上游是否正在接收请求体。

为示例创建工作目录并进入该目录。

mkdir proxy-control-example
cd proxy-control-example

创建以下 Python 脚本,作为测试上游。

request-observer.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


active_paths = set()


class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"

def do_POST(self):
active_paths.add(self.path)

try:
remaining = int(self.headers.get("Content-Length", "0"))
while remaining:
chunk = self.rfile.read(min(remaining, 8192))
if not chunk:
break
remaining -= len(chunk)
finally:
active_paths.discard(self.path)

body = b"upload complete\n"

self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

def do_GET(self):
state = "receiving" if self.path in active_paths else "waiting"
body = f"{state}\n".encode()

self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

def log_message(self, *_):
pass


ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

将 GATEWAY_CONTAINER 设为正在运行的 APISIX 或 API7 网关容器名。创建一个专用网络,并将网关接入该网络。

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-request-buffering-net
docker network connect gateway-request-buffering-net "$GATEWAY_CONTAINER"

在 request-observer.py 所在的目录中启动测试上游。

docker run -d \
--name request-observer \
--network gateway-request-buffering-net \
-v "$PWD/request-observer.py:/request-observer.py:ro" \
python:3.13.15-alpine3.24 \
python -u /request-observer.py

创建两条指向同一上游的路由。一条开启请求缓冲,另一条流式转发请求体。

如果启用了 Admin API 身份验证,请在使用 Admin API 标签页前将具有管理员角色的密钥导出为 ADMIN_API_KEY。

创建缓冲请求体的路由。

curl "http://127.0.0.1:9180/apisix/admin/routes/proxy-control-buffered" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/buffered-upload",
"plugins": {
"proxy-control": {
"request_buffering": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"request-observer:8000": 1
}
}
}'

创建流式转发请求体的路由。

curl "http://127.0.0.1:9180/apisix/admin/routes/proxy-control-streaming" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/streaming-upload",
"plugins": {
"proxy-control": {
"request_buffering": false
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"request-observer:8000": 1
}
}
}'

创建大小为 100 KiB 的请求体。

dd if=/dev/zero of=upload.bin bs=1024 count=100

以每秒 10 KiB 的速度向缓冲路由发送请求体,再检查上游是否已收到请求。

curl "http://127.0.0.1:9080/buffered-upload" \
--limit-rate 10k \
--data-binary @upload.bin \
--output /dev/null \
--silent \
--show-error &

buffered_pid=$!
sleep 1
curl "http://127.0.0.1:9080/buffered-upload"
wait "$buffered_pid"

查询状态的请求应返回 waiting。此时网关仍在缓冲上传的数据,尚未向上游发送请求。

waiting

向流式路由发起同样的上传,再查询状态。

curl "http://127.0.0.1:9080/streaming-upload" \
--limit-rate 10k \
--data-binary @upload.bin \
--output /dev/null \
--silent \
--show-error &

streaming_pid=$!
sleep 1
curl "http://127.0.0.1:9080/streaming-upload"
wait "$streaming_pid"

查询状态的请求应返回 receiving。客户端仍在发送请求体时,网关就已开始转发。

receiving

对比结果表明,关闭请求缓冲后,网关在客户端发完请求体之前就会开始转发。