跳到主要内容

Proxy Rewrite 配置选项

proxy-rewrite 插件提供灵活的选项,用于改写 API 网关转发到上游服务的请求,从而改进 API 管理。 配置涵盖插件参数。

参数​

请参阅通用配置了解所有插件可用的配置选项。

  • uri

    string


    新的上游 URI 路径。值可以是内置变量。

  • method

    string

    有效值:

    GET、POST、PUT、HEAD、DELETE、OPTIONS、MKCOL、COPY、MOVE、PROPFIND、LOCK、UNLOCK、PATCH 或 TRACE

    重写请求使用的 HTTP 方法。

  • regex_uri

    array[string]


    用于匹配客户端请求 URI 路径并组成新上游 URI 路径的正则表达式。当同时配置 uri 和 regex_uri 时,uri 具有更高优先级。

    请在扁平数组中提供一对或多对值。奇数位置的元素是匹配模式,偶数位置的元素是替换值。插件会按顺序计算各组值,并应用第一个匹配项。

    例如,使用 ["^/test/(.*)/(.*)", "/$1-$2", "^/other/(.*)", "/other"] 时,对 /test/user/agent 的请求会重写为 /user-agent,对 /other/hello 的请求会重写为 /other。

  • set_ngx_uri

    boolean

    默认值:false


    API7 网关 3.9.21 和 3.10.8 支持此字段。APISIX 3.19.0 不提供此字段;当 use_real_request_uri_unsafe 为 false 时,APISIX 3.19.0 会将 ngx.var.uri 更新为重写后的上游 URI。

    在 API7 网关中,当 use_real_request_uri_unsafe 为 false 时,如果 set_ngx_uri 为 false,ngx.var.uri 会保留原始的规范化请求 URI;如果 set_ngx_uri 为 true,则更新为重写后的上游 URI。当 use_real_request_uri_unsafe 为 true 时,两种产品都不会更新 ngx.var.uri。

  • host

    string


    设置 Host 请求头。

  • headers

    object


    要执行的请求头动作。可以设置为动作动词 add、remove 和/或 set 的对象;或由要 set 的请求头组成的对象。

    配置多个操作时,按 add、set、remove 的顺序执行。对于同一个请求头,set 会覆盖 add 添加的值,remove 会在这两项操作之后删除该请求头。

    • add

      object


      追加到请求的请求头。如果请求中已存在该请求头,则将追加该请求头值。请求头值可以设置为常量、一个或多个内置变量,或使用 $1-$2-$3 等变量的 regex_uri 匹配结果。

      请求头值也可以是数组。每个值都会独立解析,并按数组顺序追加为单独的请求头行。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。

    • set

      object


      设置到请求的请求头。如果请求中已存在该请求头,则将覆盖该请求头值。请求头值可以设置为常量、一个或多个内置变量,或使用 $1-$2-$3 等变量的 regex_uri 匹配结果。

      请求头值也可以是数组。每个值都会独立解析,且该数组会按数组顺序生成单独的请求头行,并替换任何现有值。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。

      不应用于设置 Host。

    • remove

      array[string]


      从请求中删除的请求头。

  • use_real_request_uri_unsafe

    boolean

    默认值:false


    如果为 true,则绕过 URI 规范化并允许完整的原始请求 URI。启用此选项被认为是不安全的。