From 6e2070391581b2d9a2cfde438eb1a3deab2928a6 Mon Sep 17 00:00:00 2001 From: traky Date: Mon, 23 Dec 2024 14:19:52 +0800 Subject: [PATCH 1/9] improve docs --- docs/en/latest/plugins/proxy-rewrite.md | 481 ++++++++++++++++++++--- docs/zh/latest/plugins/proxy-rewrite.md | 482 +++++++++++++++++++++--- 2 files changed, 852 insertions(+), 111 deletions(-) diff --git a/docs/en/latest/plugins/proxy-rewrite.md b/docs/en/latest/plugins/proxy-rewrite.md index dc22e1c478dc..160ab2f55783 100644 --- a/docs/en/latest/plugins/proxy-rewrite.md +++ b/docs/en/latest/plugins/proxy-rewrite.md @@ -30,33 +30,28 @@ description: This document contains information about the Apache APISIX proxy-re ## Description -The `proxy-rewrite` Plugin rewrites Upstream proxy information such as `scheme`, `uri` and `host`. +The `proxy-rewrite` Plugin offers options to rewrite requests that APISIX forwards to upstream services. With this plugin, you can modify the HTTP methods, request destination upstream address, request headers, and more. ## Attributes | Name | Type | Required | Default | Valid values | Description | |-----------------------------|---------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uri | string | False | | | New Upstream forwarding address. Value supports [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For example, `$arg_name`. | -| method | string | False | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | Rewrites the HTTP method. | -| regex_uri | array[string] | False | | | Regular expressions can be used to match the URL from client. If it matches, the URL template is forwarded to the upstream. Otherwise, the URL from the client is forwarded. When both `uri` and `regex_uri` are configured, `uri` has a higher priority. Multiple regular expressions are currently supported for pattern matching, and the plugin will try to match them one by one until they succeed or all fail. For example: `["^/iresty/(. *)/(. *)/(. *)", "/$1-$2-$3", ^/theothers/(. *)/(. *)", "/theothers/$1-$2"]`, the element with the odd index represents the uri regular expression that matches the request from the client, and the element with the even index represents the `uri` template that is forwarded upstream upon a successful match. Please note that the length of this value must be an **even number**. | -| host | string | False | | | New Upstream host address. | -| headers | object | False | | | | -| headers.add | object | false | | | Append the new headers. The format is `{"name": "value",...}`. The values in the header can contain Nginx variables like `$remote_addr` and `$balancer_ip`. It also supports referencing the match result of `regex_uri` as a variable like `$1-$2-$3`. | -| headers.set | object | false | | | Overwrite the headers. If the header does not exist, it will be added. The format is `{"name": "value", ...}`. The values in the header can contain Nginx variables like `$remote_addr` and `$balancer_ip`. It also supports referencing the match result of `regex_uri` as a variable like `$1-$2-$3`. Note that if you would like to set the `Host` header, use the `host` attribute instead. | -| headers.remove | array | false | | | Remove the headers. The format is `["name", ...]`. -| use_real_request_uri_unsafe | boolean | False | false | | Use real_request_uri (original $request_uri in nginx) to bypass URI normalization. **Enabling this is considered unsafe as it bypasses all URI normalization steps**. | +| uri | string | False | | | New upstream URI path. Value supports [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For example, `$arg_name`. | +| method | string | False | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite requests to use. | +| regex_uri | array[string] | False | | | Regular expressions used to match the URI path from client requests and compose a new upstream URI path. When both `uri` and `regex_uri` are configured, `uri` has a higher priority. The array should contain one or more **key-value pairs**, with the key being the regular expression to match URI against and value being the new upstream URI path. For example, with `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`, if a request is originally sent to `/iresty/hello/world`, the Plugin will rewrite the upstream URI path to `/iresty/hello-world`; if a request is originally sent to `/theothers/hello/world`, the Plugin will rewrite the upstream URI path to `/theothers`. | +| host | string | False | | | Set [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) request header. | +| headers | object | False | | | Header actions to be executed. Can be set to objects of action verbs `add`, `remove`, and/or `set`; or an object consisting of headers to be `set`. When multiple action verbs are configured, actions are executed in the order of `add`, `remove`, and `set`. | +| headers.add | object | False | | | Headers to append to requests. If a header already present in the request, the header value will be appended. Header value could be set to a constant, one or more [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or the matched result of `regex_uri` using variables such as `$1-$2-$3`. | +| headers.set | object | False | | | Headers to set to requests. If a header already present in the request, the header value will be overwritten. Header value could be set to a constant, one or more [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or the matched result of `regex_uri` using variables such as `$1-$2-$3`. Should not be used to set `Host`. | +| headers.remove | array[string] | False | | | Headers to remove from requests. +| use_real_request_uri_unsafe | boolean | False | false | | If true, bypass URI normalization and allow for the full original request URI. Enabling this option is considered unsafe. | -## Header Priority +## Examples -Header configurations are executed according to the following priorities: - -`add` > `remove` > `set` - -## Enable Plugin - -The example below enables the `proxy-rewrite` Plugin on a specific Route: +The examples below demonstrate how you can configure `proxy-rewrite` on a Route in different scenarios. :::note + You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash @@ -65,68 +60,446 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Rewrite Host Header + +The following example demonstrates how you can modify the `Host` header in a request. Note that you should not use `headers.set` to set the `Host` header. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "host": "myapisix.demo" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to `/headers` to check all the request headers sent to upstream: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9080/headers" +``` + +You should see a response similar to the following: + +```text { + "headers": { + "Accept": "*/*", + "Host": "myapisix.demo", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef198-29da0970383150175bd2d76d", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +### Rewrite URI And Set Headers + +The following example demonstrates how you can rewrite the request upstream URI and set additional header values. If the same headers present in the client request, the corresponding header values set in the Plugin will overwrite the values present in the client request. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/", "plugins": { - "proxy-rewrite": { - "uri": "/test/home.html", - "host": "iresty.com", - "headers": { - "set": { - "X-Api-Version": "v1", - "X-Api-Engine": "apisix", - "X-Api-useless": "" - }, - "add": { - "X-Request-ID": "112233" - }, - "remove":[ - "X-test" - ] - } + "proxy-rewrite": { + "uri": "/anything", + "headers": { + "set": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } } + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify: + +```shell +curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"' +``` + +You should see a response similar to the following: + +```text +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything" +} +``` + +Note that both headers present and the header value of `X-Api-Version` configured in the Plugin overwrites the header value passed in the request. + +### Rewrite URI And Append Headers + +The following example demonstrates how you can rewrite the request upstream URI and append additional header values. If the same headers present in the client request, their headers values will append to the configured header values in the plugin. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/", + "plugins": { + "proxy-rewrite": { + "uri": "/headers", + "headers": { + "add": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -## Example usage +Send a request to verify: -Once you have enabled the Plugin as mentioned below, you can test the Route: +```shell +curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"' +``` + +You should see a response similar to the following: + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1,v2", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +Note that both headers present and the header value of `X-Api-Version` configured in the Plugin is appended by the header value passed in the request. + +### Remove Existing Header + +The following example demonstrates how you can remove an existing header `User-Agent`. ```shell -curl -X GET http://127.0.0.1:9080/test/index.html +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "headers": { + "remove":[ + "User-Agent" + ] + } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` -Once you send the request, you can check the Upstream `access.log` for its output: +Send a request to verify if the specified header is removed: +```shell +curl "http://127.0.0.1:9080/headers" ``` -127.0.0.1 - [26/Sep/2019:10:52:20 +0800] iresty.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107 + +You should see a response similar to the following, where the `User-Agent` header is not present: + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "X-Amzn-Trace-Id": "Root=1-64fef302-07f2b13e0eb006ba776ad91d", + "X-Forwarded-Host": "127.0.0.1" + } +} ``` -## Delete Plugin +### Rewrite URI Using RegEx + +The following example demonstrates how you can parse text from the original upstream URI path and use them to compose a new upstream URI path. In this example, APISIX is configured to forward all requests from `/test/user/agent` to `/user-agent`. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "uri": "/test/*", + "plugins": { + # highlight-start + "proxy-rewrite": { + "regex_uri": ["^/test/(.*)/(.*)", "/$1-$2"] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -To remove the `proxy-rewrite` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Send a request to `/test/user/agent` to check if it is redirected to `/user-agent`: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9080/test/user/agent" +``` + +You should see a response similar to the following: + +```text +{ + "user-agent": "curl/8.2.1" +} +``` + +### Add URL Parameters + +The following example demonstrates how you can add URL parameters to the request. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/get?arg1=apisix&arg2=plugin" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify if the URL parameters are also forwarded to upstream: + +```shell +curl "http://127.0.0.1:9080/get" +``` + +You should see a response similar to the following: + +```text { + "args": { + "arg1": "apisix", + "arg2": "plugin" + }, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef6dc-2b0e09591db7353a275cdae4", + "X-Forwarded-Host": "127.0.0.1" + }, + "origin": "127.0.0.1, 103.248.35.148", + # highlight-next-line + "url": "http://127.0.0.1/get?arg1=apisix&arg2=plugin" +} +``` + +### Rewrite HTTP Method + +The following example demonstrates how you can rewrite a GET request into a POST request. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", - "plugins": {}, + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/anything", + "method":"POST" + } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a GET request to `/get` to verify if it is transformed into a POST request to `/anything`: + +```shell +curl "http://127.0.0.1:9080/get" +``` + +You should see a response similar to the following: + +```text +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef7de-0c63387645353998196317f2", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "POST", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything" +} +``` + +### Forward Consumer Names to Upstream + +The following example demonstrates how you can forward the name of consumers who authenticates successfully to upstream services. As an example, you will be using `key-auth` as the authentication method. + +Create a consumer `JohnDoe`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "JohnDoe" + }' +``` + +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-john-key-auth", + "plugins": { + "key-auth": { + "key": "john-key" + } + } + }' +``` + +Next, create a Route with key authentication enabled, configure `proxy-rewrite` to add consumer name to the header, and remove the authentication key so that it is not visible to the upstream service: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "consumer-restricted-route", + "uri": "/get", + "plugins": { + "key-auth": {}, + "proxy-rewrite": { + "headers": { + "set": { + "X-Apisix-Consumer": "$consumer_name" + }, + "remove": [ "Apikey" ] } + } + }, + "upstream" : { + "nodes": { + "httpbin.org":1 + } } -}' + }' ``` + +Send a request to the Route as consumer `JohnDoe`: + +```shell +curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key' +``` + +You should receive an `HTTP/1.1 200 OK` response with the following body: + +```text +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.4.0", + "X-Amzn-Trace-Id": "Root=1-664b01a6-2163c0156ed4bff51d87d877", + "X-Apisix-Consumer": "JohnDoe", + "X-Forwarded-Host": "127.0.0.1" + }, + "origin": "172.19.0.1, 203.12.12.12", + "url": "http://127.0.0.1/get" +} +``` + +Send another request to the Route without the valid credential: + +```shell +curl -i "http://127.0.0.1:9080/get" +``` + +You should receive an `HTTP/1.1 403 Forbidden` response. diff --git a/docs/zh/latest/plugins/proxy-rewrite.md b/docs/zh/latest/plugins/proxy-rewrite.md index d3204b9ed027..3a7f788a5b82 100644 --- a/docs/zh/latest/plugins/proxy-rewrite.md +++ b/docs/zh/latest/plugins/proxy-rewrite.md @@ -30,31 +30,22 @@ description: 本文介绍了关于 Apache APISIX `proxy-rewrite` 插件的基本 ## 描述 -`proxy-rewrite` 是处理上游代理信息重写的插件，支持对 `scheme`、`uri`、`host` 等信息进行重写。 +`proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP 方法、请求目标上游地址、请求标头等。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| --------- | ------------- | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uri | string | 否 | | | 转发到上游的新 `uri` 地址。支持 [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html) 变量，例如：`$arg_name`。 | -| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 将路由的请求方法代理为该请求方法。 | -| regex_uri | array[string] | 否 | | | 使用正则表达式匹配来自客户端的 `uri`，如果匹配成功，则使用模板替换转发到上游的 `uri`，如果没有匹配成功，则将客户端请求的 `uri` 转发至上游。当同时配置 `uri` 和 `regex_uri` 属性时，优先使用 `uri`。当前支持多组正则表达式进行模式匹配，插件将逐一尝试匹配直至成功或全部失败。例如：`["^/iresty/(.*)/(.*)/(.*)", "/$1-$2-$3", ^/theothers/(.*)/(.*)", "/theothers/$1-$2"]`，奇数索引的元素代表匹配来自客户端请求的 `uri` 正则表达式，偶数索引的元素代表匹配成功后转发到上游的 `uri` 模板。请注意该值的长度必须为**偶数值**。 | -| host | string | 否 | | | 转发到上游的新 `host` 地址，例如：`iresty.com`。| -| headers | object | 否 | | | | -| headers.add | object | 否 | | | 添加新的请求头，如果头已经存在，会追加到末尾。格式为 `{"name": "value", ...}`。这个值能够以 `$var` 的格式包含 NGINX 变量，比如 `$remote_addr $balancer_ip`。也支持以变量的形式引用 `regex_uri` 的匹配结果，比如 `$1-$2-$3`。 | -| headers.set | object | 否 | | | 改写请求头，如果请求头不存在，则会添加这个请求头。格式为 `{"name": "value", ...}`。这个值能够以 `$var` 的格式包含 NGINX 变量，比如 `$remote_addr $balancer_ip`。也支持以变量的形式引用 `regex_uri` 的匹配结果，比如 `$1-$2-$3`。请注意，若想设置 `Host` 请求头，应使用 `host` 属性。 | -| headers.remove | array | 否 | | | 移除请求头。格式为 `["name", ...]`。| -| use_real_request_uri_unsafe | boolean | 否 | false | | 使用 real_request_uri（nginx 中的原始 $request_uri）绕过 URI 规范化。启用它被认为是不安全的，因为它会绕过所有 URI 规范化步骤。| +| 名称 | 类型 | 必需 | 默认值 | 有效值 | 描述 | +|-----------------------------|-----------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| uri | string | 否 | | | 新的上游 URI 路径。值支持 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。例如，`$arg_name`。 | +| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 要使用的重写请求的 HTTP 方法。 | +| regex_uri | array[string] | 否 | | | 用于匹配客户端请求的 URI 路径并组成新的上游 URI 路径的正则表达式。当同时配置 `uri` 和 `regex_uri` 时，`uri` 具有更高的优先级。该数组应包含一个或多个 **键值对**，其中键是用于匹配 URI 的正则表达式，值是新的上游 URI 路径。例如，对于 `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`，如果请求最初发送到 `/iresty/hello/world`，插件会将上游 URI 路径重写为 `/iresty/hello-world`；如果请求最初发送到 `/theothers/hello/world`，插件会将上游 URI 路径重写为 `/theothers`。| +| host | string | 否 | | | 设置 [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求标头。| +| headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set` 的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照“添加”、“删除”和“设置”的顺序执行。| +| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 -## Header 优先级 +## 示例 -Header 头的相关配置，遵循如下优先级进行执行： - -`add` > `remove` > `set` - -## 启用插件 - -你可以通过如下命令在指定路由上启用 `proxy-rewrite` 插件： +下面的示例说明如何在不同场景中在路由上配置 `proxy-rewrite`： :::note @@ -66,69 +57,446 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 重写主机标头 + +以下示例演示了如何修改请求中的 `Host` 标头。请注意，您不应使用 `headers.set` 来设置 `Host` 标头。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "host": "myapisix.demo" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +向 `/headers` 发送请求以检查发送到上游的所有请求标头： + +```shell +curl "http://127.0.0.1:9080/headers" +``` + +您应该看到类似于以下内容的响应： + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "myapisix.demo", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef198-29da0970383150175bd2d76d", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +### 重写 URI 并设置标头 + +以下示例演示了如何重写请求上游 URI 并设置其他标头值。如果客户端请求中存在相同的标头，则插件中设置的相应标头值将覆盖客户端请求中存在的值。 + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/", + "plugins": { + "proxy-rewrite": { + "uri": "/anything", + "headers": { + "set": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } + } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +发送请求以验证： + +```shell +curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"' +``` + +您应该看到类似于以下内容的响应： + +```text { + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything" +} +``` + +请注意，存在的两个标头和插件中配置的 `X-Api-Version` 标头值都会覆盖请求中传递的标头值。 + +### 重写 URI 并附加标头 + +以下示例演示了如何重写请求上游 URI 并附加其他标头值。如果客户端请求中存在相同的标头，则它们的标头值将附加到插件中配置的标头值。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/", "plugins": { - "proxy-rewrite": { - "uri": "/test/home.html", - "host": "iresty.com", - "headers": { - "set": { - "X-Api-Version": "v1", - "X-Api-Engine": "apisix", - "X-Api-useless": "" - }, - "add": { - "X-Request-ID": "112233" - }, - "remove":[ - "X-test" - ] - } + "proxy-rewrite": { + "uri": "/headers", + "headers": { + "add": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } } + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +发送请求以验证： + +```shell +curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"' +``` + +您应该会看到类似以下内容的响应： + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1,v2", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +请注意，两个标头均存在，并且插件中配置的 `X-Api-Version` 标头值均附加在请求中传递的标头值上。 + +### 删除现有标头 + +以下示例演示了如何删除现有标头 `User-Agent`。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "headers": { + "remove":[ + "User-Agent" + ] } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +发送请求来验证指定的标头是否被删除： + +```shell +curl "http://127.0.0.1:9080/headers" +``` + +您应该看到类似以下的响应，其中 `User-Agen` 标头已被移除： + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "X-Amzn-Trace-Id": "Root=1-64fef302-07f2b13e0eb006ba776ad91d", + "X-Forwarded-Host": "127.0.0.1" + } +} ``` -## 测试插件 +### 使用 RegEx 重写 URI -通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功： +以下示例演示了如何解析原始上游 URI 路径中的文本并使用它们组成新的上游 URI 路径。在此示例中，APISIX 配置为将所有请求从 `/test/user/agent` 转发到 `/user-agent`。 ```shell -curl -X GET http://127.0.0.1:9080/test/index.html +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "uri": "/test/*", + "plugins": { + # highlight-start + "proxy-rewrite": { + "regex_uri": ["^/test/(.*)/(.*)", "/$1-$2"] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` -发送请求，查看上游服务的 `access.log`，如果输出信息与配置一致则表示 `proxy-rewrite` 插件已经生效。示例如下： +发送请求到 `/test/user/agent`，检查是否被重定向到 `/user-agent`： +```shell +curl "http://127.0.0.1:9080/test/user/agent" ``` -127.0.0.1 - [26/Sep/2019:10:52:20 +0800] iresty.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107 + +您应该会看到类似以下内容的响应： + +```text +{ + "user-agent": "curl/8.2.1" +} ``` -## 删除插件 +### 添加 URL 参数 + +以下示例演示了如何向请求添加 URL 参数。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/get?arg1=apisix&arg2=plugin" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -当你需要禁用 `proxy-rewrite` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +发送请求来验证 URL 参数是否也转发给了上游： ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9080/get" +``` + +您应该会看到类似以下内容的响应： + +```text { + "args": { + "arg1": "apisix", + "arg2": "plugin" + }, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef6dc-2b0e09591db7353a275cdae4", + "X-Forwarded-Host": "127.0.0.1" + }, + "origin": "127.0.0.1, 103.248.35.148", + # highlight-next-line + "url": "http://127.0.0.1/get?arg1=apisix&arg2=plugin" +} +``` + +### 重写 HTTP 方法 + +以下示例演示如何将 GET 请求重写为 POST 请求。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", - "plugins": {}, + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/anything", + "method":"POST" + } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +向 `/get` 发送 GET 请求，以验证它是否转换为向 `/anything` 发送 POST 请求： + +```shell +curl "http://127.0.0.1:9080/get" +``` + +您应该会看到类似以下内容的响应： + +```text +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef7de-0c63387645353998196317f2", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "POST", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything" +} +``` + +### 将消费者名称转发到上游 + +以下示例演示了如何将成功验证的消费者名称转发到上游服务。例如，您将使用 `key-auth` 作为身份验证方法。 + +创建消费者 `JohnDoe`： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "JohnDoe" + }' +``` + +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-john-key-auth", + "plugins": { + "key-auth": { + "key": "john-key" + } + } + }' +``` + +接下来，创建一个启用密钥认证的路由，配置 `proxy-rewrite` 以将消费者名称添加到标头，并删除认证密钥，以使其对上游服务不可见： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "consumer-restricted-route", + "uri": "/get", + "plugins": { + "key-auth": {}, + "proxy-rewrite": { + "headers": { + "set": { + "X-Apisix-Consumer": "$consumer_name" + }, + "remove": [ "Apikey" ] } + } + }, + "upstream" : { + "nodes": { + "httpbin.org":1 + } } -}' + }' ``` + +以消费者 `JohnDoe` 的身份向路由发送请求： + +```shell +curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key' +``` + +您应该收到一个包含以下主体的 `HTTP/1.1 200 OK` 响应： + +```text +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.4.0", + "X-Amzn-Trace-Id": "Root=1-664b01a6-2163c0156ed4bff51d87d877", + "X-Apisix-Consumer": "JohnDoe", + "X-Forwarded-Host": "127.0.0.1" + }, + "origin": "172.19.0.1, 203.12.12.12", + "url": "http://127.0.0.1/get" +} +``` + +向路由发送另一个请求，不带有有效凭证： + +```shell +curl -i "http://127.0.0.1:9080/get" +``` + +您应该收到 `HTTP/1.1 403 Forbidden` 响应。 From 3662b4d421432fbeb51dae501d509ca77da67f97 Mon Sep 17 00:00:00 2001 From: traky Date: Mon, 23 Dec 2024 14:22:53 +0800 Subject: [PATCH 2/9] update attributes --- docs/zh/latest/plugins/proxy-rewrite.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/zh/latest/plugins/proxy-rewrite.md b/docs/zh/latest/plugins/proxy-rewrite.md index 3a7f788a5b82..5e46cf04d8e8 100644 --- a/docs/zh/latest/plugins/proxy-rewrite.md +++ b/docs/zh/latest/plugins/proxy-rewrite.md @@ -41,7 +41,10 @@ description: 本文介绍了关于 Apache APISIX `proxy-rewrite` 插件的基本 | regex_uri | array[string] | 否 | | | 用于匹配客户端请求的 URI 路径并组成新的上游 URI 路径的正则表达式。当同时配置 `uri` 和 `regex_uri` 时，`uri` 具有更高的优先级。该数组应包含一个或多个 **键值对**，其中键是用于匹配 URI 的正则表达式，值是新的上游 URI 路径。例如，对于 `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`，如果请求最初发送到 `/iresty/hello/world`，插件会将上游 URI 路径重写为 `/iresty/hello-world`；如果请求最初发送到 `/theothers/hello/world`，插件会将上游 URI 路径重写为 `/theothers`。| | host | string | 否 | | | 设置 [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求标头。| | headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set` 的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照“添加”、“删除”和“设置”的顺序执行。| -| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 +| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。| +| headers.set | object | 否 | | | 要设置请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量、一个或多个 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。不应将其用于设置 `Host`。| +| headers.remove | array[string] | 否 | | | 从请求中删除的标头。 +| use_real_request_uri_unsafe | boolean | 否 | false | | 如果为 True，则绕过 URI 规范化并允许完整的原始请求 URI。启用此选项被视为不安全。| ## 示例 From 2c27e35e59215674009d15f4dac62be6720f7f52 Mon Sep 17 00:00:00 2001 From: traky Date: Mon, 23 Dec 2024 14:26:10 +0800 Subject: [PATCH 3/9] fix broken chinese --- docs/zh/latest/plugins/proxy-rewrite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/latest/plugins/proxy-rewrite.md b/docs/zh/latest/plugins/proxy-rewrite.md index 5e46cf04d8e8..c28eeeb13761 100644 --- a/docs/zh/latest/plugins/proxy-rewrite.md +++ b/docs/zh/latest/plugins/proxy-rewrite.md @@ -166,7 +166,7 @@ curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"' } ``` -请注意，存在的两个标头和插件中配置的 `X-Api-Version` 标头值都会覆盖请求中传递的标头值。 +注意到其中两个标头都存在，以及插件中配置的 `X-Api-Version` 标头值覆盖了请求中传递的标头值。 ### 重写 URI 并附加标头 From 824a29c922cae5c2c2af2042660df71e45f5ced6 Mon Sep 17 00:00:00 2001 From: traky Date: Mon, 23 Dec 2024 14:27:40 +0800 Subject: [PATCH 4/9] edit --- docs/en/latest/plugins/proxy-rewrite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/plugins/proxy-rewrite.md b/docs/en/latest/plugins/proxy-rewrite.md index 160ab2f55783..efdc6a4b547f 100644 --- a/docs/en/latest/plugins/proxy-rewrite.md +++ b/docs/en/latest/plugins/proxy-rewrite.md @@ -30,7 +30,7 @@ description: This document contains information about the Apache APISIX proxy-re ## Description -The `proxy-rewrite` Plugin offers options to rewrite requests that APISIX forwards to upstream services. With this plugin, you can modify the HTTP methods, request destination upstream address, request headers, and more. +The `proxy-rewrite` Plugin offers options to rewrite requests that APISIX forwards to upstream services. With this plugin, you can modify the HTTP methods, request destination upstream addresses, request headers, and more. ## Attributes From 20d86af702d73578e6ddfd46b9b13ad3bbb2f25f Mon Sep 17 00:00:00 2001 From: Traky Deng Date: Mon, 23 Dec 2024 15:13:18 +0800 Subject: [PATCH 5/9] update description --- docs/en/latest/plugins/proxy-rewrite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/plugins/proxy-rewrite.md b/docs/en/latest/plugins/proxy-rewrite.md index efdc6a4b547f..0b14d7c6d15c 100644 --- a/docs/en/latest/plugins/proxy-rewrite.md +++ b/docs/en/latest/plugins/proxy-rewrite.md @@ -6,7 +6,7 @@ keywords: - Plugin - Proxy Rewrite - proxy-rewrite -description: This document contains information about the Apache APISIX proxy-rewrite Plugin. +description: The proxy-rewrite Plugin offers options to rewrite requests that APISIX forwards to upstream services. With this plugin, you can modify the HTTP methods, request destination upstream addresses, request headers, and more. --- + + + + ## Description The `proxy-rewrite` Plugin offers options to rewrite requests that APISIX forwards to upstream services. With this plugin, you can modify the HTTP methods, request destination upstream addresses, request headers, and more. diff --git a/docs/zh/latest/plugins/proxy-rewrite.md b/docs/zh/latest/plugins/proxy-rewrite.md index c28eeeb13761..69c1fe8fd2e4 100644 --- a/docs/zh/latest/plugins/proxy-rewrite.md +++ b/docs/zh/latest/plugins/proxy-rewrite.md @@ -28,6 +28,10 @@ description: 本文介绍了关于 Apache APISIX `proxy-rewrite` 插件的基本 # --> + + + + ## 描述 `proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP 方法、请求目标上游地址、请求标头等。