This topic describes common issues and solutions when you use CDN to accelerate access to OSS resources. It covers scenarios such as acceleration verification, HTTPS deployment, origin fetch for private buckets, caching policies, image processing and video snapshots, and hotlink protection configuration.
Verifying CDN acceleration for OSS
Step 1: Check the CNAME record
For example, if you use Alibaba Cloud DNS, log on to the DNS Management Console, select Authoritative DNS, and click DNS Settings next to the domain name.
Verify that a CNAME record (for example,
oss.example.com.w.kunlunaq.com) has been added for the accelerated domain name (for example,oss.example.com) and that its status is Enabled.
Step 2: Verify the domain with nslookup
Open Command Prompt (Windows) or Terminal (macOS/Linux).
Run
nslookup -type=CNAME <accelerated_domain_name>. If the returned CNAME value matches the one provided in the CDN console for the accelerated domain name, CDN acceleration is active.
If you have not configured a CNAME record, see Configure a CNAME record.
Accelerating a private OSS bucket with CDN
If the origin for your accelerated domain name is a private bucket, you must enable Access Private OSS Buckets for the accelerated domain name. This allows CDN to accelerate access to resources in the private bucket.
After you enable this feature, you can access all resources in the private bucket by using the accelerated domain name, and the original URL-based private authentication method no longer applies. You can use CDN's hotlink protection and URL authentication features to protect your resources from unauthorized access. For more information, see Configure a Referer Whitelist or Blacklist and Configure URL authentication.
Deploying HTTPS certificates for CDN acceleration
When you use CDN to accelerate access to OSS, you only need to deploy an HTTPS certificate on CDN. For more information, see Configure an HTTPS certificate.
If your certificate is managed by Alibaba Cloud Digital Certificate Management Service (formerly SSL Certificate Service), you can also deploy it from the Digital Certificate Management Service console. For more information, see Deploy an SSL certificate to Alibaba Cloud services.
403 Forbidden error
Troubleshooting steps:
Check the error message on the page. If you see messages like
You don't have permission to access the URL on this serverorYou are forbidden to list buckets, accompanied by details likedenied by IP ACL = not in whitelist, you can use this information to quickly identify the blocking policy.If the only message is
You don't have permission to access the URL on this serverwith no other details, check your CDN URL authentication and remote authentication settings.
If images for a domain name fail to load with a permission denied error:
Check the private bucket origin fetch switch: Log on to the CDN console, go to the Domain Management page of the target domain name, and confirm that origin fetch for the Alibaba Cloud OSS private bucket is enabled. If it is not enabled, CDN does not have permission to access private OSS resources, which results in a 403 error.
Check the Referer whitelist/blacklist configuration: Go to the domain's settings and verify that the request's Referer is in the whitelist. If the request is blocked by a Referer rule, add the target Referer to the whitelist.
If you have configured static website hosting on OSS and the index file (for example, index.html) or the bucket itself is private, you must enable the Access Private OSS Buckets feature. Then, configure a URL rewrite rule in CDN to rewrite access URLs to the configured index file (for example, index.html). The CDN edge node issues a 302 redirect, prompting the client to request the index.html content. This process enables static website hosting. For detailed configuration, see Rewrite an access URL. To configure the rule, set Path to Rewrite to ^/$, Destination Path to /index.html, and Action to Redirect.
Slow access after enabling CDN
When you use an accelerated domain name to access a resource for the first time, the request is sent to a CDN edge node. Because the resource is not yet cached on the node, the CDN edge node performs an origin fetch from OSS, caches the resource, and then returns it to the client. Subsequent requests for the same resource are served directly from the CDN edge node. Therefore, the first access may be slower than without CDN acceleration.
You can use the CDN preheat feature to cache OSS resources on CDN edge nodes in advance. This ensures that the first client request is served directly from a CDN edge node without an origin fetch. For instructions, see Refresh and preheat resources.
Cache policy to reduce origin fetches
If you do not configure a cache expiration time or if the configured time is too short, CDN may perform frequent origin fetches. This increases origin-to-OSS traffic and associated costs, and can reduce access speed. You can configure cache expiration times based on your business needs:
For static files that are rarely updated, such as images and application installers, set the time to live (TTL) to one month or longer.
For frequently updated static files, such as JS and CSS files, set the TTL based on your update frequency.
For more information, see Configure cache expiration rules.
Ensuring users access the latest resources
After modifying a file in OSS, to ensure that CDN nodes automatically refresh their cache and clients receive the updated content, you can enable the automatic CDN cache refresh feature in the OSS console. For specific instructions, see the "Enable automatic CDN cache refresh" section in Configure automatic CDN cache refresh.
This feature does not guarantee that a refresh task will be submitted successfully or in a timely manner. If you require real-time updates or need to track the refresh status, use the CDN refresh feature. For more information, see Refresh and preheat resources.
Cannot enable automatic CDN refresh in the OSS console
You cannot enable automatic CDN cache refresh and a message appears: "Please bind this domain name in OSS first".
Solution: In the Map Custom Domain Name column, click Unbound for the corresponding domain and follow the on-screen instructions to bind the domain. If you have already bound the domain to CDN and your DNS is resolved to the CDN CNAME, do not modify the DNS record after binding the OSS domain. Otherwise, the CDN acceleration service will not function.
OSS image processing parameters are ineffective
When using CDN to accelerate OSS, requests first reach a CDN edge node. If the 'Ignore Parameters' feature is enabled in CDN, the node will strip any parameters after the ? in the request URL. If the resource is already cached, CDN will not perform an origin fetch, and the OSS image processing will not be applied. For more information, see Ignore parameters.
Disable the 'Ignore Parameters' feature. When a request includes parameters, it triggers an origin fetch to OSS, and image processing works as expected.
After you disable 'Ignore Parameters', the cache hit ratio may decrease because every request with parameters triggers an origin fetch. Alternatively, you can use the image processing feature provided by CDN to perform image processing on CDN edge nodes.
Special configuration for video snapshots
When using the OSS video snapshot feature (with parameters like x-oss-process=video/snapshot,t_1000), if 'Ignore Parameters' is enabled for the CDN domain, the original video URL and the URL with snapshot parameters will be cached as the same resource. This can cause the snapshot image to be returned when accessing the video, or the original video to be returned when requesting the snapshot.
Solution: In the CDN console, use the 'Ignore URL Parameters' feature and switch to the mode that retains specified parameters. Add x-oss-process to the list of retained parameters. This allows URLs with snapshot parameters to be cached separately, avoiding conflicts with the original video cache. After changing the configuration, you must refresh the directory that contains the video files.
Excluding files or directories from the CDN cache
When accelerating OSS with CDN, you may need to bypass the CDN cache for certain files or directories so that every request fetches the latest version directly from OSS. You can do this in two ways, depending on your management practices:
CDN-side configuration (Recommended): Manage caching rules in the CDN console. This method is suitable for scenarios where an operations team performs centralized management. Go to Cache and set the cache duration to 0. After the rule takes effect, when CDN receives requests for these paths, it performs an origin fetch from OSS and does not cache the response.
Configure on the OSS side: Set response headers for OSS files. This is suitable for scenarios where storage and content management are separate. In the CDN console, make sure the caching policy is prioritized to respect origin headers; otherwise, custom CDN rules may override them. Then, go to the OSS console, navigate to File Management > Files, select the target file, and set the Cache-Control value as needed:
Cache-control value | Use case | Description |
| Recommended: For content that requires fetching the latest version every time, such as HTML files, configuration files, or version metadata. | CDN does not cache the content. The browser revalidates with the origin by using an ETag. |
| High-sensitivity scenarios: For content that should not be stored at any point, such as user privacy data, tokens, or financial information. | Neither CDN nor the browser caches the content. A full request is made every time. |
| Personalized content: For pages that contain user-specific content that cannot be shared in a multi-user cache. | CDN does not cache the content, but the browser can still cache it. |
Both solutions apply only to new requests. If the file is already cached, these new settings will not automatically clear the cache on edge nodes, so users might still see the old version. You must also refresh the CDN cache. Enter the target URL or directory and refresh it. Subsequent requests will then follow the new rules and fetch the latest content from OSS.
Low cache hit ratio and frequent origin fetches
Troubleshooting
Run curl -I on the same resource multiple times and check the Age and X-Cache response headers. An Age: 0 or X-Cache: MISS header indicates an origin fetch.
Solutions
The cache rule's TTL is set too short or is set to "Do not cache". Adjust the caching rules to increase the cache expiration time.
The 'Ignore Parameters' feature is enabled, but the URL contains necessary parameters for version control or image processing, such as
?v=1.1orx-oss-process. This causes CDN to treat URLs with different parameters as the same resource, leading to content errors or feature failures. In this case, you must disable the 'Ignore Parameters' feature.The origin response header, such as
Cache-Control: no-cache, instructs CDN not to cache the content. In this case, adjust the origin's caching policy or configure CDN to ignore the origin's policy.
Low cache hit ratio and frequent origin fetches
Troubleshooting: Run curl -I on the same resource multiple times and check the Age and X-Cache response headers. An Age: 0 or X-Cache: MISS header indicates an origin fetch.
Solutions:
The cache rule's TTL is set too short or is set to "Do not cache". Adjust the caching rules to increase the cache expiration time.
The 'Ignore Parameters' feature is enabled, but the URL contains necessary parameters for version control or image processing, such as
?v=1.1orx-oss-process. This causes CDN to treat URLs with different parameters as the same resource, leading to content errors or feature failures. In this case, you must disable the 'Ignore Parameters' feature.The origin's response header, such as
Cache-Control: no-cache, instructs CDN not to cache the content. In this case, you must either adjust the origin's caching policy or set a cache expiration time in CDN to override the origin's policy.
Video can't be played as link identified as image
Cause: A browser determines the resource type from the Content-Type response header. If the Content-Type of a video file in OSS is incorrectly set to an image type (such as image/jpeg), the CDN passes this header through, causing the browser to process the video as an image. This issue cannot be resolved by simply adding parameters to the URL.
Solution (choose one):
Recommended: Modify the response header in the CDN console: Log on to the CDN console, go to the settings for the target domain, and add a rule to force the
Content-Typetovideo/mp4. You can apply this rule based on the file extension.Fix at the origin: Log on to the OSS console, find the corresponding video file, and manually change its
Content-Typetovideo/mp4in the file details.
OSSBrowser support for CDN accelerated domains
The OSSBrowser client tool does not support logging in with a CDN accelerated domain name. It only accepts native OSS endpoints.