CDN:Performance optimization troubleshooting guide

Performance issues are affected by many factors. Before troubleshooting, confirm that the request actually goes through CDN, and establish control groups to narrow down the root cause.

Collect access effect

A reproducible troubleshooting should at least record the following information:

• UTC time, client region and ISP, masked client IP <CLIENT_IP>, LocalDNS;

• Request URL, request method, status code, redirect chain;

• DNS result, actual connected node IP;

• X-Cache, X-Swift-CacheTime, Age (if present), Via;

• Cache-Control, Pragma, Expires, ETag, Last-Modified, Vary;

• Content-Type, Content-Length, Content-Encoding, Accept-Ranges, Content-Range;

• DNS, TCP, TLS, TTFB, download, and total duration;

• Comparison results of the same request for first CDN GET, repeated GET, specified-node GET, and direct-origin GET.

curl -sS -D /tmp/cdn-headers.txt -o /dev/null \
  -w 'remote_ip=%{remote_ip}\nhttp_code=%{http_code}\ntime_namelookup=%{time_namelookup}\ntime_connect=%{time_connect}\ntime_appconnect=%{time_appconnect}\ntime_starttransfer=%{time_starttransfer}\ntime_total=%{time_total}\nsize_download=%{size_download}\n' \
  "https://<CDN_DOMAIN>/<RESOURCE_PATH>"

curl -sS -D - -o /dev/null \
  --resolve "<CDN_DOMAIN>:443:<CDN_NODE_IP>" \
  "https://<CDN_DOMAIN>/<RESOURCE_PATH>"

curl -sS -D - -o /dev/null \
  --resolve "<CDN_DOMAIN>:443:<ORIGIN_IP>" \
  "https://<CDN_DOMAIN>/<RESOURCE_PATH>"

curl -sS -D - -o /dev/null \
  -H 'Accept-Encoding: gzip, br' \
  "https://<CDN_DOMAIN>/<RESOURCE_PATH>"

curl -sS -D - -o /dev/null \
  -H 'Range: bytes=0-1023' \
  "https://<CDN_DOMAIN>/<LARGE_RESOURCE_PATH>"

curl -sS -D - -o /dev/null "https://<CDN_DOMAIN>/<RESOURCE_PATH>"
curl -sS -D - -o /dev/null "https://<CDN_DOMAIN>/<RESOURCE_PATH>"

Poor client-to-node network quality or scheduling anomaly

Symptom: ping to the accelerated domain shows high latency or packet loss; users in a specific region or on a specific ISP are slow; users are scheduled to distant nodes.

Possible causes and troubleshooting:

• Incorrect acceleration region setting: When the acceleration region is set to "Mainland China only", overseas users are scheduled to mainland China nodes; when set to "Global (excluding Mainland China)", mainland China users are scheduled to overseas nodes. Set the acceleration region to the correct scope based on user distribution (for example, "Global").

• Domain has not completed ICP filing: Unfiled domains can only select "Global (excluding Mainland China)". When mainland China users access through overseas nodes, the link is longer and speed may be unsatisfactory. To provide acceleration for mainland China users, please complete ICP filing first; if filing is not possible, consider using Edge Security Acceleration (ESA) to reduce latency for mainland China users accessing overseas sites.

• Incorrect client DNS settings: For example, a Tokyo user using a US DNS may be scheduled to a US node instead of a nearby node. Instruct the user to change to a DNS corresponding to their location and ISP.

• Regional ISP network fluctuation: When the acceleration region and DNS are correct but access is still slow, collect traceroute and MTR information to confirm the specific link segment where latency occurs; test by binding the node IP that the user request reaches to confirm whether the node itself responds normally, then combine cache hit status and resource size for further analysis.

Low cache hit ratio or frequent origin fetch causing slow access

Symptom: Response header X-Cache is MISS, X-Swift-CacheTime is 0; high origin pressure and high origin traffic; first access is slower than accessing the origin directly.

Common causes and optimization solutions:

• First access has no cache: The node must fetch data from origin on first response. We recommend using the URL prefetch feature to proactively prefetch origin content to CDN nodes; see Purge and prefetch resources.

• Low traffic and insufficient file popularity: Node cache evicts least popular items by popularity; low-traffic resources are evicted earlier. In low-traffic scenarios, you can appropriately extend cache time or use prefetch to maintain popularity.

• Unreasonable cache configuration:

  • When no cache rule is configured and static files do not return ETag and Last-Modified response headers, the file cannot be cached. Please add these two response headers at the origin, or configure cache rules on the CDN side; see Configure CDN cache expiration.

  • When no cache rule is configured, the default cache policy is used, with a maximum cache time not exceeding 3600 seconds, which easily leads to frequent expiration and origin fetch. Please set a reasonable cache time based on your business.

  • When the origin response header contains any of s-maxage=0, max-age=0, no-cache, no-store, private, or Pragma: no-cache, the content will not be cached even if cache rules are configured. Please modify the origin response header to a cacheable value (such as public), or enable Ignore Origin No-Cache Header in the CDN cache rule.

