配置缓存行为

媒体 CDN 使用 Google 的全球边缘缓存基础架构缓存内容，并减少源站基础架构的负载，从而尽可能将内容提交到靠近用户的位置。

您可以控制为每个路由缓存内容的方式。这样，您就可以根据内容类型、客户端请求属性和新鲜度要求优化行为。

可缓存性

以下部分介绍了 Media CDN 缓存的响应以及如何改进缓存分流。

默认缓存行为

默认情况下，以下与缓存相关的设置适用于每个边缘缓存服务：

• CACHE_ALL_STATIC 的默认缓存模式：

  • 遵循来源缓存指令（例如 Cache-Control 或 Expires），但不超过可配置的最大 TTL。
  • 如果没有源站缓存指令，则自动缓存静态媒体类型，默认 TTL 为 3600 秒。
  • 缓存 HTTP 200 和 206 状态代码（未启用否定缓存）。

• 不会缓存包含 no-store 或 private 缓存控制指令的响应，也不会缓存其他不可缓存的响应。

除非明确配置缓存，否则系统不会缓存非静态内容或缺少有效缓存指令的响应。如需了解如何替换默认行为，请参阅有关缓存模式的文档。

默认行为等同于以下 cdnPolicy。如果未配置显式 cdnPolicy，路由的行为就像具有以下配置一样：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    includeProtocol: false
    excludeHost: false
    excludeQueryString: false
  signedRequestMode: DISABLED
  negativeCaching: false

可缓存的响应

可缓存响应是一种可供 Media CDN 存储并快速检索，因而有助于缩短加载时间的 HTTP 响应。并非所有 HTTP 响应都可以缓存。

您可以为每个路由配置缓存模式以替换此行为（例如，使用 CACHE_ALL_STATIC 缓存模式缓存常见的媒体类型），即使源站未在响应中设置缓存控制指令也是如此。

符合不可缓存的响应中定义的条件的请求和响应会取代可缓存性。

下表介绍了缓存特定 HTTP 响应的要求。GET 和 HEAD 响应都必须遵循这些要求。

HTTP Age 标头的设置基于 Media CDN 首次缓存响应的时间，通常表示对象在源站屏蔽位置缓存后的秒数。如果您的源站生成 Age 响应标头，请使用 FORCE_CACHE_ALL 缓存模式，以防止在 Age 超出缓存 TTL 时重新验证。

如需详细了解 Media CDN 如何解读 HTTP 缓存指令，请参阅缓存控制指令。

来源要求

如需允许媒体 CDN 缓存大于 1 MiB 的源站响应，源站必须在 HEAD 和 GET 请求的响应标头中包含以下内容，除非另有说明：

• Last-Modified 或 ETag HTTP 响应标头（验证器）。
• 有效的 HTTP Date 标头。
• 有效的 Content-Length 标头。
• Content-Range 响应标头，用于响应 Range GET 请求。Content-Range 标头必须具有采用 bytes x-y/z 格式的有效值（其中 z 是对象大小）。

默认的来源协议为 HTTP/2。如果您的来源仅支持 HTTP/1.1，您可以为每个来源明确设置协议字段。

不可缓存的响应

下表详细介绍了会阻止缓存响应的请求和响应属性。可缓存但与“不可缓存”条件匹配的响应不会被缓存。

除了配置的缓存模式外，这些规则也会应用。具体而言：

• 配置 CACHE_ALL_STATIC 缓存模式后，系统只会缓存被视为静态内容的响应，或响应标头中包含有效缓存指令的响应。其他响应会按原样代理。
• FORCE_CACHE_ALL 缓存模式会无条件缓存所有响应，但须遵守前面所述的不可缓存性要求。
• USE_ORIGIN_HEADERS 缓存模式要求响应不仅具有可缓存的状态代码，还必须在响应标头中设置有效的缓存指令。

注意：

• 系统不会更改未缓存的响应的缓存控制指令或其他标头，而是将其原封不动地代理。
• 响应的 Cache-Control 和 Expires 标头可以合并到单个 Cache-Control 字段中。例如，如果响应中 Cache-Control: public 和 Cache-Control: max-age=100 分别位于不同行，则会合并为 Cache-Control: public,max-age=100。
• 从结算角度来看，不可缓存的响应（永远不会缓存的响应）不会计为 Cache Egress。

使用缓存模式

借助缓存模式，您可以配置 Media CDN 应在何时遵循源站缓存指令、缓存静态媒体类型，以及缓存来自源站的所有响应（无论设置了哪些指令）。

