alibabacloud-cdn-refresh-preload

CDN 更新およびプリロードの診断

CDN の更新およびプリロードに関する問題を診断します：「更新後もコンテンツが更新されない」「プリロードに失敗する」「キャッシュがクリアされない」「URL の更新が反映されない」「ディレクトリを更新しても古いコンテンツが表示される」。

基本的なアプローチ：まず更新／プリロードのタスク記録を照会してタスクのステータスを確認し、次に更新の種類（ファイル／ディレクトリ／プリロード）に応じて異なる診断手順に進みます。

可観測性

すべての OpenAPI 呼び出し（aliyun CLI 経由で実行）には、以下が含まれます。

• User-Agent：--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
• SKILL_NAME：alibabacloud-cdn-refresh-preload
• session-id：診断セッションごとに生成される 32 文字の 16 進数文字列

前提条件

1. Python 3.11 以降および aliyun CLI — 必須です。aliyun cdn describe-refresh-tasks と aliyun sts assume-role は、どちらも aliyun CLI 経由で実行されます（HTTP 署名を直接行いません）。外部の Python SDK 依存関係はありません。

2. Alibaba Cloud の認証情報 — 認証情報は aliyun CLI のデフォルト認証情報チェーン（環境変数または ~/.aliyun/config.json）によって自動的に解決されます。AK／SK／STS トークンを明示的に読み取ったり、表示したり、渡したりしないでください。

3. 対象の入力値：URL（診断対象のリソース）と UID（Alibaba Cloud アカウントの UID）。UID は省略できます。省略した場合は、aliyun sts get-caller-identity から取得した呼び出し元アカウントがデフォルトで使用されます。まず自動入力し、それから質問してください。導出できる場合は、UID やロール名をユーザーに尋ねないでください。

   自動入力の明示要件：パラメーター（UID、ドメイン、URL、ロール名のいずれか）を自動入力する場合は、エージェントは応答またはレポートのメタデータにその旨を明示しなければなりません。たとえば、「UID は sts:GetCallerIdentity により自動取得しました：1772241626973633」や「ドメインは DescribeUserDomains により自動検出しました：tofirae.com」、「URL は更新タスク記録から自動抽出しました：https://tofirae.com/1.png」のように記載します。この明示は必須であり、最終出力に含める必要があります。

   URL の自動補完：ユーザーがドメイン名のみ（URL なし）を指定した場合、このスキルはそのドメインのタスク記録を照会し、最新の URL を自動抽出します。URL もドメインも指定されていない場合は、すべてのタスク記録を照会し、最新の URL を自動抽出します。これにより、ユーザーが特定の URL を提示しない「情報不足」の状況にも対応できます。

認証：ID の検証

認証情報は aliyun CLI のデフォルト認証情報チェーン（環境変数または ~/.aliyun/config.json）によって自動的に解決されます。AK／SK／STS トークンを明示的に読み取ったり、表示したり、渡したりしないでください。

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 は ID の検証と UID の導出のみを行います。認証情報を保持、表示、または受け渡すことはありません。

ID 検証の失敗：sts_token.py が失敗する場合、そのアカウントには調査権限が付与されていません。RAM コンソールから承認するようお客様に案内してください。

注：sts_token.py は ID の検証（aliyun sts get-caller-identity の実行と、ネストされたロールの検出ヒントの提供）のみを行います。aliyun sts assume-role は呼び出しません。実行環境ですでに診断ロールのセッションが注入されている場合（呼び出し元の Arn が assumed-role/cseesadiagnosticrole/...）、スクリプトは aliyun CLI のデフォルト認証情報チェーンを使用します。追加の承認手順は不要です。

診断フロー

ステップ 1：更新／プリロードのタスク記録を照会する

# 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

