刷新和预热资源

功能介绍

前提条件

• 权限要求：使用 RAM 用户调用刷新预热 API（如 cdn:RefreshObjectCaches、cdn:PushObjectCache）或操作控制台时，须授予 cdn:RefreshObjectCaches（刷新）和 cdn:PushObjectCache（预热）权限。建议遵循最小权限原则，仅授予业务所需的操作权限。详情请参见CDN自定义权限策略参考。

• URL 格式：提交的 URL 中若包含非 ASCII 字符（如中文、空格等），必须先进行 UTF-8 百分号编码（Percent-encoding），否则刷新或预热任务可能无法生效。

  示例：如 https://<加速域名>/文档/说明.pdf，须编码为 https://<加速域名>/%E6%96%87%E6%A1%A3/%E8%AF%B4%E6%98%8E.pdf。

刷新与预热注意事项

• 操作时机：缓存刷新和预热任务都会产生回源流量，建议在业务流量低峰期执行大批量的缓存刷新和缓存预热任务。

• 配置共享缓存：

  • 使用主域名或任意关联域名提交刷新任务，均可使所有关联域名的缓存失效。

  • 使用主域名提交预热任务，只会预热主域名的回源节点组。需要同时预热关联域名的回源节点组时，需要提交工单确认主域名和关联域名的回源节点组是否一致，若一致，预热主域名即可覆盖。

• 重写访问URL：如果域名配置了重写访问URL，节点将使用重写后的 URL 来生成缓存键，因此需要提交重写后的 URL 进行刷新预热操作。

• 刷新与缓存规则的关系：URL 刷新仅使 CDN 边缘节点上的具体资源缓存失效，不会删除或修改您在控制台中配置的目录类型缓存规则。

• 源站无关性：刷新操作针对 CDN 边缘节点缓存执行，不支持指定只刷新某个源站的缓存。CDN 屏蔽了多源站的差异，刷新会统一作用于所有节点上的匹配资源。

• 忽略参数场景的刷新：若域名配置了忽略参数缓存规则，URL 刷新时应确保提交的刷新 URL 与实际缓存键匹配，或使用目录刷新。灰度发布期间新旧版本共存时，可通过刷新带版本参数的 URL 获取最新内容。

• URL 鉴权场景的刷新和预热：

  • 提交的刷新 URL 或预热 URL 应与实际缓存键一致。对于已配置 URL 鉴权的域名，应提交不含鉴权参数的原始 URL（加速域名 + 文件路径）。

  • 若业务查询参数（query string）中包含/ ，提交前需将其编码为 %2F。

  控制台在提交刷新或预热请求前，仅对 URL 进行格式校验，并按用户输入提交，不会自动删除鉴权参数、重新编码业务查询参数或规范化 URL。不要直接提交包含鉴权参数的客户访问 URL，否则可能因与实际缓存键不一致，导致无法命中目标缓存。

  以下示例以配置了 F 方式 URL 鉴权的域名为例。示例中的 k 和 t 分别表示该域名配置的签名参数和时间戳参数名称。

  1. 客户访问 URL：

     https://image.example.com/cat.jpg?x-oss-process=image/resize,m_fill,w_390,h_520,limit_1/auto-orient,1/sharpen,100/quality,q_80&k=123456789abcdefg&t=123abc

  2. 去除鉴权参数后的 URL：删除 k 和 t，保留业务查询参数。

     https://image.example.com/cat.jpg?x-oss-process=image/resize,m_fill,w_390,h_520,limit_1/auto-orient,1/sharpen,100/quality,q_80

  3. 最终刷新/预热 URL：将业务查询参数 x-oss-process 值中的 / 编码为 %2F；路径 /cat.jpg 中的路径分隔符保持不变。

     https://image.example.com/cat.jpg?x-oss-process=image%2Fresize,m_fill,w_390,h_520,limit_1%2Fauto-orient,1%2Fsharpen,100%2Fquality,q_80

费用说明

刷新和预热功能本身不收取任何操作费用。

