# Proxy Control

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

## 请求处理[​](#request-handling "请求处理的直接链接")

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

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

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

## 示例[​](#example "示例的直接链接")

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

### 对比缓冲上传和流式上传[​](#compare-buffered-and-streaming-uploads "对比缓冲上传和流式上传的直接链接")

此示例需要一个正在运行且能加入 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`。

* 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}"
```

创建一个服务，包含缓冲路由和流式路由。

adc.yaml

```
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
```

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