Purge and prefetch resources

Resource purge

A purge operation sends a cache invalidation command to edge nodes rather than directly deleting files. When an edge node receives the command, it marks the matching cached resources as "invalid" or "expired." The next time a user requests the resource, the edge node detects that the cache is invalid, performs an origin fetch to retrieve the latest version, and serves it to the user while caching the new version.

Default purge method in the console: When you perform a directory purge or regex-based purge in the CDN console, the system uses a soft purge by default. A soft purge only marks the cache as expired. When the edge node performs an origin fetch, it includes an If-Modified-Since or If-None-Match header in the request. If the origin server returns a 304 Not Modified response, the edge node retains the old cached copy. This method saves origin fetch traffic but may cause users to access stale content in scenarios such as same-name file updates, non-compliant content removal, or after configuration changes. To completely purge the cache, we recommend calling thepurgeObjectCaches API operation and setting theForce parameter totrue to perform a force purge.

Use cases

• Resource updates and releases: After you update or upgrade resources on your origin server, submit the corresponding URLs or directories for a purge to ensure users can access the latest content, which is then cached on the edge nodes.

• Non-compliant resource removal: If your website has non-compliant content, simply deleting it from the origin server is not enough, as it may still exist in the cache of edge nodes. You must perform a URL purge to purge the cached resources and ensure the non-compliant content is removed promptly.

Resource prefetch

A prefetch operation is a pull-based mechanism that causes edge nodes to proactively fetch resources from your origin server and cache them. It is not a push from the origin server. Prefetching improves the initial access speed for new resources or event pages and reduces origin fetch pressure during product or event launches, thereby protecting your origin server.

Prefetch mechanism: By default, a prefetch operation caches resources on Tier-2 origin-pull nodes (the L2 cache layer) instead of distributing them to all L1 edge nodes. When a user first accesses a resource, the L1 edge node pulls the content from a Tier-2 origin-pull node or the origin server and caches it. Therefore, prefetching primarily reduces the load on your origin server. Comprehensive cache coverage on L1 edge nodes depends on actual user access patterns. Only after a user's request triggers an L1 node to cache the content locally can subsequent users in the same region benefit from a direct cache hit from that L1 node.

Use cases

• Initial CDN setup: After adding your domain to CDN, prefetch popular static resources to edge nodes. When users request these resources, the edge nodes can respond directly, which eliminates slow initial load times and improves user experience.

• Launch promotional events: Before a major event, prefetch all static resources for the event pages. When the event starts, all static resources are already cached on edge nodes and can be served directly, ensuring fast page load times.

• Release installation packages or large files: Before releasing a new version or an update package, prefetch the resources to edge nodes. After the product goes live, edge nodes serve download requests directly, which improves download speeds and reduces the load on your origin server.

Prefetch cache hierarchy and expected results

A prefetch operation primarily caches resources on L2 aggregation nodes, not on all L1 edge nodes (POPs). When a user requests a prefetched resource for the first time, the L1 POP retrieves it from the L2 node or the origin server. Therefore, the primary purpose of prefetching is to reduce origin server pressure, not to guarantee immediate cache hits on all L1 POPs.

• Cost evaluation: Prefetching helps improve cache hit rates. However, for small files or non-popular resources, evaluate the prefetch cost carefully. Prefetching generates origin fetch traffic, which is roughly equal to the file size multiplied by the number of L2 nodes.

purge resources

1. Log on to theCDN console.

2. In the left-side navigation pane, click Purge and Prefetch.

3. On the Purge/Prefetch tab, select Purge as the operation type.

4. Select a purge method and submit the task.

How to purge an entire site (full-site purge or root directory purge)

CDN does not offer a one-click full-site purge option, but you can achieve this through the following methods:

