自定义 Rewrite 功能用户指南

自定义Rewrite 功能是指通过 DSL（Domain Specific Language）书写 Rewrite 规则（支持函数，变量，字符串常量的自由组合），以完成对请求的重写。

该功能适用范围：UPYUN 存储及自主源站服务。

快速开始

下面带大家了解下如何在 UPYUN 管理中心使用该功能。

首先打开 UPYUN 管理中心，依次进入

服务 > 高级功能 > Rewrite 配置，点击“管理”按钮

功能开关

在弹出的弹出框上方首先是该功能的总开关，用户控制您自定义的 Rewrite 规则是否生效。默认为关闭状态，需要用户手动开启，点击保存后生效，初次配置您可以设为开启状态，日后需要关闭时再进行更改。 

添加规则

点击“添加规则”按钮，在列表中输入「Rewrite 规则」，「URI 提取正则」，及「break 选项」，如下图

「URI 提取正则」为对当前请求 URI 进行匹配的 PCRE 正则表达式，匹配后，产生 $1, $2 … 这样的变量；「Rewrite规则」为当前的 rewrite 规则，「break选项」表示如果此次 rewrite 成功后是否要终止剩下的的 rewrite 过程，该选项默认为选中状态，填写完毕后点击对号图标，并点击保存完成添加。

关于规则的书写，参见《Rewrite规则》配置说明。

调试模式

由于 rewrite 过程会对当前请求产生副作用，这是非常危险的，例如随意的填写一条 rewrite 规则：/foo

此规则会将所有请求的 URI 改写成 /foo，这样客户端所有请求的响应就变成 404 了， 这是您极不愿意看到的结果。我们允许对 rewrite 规则进行调试，即新增加一条规则时，调试模式 开关会默认打开

这样添加规则后，即使当前请求命中该 rewrite 规则， rewrite 过程也不会生效，只有当包含以下请求头时，rewrite 过程才会生效：

X-Upyun-Rewrite-Preview: true

使用命令行工具 curl 即可对规则调试：

curl -H "X-Upyun-Rewrite-Preview: true" http://your-domain/foo/bar.html -v

这样经过调试，确定该 rewrite 过程符合预期后，即可将 调试模式 关闭，此时该 rewrite 过程会对所有命中的请求生效。

调整规则排序

自定义 Rewrite 功能支持自定义多条规则，请求时按顺序对规则进行匹配，一个请求可命中多条规则。如果检查到有 break 标识且此次 rewrite 成功，则跳出查找，使用此次匹配到的规则；如未找到 break 标识，则用最后一条匹配的规则。

您可以通过点击上下箭头，控制规则的排序。将权重较高的规则排在下方，如下图所示：

修改及删除

支持对规则的修改及删除

点击「删除」按钮，确认后即可删除文件，数据删除后无法恢复！

注意事项

1. 一个规则集里面最多支持添加 20 条规则，URI 提取正则和 rewrite 规则最多支持输入 256 个字符。

2. rewrite 规则中支持插入函数、变量、字符串常量，并且函数间可以相互嵌套。例如：/$SUB($DECODE_BASE64($_HEADER_foo), $_GET_from, $_GET_to)/ 。

3. 对于含有请求参数的规则，原先的请求参数会附加到后面，如果不希望这样，可以放置一个 '?' 在规则的最后面，例如：/foo?bar=$1?。