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 脚本,作为测试上游。
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。
- Admin API
- ADC
创建缓冲请求体的路由。
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
}
}
}'
配置 ADC 以连接目标后端。后续 ADC 命令会从这些环境变量读取连接设置。
- APISIX
- API7 Gateway
如果启用了 Admin API 身份验证,请在配置 ADC 前将具有管理员角色的密钥导出为 ADMIN_API_KEY。
export ADC_BACKEND=apisix
export ADC_SERVER="http://127.0.0.1:9180"
export ADC_TOKEN="${ADMIN_API_KEY}"
export ADC_BACKEND=api7ee
export ADC_SERVER="https://{DASHBOARD_ADDR}"
export ADC_TOKEN="{DASHBOARD_TOKEN}"
export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
创建一个服务,包含缓冲路由和流式路由。
services:
- name: proxy-control-service
labels:
docs-example: proxy-control
routes:
- name: proxy-control-buffered
uris:
- /buffered-upload
plugins:
proxy-control:
request_buffering: true
- name: proxy-control-streaming
uris:
- /streaming-upload
plugins:
proxy-control:
request_buffering: false
upstream:
type: roundrobin
nodes:
- host: request-observer
port: 8000
weight: 1
预览本示例的改动。
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=proxy-control
核对差异,再仅同步带有此标签的服务。
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=proxy-control
创建大小为 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
对比结果表明,关闭请求缓冲后,网关在客户端发完请求体之前就会开始转发。