• URL carries variable parameters: When URLs with different parameters access the same file, CDN treats them as different resources and fetches from origin separately. Please enable the ignore parameter feature; see Ignore parameters.

• Large files are slow to fetch from origin: For large file scenarios, we recommend enabling Range origin fetch to optimize origin fetch efficiency; see Configure range origin fetch.

• Frequent cache refresh: Frequent URL or directory cache refresh causes node cache to remain invalid and reduces hit ratio. Please only refresh affected resources when content is updated.

Verification method: Bind the user domain in hosts to the origin IP and access directly, then compare the load time with CDN access to verify the acceleration effect and confirm whether the bottleneck is in origin fetch or distribution link. For more hit-ratio optimization strategies, see Cache troubleshooting.

Slow dynamic requests

Symptom: Dynamic content such as API interfaces is slow; static resources are fast but the overall page loads slowly.

Cause: CDN cannot cache dynamic content that changes in real time. Dynamic requests are forwarded to the origin server every time, so CDN cache acceleration has no effect on them. If the origin itself is slow, dynamic requests will become slow synchronously.

Solution:

• Separate static and dynamic content at the origin: use a CDN-accelerated domain for static resources, and a domain that resolves directly to the origin for dynamic requests.

• Use Edge Security Acceleration (ESA) to accelerate dynamic requests through route optimization, transport optimization, and other technologies to shorten the origin chain. Note that dynamic acceleration is link optimization; if the origin server itself is slow, the origin still needs to be optimized.

Cross-country or cross-border origin fetch is slow

Symptom: When the origin and primary users are in different countries or regions, origin fetch quality fluctuates, origin fetch is slow, and origin failure rate is high, affecting cache and content distribution.

Cause: Cross-border origin fetch is affected by submarine cable capacity and public network congestion between countries.

Solution: Use Global Accelerator (GA) to provide targeted acceleration for the origin in the corresponding country, and configure CDN region-specific origin fetch policies to improve origin fetch quality when cache is missed. GA supports origin types such as ECS, ALB, and OSS, and provides solutions such as Accelerate back-to-origin with GA and CDN.

Website home page loads slowly

Symptom: The home page request stays in Pending state for a long time in Network; after the home page returns, static resources load quickly.

Cause: The home page is usually a dynamic resource or configured as non-cacheable, so every visit goes back to origin. When the origin response is slow, the home page request is blocked, and subsequent resources such as images, JS, and CSS referenced by the home page HTML cannot start loading.

Solution: First confirm through response headers whether the home page hits cache (see How to identify the direction of slow access issues); if it misses, troubleshoot cache configuration according to Low cache hit ratio or frequent origin fetch causing slow access; if the origin response is slow, optimize origin performance or adopt static/dynamic separation.

Large resources load slowly

Symptom: Content Download accounts for a large proportion of Timing; page resources have a large total size.

Solution: Enable performance optimization features (smart compression, page optimization, etc.) to reduce file size and improve loading speed; see Performance optimization. Smart compression supports the following formats: text/xml, text/plain, text/css, application/javascript, application/x-javascript, application/rss+xml, text/javascript, image/tiff, image/svg+xml, application/json, application/xml.

Gzip compression not working after origin fetch

Symptom: The origin (such as Nginx) has Gzip compression enabled, and the response header returns Content-Encoding: gzip when the client accesses the origin directly; when accessing through CDN with the request header carrying Accept-Encoding: gzip, deflate, the response header only returns Content-Length, and the content is not compressed.

Cause: CDN origin fetch requests carry the Via request header to identify that the request comes from a proxy server. The Nginx ngx_http_gzip_module module uses the gzip_proxied configuration to control whether compression is enabled for proxy requests. The default value of this configuration is off, so origin fetch requests from CDN do not return compressed content.

Solution:

1. Set gzip_proxied any in the Nginx configuration file (http, server, or location block, whichever applies) so that all requests from proxy servers are compressed.

2. Run nginx -t to confirm the configuration is correct, then run nginx -s reload to reload the configuration.

3. Access through CDN and confirm that the response header contains Content-Encoding: gzip.

Verification method: Use curl to test directly against the origin — when no Via header is sent, it returns Content-Encoding: gzip; after adding -H 'Via:xxx' to simulate a proxy request, it only returns Content-Length. This confirms the issue is caused by the gzip_proxied configuration.

Note: The troubleshooting approach is the same when Brotli compression does not work — confirm whether the origin refuses to return compressed content for proxy requests due to the Via request header or gzip_proxied-like configuration, and replace the Gzip-related configuration with the corresponding Brotli configuration.

Trade-off with page optimization: If you also enable page optimization, note that origin compression and page optimization are mutually exclusive; CDN cannot perform page optimization after the origin returns compressed content. Choose between origin compression (saving origin bandwidth) and page optimization (reducing HTML size) based on business priority.

Page optimization not working when both page optimization and Gzip compression are enabled

