本文档介绍如何在火山引擎内容分发网络（CDN）中通过创建缓存键规则来配置缓存键。

缓存键概述

缓存键是缓存中每个文件的唯一标识。通常情况下，缓存键包含用户请求 URL 中的 hostname、路径和查询参数。您可以对缓存键中包含的查询参数进行配置。

当收到用户请求时，CDN 会为所请求的文件生成一个缓存键，然后尝试将该缓存键与每个缓存文件的缓存键进行匹配。缓存键的匹配需要完整匹配请求 URL 中的 hostname、路径和查询参数。查询参数的匹配包括参数出现的顺序。如果 CDN 找到一个匹配，则表示该请求命中了缓存。需要留意的是，缓存键的匹配过程区分大小写。

缓存键配置

CDN 提供了缓存键配置的功能。您可以在控制台中创建缓存键规则。缓存键规则影响缓存命中率，因为 CDN 基于缓存键来匹配用户请求和已缓存的文件。

配置缓存键有以下两种方式：

• 常规方式：在域名配置页面，您可以创建缓存键规则，指定缓存键包含的查询参数。本文主要介绍这种方式。
• 规则引擎：您也可以在规则引擎中配置缓存键。规则引擎提供了更丰富的配置项。除了查询参数，您还可以：
  • 设置缓存键中包含的请求头。
  • 设置缓存键中包含的 Cookie。
  • 改写缓存键中文件的路径。
  • 指定缓存键中的文件路径是否区分大小写。
    更多信息，参见 规则引擎。

:::tip

• 默认情况下，缓存键包含所有查询参数，但不包含任何 Cookie 和请求头。
• 关于响应头 Vary 对缓存的影响：当源站响应中包含 Vary 头部时，CDN 会把 Vary 声明的请求头字段动态纳入缓存命中判断的维度，即在匹配缓存时除了比对 URL 和已配置的缓存键字段，还会额外比对这些请求头的取值。对于同一个 URL，请求头取值不同的请求会被视为不同副本，分别缓存和命中。例如源站返回 Vary: Accept-Encoding 时，Accept-Encoding: gzip 和 Accept-Encoding: br 会被分别缓存为两份副本。
• CDN 响应中包含 Vary 响应头的常见场景：
  • 当源站响应中包含 Content-Encoding（即源站已对内容进行压缩）时，CDN 会默认在响应中返回 Vary: Accept-Encoding；如果源站响应已包含该 Vary 头，CDN 沿用源站返回的值，不重复添加。
  • 当 CDN 侧开启了智能压缩（如 gzip 或 br）、源站未返回压缩响应头，且请求的资源匹配到可压缩的 Content-Type 时，CDN 会在返回的响应中附加 Vary: Accept-Encoding，以便下游缓存和浏览器能够按 Accept-Encoding 区分压缩与未压缩的版本。
  • 在跨域（CORS）加速场景中，如果您希望浏览器端按 Origin 区分缓存，我们建议您在 CDN 侧通过 HTTP 响应头设置配置 Vary: Origin，而不是在源站配置。详见 CDN 跨域（CORS）配置的最佳实践。
    :::
    在本文最后，我们提供了一个 配置示例 帮助您更好理解缓存键设置对于缓存命中的影响。
    

使用场景

如果您站点上文件 URL 中的查询参数并不是用来区分文件的，您可以通过创建缓存键规则来指定 CDN 在生成的缓存键中需要丢弃的查询参数，以提高缓存命中率，减少回源请求。常见场景包括：

• 鉴权类参数：URL 中包含 auth、sign、token 等参数，用于验证用户身份，不用于区分文件。
• 用于指示源站改写响应的参数：URL 中包含一些用于指示源站动态生成响应的参数（例如指示 TOS 等对象存储改写响应头的 response-content-disposition=attachment;filename=xxx）。由于此类参数的值会随请求动态变化，如果被包含在缓存键中，相同文件的不同请求会生成不同的缓存键，导致缓存内容相同但缓存键不同（缓存冗余），拉低缓存命中率。建议在缓存键中忽略此类参数。

操作步骤

1. 登录 火山引擎内容分发网络控制台。
2. 在左侧导航栏，点击 域名管理。
3. 在 域名管理 页面，找到需要配置的域名，点击 管理。
   
4. 定位 缓存键值 模块。
   • 如果您使用的是旧版域名管理页面，点击 编辑配置，然后在 缓存配置 标签页中定位 缓存键值 模块。
   • 如果您使用的是新版域名管理页面，点击 编辑域名。在页面左侧的树状配置项列表中，定位 功能配置 > 缓存配置 > 缓存键值。
     
     关于新旧版域名管理页面的区别，参见 新版域名配置。
5. 在 缓存键值 模块中，点击 新增规则。您最多可以添加 50 条规则。
6. 根据 配置说明 进行设置。
7. 配置完成后，点击 提交编辑。


预设缓存键值规则

