CDN：緩衝排障指南

排查步驟：

1. 確認配置已生效：新增或修改緩衝規則後，規則狀態會顯示配置中，表示配置正在下發到全網節點，通常幾分鐘內變為成功。配置未生效期間不要急於驗證。

2. 確認新規則已對目標資源生效：新規則只對新請求生效，已緩衝在節點上的資源仍按舊策略提供服務直至到期。如需立即生效，請先執行重新整理預熱清除舊緩衝。

3. 檢查規則匹配優先順序：請求同時命中多條規則時只有一條生效，預設權重高者優先；權重相同時通常建立時間晚的規則優先（以控制台實際說明為準）。請確認目標路徑命中的規則權重最高，例如具體目錄（/static/）的權重應高於根目錄（/）的規則。

4. 檢查來源站點回應標頭是否禁止緩衝：若來源站點返回 Cache-Control: no-cache、no-store、max-age=0 或 Pragma: no-cache，CDN 預設遵循來源站點指令，不同指令對回源行為的影響見下方表格。可在緩衝規則中開啟忽略來源站點不緩衝標題強制按控制台規則緩衝，或調整來源站點配置，對靜態資源去掉不緩衝指令。

5. 檢查 URL 參數處理方式：若 URL 帶參數且未開啟忽略參數，不同參數的 URL 會被視為不同資源，導致命中率下降。可開啟忽略參數或保留指定參數。

6. 檢查是否誤配置了根目錄不緩衝：若根目錄 / 的規則權重最高且到期時間為 0 秒，所有請求都會回源。

上述第 4 步中，不同的來源站點不緩衝指令對回源行為的影響差異較大，請根據實際指令判斷來源站點壓力：

到期時間設為 0 的目的是每次請求都回源擷取最新內容。若仍返回舊內容，排查步驟：

1. 排除瀏覽器本機快取：清除瀏覽器緩衝或使用無痕模式重新測試，確認是節點返回舊內容而非瀏覽器緩衝。

2. 清除配置修改前的存量緩衝：修改配置前已緩衝的資源不會自動清除，需通過重新整理預熱提交 URL 重新整理。

3. 檢查來源站點自身是否有緩衝：來源站點伺服器（如 Nginx 緩衝、應用程式層緩衝）可能返回舊內容，CDN 回源拿到的就是舊資料。

4. 確認配置已全網生效：規則狀態需為成功，配置下發到全部節點需要幾分鐘。

5. 確認請求命中了預期節點：不同電訊廠商、不同地區的使用者可能命中不同節點。可在多個地區分別測試，或結合 CDN 即時日誌、響應中的節點 IP 進一步定位。

1. 檢查配置完整性：自訂 Cache Key 通常需要按請求特徵（如 User-Agent）設定規則條件，再分別添加不同的 Cache Key 變數。請確認已正確識別移動端和 PC 端的請求特徵，且兩條規則的匹配條件不會互相覆蓋。

2. 等待生效：配置提交後需等待 5～10 分鐘全網同步。

3. 重新整理舊緩衝：配置修改前已按舊 Cache Key 緩衝的資源不會自動失效，需提交重新整理（建議使用目錄重新整理）。

4. 用戶端驗證：清除瀏覽器緩衝後重試，檢查回應標頭中的 X-Cache 是否為 MISS。

5. 使用真實終端測試：使用不同終端的真實 User-Agent 發起請求，而非僅切換瀏覽器視窗尺寸（瀏覽器類比的 UA 可能與真實裝置不同）。

問題原因：當來源站點響應中包含 Set-Cookie 回應標頭時，CDN 預設不會緩衝該響應，導致快取命中率為 0。

推薦方案（按優先順序）：

• 來源站點側治理（推薦）：讓來源站點對靜態資源（圖片、CSS、JS、字型等）停止返回 Set-Cookie。這是根本解決方案，既不影響動態介面的會話管理，又能提升快取命中率。

• CDN 側按路徑刪除：若來源站點無法調整，可在 CDN 側僅對靜態資源路徑（如 /static/、*.css、*.js）刪除該回應標頭，避免影響動態介面。

CDN 側按路徑刪除的操作步驟：

1. 登入 CDN 控制台，在網域名稱管理中找到目標網域名稱，單擊管理。

2. 在網域名稱詳情頁左側導覽列中，單擊回源配置，進入修改入站回應標頭頁簽。

3. 單擊添加，將規則條件限定在靜態資源路徑，回應標頭操作選擇刪除，回應標頭名稱填寫 Set-Cookie。

4. 配置完成後，通過重新整理預熱清除已緩衝的舊響應，使新規則生效。