缓存模式在路由级配置，结合使用 TTL 替换项后，您可以按主机、路径、查询参数和标头（任何可匹配的请求参数）配置缓存行为。

• 默认情况下，Media CDN 使用 CACHE_ALL_STATIC 缓存模式，该模式会自动将常见的静态媒体类型缓存 1 小时（3600 秒），同时优先考虑源站为可缓存响应指定的任何缓存指令。
• 您可以通过在路由上设置 cdnPolicy.defaultTtl 字段，来增加或减少应用于未设置显式缓存 TTL（max-age 或 s-maxage 指令）的响应的缓存 TTL。
• 为防止将非成功响应缓存的时间超出预期，系统不会根据其 Content-Type（MIME 类型）缓存非 2xx（非成功）状态代码，也不会应用默认的 TTL。

下表显示了可用的缓存模式（在每个路线的 cdnPolicy.cacheMode 上设置）。

静态内容 MIME 类型

借助 CACHE_ALL_STATIC 缓存模式，Media CDN 可以根据 Content-Type HTTP 响应标头中返回的 MIME 类型，自动缓存视频、音频、图片和常见 Web 资源等常见静态内容。不过，无论媒体类型如何，Media CDN 都会优先处理来源响应中的任何显式 Cache-Control 或 Expires 标头。

下表列出了可使用 CACHE_ALL_STATIC 缓存模式自动缓存的 MIME 类型。

如果响应没有 Content-Type 响应标头，且该标头的值与以下值不匹配，则系统不会自动缓存响应。您必须确保响应设置了有效的缓存指令，或者您必须使用 FORCE_CACHE_ALL 缓存模式以无条件缓存响应。

请注意以下几点：

• 您的源站 Web 服务器软件必须为每个响应设置 Content-Type。许多 Web 服务器会自动设置 Content-Type 标头，包括 NGINX、Varnish 和 Apache。
• 使用 Google Cloud 控制台或 gcloud CLI 上传内容时，Cloud Storage 会在上传时自动设置 Content-Type 标头。
• Cloud Storage 始终向 Media CDN 提供 Cache-Control 标头。如果未明确选择值，它会发送默认值。因此，除非您在 Cloud Storage 中明确调整了对象的缓存控制元数据，或者使用 FORCE_CACHE_ALL 模式替换 Cloud Storage 发送的值，否则所有成功的 Cloud Storage 响应都会根据 Cloud Storage 默认值进行缓存。

如果响应可根据其 MIME 类型缓存，但 Cache-Control 响应指令为 private 或 no-store，或标头为 Set-Cookie，则不会缓存该响应。

默认情况下，HTML (text/html) 和 JSON (application/json) 等其他媒体类型不会被缓存。这些类型的响应通常是动态的（每个用户），也不适合 Media CDN 的架构。我们建议使用 Cloud CDN 来传送 Web 资源和缓存 API 响应。

配置缓存 TTL

借助存活时间 (TTL) 替换项，您可以为缓存内容设置默认 TTL 值，并替换由来源设置的 max-age 和 s-maxage 缓存控制指令（或 Expires 标头）中设置的 TTL 值。

TTL（无论是通过替换项还是通过缓存指令设置的）都是乐观的。不常访问或不受欢迎的内容可能会在达到 TTL 之前从缓存中逐出。

下表显示了三种 TTL 设置。

如果将任何 TTL 值设置为零 (0 秒)，系统会在提供响应之前对每个请求与源站进行重新验证，如果设置过宽，则会增加源站的负载。

将缓存模式设置为 Use Origin Headers 时，无法配置 TTL 设置，因为媒体 CDN 依赖于源站来确定行为。

注意：

• TTL 上限的值始终必须大于（或等于）默认 TTL 的值。
• 客户端 TTL 的值始终必须小于（或等于）最大 TTL 的值。
• 当 Media CDN 替换源站 TTL 值时，发送给客户端的 Cache-Control 标头也会反映该值。
• 如果源设置了 Expires 标头，而 Media CDN 替换了有效 TTL（基于时间戳），则在向客户端的下游响应中，Expires 标头会替换为 Cache-Control 标头。

负缓存

否定缓存用于定义 Media CDN 如何缓存非成功 HTTP 状态代码（即除 2xx 以外的代码）。

这样，您就可以将重定向 (HTTP 301 和 308) 和未找到 (HTTP 404) 等错误响应缓存在离用户更近的位置，并在响应不太可能发生变化且可以缓存的情况下更广泛地减少源端负载。

默认情况下，负缓存处于停用状态。下表显示了启用否定缓存且未使用 negativeCachingPolicy 时，每种状态代码的默认值。