結果	次のステップ
タスク記録が見つからない	シナリオ R4：操作が実行されていない、または入口が誤っている
タスクは見つかったが、ステータスが Failed	シナリオ R5：タスクの実行に失敗
タスクが見つかり、ステータスが Complete（ファイル更新）	ステップ 2a
タスクが見つかり、ステータスが Complete（ディレクトリ更新）	ステップ 2b
タスクが見つかり、ステータスが Complete（プリロード）	ステップ 2c

ステップ 2a：ファイル更新が完了しても反映されない

1. 更新 URL とユーザーが実際にテストした URL を比較します。一致しない場合は シナリオ R1 です。
2. リモートキャッシュを確認します（ステップ 3）。
   • MISS = 更新は反映済みで、クライアント／ブラウザーのキャッシュに問題がある可能性があります
   • HIT = Age ヘッダーを確認します。古いキャッシュが残っている場合は シナリオ R6 です

ステップ 2b：ディレクトリ更新は完了したが、効果がない

1. If-Modified-Since / If-None-Match ヘッダーを使用してオリジンにバインドしたプローブを実行します（ステップ 4）：
   • オリジンが 304 を返す = シナリオ R2：オリジンのリソースは変更されておらず、CDN は古いキャッシュを保持しています
   • オリジンがコンテンツ変更を伴う 200 を返す = 調査を続行します
2. リモートキャッシュの確認（ステップ 3）
3. 依然として異常がある = シナリオ R6（フォールバック）

ステップ 2c：プリロードは完了したが、効果がない

1. リモートキャッシュの確認（ステップ 3）：
   • HIT = プリロードの効果があります
   • MISS = 続行します
2. オリジンにバインドしたプローブを実行し、オリジンの Cache-Control／ステータスコードを確認します（ステップ 4）：
   • オリジンが no-cache / no-store / private を返す = シナリオ R3
   • オリジンが 200 以外のステータスを返す = シナリオ R3
   • オリジンがキャッシュヘッダー付きで正常な 200 を返す = シナリオ R6（フォールバック）

ステップ 3：リモートキャッシュの確認

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

注目する項目：X-Cache（HIT/MISS）、Age、Via、Cache-Control、Last-Modified、ETag。

HTTPS プローブが SSL/TLS ハンドシェイクエラー（curl の終了コード 35 など）で失敗した場合は、同じプローブを http:// スキームで再試行してください。HTTP 応答にも CDN キャッシュヘッダー（X-Cache/Age）が含まれます。

すべてのプローブコマンド（dig/curl/openssl）は scripts/cdn_probe.py 経由で実行する必要があります。シェルから dig や curl を直接実行してはいけません。

ステップ 4：オリジンにバインドしたプローブ（任意。エージェントが curl/dig で実行）

このスキルのスクリプトは、オリジンの設定を自動的に取得しません（すべてのスクリプトは CLI ベースの読み取り専用クエリです）。エージェントはまず、オリジンのアドレスを手動で取得する必要があります：

• 顧客にオリジンの IP／ドメインを尋ねる、または
• cdn_probe.py 'dig <accelerated domain>' を使用し、DNS の名前解決を手掛かりとして調べます。

すべてのプローブコマンド（dig/curl/openssl）は scripts/cdn_probe.py 経由で実行する必要があります。シェルから dig や curl を直接実行してはいけません。

次に、ステップ 3 の応答から Last-Modified と ETag を抽出し、オリジンにバインドしたプローブを実行します：

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>"'

注目する項目：オリジンが 304（リソース未変更）または 200（リソース変更）を返すかどうかです。Cache-Control、Pragma、Set-Cookie も確認してください。

オリジンのアドレスを取得できない場合は、このステップを省略し、ステップ 2／3 の結果から判断します。

ステップ 5：診断レポートの出力

references/report-template.md に従ってレポートを作成します。

障害シナリオ

R1：更新 URL の不一致

ファイル更新は完了しているのに、ユーザーには古いコンテンツが表示されます。送信された更新 URL が、アクセスした URL（プロトコル、パス、パラメーター）と一致していません。修正方法：正確な URL を再送信します。