如果配置後快取命中率仍未提升，請檢查：緩衝規則中是否已開啟忽略來源站點不緩衝標題；是否開啟了忽略參數，避免同一資源因查詢參數不同而被拆分為多個緩衝對象。CDN 預設緩衝規則請參見配置CDN緩衝到期時間。

命中率過低意味著大部分請求都要回源，公網鏈路不穩定會讓加速效果變差，同時給來源站點帶來負載壓力。排查步驟：

1. 檢查來源站點是否返回不緩衝指令：這是命中率低和來源站點頻寬跑滿最常見的原因。若來源站點返回 Cache-Control: no-cache、no-store、max-age=0 或 Pragma: no-cache，CDN 會遵循來源站點指令不緩衝，每次請求均回源。可在緩衝到期時間配置中開啟忽略來源站點不緩衝標題強制按控制台規則緩衝，或調整來源站點配置。

2. 檢查緩衝規則是否誤配置：確認根目錄 / 的緩衝到期時間未被配置為 0 秒且權重最高，否則所有請求都會回源。

3. 檢查 URL 是否帶可變參數：URL 中問號後的參數變化會讓同一份內容被視為不同資源。開啟忽略參數後可將這類請求合并為同一緩衝對象，詳見下一條。

4. 區分動靜資源分別配置：為靜態資源（圖片、CSS、JS、字型等）設定較長緩衝時間（如 30 天），為動態內容（如 PHP、JSP、API 介面）設定到期時間 0 秒。

5. 大檔案情境開啟 Range 回源：對視頻、安裝包等大檔案確保已開啟 Range 回源，避免每次請求都回源擷取完整檔案。開啟前請確認來源站點支援 Range 請求（即能夠返回 206 Partial Content），來源站點不支援時開啟該功能可能導致請求失敗或返回異常內容。

6. 檢查業務 QPS 是否過低：節點磁碟空間有限，訪問頻率低的資源會被熱點資源汰換掉從而造成回源。QPS 只有十幾的網域名稱建議通過重新整理預熱提交預熱任務，保證資源常駐節點。

問題現象：頁面整體命中率很低，檢查回應標頭發現主請求的 X-Cache 為 MISS，但頁面內單個檔案的 URL 回應標頭為 HIT。

問題原因：URL 中攜帶了隨請求變化的參數（如時間戳記），未開啟忽略參數功能時，CDN 將每個參數不同的 URL 視為獨立資源，無法複用緩衝。例如 http://example.com/movie/res/ArrowScene.ccbi?_t=1699999999 中 ?_t= 後的數值每次都不同。

解決方案：在 CDN 控制台開啟忽略參數功能，開啟後參數部分不參與緩衝對象的計算，同一資源的不同參數請求會命中同一份緩衝。若業務確實依賴部分參數，可選擇保留指定參數，僅忽略無關參數。

命中率短期波動或持續下降，常見原因如下：

• 執行過重新整理快取作業：手動或自動重新整理會清除節點緩衝，短時間內命中率下降屬正常現象，隨著資源重新緩衝通常在數小時內自動回升。

• 頻寬突增：短時間內流量大幅上漲會帶來大量首次請求，回源增多導致命中率下降。

• 大量訪問新內容：節點頻繁請求首次訪問的新資源時必然回源，表現為命中率走低。

• 調整過緩衝規則：修改緩衝策略（尤其是縮短到期時間）會影響命中率。

• URL 帶可變參數：參數變化使同一內容被拆成多個緩衝對象。

• 緩衝到期時間設定不合理：未按資源更新頻率區分配置，導致緩衝過早失效。

已在 CDN 配置跨域回應標頭，但用戶端仍報跨域錯誤且回應標頭中看不到該欄位，可能原因與處理方法如下：

• 配置未生效：確認配置已儲存且規則狀態為成功。

• 配置尚未下發完成：出站回應標頭配置修改後一般在 5 分鐘內生效，請等待後重試。該配置隻影響用戶端收到的響應，不影響節點的緩衝行為，因此無需重新整理或重新預熱（預熱不會改變已緩衝資源的回應標頭）。

• 來源站點回應標頭與 CDN 配置衝突：來源站點也返回了跨域回應標頭時可能相互覆蓋。建議統一來源站點和 CDN 的跨網域設定，或在修改出站回應標頭中將是否允許重複設為不允許，使 CDN 配置的值覆蓋來源站點返回的值。

• 瀏覽器緩衝了舊響應：清除瀏覽器緩衝或使用無痕模式測試。

• 泛網域名稱配置方式不支援：開啟跨域驗證後僅支援配置單個泛網域名稱，或將多個精確網域名稱用逗號分隔，不支援用逗號分隔多個泛網域名稱。