默认的一组负缓存代码与 HTTP RFC 9110 中所述的启发法可缓存状态代码相匹配，但存在以下例外情况：

• 为避免缓存中毒，不支持缓存 HTTP 代码 414（URI 过长）。
• 如 HTTP RFC 7725 中所述，HTTP 代码 451（因法律原因无法访问）支持缓存。

如果您需要配置自己的各状态代码 TTL 并替换默认行为，可以配置 cdnPolicy.negativeCachingPolicy。这样，您就可以为 Media CDN 允许的任何状态代码设置 TTL：300、301、302、307、308、400、403、404、405、410、451、500、501、502、503 和 504。

例如，如需为 HTTP 404（未找到）响应设置短 TTL（5 秒），并为 HTTP 405（不允许使用的方法）响应设置 10 秒 TTL，请对每个适用的路由使用以下 YAML 定义：

cdnPolicy:
  negativeCaching: true
  negativeCachingPolicy:
    "404": 5s
    "405": 10s
  # other status codes to apply TTLs for

为防止缓存中毒，我们不建议为状态代码 400（请求错误）或 403（禁止）启用缓存。确保您的源服务器仅检查缓存键中包含的请求组件，以便返回任一代码。例如，如果源服务器在缺少正确的 Authorization 标头的情况下返回 403 错误响应，就可能会发生缓存中毒。在这种情况下，缓存 403 错误响应会导致 Media CDN 向所有后续请求提供 403 错误响应，直到 TTL 到期为止，即使请求包含正确的 Authorization 标头也是如此。

如需停用负缓存，请执行以下操作：

• 如需停用默认的负缓存行为，请对路线设置 cdnPolicy.negativeCaching: false。请注意，具有有效缓存指令和可缓存状态代码的源站响应仍会被缓存。
• 如需阻止针对特定状态代码使用负缓存，但仍遵循来源缓存指令，请在 negativeCachingPolicy 定义中省略状态代码 (cdnPolicy.negativeCachingPolicy[].code)。
• 如需明确忽略特定状态代码的来源缓存指令，请将该状态代码的 cdnPolicy.negativeCachingPolicy[].ttl 设置为 0（零）。

注意：

• 在某个路线上启用 negativeCaching 后，如果响应定义了有效的缓存指令，则响应中的缓存指令优先。
• 如果您配置了显式 negativeCachingPolicy，并且为给定状态代码定义了 TTL，则始终使用政策中定义的 TTL。
• 由 negativeCachingPolicy 设置的 TTL 的最大值为 1800 秒 (30 分钟)，但系统会遵循 TTL 更高的源站缓存指令。
• 如果缓存模式配置为 FORCE_CACHE_ALL，则在任何情况下都会忽略来源指令。

缓存控制指令

此处定义了媒体 CDN 针对 Cache-Control 指令的行为。

如果指令不适用于请求或响应（例如 only-if-cached，这是一个仅限客户端的指令），则该列中会标记“不适用”。

媒体 CDN 尽可能符合 RFC 规范 (HTTP RFC 7234)，但更倾向于优化缓存分流，并最大限度地降低客户端对命中率和总体来源负载的影响。

对于使用 HTTP/1.1 Expires 标头的响应：

• Expires 标头的值必须是 RFC 7231 中定义的有效 HTTP 日期
• 过去的日期值、无效日期或值 0 表示内容已过期，需要重新验证。
• 如果响应中存在 Cache-Control 标头，Media CDN 会忽略 Expires 标头。

如果响应中存在 HTTP/1.0 Pragma 标头，则 Cloud CDN 会忽略该标头，并按原样将其传递给客户端。

缓存键

您可以考虑请求的唯一标识符，并移除请求之间可能经常更改的组件，从而减少 Media CDN 需要与您的源站联系的次数。这组请求组件通常称为“缓存键”。

以下部分介绍了如何配置缓存键。

缓存键组成部分

缓存键是缓存对象引用的一组请求参数（例如主机、路径和查询参数）。

默认情况下，边缘缓存服务的缓存键包含请求主机、路径和请求中的查询参数，并且其作用域限定为特定的 EdgeCacheService。

请注意以下几点：

