AI 助理
文档备案控制台
官方文档
首页

自定义Cache Key

更新时间：
复制 MD 格式
产品详情
我的收藏

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

功能对比与选择

  • 自定义Cache Key与 忽略参数 存在冲突 ：开启忽略参数后，节点会去除URL中?之后的参数，导致自定义Cache Key中的请求参数配置失效。使用自定义Cache Key前，请关闭忽略参数。

  • 自定义Cache Key功能更全面，可替代忽略参数缓存键配置，推荐优先使用。配置对比：

    场景

    忽略参数

    自定义Cache Key

    在缓存键中忽略所有请求参数

    忽略参数设置为是，保留指定参数留空

    添加一条请求参数处理策略：

    • 操作方式：保留

    • 参数名：设为任意不存在的参数名，例如 example-argument

    在缓存键中仅保留请求参数key1

    忽略参数设置为是，保留指定参数设置为key1

    添加一条请求参数处理策略：

    • 操作方式：保留

    • 参数名：key1

    在缓存键中仅删除请求参数key1

    删除指定参数设置为key1

    添加一条请求参数处理策略：

    • 操作方式：删除

    • 参数名：key1

  • 回源参数改写：自定义Cache Key功能不修改回源URL，仅修改请求的缓存标识，回源请求与客户端请求内容一致。如果需要改写回源URL携带的请求参数，请使用重写回源参数。

  • 缓存刷新：配置自定义 Cache Key 后，按URL提交刷新任务可能无法正确匹配缓存内容，请提交经过自定义Cache Key功能处理后的缓存键作为刷新对象。

使用场景

重要

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

Cache Key是一个文件在CDN节点上缓存时唯一的身份ID，每个在CDN节点上缓存的文件都对应一个Cache Key。文件的Cache Key默认为客户端请求的URL（带参数）。

场景一

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

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

场景二

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

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

重要

功能配置在引用规则引擎上的规则条件配置时，配置的执行顺序不是按照配置的优先级顺序执行，而是会按照配置关联的规则条件的优先级顺序来执行。

操作步骤

  1. 登录CDN控制台。

  2. 在左侧导航栏，单击域名管理。

  3. 在域名管理页面，找到目标域名，单击操作列的管理。

  4. 在指定域名的左侧导航栏，单击缓存配置。

  5. 在自定义Cachekey页签下，单击配置，配置Cache Key。

    参数类型

    操作说明

    规则条件

    规则条件能够对用户请求中携带的各种参数信息进行识别，以此来决定某个配置是否对该请求生效。

    重要

    引用规则条件时，按所关联规则条件的优先级匹配，而非按功能自身的配置顺序匹配。

    • 不使用：不使用规则条件。

    • 若需新增或编辑规则条件，请在规则引擎中进行管理。

    URI

    当客户端请求的URI与配置中的源URI相匹配时，系统会用配置中的目标URI替换源URI，来生成Cache Key。则使用配置中的目标URI替换源URI来拼接Cache Key。

    支持配置多个URI替换策略。若存在多条策略，则按照从上到下的顺序依次进行匹配。一旦匹配到某个源URI，系统将使用该策略对应的目标URI执行替换操作，并停止与后续策略的匹配。

    • 源URI：以正斜线（/）开头的URI，不含http://头及域名。支持PCRE正则表达式。

    • 目标URI：以正斜线（/）开头的URI，不含http://头及域名。

    请求参数

    操作的对象是用户发起的原始请求URL中携带的参数，可以对参数进行新增、删除、修改、保留操作，操作后的结果将会拼接到Cache Key中。支持设置多个操作，存在多个操作的情况下，将会从上到下按顺序逐个执行。

    • 新增：将新增的请求参数拼接到Cache Key中。例如：原始URL为http://image.example.com/cat.jpg，新增一个请求参数type=jpg，则Cache Key为http://image.example.com/cat.jpg?type=jpg。

    • 删除：在生成Cache Key的时候删除原始请求URL中的指定参数。例如：原始URL为 http://image.example.com/cat.jpg?type=jpg，删除参数type，则Cache Key为http://image.example.com/cat.jpg。

    • 修改：在生成Cache Key的时候修改原始请求URL中的指定参数。例如：原始URL为 http://image.example.com/cat.jpg?type=jpg，修改参数type=png，则Cache Key为。

    • 保留：在生成Cache Key的时候仅保留原始请求URL中的指定参数。例如：原始URL为http://image.example.com/cat.jpg?type=jpg&path=image，保留参数type，则Cache Key为http://image.example.com/cat.jpg?type=jpg。

    HTTP Header

    将客户端原始请求中携带的指定HTTP Header的值拼接到Cache Key中。支持配置多个HTTP Header名称（多个 HTTP Header 名称之间用空格分隔），效果是每个HTTP Header的值将会按顺序拼接到Cache Key中。

    例如：原始URL为 http://image.example.com/cat.jpg，客户端请求携带了一个HTTP Header（path:image）；如果HTTP Header中设置了path这个请求头，则Cache Key为http://image.example.com/cat.jpgimage。

    自定义变量

    可以使用正则表达式来匹配客户端原始请求中携带的指定请求参数的值、指定HTTP Header的值、指定Cookie参数的值、指定的URI，正则表达式匹配命中时，将对应的值拼接到Cache Key中。具体使用请参见配置示例。

  6. 单击确定。

配置示例

URI

客户端的请求http://aliyundoc.com/a/b/image.jpg和http://aliyundoc.com/a/b/c/image.jpg 将视为请求同一个文件，该文件的Cache Key为http://aliyundoc.com/c/image.jpg。URI改写规则配置示例：将源URI /a/b 改写为目标URI /c，将源URI /a/b/c 改写为目标URI /c。单击+ 添加源URI可新增改写规则，单击删除可移除已有规则。

