版本：3.10.x

改写代理请求

proxy-rewrite插件允许你在客户端请求发送到上游服务之前修改该请求。它适用于修改 URI 路径、覆盖 HTTP 方法，或添加后端所需的强制请求头等任务。

前提条件

API7 企业版实例正在运行。
已创建网关组，并且网关实例正在运行。
Dashboard Token。

改写静态 URI 路径

你可以在请求到达上游之前替换整个 URI 路径。例如，将 /rewrite/get 改写为 /get。

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/services/proxy-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proxy-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/static-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "static-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite/get"],
    "service_id": "proxy-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'

adc.yaml
services:
  - name: proxy-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: static-rewrite-route
        uris:
          - /rewrite/get
        methods:
          - GET
        plugins:
          proxy-rewrite:
            uri: /get

adc sync -f adc.yaml

使用正则表达式改写

正则改写更灵活，可用于剥离前缀或转换路径的一部分。例如，剥离 /rewrite-regex 前缀，使上游收到 /get。

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/services/regex-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/regex-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite-regex/*"],
    "service_id": "regex-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "regex_uri": ["^/rewrite-regex/(.*)", "/$1"]
      }
    }
  }'

adc.yaml
services:
  - name: regex-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: regex-rewrite-route
        uris:
          - /rewrite-regex/*
        methods:
          - GET
        plugins:
          proxy-rewrite:
            regex_uri:
              - "^/rewrite-regex/(.*)"
              - "/$1"

adc sync -f adc.yaml

regex_uri 字段接收一组 [pattern, replacement] 配对数组。数组中第一个匹配的模式会用于改写。

修改请求头

你可以在代理到上游之前添加、设置或移除请求头。这通常用于注入认证 Token，或移除敏感的客户端请求头。

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/services/header-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/header-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-route",
    "methods": ["GET"],
    "paths": ["/anything/headers-rewrite"],
    "service_id": "header-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "headers": {
          "set": {
            "X-Internal-Token": "secret-value"
          },
          "add": {
            "X-Added-Header": "example"
          },
          "remove": ["User-Agent"]
        }
      }
    }
  }'

adc.yaml
services:
  - name: header-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: header-rewrite-route
        uris:
          - /anything/headers-rewrite
        methods:
          - GET
        plugins:
          proxy-rewrite:
            headers:
              set:
                X-Internal-Token: "secret-value"
              add:
                X-Added-Header: "example"
              remove:
                - "User-Agent"

adc sync -f adc.yaml

请求头操作

set：将请求头设置为指定值，并覆盖已有值。
add：向请求添加请求头，不覆盖已有值。
remove：从请求中移除指定请求头。

覆盖 HTTP 方法

你可以为所有上游请求强制指定 HTTP 方法。例如，将 PUT 请求改为 POST 请求。

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/services/method-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/method-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-route",
    "paths": ["/anything/method-rewrite"],
    "service_id": "method-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "method": "POST"
      }
    }
  }'

adc.yaml
services:
  - name: method-rewrite-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: method-rewrite-route
        uris:
          - /anything/method-rewrite
        plugins:
          proxy-rewrite:
            method: POST

adc sync -f adc.yaml

验证配置

向已配置的路由发送请求，并观察响应或检查上游日志，以验证改写是否生效。

curl -i "http://127.0.0.1:9080/rewrite/get"

对于请求头改写示例，可以查看 httpbin 返回的上游请求头：

curl -s "http://127.0.0.1:9080/anything/headers-rewrite"

对于方法改写示例，发送 PUT 请求并确认上游看到的是 POST：

curl -s -X PUT "http://127.0.0.1:9080/anything/method-rewrite"

如果你配置了正则改写示例，向 http://127.0.0.1:9080/rewrite-regex/get 发送请求时，上游应收到 /get。

如果应用配置后路由立即返回 404，请等待几秒钟，让最新配置下发到网关后再重试。

故障排除

正则未匹配：确保正则模式正确，并在需要时覆盖完整 URI 路径。如果使用复杂模式，可以通过 pcregrep 等工具测试正则。
请求头冲突：如果多个插件修改同一个请求头，执行顺序会影响结果。请确保 proxy-rewrite 相对于其他插件配置在合适的位置。
无效 URI：uri 字段必须以 / 开头。如果配置时遇到 400 Bad Request，请检查 uri 语法。

后续步骤

实现流量拆分 — 将一定比例的流量路由到新版本。
配置限流 — 保护服务免受流量突增影响。

前提条件​

改写静态 URI 路径​

使用正则表达式改写​

修改请求头​

请求头操作​

覆盖 HTTP 方法​

验证配置​

故障排除​

后续步骤​