CDN Refresh and Preload Diagnostics

Diagnose CDN refresh and preload issues: "content not updated after refresh", "preload failed", "cache not cleared", "URL refresh not effective", "directory refresh still shows old content".

Core approach: First query refresh/preload task records to confirm task status, then follow different diagnostic branches based on refresh type (file / directory / preload).

Observability

All OpenAPI calls (invoked through the aliyun CLI) include:

• User-Agent: --user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
• SKILL_NAME: alibabacloud-cdn-refresh-preload
• session-id: 32-character hex string generated per diagnostic session

Prerequisites

1. Python 3.11+ and aliyun CLI — required: aliyun cdn describe-refresh-tasks and aliyun sts assume-role are both invoked via the aliyun CLI (no direct HTTP signing). No external Python SDK dependencies.

2. Alibaba Cloud credentials — Credentials are resolved automatically by the aliyun CLI default credential chain (environment or ~/.aliyun/config.json). Do not read, print, or pass AK/SK/STS tokens explicitly.

3. Target inputs: URL (the resource to diagnose) and UID (the Alibaba Cloud account UID). UID can be omitted — it defaults to the caller account derived via aliyun sts get-caller-identity. Auto-fill first, ask second: never ask the user for UID or role name when they can be derived.

   Auto-fill declaration requirement: Whenever any parameter is auto-filled (UID, domain, URL, or role name), the Agent MUST explicitly declare this in the response or report metadata. For example: "UID auto-derived via sts:GetCallerIdentity: 1772241626973633" or "Domain auto-discovered via DescribeUserDomains: tofirae.com" or "URL auto-extracted from refresh task records: https://tofirae.com/1.png". This declaration is mandatory and must appear in the final output.

   URL auto-completion: If the user provides only a domain name (without URL), the skill queries task records for that domain and auto-extracts the most recent URL. If neither URL nor domain is provided, the skill queries all task records and auto-extracts the most recent URL. This enables "information incomplete" scenarios where the user doesn't provide a specific URL.

Authentication: Identity Verification

Credentials are resolved automatically by the aliyun CLI default credential chain (environment or ~/.aliyun/config.json). Do not read, print, or pass AK/SK/STS tokens explicitly.

SKILL_DIR=~/.qoderwork/skills/alibabacloud-cdn-refresh-preload

# Verify caller identity and derive the caller UID (auto-cached)
# --uid is informational only (recorded in the report for traceability); credentials always come from the CLI default credential chain
# --role-name defaults to cseesadiagnosticrole if omitted; do not ask the user for it
cd $SKILL_DIR && python3 scripts/sts_token.py --json

sts_token.py only performs identity verification and UID derivation — it does not carry, print, or pass credentials.

Identity Verification Failure: If sts_token.py fails, the account has not granted investigation permissions. Guide the customer to authorize via RAM console.

Note: sts_token.py only performs identity verification (via aliyun sts get-caller-identity plus a nested-role detection hint); it never calls aliyun sts assume-role. If the runtime already injected a session of the diagnosis role (caller Arn is assumed-role/cseesadiagnosticrole/...), the script simply relies on the aliyun CLI default credential chain — no extra authorization step is needed.

Diagnostic Flow

Step 1: Query Refresh/Preload Task Records

# Mode 1: URL provided (existing behavior)
# uid omitted -> auto-derived via aliyun sts get-caller-identity
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py --url <URL>

# Mode 2: Domain-only (auto-extract URL from task records)
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py --domain <DOMAIN>

# Mode 3: No params (auto-extract most recent URL from all task records)
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py

| Result | Next Step | |--------|-----------| | No task records found | Scenario R4: No operation executed or wrong entry point | | Tasks found but status is Failed | Scenario R5: Task execution failed | | Tasks found, status Complete (file refresh) | Step 2a | | Tasks found, status Complete (directory refresh) | Step 2b | | Tasks found, status Complete (preload) | Step 2c |

Step 2a: File Refresh Complete but Not Effective

1. Compare refresh URL with user's actual test URL. Mismatch = Scenario R1.
2. Remote cache verification (Step 3):
   • MISS = refresh effective, likely client/browser cache issue
   • HIT = check Age header; if old cache persists = Scenario R6

Step 2b: Directory Refresh Complete but Not Effective

1. Bound origin probe with If-Modified-Since / If-None-Match headers (Step 4):
   • Origin returns 304 = Scenario R2: origin resource unchanged, CDN keeps old cache
   • Origin returns 200 with content change = continue investigation
2. Remote cache verification (Step 3)
3. Still abnormal = Scenario R6 (fallback)

Step 2c: Preload Complete but Not Effective

1. Remote cache verification (Step 3):
   • HIT = preload effective
   • MISS = continue
2. Bound origin probe, check origin Cache-Control / status code (Step 4):
   • Origin returns no-cache / no-store / private = Scenario R3
   • Origin returns non-200 status = Scenario R3
   • Origin normal 200 with cache headers = Scenario R6 (fallback)

