自定义Cachekey-边缘安全加速(ESA)-阿里云帮助中心

配置自定义缓存键（Cache Key），开发者可以根据HTTP请求的不同部分（例如URI、请求参数、HTTP请求头或自定义变量等）制定规则来生成Cache Key，将访问同一个文件的一类请求转化为统一的Cache Key，提高缓存命中率，降低回源率，减少请求的响应时间和带宽消耗。

注意事项

自定义 CacheKey 与忽略参数

自定义 CacheKey 的参数操作功能与忽略参数功能均可控制 URL 查询参数是否参与缓存键的生成。同时开启两项功能时，可能导致缓存键生成规则冲突，出现缓存命中率下降或缓存内容异常。

重要

如果已开启自定义 CacheKey 的参数操作，建议关闭忽略参数功能，避免规则相互覆盖。自定义 CacheKey 的参数操作已涵盖忽略参数的能力（通过删除或保留操作实现），且提供更灵活的参数控制。

如果当前使用忽略参数功能，可参考以下对比表格，选择是否迁移到自定义 CacheKey 的参数操作。

场景	忽略参数	自定义 CacheKey
在缓存键中忽略所有请求参数	忽略参数设置为是，保留指定参数为空	添加一条请求参数处理策略：操作方式：保留参数名：设置为任意一个不存在的参数名即可，例如：`example-argument`
在缓存键中仅保留请求参数`key1`	忽略参数设置为是，保留指定参数设置为`key1`	添加一条请求参数处理策略：操作方式：保留参数名：`key1`
在缓存键中仅删除请求参数`key1`	删除指定参数设置为`key1`	添加一条请求参数处理策略：操作方式：删除参数名：`key1`

说明

如果需要在忽略或保留参数的基础上，进一步修改参数值或新增额外参数，建议使用自定义 CacheKey 的参数操作替代忽略参数功能。

缓存刷新

配置自定义 CacheKey 后，DCDN 节点上缓存的文件将使用处理后的缓存键进行索引。通过 URL 刷新缓存时，提交的 URL 必须与 DCDN 节点上实际存储的缓存键一致，否则刷新操作无法命中目标缓存。

说明

例如，配置了 URI 替换规则将 `/a/b/image.jpg` 替换为 `/c/image.jpg`，则 DCDN 节点上该文件的缓存键为 `http://aliyundoc.com/c/image.jpg`。刷新该文件的缓存时，需要提交 `http://aliyundoc.com/c/image.jpg`（处理后的缓存键），而非客户端的原始请求 URL。

如果配置了参数操作（如删除或修改参数），刷新时同样需要使用参数处理后的 URL 作为刷新地址。建议在配置自定义 CacheKey 规则后，记录最终生成的缓存键格式，便于后续执行缓存刷新操作。

回源参数改写

自定义 CacheKey 仅影响 DCDN 节点上缓存键的生成规则，不会修改实际的回源 URL。DCDN 节点回源时仍然使用客户端原始请求的 URL 向源站发起请求。如需改写回源请求的参数或路径，请使用回源改写功能。

说明

例如，客户端请求 http://example.com/image.jpg?key1=1&key2=2，配置自定义 CacheKey 删除参数 key1 后，缓存键变为 http://example.com/image.jpg?key2=2，但回源时 DCDN 节点仍然向源站请求原始 URL http://example.com/image.jpg?key1=1&key2=2。

使用场景

重要

自定义Cache Key功能不会修改回源的URL，仅会修改请求的缓存标识，回源的请求和客户端发起的请求内容保持一致。

Cachekey 是文件在 DCDN 节点上缓存时的唯一标识，每个缓存文件都对应一个 Cachekey。默认的 Cachekey 为客户端请求的完整 URL（含参数）。

场景一

客户不同请求的 URL 中含有复杂的参数，因此即使多个请求访问的是同一个文件，但由于 URL 参数不同，DCDN 节点会视为请求不同文件而将不同请求缓存成多个文件，造成回源的请求增加。

可通过自定义 Cachekey 规则将同一类请求的 Cachekey 统一，降低回源率。

场景二

客户端请求的 URL 一样时，DCDN 将视为请求同一个文件。但实际上请求的 HTTP Header 中携带了 client 字段区分了客户端系统，希望请求不同文件。场景一

此时可通过自定义 Cachekey 将 client 字段的值拼接至 Cachekey，两个请求即可识别为 2 个不同的 Cachekey。场景二

操作步骤

登录DCDN控制台。
在左侧导航栏，单击域名管理。
在域名管理页面，单击目标域名对应的配置。
在指定域名的左侧导航栏，单击缓存配置。

在自定义Cachekey页签配置 Cachekey。

说明

支持对 URI、参数操作、HTTP Header 进行修改，同时支持自定义变量，从请求中提取需要的字段。最终的 Cachekey 将由 URI、参数操作、HTTP Header、自定义变量四部分组合而成。

自定义Cachekey

