配置缓存行为

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

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

可缓存性

以下部分介绍了 Media CDN 会缓存哪些响应，以及如何提高缓存分流。

默认缓存行为

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

• CACHE_ALL_STATIC 的默认缓存模式：

  • 遵循源站缓存指令（例如 Cache-Control 或 Expires），但不得超过可配置的最大 TTL。
  • 如果不存在源站缓存指令，则自动缓存 static media types，默认 TTL 为 3600 秒。
  • 缓存 HTTP 200、204 和 206 状态代码（未启用负缓存）。

• 不缓存具有 no-store 或 private cache-control 指令或以其他方式不可缓存的响应。

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

默认行为相当于以下 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 标头。
• 针对 Range GET 请求的 Content-Range 响应标头。 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。
• 为防止缓存非成功响应的时间超出预期，系统不会根据非 2xx（非成功）状态代码的 Content-Type（MIME 类型）来缓存这些状态代码，也不会应用默认 TTL。

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

静态内容 MIME 类型

借助 CACHE_ALL_STATIC 缓存模式，媒体 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 代码 451（因法律原因而无法提供）支持缓存，如 HTTP RFC 7725 中所述。

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

例如，如需为 HTTP 404（未找到）响应设置较短的 5 秒 TTL，并为 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，则无论在何种情况下，系统都会忽略源指令。

缓存控制指令

此处定义了 Media 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"]

请务必添加可唯一标识内容的查询参数，并排除无法唯一标识内容的查询参数。例如，排除仅对客户端唯一的分析查询参数、播放会话 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- 开头的任何标头
• accept-encoding
• accept
• authorization
• 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）通过将最热门的内容缓存到尽可能靠近用户的位置来运作。

Media CDN 的存储空间非常大，并且具有源站防护功能，因此即使是不受欢迎的内容，也无需将其逐出。每天访问次数较少的内容最终可能会被逐出。

• 达到配置的 TTL 的缓存响应可能不会立即被逐出。对于热门内容，媒体 CDN 会向源站发出 HEAD 请求，以确认标头未发生变化，从而重新验证缓存的响应是否为最新版本。
• 设置了 max-age 或 s-maxage 缓存指令或使用 TTL 替换来指定高 TTL 值（例如 30 天）的响应可能不会在缓存中存储整个 TTL。我们无法保证对象在整个时长内都存储在缓存中，尤其是在不常访问的情况下。

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

其他注意事项

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

Vary 标头

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

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

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

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

绕过缓存

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

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

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

缓存失效操作

请参阅缓存失效。

字节范围请求

媒体 CDN 支持 RFC 9110 中定义的 HTTP 范围请求。

此外，Media CDN 会使用范围请求从源站提取较大的响应。这样一来，Media CDN 就可以缓存各个字节范围，而无需一次性提取整个对象进行缓存。

• 大于 1 MiB 的对象会以字节范围请求的形式提取，每个请求最多 2 MiB。
• 在源站不支持字节范围的情况下，可以提取大小不超过 1 MiB 的响应。
• 如果源站不支持字节范围，则不会提供大于 1 MiB 的响应。

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

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

每个字节范围的各个源填充请求都会记录为离散的日志条目，并与各自的父客户端请求相关联。您可以通过匹配每个请求的 jsonPayload.cacheKeyFingerprint 值来对这些请求进行分组。

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

多部分范围请求

媒体 CDN 支持分段范围请求，使用户能够在单个 HTTP 请求中请求文件的多个不连续的段，例如 Range: bytes=0-499, 1000-1499。

为了最大限度地提高客户端性能和源站分流，媒体 CDN 可以从其缓存中提供所请求的各个字节范围，并将它们整合到单个响应中，该响应具有 HTTP 206 Partial Response 状态代码，并且 Content-Type 设置为 multipart/byteranges。

对于可缓存的响应，当客户端请求多部分范围时，媒体 CDN 会通过将请求转换为一组单部分范围请求来优化流程。每个请求的大小为 2 MB，以涵盖客户端请求的所有字节范围部分。然后，Media CDN 会使用这些响应在边缘生成单个多部分响应。这种方法可实现高效的缓存利用率，减少冗余的源提取，并支持大容量使用情形，例如应用商店下载和操作系统更新。

对于不可缓存的内容，媒体 CDN 会直接将请求转发到源站。

开放式范围请求

Media CDN 支持“开放式”Range 请求（例如，包含 Range: bytes=0- 的请求），此类请求会一直保持对源的开放状态，直到源关闭响应（例如，源将所有字节写入线路）或超时为止。

开放式字节范围通常由请求 Apple 的低延迟 HLS 片段的客户端使用：当每个 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) 证书。
• 配置已签名请求，以对内容访问进行身份验证。
• 如需详细了解如何使用 Terraform 配置 EdgeCacheService 资源，请参阅 Terraform 注册表文档。