URL刷新会立即删除指定缓存；目录或正则刷新会使匹配缓存失效，后续用户请求可能触发回源。预热任务则会主动回源拉取资源。由此产生的回源流量和回源请求次数可能按源站产品的计费规则收费：

• 源站为阿里云 OSS 时，将按 OSS 的计费规则收取回源流量费用和回源请求次数费用。

• 源站为 ECS 或其他服务器时，将按其网络带宽或流量计费。

大规模刷新或预热操作（尤其短时间内集中执行）可能导致回源成本增加。

操作步骤

验证结果

手动查询

操作记录页签可查看资源刷新或预热的详细记录和进度。进度为100%表示任务执行完成。刷新或预热的数量过多会影响任务的完成进度，请耐心等待。

接口查询

调用查询刷新预热任务-按ID接口，查询刷新或预热任务是否完成。

命令行验证

执行命令curl -I <资源链接>，系统显示结果如下：

~ % curl -I http://oss.xxx.cn/1.png
HTTP/1.1 200 OK
Server: Tengine
Content-Type: image/png
Content-Length: 1605553
Connection: keep-alive
Date: Sun, 23 Feb 2025 15:33:38 GMT
x-oss-request-id: 67BB3Fxxx32B63123
x-oss-cdn-auth: success
Accept-Ranges: bytes
ETag: "469118F2ACF477CACAF4C9xxx"
Last-Modified: Wed, 12 Feb 2025 03:29:36 GMT
x-oss-object-type: Normal
x-oss-hash-crc64ecma: xxx005350070
x-oss-storage-class: Standard
Content-MD5: RpEY8qz0d8rxxx
x-oss-server-time: 103
Via: cache6.12cn2655[196,195,200-0,M], cache15.12cn2655[197,0], kunlun3.cn192[0,0,200-0,H], kunlun7.cn192[3,0]
Age: 69
Ali-Swift-Global-Savetime: 1740324818
X-Cache: HIT TCP_MEM_HIT dirn:-2:-2
X-Swift-SaveTime: Sun, 23 Feb 2025 15:33:38 GMT
X-Swift-CacheTime: 3600
Timing-Allow-Origin: *
EagleId: 3adad01b1740324887846539le

响应头中的X-Cache反映当前请求是否命中缓存：

• X-Cache为HIT，表示当前请求命中了缓存，但不能单独证明该缓存由本次预热任务生成。还需在控制台核对对应预热任务的状态和URL。

• X-Cache为MISS，表示当前请求未命中缓存。首次访问的L1节点尚未缓存、缓存已过期或缓存键不一致均可能导致MISS，不能据此直接判定预热失败。

如果响应中不存在X-Cache：

先通过DNS解析结果、响应链路和CDN控制台配置确认请求是否经过阿里云CDN。部分响应不包含该字段，不能仅凭字段缺失判定资源未接入CDN。域名尚未接入时，请参见快速接入阿里云CDN完成接入后再预热。

使用限制

刷新和预热功能存在配额限制，超出限制后任务将被拒绝。如需提升配额，可前往配额管理申请：

大量文件预热的使用限制

• 不支持目录预热：预热仅支持提交具体文件的URL，不支持输入以/结尾的目录路径。

• 优先选择热点资源：仅预热预计会被集中访问且可能给源站造成压力的资源。小文件或非热点文件通常可在首次访问时自然填充缓存。

• 配额与队列：每个账号每日默认1000条URL预热配额，预热队列最大容量为100,000条URL。

• 回源流量：预热会触发CDN回源层节点拉取资源，实际回源量受节点分布、文件大小、任务范围和源站类型影响。建议分批提交并观察源站负载；视频类业务可配合Range回源，避免一次性拉取完整大文件。

参考：CDN的缓存刷新机制

URL刷新直接删除指定文件的缓存。目录刷新和正则刷新默认采用标记刷新，也可通过API使用强制刷新；忽略参数刷新同样支持Force参数。

{
  "ObjectType": "Directory",
  "ObjectPath": "https://<加速域名>/static/",
  "Force": true
}

常见问题

刷新和预热相关常见问题