• Access-Control-Allow-Origin 值與請求 Origin 不一致：瀏覽器報錯 "The 'Access-Control-Allow-Origin' header has a value that is not equal to the supplied origin" 時，說明返回的允許源與實際請求源不匹配。可通過以下方式解決：

  • 在修改出站回應標頭中重新設定 Access-Control-Allow-Origin，是否允許重複選擇不允許，使新值覆蓋來源站點返回的舊值。

  • 業務允許時，可將該回應標頭配置為動態返回請求中的 Origin 值，使允許源始終與請求源一致。配置完成後等待約 5 分鐘生效即可，無需重新整理緩衝。

跨域資源共用的配置方法請參見配置跨域資源共用。

• 確認請求經過了 CDN 節點：檢查網域名稱 DNS 解析是否只保留 CDN 的 CNAME 記錄，刪除了 OSS 等來源站點的直接解析記錄。流量直連來源站點時，CDN 配置的回應標頭不會生效。

• 確認配置的是出站而非入站回應標頭：入站回應標頭僅作用於來源站點到 CDN 節點之間的通訊，終端使用者不會感知。如需影響終端使用者收到的響應，請配置修改出站回應標頭。

• 確認來源站點是否返回了該回應標頭：CDN 預設透傳來源站點回應標頭，來源站點未返回時 CDN 也不會返回。若希望無論來源站點是否返回都強制攜帶該回應標頭，請在修改出站回應標頭中選擇添加操作。

• Content-Type 未生效時檢查來源站點中繼資料：若來源站點（如 OSS）在上傳檔案時未指定正確的 Content-Type，回源擷取的中繼資料會與預期不符。請檢查來源站點上傳檔案時的 Content-Type 設定。

• 確認已等待配置生效：出站回應標頭配置修改後一般在 5 分鐘內生效，且僅影響用戶端收到的響應、不影響節點的緩衝行為，因此無需重新整理或重新預熱（預熱不會改變已緩衝資源的回應標頭）。

出站回應標頭的配置方法與參數說明，請參見修改出站回應標頭。

問題原因：來源站點返回的 Content-Type 回應標頭未正確指定字元編碼，用戶端按錯誤編碼解析內容導致頁面亂碼。

方案一（推薦，從源頭修複）：修改來源站點配置，確保返回 HTML 時 Content-Type 包含正確的字元編碼聲明。

方案二（在 CDN 側改寫）：

1. 登入 CDN 控制台，在網域名稱管理中找到目標網域名稱，單擊管理。

2. 在修改入站回應標頭中添加規則，將匹配路徑下的 Content-Type 改寫為 text/html; charset=utf-8。

3. 配置完成後，通過重新整理預熱重新整理該路徑下的緩衝資源，使節點按正確的類型重新緩衝。

可通過修改出站回應標頭功能配置 Content-Disposition 回應標頭來控制視頻的下載或預覽行為：設定為 attachment; filename='video.mp4' 時，使用者訪問該資源將觸發下載；設定為 inline 時，資源將在瀏覽器中直接預覽。

如果配置不生效，請檢查以下事項：

1. 規則引擎匹配條件：確保規則的匹配條件針對的是 URI 路徑（如包含 /video-origin/20260414），而非僅匹配查詢參數（query string）。規則引擎通過識別使用者請求中的路徑資訊來決定配置是否生效。

2. 節點已緩衝舊回應標頭：Content-Disposition 直接影響瀏覽器行為，若配置後 5 分鐘仍未生效，請先排除瀏覽器本機快取（使用無痕模式重試），並確認規則狀態為成功。

問題原因：來源站點首次返回 JS 檔案時，Content-Type 回應標頭被錯誤設定為 text/html。CDN 將該錯誤類型緩衝後，瀏覽器按 text/html 解析 JS 檔案，導致亂碼或執行異常；第二次訪問時，由於來源站點已修正 Content-Type 或 CDN 重新回源擷取了正確類型，頁面恢複正常。

解決方案：

1. 在 CDN 控制台的修改入站回應標頭中添加規則，匹配 JS 檔案路徑（如 *.js），將 Content-Type 強制替換為 application/javascript。

2. 配置完成後，通過重新整理預熱重新整理該 JS 檔案的緩衝，使新規則立即生效。

問題原因：節點上緩衝的檔案長度與來源站點實際內容不一致，或來源站點返回了異常的 Content-Length 回應標頭。最常見於來源站點更新了視頻檔案但 CDN 仍返回舊版本緩衝。

解決方案：

• 在重新整理預熱頁面提交該視頻 URL 的重新整理任務，清除節點上的舊緩衝。

• 若來源站點為 OSS，可在 OSS 控制台開啟CDN 緩衝自動重新整理功能，來源站點檔案更新後自動觸發 CDN 緩衝重新整理。

• 檢查來源站點穩定性，確保不會間歇性返回異常的 Content-Length，可通過多次使用 curl -I 直連來源站點對比驗證。