请求参数

客户端的请求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的值将被拼接到Cache Key中。例如请求http://aliyundoc.com/a/b/image.jpg中的User-Agent=Mozilla/5.0 (Linux; X11)，Accept-Language=en，则该请求的Cache Key为：http://aliyundoc.com/a/b/image.jpgMozilla/5.0(Linux;X11)en。在 HTTP HEADER 输入框中填写需要采集的请求头字段，例如 User-Agent 和 Accept-Language。

自定义变量

示例一

变量名为language，来源为Request Header，来源字段名为Accept-Language，匹配规则为 ([%w]+),([%w]+)，变量表达式为$1aa。自定义变量配置示例：变量名设置为 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后方形成最终的Cache Key：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。自定义变量配置示例： - 变量名：expired - 来源：Request Cookie - 来源字段名：a - 匹配规则：[%w]+:(.*) - 变量表达式：$1

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

示例三

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

URI：

将所有URI符合/abc/.*/abc的请求都合并成 /abc。源URI为/abc/.*/abc，目标URI为/abc。

自定义变量：

变量名为testname，来源为Path，匹配规则为/abc/xyz/(.*)，变量表达式为$1。变量名：testname；来源：Path；匹配规则：/abc/xyz/(.*)；变量表达式：$1

客户端的请求URLhttp://aliyundoc.com/abc/xyz/abc/image.jpg，按URI的配置Cache Key将被合并成http://aliyundoc.com/abc/image.jpg， 然后根据自定义变量的配置该URL将会命中/abc/xyz/(.*)，此时$1将被赋值为abc并拼接到Cache Key中，形成最终的Cache Key：http://aliyundoc.com/abc/image.jpgabc，从而达到两个规则组合使用，实现更复杂的缓存逻辑。

如果没有匹配到Cache Key的自定义变量，则变量表达式$1就不会被拼接到Cache Key中。

示例四

同时设置规则条件和自定义变量，使来自Mobile端和PC端的请求生成不同的Cache Key。

Mobile规则条件：

User-Agent包含*Mobile*,*Android*,*iPhone*,*ipad*其中任意一个

PC规则条件：

User-Agent不包含*Mobile*,*Android*,*iPhone*,*ipad*其中任意一个

Mobile自定义Cache Key：

规则条件选择Mobile，自定义变量的变量名为Mobile，来源为Path，匹配规则为/，变量表达式为+mobile。

PC自定义Cache Key：

规则条件选择PC，自定义变量的变量名为PC，来源为Path，匹配规则为/，变量表达式为+pc。

客户端的请求URLhttp://aliyundoc.com/image.jpg，根据User-Agent的值，请求分别命中Mobile端和PC端的自定义Cache Key规则。Mobile端最终生成的Cache Key为：http://aliyundoc.com/image.jpg+mobile；PC端最终生成的Cache Key为：http://aliyundoc.com/image.jpg+pc。

常见问题

配置自定义 Cache Key 区分不同 Token 请求后仍命中缓存且未回源怎么办？

配置自定义 Cache Key 区分不同 Token 的请求后，仍出现命中缓存且请求未回源的情况，请按以下步骤排查：

  1. 检查配置：确认已将携带 Token 的 HTTP Header 加入自定义 Cache Key，或者将缓存时间设置为 0 秒。

  2. 刷新缓存：配置修改后，需提交目录刷新以清除旧缓存。URL 刷新不支持通配符 *，建议使用目录刷新。

  3. 客户端验证：清除浏览器缓存或重启浏览器后重试，检查响应头中的缓存标识是否为 MISS，确认未命中 CDN 缓存。

  4. 后端排查：若响应头显示 MISS 但后端仍无日志，需检查后端负载均衡配置及网关日志，确认请求是否到达源站。

  5. 权限核查：若无法查询详细日志，需确认当前账号是否有该 CDN 域名的管理权限，或通过主账号申请 AliyunSupportFullAccess 权限，提供 EagleID 由拥有域名的账号协助排查。

配置自定义 Cache Key 区分移动端和 PC 端缓存后测试未生效怎么办？

配置自定义 Cache Key 区分 Mobile 和 PC 端缓存后测试未生效，请按以下步骤排查：

  1. 检查配置冲突：确认未开启忽略参数功能。忽略参数会与自定义 Cache Key 冲突，导致配置不生效。

  2. 检查配置完整性：确保 Mobile 和 PC 分别配置了自定义变量。Mobile 规则的变量表达式应设为 +mobile，PC 规则的变量表达式应设为 +pc。配置示例见本文「示例四」。

  3. 等待生效：配置提交后需等待 5～10 分钟全网同步。

  4. 进一步排查：如以上步骤确认无误仍未生效，建议提供测试返回的 EagleID 以便查询 CDN 日志进一步排查。

未开启 ESA 时是否可以使用自定义 Cache Key？

可以。自定义 Cache Key 是 CDN 的基础缓存配置功能，无需开启 ESA 即可使用。

配置路径：登录 CDN 控制台 > 域名管理 > 单击目标域名的管理 > 左侧导航栏选择缓存配置 > 在自定义 Cache Key 页签下单击配置。

重要

若已开启忽略参数功能，需先关闭，否则会导致自定义 Cache Key 中的请求参数配置失效。

CDN 自定义 Cache Key 能否实现动态接口的缓存效果？

不能。CDN 主要用于静态资源加速，无法实现动态接口的加速效果。自定义 Cache Key 用于优化静态资源的缓存策略（如统一 URL 参数、区分客户端等），不适用于动态接口缓存场景。如需动态内容加速，可使用。

上一篇：重写访问URL下一篇：配置共享缓存