参数类型	操作说明
规则条件	规则条件能够对用户请求中携带的各种参数信息进行识别，以此来决定某个配置是否对该请求生效。不使用：不使用规则条件。若需新增或编辑规则条件，请在规则引擎中进行管理。
URI	当客户端请求的 URI 与配置中的源URI相匹配时，系统会用配置中的目标URI替换源URI来生成 Cachekey。支持配置多个 URI 替换策略。若存在多条策略，则按照从上到下的顺序依次进行匹配。一旦匹配到某个源URI，系统将使用该策略对应的目标URI执行替换操作，并停止与后续策略的匹配。源URI：以正斜线（/）开头的 URI，不含 http：//头及域名。支持`PCRE`正则表达式。目标URI：以正斜线（/）开头的 URI，不含 http：//头及域名。
参数操作	操作的对象是用户发起的原始请求 URL 中携带的参数，可以对参数进行新增、删除、修改、保留操作，操作后的结果将会拼接到 Cachekey 中。支持设置多个操作，存在多个操作的情况下，将会从上到下按顺序逐个执行。新增：将新增的请求参数拼接到 Cachekey 中。例如：原始 URL 为`http://image.example.com/cat.jpg`，新增一个请求参数`type=jpg`，则 Cachekey 为`http://image.example.com/cat.jpg?type=jpg`。删除：在生成 Cachekey 时删除原始请求 URL 中的指定参数。例如：原始 URL 为`http://image.example.com/cat.jpg?type=jpg`，删除参数`type`，则 Cachekey 为`http://image.example.com/cat.jpg`。修改：在生成 Cachekey 时修改原始请求 URL 中的指定参数。例如：原始 URL 为`http://image.example.com/cat.jpg?type=jpg`，修改参数`type=png`，则 Cachekey 为`http://image.example.com/cat.jpg?type=png`。保留：在生成 Cachekey 时仅保留原始请求 URL 中的指定参数。例如：原始 URL 为`http://image.example.com/cat.jpg?type=jpg&path=image`，保留参数`type`，则 Cachekey 为`http://image.example.com/cat.jpg?type=jpg`。
HTTP HEADER	将客户端原始请求中携带的指定 HTTP Header 的值拼接到 Cachekey 中。支持配置多个 HTTP Header 名称（多个名称之间用空格分隔），每个 HTTP Header 的值将按顺序拼接到 Cachekey 中。例如：原始 URL 为`http://image.example.com/cat.jpg`，客户端请求携带了一个`HTTP Header（path:image）`；如果HTTP Header中设置了`path`这个请求头，则 Cachekey 为`http://image.example.com/cat.jpgimage`。
自定义变量	可以使用正则表达式来匹配客户端原始请求中携带的指定请求参数的值、指定 HTTP Header 的值、指定 Cookie 参数的值、指定的 URI，正则表达式匹配命中时，将对应的值拼接到 Cachekey 中。具体使用请参见配置示例。

单击确定，完成配置。

配置示例

URI

客户端的请求http://aliyundoc.com/a/b/image.jpg和http://aliyundoc.com/a/b/c/image.jpg 将视为请求同一个文件，该文件的 Cachekey 为http://aliyundoc.com/c/image.jpg。

参数操作

客户端的请求http://aliyundoc.com/a/b/image.jpg?delete_par=1&modify_par=1 将按规则添加add_par=1，删除delete_par，将modify_par的值修改为2，最终转化为http://aliyundoc.com/a/b/image.jpg?modify_par=2&add_par=1。

重要

参数操作中，如对同一个变量同时进行了多个操作，则各种操作的生效优先级：新增>；删除>；仅保留>；修改。

HTTP HEADER

客户端请求的 HTTP Header 的User-Agent和Accept-Language的值将被拼接到 Cachekey 中。例如请求http://aliyundoc.com/a/b/image.jpg中的User-Agent=Mozilla/5.0 (Linux; X11)，Accept-Language=en，则该请求的 Cachekey 为：http://aliyundoc.com/a/b/image.jpgMozilla/5.0(Linux;X11)en。

自定义变量

示例一

变量名为language，来源为Request Header，来源字段名为Accept-Language，匹配规则为 ([%w]+),([%w]+)，变量表达式为$1aa。

客户端的请求http://aliyundoc.com/a/b/image.jpg且携带 HTTP 请求头Accept-Language=en,ch ，则匹配规则将匹配到en赋值给变量表达式中的$1。变量表达式还将在末尾拼接上aa，得到enaa的变量并取别名为language，拼接在 URL 后方形成最终的 Cachekey：http://aliyundoc.com/a/b/image.jpgenaa。

说明

变量表达式中的$n的含义是匹配规则中第n个括号所匹配到的内容。例如示例一中Accept-Language=en,ch，匹配规则为([%w]+),([%w]+)，则$1=en，$2=ch。

示例二

变量名为expired，来源为Request Cookie，来源字段名为a，匹配规则为[%w]+:(.*)，变量表达式为 $1。

客户端的请求http://aliyundoc.com/a/b/image.jpg且携带Cookie a=expired_time:12635187，则匹配规则将匹配到12635187赋值给变量表达式中的$1并取别名为expired，拼接在 URL 后方形成最终的 Cachekey：http://aliyundoc.com/a/b/image.jpg12635187。

示例三

同时设置 URI 规则和自定义变量。

URI：
将所有 URI 符合/abc/.*/abc的请求都合并成 /abc。
自定义变量：
变量名为testname，来源为Path，匹配规则为/abc/xyz/(.*)，变量表达式为$1。
客户端的请求 URLhttp://aliyundoc.com/abc/xyz/abc/image.jpg，按 URI 的配置 Cachekey 将被合并成http://aliyundoc.com/abc/image.jpg，然后根据自定义变量的配置该 URL 将会命中/abc/xyz/(.*)，此时$1将被赋值为abc并拼接到 Cachekey 中，形成最终的 Cachekey：http://aliyundoc.com/abc/image.jpgabc，从而达到两个规则组合使用，实现更复杂的缓存逻辑。
如果没有匹配到 CacheKey 的自定义变量，则变量表达式$1就不会被拼接到 CacheKey 中。