跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：proxy-rewrite 插件

概览​

proxy-rewrite 插件会在 API7 企业版转发请求前重写请求属性。它可以修改 URI 路径、Host 请求头、HTTP 方法和 scheme，也可以新增、设置或移除请求头，而无需修改后端服务。

适用场景​

  • 转发前重写 URI 路径，例如移除 /api/v1 这样的前缀
  • 重写 Host 请求头以适配后端路由
  • 修改 HTTP 方法，例如将 POST 转换为 PUT
  • 代理前添加、设置或移除请求头
  • 使用基于正则的 URI 重写处理复杂路径转换
  • 代理时在 HTTP 和 HTTPS 之间切换 scheme

插件配置参考（路由/服务）​

字段类型是否必填默认值说明
uristring否—新的上游请求 URI。支持 NGINX 变量（例如 $uri、$arg_name）。
methodstring否—覆盖 HTTP 方法，必须使用大写形式：GET、POST、PUT、DELETE 等。
hoststring否—发送到上游的新 Host 请求头值。
schemestring否—上游请求使用的新 scheme：http 或 https。
headersobject否—用于通过 set、add 和 remove 字段操作请求头的对象。
headers.setobject否—设置（覆盖）请求头。键值对形式，支持 NGINX 变量。
headers.addobject否—追加请求头。键值对形式，即使请求头已存在也会追加。
headers.removearray[string]否—移除请求头。填写要移除的请求头名称列表。
regex_uriarray[string]否—包含两个字符串的数组：[pattern, replacement]。使用 PCRE 正则重写 URI。
use_real_request_uri_unsafeboolean否false使用原始未转义 URI。存在安全风险，仅在理解影响后启用。

**优先级：**如果同时设置 uri 和 regex_uri，则 uri 优先。

分步操作：在路由上启用 proxy-rewrite​

1. 简单 URI 重写（移除前缀）​

移除 /api/v1 前缀，使网关组 default 中的 /api/v1/users 转换为 /users：

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "proxy-rewrite-backend",
  "name": "proxy-rewrite-backend",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "strip-prefix",
  "uri": "/api/v1/*",
  "service_id": "proxy-rewrite-backend",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/api/v1/(.*)", "/$1"]
    }
  }
}
EOF

2. 重写 Host 请求头​

将请求路由到后端的另一个虚拟主机：

a7 service create --gateway-group prod -f - <<'EOF'
{
  "id": "legacy-backend-service",
  "name": "legacy-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group prod -f - <<'EOF'
{
  "id": "rewrite-host",
  "uri": "/legacy/*",
  "service_id": "legacy-backend-service",
  "plugins": {
    "proxy-rewrite": {
      "host": "legacy.internal.svc"
    }
  }
}
EOF

3. 添加和移除请求头​

a7 service create --gateway-group stage -f - <<'EOF'
{
  "id": "header-backend-service",
  "name": "header-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group stage -f - <<'EOF'
{
  "id": "header-manip",
  "uri": "/api/*",
  "service_id": "header-backend-service",
  "plugins": {
    "proxy-rewrite": {
      "headers": {
        "set": {
          "X-Forwarded-Proto": "https",
          "X-Real-IP": "$remote_addr"
        },
        "add": {
          "X-Request-Start": "$msec"
        },
        "remove": ["X-Internal-Debug", "X-Secret-Token"]
      }
    }
  }
}
EOF

常见模式​

使用捕获组进行正则 URI 重写​

将 /products/123/reviews 重写为 /api/products?id=123&section=reviews：

{
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/products/(\\d+)/(.*)$", "/api/products?id=$1&section=$2"]
    }
  }
}

修改 HTTP 方法​

将 GET 转换为 POST，以适配旧版后端：

{
  "plugins": {
    "proxy-rewrite": {
      "method": "POST"
    }
  }
}

静态 URI 替换​

替换整个 URI 路径：

{
  "plugins": {
    "proxy-rewrite": {
      "uri": "/internal/health"
    }
  }
}

在 URI 中使用 NGINX 变量​

{
  "plugins": {
    "proxy-rewrite": {
      "uri": "/api/$arg_version/resource"
    }
  }
}

结合 URI 重写和请求头操作​

{
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v2/(.*)", "/v3/$1"],
      "headers": {
        "set": {
          "X-API-Version": "v3"
        }
      }
    }
  }
}

故障排查​

现象原因解决方法
URI 未重写同时设置了 uri 和 regex_uri，且 uri 优先需要使用正则时移除 uri
正则未匹配模式错误或字符未转义使用 PCRE 语法测试正则；在 JSON 中转义反斜杠：\\d+
NGINX 变量未解析变量名拼写错误或变量不可用检查 NGINX 变量列表
重写后返回 404重写后的 URI 与上游路径不匹配验证后端存在重写后的路径
Host 请求头未改变未设置 host 字段，或被上游覆盖在 proxy-rewrite 配置中显式设置 host
请求头出现两次混淆了 set 和 add使用 set 覆盖，使用 add 追加
配置未生效指定了错误的网关组确保 --gateway-group 与目标网关组一致

配置同步示例​

version: "1"
services:
  - id: proxy-rewrite-backend
    name: proxy-rewrite-backend
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: api-rewrite
    uri: /api/v1/*
    service_id: proxy-rewrite-backend
    plugins:
      proxy-rewrite:
        regex_uri:
          - "^/api/v1/(.*)"
          - "/$1"
        headers:
          set:
            X-Forwarded-Prefix: "/api/v1"
          remove:
            - X-Debug

本页面由 api7/a7 仓库中的 a7-plugin-proxy-rewrite/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。