缓存键值--内容分发网络-火山引擎

文档中心

内容分发网络

缓存配置

缓存键值

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

缓存键概述

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

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

缓存键配置

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

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

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

说明

默认情况下，缓存键包含所有查询参数，但不包含任何 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）。由于此类参数的值会随请求动态变化，如果被包含在缓存键中，相同文件的不同请求会生成不同的缓存键，导致缓存内容相同但缓存键不同（缓存冗余），拉低缓存命中率。建议在缓存键中忽略此类参数。

操作步骤

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

预设缓存键值规则

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

配置说明

配置	说明
规则类型	表示规则中的过滤条件。该配置有以下选项：文件后缀：表示路径末尾的扩展名。文件目录：表示路径中的目录。文件全路径：表示请求 URL 中的路径。全路径正则表达式：表示请求 URL 中的路径，通过正则表达式匹配。要指定该选项，请提交工单。
忽略大小写匹配	表示 CDN 在查询缓存以及匹配请求时，规则内容是否是大小写敏感的。
规则内容	表示规则中的过滤值。多个过滤值之间使用分号（;）分隔，总长度不能超过 1,024 个字符，不能包含以下字符：双斜杠（//）、空格、美元符号（$）、问号（?） CDN 在尝试将规则中的过滤条件与用户请求匹配时，匹配过程是大小写不敏感的。另外，如果规则类型是文件后缀，过滤值是一个或者多个文件后缀。文件后缀无需以句点（.）开头。例如：`png;txt`。如果规则类型是文件目录，过滤值是一个或者多个目录路径。目录路径必须以斜杠（/）开头和结尾。例如：`/chs/foods/;/us/birds/`。如果规则类型是文件全路径，过滤值是一个或者多个文件路径。文件路径必须以斜杠（/）开头，可以包含星号（）用来表示一个或者多个字符。例如：`/chs/foods/localsets;/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 按规则的优先级，从高到低尝试将请求与规则匹配。如果请求匹配了一条规则，匹配过程就停止了。您可以拖动规则来调整优先级。需要留意的是，您无法调整那条预设规则的优先级。

内容分发网络

缓存键概述 #

缓存键配置 #

使用场景 #

操作步骤 #

预设缓存键值规则 #

配置说明 #

规则优先级 #

更多信息 #

配置示例 #

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