正常。視頻播放器和下載工具通常使用 Range 請求分段載入資源，每次只請求部分內容，服務端返回 206 Partial Content。即使命中 CDN 緩衝，返回的也是 206 狀態代碼，不屬於異常。

費用說明：只要用戶端向 CDN 發起請求並接收資料，無論是否命中緩衝，均計入 CDN 流出流量費用。

最佳化建議：確保已開啟 Range 回源，使節點能按需從來源站點拉取分區並緩衝，提高後續分段請求的命中率；同時在來源站點配置合理的 Cache-Control（如 max-age=86400），利用瀏覽器本機快取減少重複請求。

問題原因：圖片、CSS、JS 等靜態資源已命中緩衝並正常加速，但首頁（根路徑 /）通常沒有配置緩衝規則，每次訪問都要回源擷取，載入速度完全取決於來源站點處理耗時。

解決方案：為加速網域名稱添加根目錄的緩衝到期時間規則，讓首頁內容也被節點緩衝：

1. 在緩衝到期時間頁簽下添加規則，類型選擇目錄，地址填寫 /。

2. 到期時間根據首頁內容的更新頻率設定，例如 30 秒至數分鐘。

3. 調整規則權重，使根目錄規則的權重低於具體路徑規則（如 /static/），避免覆蓋靜態資源的緩衝規則。

配置生效後首頁內容將由節點直接返回，不再每次回源。詳細配置說明請參見配置CDN緩衝到期時間。

問題原因：節點未命中緩衝時會轉寄用戶端請求並在要求標頭中追加特定參數（如 Via、X-Forwarded-For），部分來源站點會根據這些參數返回不同響應。例如來源站點判斷要求標頭中是否含有 Via 來識別代理請求，從而做出不同處理。

排查步驟：

1. 定位導致差異的要求標頭：先直接存取來源站點記錄返回結果，再用 curl 手動添加 CDN 會追加的要求標頭訪問來源站點，逐個替換測試，直到複現出不一致的結果。

2. 調整來源站點配置：檢查來源站點 Web 服務器對該要求標頭的處理邏輯，按業務需求修改。

3. 或在 CDN 側刪除該要求標頭：若該要求標頭對業務無實際作用，可在 CDN 控制台配置中刪除。

問題原因：來源站點對檔案進行了同名更新（修改了檔案內容但未修改檔案名稱），在緩衝到期之前 CDN 節點仍直接返回舊緩衝，導致下載到的檔案與來源站點不一致。

解決方案：

1. 方案 1：手動重新整理緩衝。來源站點同名更新後，在重新整理預熱頁面提交 URL 重新整理（適合單個資源、生效較快）或目錄重新整理（適合整個目錄、範圍廣但會短暫增加來源站點回源壓力）。

2. 方案 2：強制重新整理繞過 304。當來源站點檔案內容變更但 Last-Modified 時間戳記未更新時，CDN 節點通過條件請求（If-Modified-Since）校正後收到 304 Not Modified，判斷檔案未變更而不更新緩衝，此時普通 URL 重新整理可能不生效。需調用 RefreshObjectCaches API 並將 Force 參數設為 true 強制回源拉取完整檔案。

3. 方案 3：版本化命名（推薦的長期方案）。建議來源站點避免同名更新，改為給檔案名稱添加版本號碼或雜湊值（如 style.v2.css、app.abc123.js），或通過 URL 參數攜帶版本標識（如 ?v=20260828）。

4. 方案 4：OSS 來源站點開啟自動重新整理。如果來源站點是 OSS，可在 OSS 控制台開啟CDN 緩衝自動重新整理，當 OSS 來源站點出現 Object 同名更新時，會自動調用 CDN 的重新整理介面重新整理對應的 URL。

Web 服務器返回 HTTP 404 狀態代碼時會自動跳轉到 404 頁面，說明請求的資源在來源站點上不存在。常見原因包括：URL 建置規則變更、檔案被更名或移動位置、連結拼字錯誤、請求的連接埠無法訪問網站、Web 服務擴充鎖定策略或 MIME 對應策略阻止了本請求。

若訪問的頁面中包含多個資源、僅部分資源不可訪問，則頁面不會整體跳轉到 404 頁面。自訂錯誤頁面的配置方法請參見配置自訂頁面。

為 403 狀態代碼配置自訂錯誤頁面時，如果直接在錯誤版面設定中配置跳轉連結，可能出現網域名稱跳轉或迴圈重新導向。請改用以下方式：

1. 通過重寫訪問URL功能配置，而非直接在自訂錯誤頁面中設定跳轉連結。

2. 將待重寫的 Path 設定為 /，並將目標路徑指向正確的 403 靜態頁面地址（例如 /error/403.html）。