• 缓存键不会附加到已配置的来源，因此您可以更新来源配置（或完全替换来源），而无需担心“刷新”缓存（例如，在提供商之间迁移来源存储空间时）。
• 缓存键仅限于 EdgeCacheService。不同的 EdgeCacheService 具有不同的缓存命名空间，这可防止您在生产环境、预演环境和其他测试环境之间意外缓存对象，即使主机、路径或其他缓存键组件匹配也是如此。删除 EdgeCacheService 会有效地使该服务的所有缓存对象失效。
• 缓存键的范围不局限于单个路由。多个路由可能引用相同的缓存键，尤其是当这些路由在缓存键中不包含的组件（例如请求标头或排除的参数）上匹配时。如果您希望多个路由共享相同的缓存，但返回不同的响应标头或 CORS 配置，这会非常有用。
• 缓存键不包含网址重写配置；例如，缓存键基于面向用户的请求，而不是最终的“重写”请求。
• 在路由上配置已签名请求时，缓存键中不会包含已签名属性。系统会将请求视为以 edge-cache-token 开头且以下一个路径分隔符（“/”）结尾的（已签名）查询参数或路径组成部分不属于网址的一部分。

包含或排除查询参数

您可以通过将参数名称添加到给定路线上的 includedQueryParameters 或 excludedQueryParameters 缓存键配置中，从缓存键中包含或排除特定查询参数。

例如，如需在缓存键中添加 contentID 和 country 查询参数并忽略所有其他参数，请执行以下操作：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    includedQueryParameters: ["contentID", "country"]

请务必添加用于唯一标识内容的查询参数，并排除不用于唯一标识内容的查询参数。例如，排除 Google Analytics 查询参数、播放会话 ID 或仅对客户端而言是唯一的其他参数。添加的查询参数过多可能会降低缓存命中率。

或者，您也可以选择要从缓存键中排除哪些参数，而不是指定要将哪些参数包含在缓存键中。例如，如需从缓存键中排除特定于客户端的播放 ID 和时间戳信息，请配置以下内容：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    excludedQueryParameters: ["playback-id", "timestamp"]

对于给定路线，您可以指定 includedQueryParameters 或 excludedQueryParameters 中的一个。

如果查询参数从未用于唯一标识请求中的不同内容，您可以从路由的缓存键中移除所有查询参数。为此，请将 excludeQueryString 设置为 true，如下所示：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    excludeQueryString: true

如果在某个路线上启用了已签名请求，则用于签名的查询参数不会包含在查询字符串中，如果包含，则会被忽略。在缓存键中添加已签名参数可有效地使每个用户请求都具有唯一性，并且要求每个请求都从源服务器提供。

查询参数排序

默认情况下，系统会对查询参数（查询字符串）进行排序，以提高缓存命中率，因为客户端可能会对同一缓存对象重新排序或以其他方式请求，而查询参数的顺序会有所不同。

例如，在派生缓存键之前，查询参数 b=world&a=hello&z=zulu&p=paris 和 p=paris&a=hello&z=zulu&b=world 会按 a=hello&b=world&p=paris&z=zulu 进行排序。这样，这两个请求就可以映射到同一缓存对象，从而避免对源的多余请求（以及源的多余响应）。

如果某个查询参数键有多个实例，且每个实例的值各不相同，则系统会按参数的完整值对其进行排序（例如，a=hello 在 a=world 之前排序）。无法停用排序。

添加标头

标头名称不区分大小写，并会由 Media CDN 转换为小写形式。

缓存键中不得包含以下标头：

• 以 access-control- 开头的任何标头
• 以 sec-fetch- 开头的任何标头
• 以 x-amz- 开头的任何标头
• 以 x-goog- 开头的任何标头
• 以 x-media-cdn- 开头的任何标头
• accept-encoding
• accept
• authorization
• cdn-loop
• connection
• content-md5
• content-type
• cookie
• date
• forwarded
• from
• host
• if-match
• if-modified-since
• if-none-match
• origin
• proxy-authorization
• range
• referer
• referrer
• user-agent
• want-digest
• x-csrf-token
• x-csrftoken
• x-forwarded-for

如需在缓存键中添加 HTTP 方法，请使用特殊的标头名称 :method。

包含 Cookie

Cookie 名称区分大小写。

缓存键中不能使用以大写或小写字母 edge-cache- 开头的 Cookie。

重新验证、逐出和到期

内容分发网络（包括媒体 CDN）的运作方式是将最热门的内容缓存在尽可能靠近用户的位置。

媒体 CDN 的大量存储空间以及源站防护功能可减少甚至无需驱逐不受欢迎的内容。每天被访问次数较少的内容最终可能会被逐出。