1. Directory purge: Select Directory as the purge method and enter the root directory URL of your domain name (for example, https://www.example.com/). The URL must end with a forward slash (/).

2. Forced purge (API): If some POPs still serve stale content after a directory purge, call the Cache Purge API (RefreshObjectCaches) and set the Force parameter to true. A forced purge unconditionally removes the cached resources from all POPs, forcing an origin fetch on the next request.

   Note

   The Force parameter is not available in the console purge form. To perform a forced purge, use the API or SDK.

3. ClickSubmit to start the purge task.

   • Once submitted, a purge task cannot be canceled.

   • A purge task typically takes 5 to 6 minutes to propagate across the entire network. If a cached resource has an expiration time shorter than this, you do not need to manually purge it.

   • If you enableautomatic CDN cache purge in the OSS console, you cannot view automatic purge tasks initiated from OSS in the CDN console.

Prefetch resources

1. Log on to the CDN console.

2. In the left-side navigation pane, clickPurge and Prefetch.

3. On the Purge/Prefetch tab, selectPrefetch as the operation type.

4. In the content input box, enter the full URLs of the files to prefetch, one per line. Directory prefetch is not supported. Example: https://www.example.com/install/package.zip.

5. ClickSubmit to start the prefetch task.

   • Once submitted, a prefetch task cannot be canceled.

   • The completion time for a prefetch task depends on the file size, number of files, and origin server performance. It typically takes 5 to 30 minutes.

Notes on prefetching OSS files

When your origin server is OSS, take note of the following URL requirements:

• URL format: You must enter the full URL of the CDN-accelerated domain name (for example, https://cdn.example.com/path/file.zip). Do not enter the internal or public endpoint URL of the OSS bucket (for example, https://examplebucket.oss-cn-hangzhou.aliyuncs.com/...).

• Signature parameters: Prefetch URLs must not contain OSS temporary signature parameters such as Expires, OSSAccessKeyId, or Signature. These are temporary authorization parameters that cause prefetch tasks to fail.

• Origin server response status code: A prefetch task requires a 200 status code from the origin server. If the origin server returns a 308 redirect or any non-200 status code, the prefetch task fails. For example, if a missing trailing slash in the URL causes a redirect, add the trailing slash and resubmit the task.

Automate purge or prefetch tasks

We recommend that you use an automated script to purge and prefetch resources in the following situations:

• You do not have developers to automate tasks, and submitting them manually results in high operational costs.

• You have too many URLs to purge or prefetch, and submitting them in batches is inefficient.

• You need to manually or programmatically check whether purge and prefetch tasks are running as expected.

Soft purge (default CDN policy)

• Use case: Routine content updates, such as publishing new versions of static files.

• Mechanism: This is the default behavior for directory and regex-based purgees submitted through the console. When a CDN edge node performs an origin fetch, it includes anIf-Modified-Since orIf-None-Match header in the request. The origin server uses these headers to determine if the resource has been updated.

• Effect: If the resource on the origin server has not changed, the origin server returns a 304 Not Modified status code. The CDN edge node then continues to serve the old cached copy, which consumes no origin fetch traffic. This is an optimized method that saves costs and reduces the load on the origin server. Note: If you need to completely purge the cache (for example, to remove non-compliant content, apply configuration changes, or update a file with the same name), a soft purge may not meet your needs. In such cases, use a force purge.

Force purge

• Use cases: Urgent removal of non-compliant or erroneous resources, forcing a network-wide update after fixing incorrect Cache-Control response header configurations, or updating a file on the origin server that has the same name.

• Mechanism: To trigger a force purge, set the Force parameter to true when you call the purgeObjectCaches API. In this mode, the CDN edge node unconditionally marks the cached resource as invalid and does not perform a 304 validation check.

• Effect: On the next request for the resource, the CDN edge node must perform an origin fetch to get the new version, even if the file on the origin server has not changed.

API force purge parameter example:

{
  "ObjectType": "Directory",
  "ObjectPath": "https://www.example.com/static/",
  "Force": true
}

Key parameter descriptions:

• ObjectType: Specify Directory or File.

• ObjectPath: Specify the full directory path ending with /, or a specific file URL.

• Force: Set to true to enable force purge. This clears the cache directly, bypassing the origin server's If-Modified-Since/If-None-Match validation.

Typical use cases for forced purge

We recommend that you use forced purge (by calling the Cache Purge API and setting Force=true) in the following scenarios:

• Non-compliant content or malware removal: After you delete malicious files from the origin server, you must use a forced purge or ensure the origin server returns the correct HTTP status code (such as 404) for the deleted URL. Otherwise, POPs may continue to serve non-compliant content from cache after a standard revalidation.

• Same-name file updates (configuration changes): If you replace a file on the origin server with a new version using the same filename, a revalidation may return a 304 Not Modified status code and continue serving the old cached content. Use a forced purge to ensure the latest content is served across all POPs.

• Page display issues or homepage loops: If other pages on your website keep showing the homepage or images display incorrectly, and URL purge does not resolve the issue, use a directory purge with Force=true through the API.