Step 3: Remote Cache Verification

cd $SKILL_DIR && python3 scripts/cdn_probe.py 'curl -ksI "<URL>"'

Focus: X-Cache (HIT/MISS), Age, Via, Cache-Control, Last-Modified, ETag.

If the HTTPS probe fails with an SSL/TLS handshake error (e.g., curl exit code 35), retry the same probe using the http:// scheme - HTTP responses still carry the CDN cache headers (X-Cache/Age).

ALL probe commands (dig/curl/openssl) MUST be executed through scripts/cdn_probe.py — never run dig or curl directly in the shell.

Step 4: Bound Origin Probe (optional, agent-driven with curl/dig)

No script in this skill fetches origin configuration automatically (all scripts are CLI-based read-only queries). The agent must first obtain the origin address manually:

• Ask the customer for the origin IP/domain, or
• Use cdn_probe.py 'dig <accelerated domain>' to inspect DNS resolution as a clue.

ALL probe commands (dig/curl/openssl) MUST be executed through scripts/cdn_probe.py — never run dig or curl directly in the shell.

Then extract Last-Modified and ETag from the Step 3 response and run the bound origin probe:

cd $SKILL_DIR && python3 scripts/cdn_probe.py 'curl -ksI -H "Host: <CDN domain>" -H "If-Modified-Since: <Last-Modified>" -H "If-None-Match: <ETag>" --resolve <origin host>:443:<origin IP> "https://<origin host>/<path>"'

Focus: Origin returns 304 (resource unchanged) or 200 (resource changed). Also check Cache-Control, Pragma, Set-Cookie.

If the origin address cannot be obtained, skip this step and conclude from Steps 2/3 results.

Step 5: Output Diagnostic Report

Generate report per references/report-template.md.

Fault Scenarios

R1: Refresh URL Mismatch

File refresh Complete but user still sees old content. The submitted refresh URL does not match the visited URL (protocol, path, parameters). Fix: resubmit with exact URL.

R2: Directory Refresh (Expire Mode) + Origin 304

Directory refresh uses "expire" mode. CDN validates with origin; origin returns 304 (unchanged), CDN keeps old cache. Fix: use "force delete" mode, or origin updates Last-Modified/ETag. See references/cache-rules.md.

R3: Origin No-Cache Policy Causes Preload Failure

Origin returns no-cache / no-store / private / non-200 / Set-Cookie. CDN respects origin policy and does not cache. Fix: adjust origin Cache-Control, or CDN console overrides. See references/cache-rules.md.

R4: No Task Records

User claims refresh/preload done but no records found. Fix: confirm domain/URL and operation entry point.

R5: Task Execution Failed

Task status Failed. Fix: check URL format, domain config, HTTPS cert, origin reachability.

R6: Node Cache Not Synced (Fallback)

Task Complete, origin normal, but specific nodes still return old content. Fix: wait and retry, or bind specific node IP to locate anomalous node. Requires PE escalation.

Constraints

• Read-only operations: Only queries task records and performs diagnostics; never submits refresh/preload operations.
• Solutions must be evidence-based: Based on verified product features or official documentation only.
• Reference: references/cache-rules.md for CDN cache priority rules and status code cache behavior.

Available Scripts

| Script | Purpose | |--------|---------| | scripts/cdn_refresh_preload.py | Query refresh/preload task records, verify cache hit status | | scripts/cdn_probe.py | Execute diagnostic commands locally (curl/dig/openssl) | | scripts/sts_token.py | Verify caller identity and derive UID via the default credential chain |

Local Probing

All external probing commands are executed locally via cdn_probe.py. ALL probe commands (dig/curl/openssl) MUST be executed through scripts/cdn_probe.py — never run dig or curl directly in the shell.

cd $SKILL_DIR && python3 scripts/cdn_probe.py '<command>'

Standard probes: DNS (dig), HTTPS (curl -ksI), SSL cert (openssl), direct origin test (curl -ksI -H "Host: <CDN domain>"). See references/probe-result-routing.md for result routing.

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | No credentials found | Default credential chain not configured | Configure the aliyun CLI default credential chain (run aliyun configure) | | Identity verification failed (sts get-caller-identity) | Sandbox credentials missing or invalid | Check the runtime credential configuration; no extra authorization is needed when the default chain works | | API error (Forbidden / InvalidParameter / Throttling / InternalError) | OpenAPI returned an error for a query | Record the error, skip the affected query, continue the remaining diagnostic steps and still output the report | | API returns empty tasks | No refresh/preload in lookback window | Extend --days or verify domain/URL | | Probe command timeout | Network unreachable or command hung | Retry or check local network connectivity |

On repeated API errors from the packaged script, verify with a direct aliyun cdn describe-refresh-tasks CLI call to distinguish service-side failures from script issues.