• 已达到配置的 TTL 的缓存响应可能不会立即被驱逐。对于热门内容，Media CDN 会向源服务器发出 HEAD 请求，以确认标头未发生更改，从而重新验证缓存的响应是否为最新版本。在某些情况下，Media CDN 会改为向源发送包含以下任一或全部请求标头的请求：If-None-Match 和 If-Modified-Since。在这种情况下，如果缓存中包含该响应的“最新”副本，则正确配置的来源应返回 HTTP 304（未修改）响应，而不包含正文字节。
• 设置 max-age 或 s-maxage 缓存指令或使用TTL 替换项指定较高 TTL 值（例如 30 天）的响应可能不会在缓存中存储完整 TTL 的时间。我们无法保证对象会在整个时段内存储在缓存中，尤其是在对象被访问频率较低的情况下。

如果您发现驱逐率很高，则应确保已配置缓存键以排除无法唯一标识响应的参数。

其他注意事项

以下注意事项可能也适用于缓存。

Vary 标头

Vary 标头表示响应会因客户端的请求标头而异。如果响应中存在 Vary 标头，Media CDN 不会将其缓存，除非该标头指定了配置为缓存键设置的标头之一或以下某个值：

• Accept：用于指明客户端接受哪些媒体类型
• Accept-Encoding：用于指明客户端接受的压缩类型
• Available-Dictionary：用于提供可用字典的哈希以进行压缩
• Origin/X-Origin：通常用于跨域资源共享
• X-Goog-Allowed-Resources:：支持 Google Cloud 组织限制
• Sec-Fetch-Dest/Sec-Fetch-Mode/Sec-Fetch-Site:：用于提取元数据请求标头

Media CDN 会将包含 Vary 标头的响应缓存在响应中，方法是将该标头的值用作缓存键的一部分。如果响应中的 Vary 标头包含多个值，则会按字典顺序对这些值进行排序，以确保缓存键是确定性的。

媒体 CDN 最多会为给定缓存键缓存 100 个变体，并会随机从缓存中移除超出此限制的变体。当明确使给定网址或缓存标记的缓存失效时，所有变体都会失效。

绕过缓存

您可以在路线上配置 BYPASS_CACHE 缓存模式，以便在匹配请求时有意绕过缓存。如果您需要绕过缓存来处理一小部分非关键流量，或者调试源连接，这会非常有用。

如果您需要提供动态响应（例如 API 后端），我们建议您配置外部应用负载平衡器。

通常，建议您仅在调试场景中使用此功能，以避免意外增加源加载。绕过缓存时出站的流量按照互联网出站流量费率计费。

缓存失效操作

请参阅缓存失效。

字节范围请求

Media CDN 支持 RFC 7233 中定义的单部分 HTTP 范围请求。

此外，Media CDN 还使用范围请求从源站提取较大的响应。这样，Media CDN 就可以单独缓存分块，而无需一次提取整个对象进行缓存。

• 大于 1 MiB 的对象会以字节范围请求（“分块”）的形式提取，每个分块最多 2 MiB。
• 可以提取大小不超过 1 MiB 的响应，而无需支持源端的字节范围。
• 如果源站不支持字节范围，则不会传送大于此值的响应。

源对字节范围请求的支持取决于以下因素：

• HTTP 状态代码为 200（OK）或 206（部分内容）。
• 有效的 Content-Length 或 Content-Range 响应标头。
• 响应验证器 (ETag 或 Last-Modified)。

每个“分块”（字节范围）的各个源填充请求都会作为单独的日志条目记录下来，并与其父级客户端请求相关联。您可以按 jsonPayload.cacheKeyFingerprint 上的匹配请求对这些请求进行分组。

如需详细了解记录的内容，请参阅 Cloud Logging 文档。

开放式范围请求

媒体 CDN 支持“无限期”Range 请求（例如包含 Range: bytes=0- 的请求），这些请求会将对源的请求保持打开状态，直到响应被源关闭（例如，源将所有字节写入线）或超时。

请求 Apple 低延迟 HLS 片段的客户端通常使用开头为 0 的字节范围：随着每个 CMAF 分块写入线路上，CDN 可以将该分块缓存并传送给客户端。

在其他情况下（例如，不需要与 DASH 实现互操作性时），媒体播放列表会向播放器指明哪些字节代表每个分块：

  #EXTINF:4.08,
  fs270.mp4
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=20000@0
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=23000@20000
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=18000@43000
  #EXT-X-PRELOAD-HINT:TYPE=PART,URI="fs271.mp4",BYTERANGE-START=61000

您可以使用 EdgeCacheOrigin.timeouts.readTimeout 配置值配置 Media CDN 在两次读取之间等待的时间。通常，此值应配置为目标时长的倍数（例如 2 倍）。

后续步骤

• 查看高级路由。
• 了解如何连接到不同的来源。
• 为您的服务设置 TLS (SSL) 证书。
• 配置已签名请求，以对内容访问权限进行身份验证。