Symptom: Page optimization is enabled. When curl is sent without the Accept-Encoding request header, the returned HTML is optimized; but when accessed from a browser (which sends Accept-Encoding: gzip by default), the returned content is not page-optimized.

Cause:

• Origin returns Gzip-compressed content: Browsers carry the Accept-Encoding: gzip request header by default, and CDN forwards this header when fetching from origin. When the origin has Gzip enabled, it returns compressed content. CDN nodes do not decompress content already compressed by the origin before performing page optimization, so page optimization cannot take effect when the origin returns compressed content.

• CDN smart compression does not block page optimization: CDN smart compression runs after page optimization; the two are not in conflict. This symptom only appears when the origin has already returned compressed content — origin pre-compression prevents CDN from performing page optimization, and is unrelated to CDN-side smart compression.

Solution:

• Option 1: Ensure the origin does not return Gzip-compressed content for CDN origin fetch requests. For Nginx origins, modify the gzip_proxied parameter so that requests from proxy servers do not return compressed content.

• Option 2: In the CDN configuration, remove Accept-Encoding from the origin HTTP request header so that the origin returns uncompressed content and CDN performs page optimization.

Note: After the origin stops returning compressed content, CDN can compress the client response through the smart compression feature, achieving both page optimization and transmission compression.

Business exceptions after enabling ignore parameters

Symptom: After enabling ignore parameters, authentication fails, user data is mixed, wrong cached content is returned, or image processing becomes invalid.

Cause: After ignore parameters is enabled, CDN treats requests with different parameters as the same resource for caching. The following types of URL parameters should not be globally ignored:

• User identity identifiers (such as UID, Token, Session ID): ignoring them causes authentication failure or mixed user data.

• Dynamic content differentiation (such as version ?v=1, page number ?page=2): ignoring them returns the wrong cached content.

• Origin processing directives (such as OSS image processing parameter x-oss-process): ignoring it invalidates the processing parameter and returns the unprocessed original resource.

Troubleshooting and solution:

1. Delete or disable the ignore parameter configuration.

2. Perform cache refresh (URL refresh or directory refresh) to clear stale cache on edge nodes.

3. If some parameters need to be retained, use the retain specified parameters mode and set key parameters (such as x-oss-process, token) as retained. For details about the ignore parameter feature, see Ignore parameters.

Ignore parameter configuration not effective after modification

Symptom: After modifying the ignore parameter configuration, access is still abnormal or origin traffic has not decreased.

Cause: After the configuration is modified, files already cached on edge nodes are not automatically updated; old cache still responds according to the old policy.

Troubleshooting steps:

1. Confirm the configuration is saved: Log in to the CDN console, reopen the ignore parameter configuration page, and confirm the current configuration matches the expected state.

2. Check for conflict with custom Cache Key: Custom Cache Key overrides the ignore parameter configuration. If custom Cache Key is enabled, the ignore parameter configuration will not take effect. Please confirm that both are not enabled at the same time.

3. Perform cache refresh: On the Purge and prefetch resources page, perform URL refresh or directory refresh. The new configuration can only take full effect after old cache is cleared.

4. Verify configuration effect: Run curl -I "full URL" and check the response header X-Cache to confirm the cache hit status meets expectations.

Incorrect OSS image processing or video frame capture content

Symptom: When using OSS image processing (such as x-oss-process=image/resize,w_200) or video frame capture, the access returns the unprocessed original image or video, or requests with different processing parameters return the same content.

Cause: After ignore parameters is enabled for the CDN domain, the original image link and the link with processing parameters are cached as the same resource, causing incorrect content.

Solution: In the CDN console ignore parameter configuration, set the x-oss-process parameter to retain specified parameters mode, so that URLs with image processing parameters are cached separately and do not conflict with the original image cache. After modifying the configuration, refresh the cache (see Ignore parameter configuration not effective after modification).

Inconsistent cache hit status after enabling ignore parameters

Symptom: Ignore parameters is enabled, but cache hit status is inconsistent across clients; some requests show X-Cache MISS.

Possible causes:

1. URL carries unignored dynamic authentication parameters: For example, the URL has auth_key and other authentication parameters set as retained. Each request has a different authentication value, so CDN still recognizes them as different resources.

2. First access has no cache on the node: The resource has not yet been cached on that edge node, so the first access will inevitably show MISS.

3. Client request header differences: For example, different Accept-Encoding may trigger multi-copy caching (Gzip and non-Gzip versions cached separately). If the origin returns Vary: User-Agent, requests from different UAs will also be cached separately.

4. Conflict with custom Cache Key: Custom Cache Key overrides the ignore parameter configuration; when both are enabled, ignore parameters does not take effect.

Troubleshooting method: On the client, run curl -I "full URL" and compare the response headers X-Cache and X-Swift-CacheTime to confirm cache status. Solution: Confirm that the ignore parameter configuration is correct (enabled and key parameters are retained), ensure consistent client request header strategy, and confirm that custom Cache Key is not enabled at the same time.