在您添加域名时，CDN 会默认为您添加一条缓存键值规则。该规则对所有文件的请求生效。您可以修改该规则的配置，但是无法删除该规则。在您添加其他缓存键值规则时，这条规则的优先级始终是最低的，其确保了任何请求都可以匹配到一条规则。

配置说明

| | | \

配置	说明
规则类型	表示规则中的过滤条件。该配置有以下选项：
	* 文件后缀：表示路径末尾的扩展名。
	* 文件目录：表示路径中的目录。
	* 文件全路径：表示请求 URL 中的路径。
	* 全路径正则表达式：表示请求 URL 中的路径，通过正则表达式匹配。 要指定该选项，请 提交工单。
忽略大小写匹配	表示 CDN 在查询缓存以及匹配请求时，规则内容 是否是大小写敏感的。
	当 规则类型 为 全路径正则表达式 时，该选项置灰。对于全路径正则表达式，匹配过程的大小写敏感性，以您填写的正则表达式为准。
规则内容	表示规则中的过滤值。多个过滤值之间使用分号（;）分隔，总长度不能超过 1,024 个字符，不能包含以下字符：
	* 双斜杠（//）、空格、美元符号（$）、问号（?）
	另外，
	* 如果 规则类型 是 文件后缀，过滤值是一个或者多个文件后缀。文件后缀无需以句点（.）开头。例如：png;txt。
	* 如果 规则类型 是 文件目录，过滤值是一个或者多个目录路径。目录路径必须以斜杠（/）开头和结尾。例如：/chs/foods/;/us/birds/。
	* 如果 规则类型 是 文件全路径，过滤值是一个或者多个文件路径。文件路径必须以斜杠（/）开头，可以包含星号（*）用来表示一个或者多个字符。例如：/chs/foods/local*sets;/us/birds/chickadee。
	* 如果 规则类型 是 全路径正则表达式，过滤值是一个或者多个正则表达式，用于匹配请求路径中的任意字符串。例如：^/a{1,2}.*g$。
参数设置	表示 CDN 在生成的缓存键中包含哪些请求 URL 中的查询参数。该配置的取值如下：
	* 保留全部参数：表示缓存键中包含请求 URL 中全部的查询参数。缓存键中查询参数的顺序与请求 URL 中的顺序相同。
	* 删除全部参数：表示缓存键中不包含请求 URL 中任何的查询参数。
	* 删除指定参数：表示缓存键中包含请求 URL 中全部的查询参数，除了 参数名称 中指定的查询参数。CDN 对包含在缓存键中的查询参数按字母顺序排序后生成缓存键。
	* 保留指定参数：表示如果用户请求 URL 中存在 参数名称 中指定的查询参数，那么缓存键中包含这些指定的查询参数。CDN 对包含在缓存键中的查询参数按字母顺序排序后生成缓存键。
参数忽略大小写	表示 CDN 在查询缓存以及匹配请求时，参数名称 是否是大小写敏感的。该配置仅当 参数设置 是 删除指定参数 或者 保留指定参数 时有效。
	例子：您指定保留的参数是 size，参数忽略大小写 为开启。然后，CDN 收到了一个 URL 包含 SIZE 参数的请求。在这个情况下，CDN 会在请求文件的缓存键中保留 SIZE 参数。
参数名称	表示需要保留或者丢弃的查询参数。参数名称可以包含字母、数字、中划线（-）、下划线（_)、句号（.）、逗号（,）、感叹号（!）。多个查询参数用英文分号（;）分隔。例如 version;size。
	* 如果 参数设置 是 保留全部参数 或者 删除全部参数，该配置的值必须是 *。* 表示全部查询参数。
	* 如果 参数设置 是 删除指定参数 或者 保留指定参数，您可以指定一个或者多个查询参数，但是您不能指定 *。同时，您指定的查询参数不能包含双斜杠（//）、百分号（%）、空格。
	该配置的默认值是 *。

规则优先级

在规则列表中，每条规则都有优先级。优先级为 1 的规则具有最高优先级。当收到一个用户请求时，CDN 按规则的优先级，从高到低尝试将请求与规则匹配。如果请求匹配了一条规则，匹配过程就停止了。您可以拖动规则来调整优先级。需要留意的是，您无法调整那条预设规则的优先级。

更多信息

配置示例

• 您站点根目录下的文件 URL 中包含 version，token 这两个参数。
• 这两个参数中，只有 version 是用来区分文件的。例如 /image.png?version=1 与 /image.png?version=2 是两个不同的文件。但是 /image.png?version=1&token=abc 与 /iamge.png?version=1&token=xyz 是相同的文件。
• CDN 先后收到两个该文件的请求。请求 URL 分别是 https://<domain>/image.png?version=1&token=12345 和 https://<domain>/image.png?version=1&token=abcde。

未创建缓存键值规则的结果

在收到第一个请求时，CDN 缓存该文件。该文件在缓存中的缓存键是 /image.png?version=1&token=12345。在收到第二个请求时，CDN 会使用 /image.png?version=1&token=abcde 去匹配缓存中的文件。由于没有命中缓存，CDN 会向源站请求该文件。