R2：ディレクトリ更新（Expire モード）＋オリジン 304

ディレクトリ更新では「expire」モードが使用されます。CDN がオリジンに検証を行い、オリジンが 304（変更なし）を返すため、CDN は古いキャッシュを保持します。修正方法：「force delete」モードを使用するか、オリジンの Last-Modified/ETag を更新します。references/cache-rules.md を参照してください。

R3：オリジンの No-Cache ポリシーによるプリロード失敗

オリジンが no-cache / no-store / private / 200 以外のステータス / Set-Cookie を返します。CDN はオリジンのポリシーに従い、キャッシュしません。修正方法：オリジンの Cache-Control を調整するか、CDN コンソールで上書きします。references/cache-rules.md を参照してください。

R4：タスク記録なし

ユーザーは更新／プリロードが完了したと申告していますが、記録が見つかりません。修正方法：ドメイン／URL と操作の開始場所を確認します。

R5：タスク実行失敗

タスクのステータスが Failed です。修正方法：URL の形式、ドメイン設定、HTTPS 証明書、オリジンへの接続性を確認します。

R6：ノードキャッシュの同期ずれ（フォールバック）

タスクは完了し、オリジンも正常ですが、特定のノードは古いコンテンツを返します。修正方法：待ってから再試行するか、特定のノード IP にバインドして異常なノードを特定します。PE へのエスカレーションが必要です。

制約

• 読み取り専用操作：タスク記録の照会と診断のみを行います。更新／プリロード操作は決して送信しません。
• 解決策は証拠に基づく必要があります：検証済みの製品機能または公式ドキュメントのみに基づきます。
• 参照先：references/cache-rules.md で、CDN のキャッシュ優先順位ルールとステータスコードのキャッシュ動作を確認してください。

利用可能なスクリプト

スクリプト	用途
scripts/cdn_refresh_preload.py	更新／プリロードのタスクレコードを照会し、キャッシュヒット状況を確認します
scripts/cdn_probe.py	診断コマンド（curl/dig/openssl）をローカルで実行します
scripts/sts_token.py	呼び出し元の ID を確認し、デフォルトの認証情報チェーンを使用して UID を導出します

ローカルプロービング

外部へのプロービングコマンドはすべて、cdn_probe.py を介してローカルで実行します。すべてのプロービングコマンド（dig/curl/openssl）は scripts/cdn_probe.py を介して実行する必要があります。シェルで dig や curl を直接実行しないでください。

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

標準的なプローブ：DNS（dig）、HTTPS（curl -ksI）、SSL 証明書（openssl）、オリジンへの直接テスト（curl -ksI -H "Host: <CDN domain>"）。結果の振り分けについては、references/probe-result-routing.md を参照してください。

エラー処理

エラー	原因	解決方法
認証情報が見つかりません	デフォルトの認証情報チェーンが設定されていません	aliyun CLI のデフォルトの認証情報チェーンを設定します（aliyun configure を実行）
ID の確認に失敗しました（sts get-caller-identity）	サンドボックスの認証情報がないか、無効です	ランタイムの認証情報設定を確認します。デフォルトのチェーンが機能している場合、追加の認証は不要です
API エラー（Forbidden / InvalidParameter / Throttling / InternalError）	クエリに対して OpenAPI がエラーを返しました	エラーを記録し、該当するクエリをスキップして、残りの診断手順を続行し、レポートを出力します
API が空のタスクを返します	参照期間内に更新／プリロードがありません	--days を延長するか、ドメイン／URL を確認します
プローブコマンドがタイムアウトしました	ネットワークに到達できないか、コマンドがハングしました	再試行するか、ローカルネットワークへの接続を確認します

パッケージ化されたスクリプトで API エラーが繰り返し発生する場合は、aliyun cdn describe-refresh-tasks を CLI から直接実行して確認し、サービス側の障害かスクリプトの問題かを切り分けてください。