Azure代理開戶服務 Azure Blob 大文件分片上傳失敗處理

第一章：為什麼大文件分片上傳會失敗

在 Azure Blob 上傳大文件，分片上傳（Block Blob 的分塊上傳）通常是最穩的方案之一：你不必把整個文件一次性塞進記憶體，也能在失敗時重試部分分片。可是在實務上，失敗仍然常見。原因往往不是「分片機制壞了」，而是整個流程牽涉到：網路、SDK/程式碼、儲存帳戶限制、權限、以及你如何管理上傳狀態。

Azure代理開戶服務 當你看到錯誤時，很多人第一反應是「再重試一次」。但大文件的重試可能讓問題更糟：同一批 block 重複上傳、commit 狀態不一致、或因 blockId 規則錯誤導致 commit 失敗。更糟的是，有些錯誤其實是可恢復的（例如某個分片傳輸逾時），有些則是不可恢復的（例如認證失敗、封存到期、權限不足）。如果你不能先判斷類型，就容易陷入無限重試與無效成本。

要處理「分片上傳失敗」，你需要的是一套清晰的思路：先把錯誤分門別類，再針對不同類型採取策略；同時在流程設計上讓每次嘗試可對回、可恢復、可清理。

第二章：常見失敗類型與背後原因

Azure Blob 分片上傳失敗通常會以幾種形式出現。你可能遇到的是 HTTP 狀態碼、SDK 丟出的例外，或是 commit 階段失敗。下面按「你最可能遇到的狀況」整理原因與判斷方式。

2.1 網路抖動與逾時

大文件分片上傳的單次請求可能持續數秒到數十秒。若中間網路波動、代理閘道重置連線、或你的上傳機制啟用了過高的並行度，都可能導致逾時或連線被中止。這類錯誤多半在傳輸某個 block 時發生，而不是在 commit 時。

判斷線索：錯誤訊息常見包含「timeout」「connection reset」「temporarily unavailable」等字樣；或你在日誌中看到某個 blockId 對應請求失敗，但其他分片已完成。

2.2 權限與認證問題

若你使用 SAS、Shared Key 或 Azure AD 權限不足，可能在上傳某些分片時才暴露問題。尤其是 SAS 的有效期很短、或你在分片上傳流程中停頓過久，導致 SAS 到期。這類錯誤通常會在所有或多數請求中重現，重試也無法成功。

判斷線索：HTTP 401/403；或錯誤訊息包含「authentication failed」「authorization failure」「SAS expired」。

Azure代理開戶服務 2.3 分片大小、Block 數量與規則不匹配

Block Blob 有其限制：例如 block 數量上限、blockId 長度與編碼規則、以及 commit 使用的 blockList 必須完整且符合期望。若你切分邏輯導致 block 數量超限，或 blockId 生成方式不穩定（例如不同重試產生不同順序或不同內容），就可能 commit 失敗。

判斷線索：錯誤通常出現在 commit（Put Block List）或是回報說 blockId 格式無效、超出限制、或提交的 blockList 不一致。

Azure代理開戶服務 2.4 並行上傳的競態條件

你可能會把每個分片用多執行緒/非同步並行上傳。若程式碼沒有良好同步機制，可能出現：

• 同一個 blockId 被重複上傳但結果未正確追蹤，導致 commit 使用了錯誤的分片集合。
• 重試流程把「已成功上傳」的分片又標記為失敗，造成不必要的重傳或覆蓋。
• commit 提前觸發，尚未完成全部 block，上傳流程之間沒有鎖或狀態機。

判斷線索：錯誤偶發但與並行度高度相關；或日誌中 commit 發生時間早於最後一個 block 的成功回應。

2.5 儲存帳戶限制與配額

例如請求頻率過高、網路出站受限、或儲存帳戶在某些時間段面臨限制。你可能看到 429（Too Many Requests）或 5xx 錯誤。此類錯誤通常可透過節流（throttling）與指數退避重試改善。

判斷線索：狀態碼 429 或 503；並伴隨明顯的節流提示或重試建議。

第三章：先定位，再修復——建立可觀測的失敗分析

很多團隊在分片上傳失敗時，做法是「看錯誤訊息，抓幾個 retry 再看」。這會造成兩個問題：一是你很難知道失敗是否可恢復；二是你無法在不同檔案、不同大小、不同網路條件下比較結果。

你需要把上傳流程做成「可觀測」：每一個 blockId、每一次嘗試、每一次回應狀態、以及最终 commit 的 blockList，都要能追溯。

3.1 設計統一的上傳上下文

在程式層級先定義上傳上下文（Upload Context），至少包含：

• 文件唯一識別：例如你可以用檔案雜湊（或你系統的 uploadId）作為識別。
• Blob 名稱與目標容器。
• 切片策略：分片大小、總分片數、生成 blockId 的規則。
• 上傳狀態：每個 blockId 是否成功、成功時間、重試次數。
• commit 依賴：本次 commit 應提交的 blockId 列表。

有了這些資料，你才能在錯誤發生後判斷「到底失敗的是哪個分片」以及「commit 是否正確」。

3.2 記錄結構化日誌與相關性識別

不要只記錄文字錯誤。最少要能做到：同一個 uploadId 的所有事件可串起來。你可以在每條日誌中加入：

• uploadId、blobUri、blockId、分片序號
• 嘗試次數（attempt）與耗時（duration）
• HTTP 狀態碼（若有）、例外類型
• 是否由重試觸發

當你回看日誌時，才能回答：「是某個分片總是失敗嗎？」或「是只有在並行度上升時才失敗？」

3.3 建立錯誤分類：可恢復/不可恢復

你可以依據狀態碼或錯誤代碼建立基本分類：

• 不可恢復：401/403（權限/認證）；blockId 格式錯誤/超限（程式碼邏輯）。
• 可恢復：408（timeout）、429（節流）、5xx（暫時性服務問題）、網路錯誤（如 connection reset）。

對不可恢復錯誤，應立即停止並回報；對可恢復錯誤，才進入重試策略。

第四章：設計一個可恢復的分片上傳流程

真正穩的分片上傳，不只是重試，而是「可恢復」。可恢復意味著：當你中途失敗或重啟程式，仍能繼續而不必從頭開始；或至少不會導致 commit 使用不一致的 block 集合。

4.1 上傳階段：只做 Put Block，別急著 commit

最佳實務是把流程明確拆成兩段：

• 階段 A：對每個分片執行 Put Block（或等效的 UploadBlock）。只要完成某 block，就把它標記為已完成。
• 階段 B：當所有 block 都完成後，執行 Put Block List（commit）。

這樣你能清楚知道失敗發生在哪一段。若失敗出現在階段 A，你只需補上缺失的 block；若失敗出現在階段 B，你要檢查 blockList 與 blockId 規則，而不是盲目重傳所有分片。

4.2 blockId 生成要穩定且可復現

blockId 的目的是讓 Azure 在 commit 時知道要使用哪些 block。你必須確保同一個 uploadId + 相同分片序號，blockId 永遠一致。常見做法是：

• 用固定格式生成：例如 prefix + 序號，並做必要的編碼（Base64 等）。
• 序號只依賴切分邏輯，不依賴執行時間或記憶體狀態。

如果你的 blockId 每次重啟都不同，那 commit 就很難復原，因為你會上傳了新的 block，卻找不到舊的。

4.3 寫入狀態到外部持久層

你不能只把成功列表存在記憶體。實務上通常會把上傳狀態寫到外部持久層（例如資料庫、快取帶持久化、或檔案系統）。狀態內容至少包含：

• uploadId、blobName
• Azure代理開戶服務 分片大小、總分片數
• 每個分片序號是否完成、完成時間、hash（若需要驗證）
• Azure代理開戶服務 最後一次 commit 狀態

這樣你才能在程式重啟後查出「還缺哪幾片」，繼續補齊。

4.4 補齊策略：只重傳缺失 block

當某次上傳中途失敗，你應做兩件事：

• 更新狀態：標記哪些 block 成功、哪些 block 失敗。
• 在下一次嘗試時，根據狀態只補缺失 block。

這樣可以把成本降到最低，也降低對網路與服務的壓力。

4.5 並行度管理：從「快」轉成「穩」

並行度是雙面刃。並行度高能提高吞吐，但也更容易觸發節流、增加逾時機率、以及引入競態。建議採取「可調」並行度：

• 先用保守並行度（例如 4～8，視網路與機器而定）。
• 遇到 429/5xx 時降低並行或拉大退避。
• 以每個 block 的實際耗時作為節奏調整依據。

並行上傳仍然可以很可靠，但你必須確保 commit 不會在所有 block 完成前觸發。

第五章：重試策略與退避設計（不要只會固定次數重試）

重試不是越多越好。針對不同錯誤，你要使用不同策略。重試的核心目標是：在可恢復錯誤上提高成功率，在不可恢復錯誤上避免浪費。

5.1 指數退避 + 抖動（jitter）

對可恢復錯誤（429、5xx、逾時），建議使用指數退避。基本形式是：

• 第一次等待 1s，第二次等待 2s，第三次等待 4s……
• 每次加上一點抖動，避免大量客戶端同步重試造成「集體擁塞」。

抖動可以是 0～500ms 或根據百分比變動。

5.2 分片重試與總體上限

你可以為每個 block 設定重試上限（例如 3 次或 5 次），同時為整個上傳流程設定總耗時或總重試次數上限。避免「某個 block 永遠不通」拖垮整個流程。

Azure代理開戶服務 當超過上限，你應回報清楚：失敗的 blockId 是哪一片、嘗試過幾次、最後錯誤是什麼。

5.3 針對 429/節流的節奏調整

如果你收到 429，固定重試往往只會讓事情更糟。你可以加入更明確的節流策略：

• Azure代理開戶服務 降低並行度
• 增大等待時間
• 必要時停一段時間再繼續補齊

如果錯誤訊息包含 Retry-After，你應尊重該值。

5.4 避免「無限重試」造成雙重上傳與 commit 錯亂

當你對 block 做重試時，blockId 若固定，通常重試只是覆蓋同一個 block 內容（取決於實作方式）。但若你的切片內容在重試期間改變（例如檔案本身變更、或你切分策略不一致），那就會造成 commit 的內容不符合預期。

因此你要在開始上傳時鎖定來源文件（例如先取得檔案大小與雜湊，確保後續分片一致），或至少記錄來源的雜湊，用於重啟後驗證。

第六章：commit 失敗怎麼辦——讓提交階段可控

很多人遇到問題只看 Put Block 的失敗，其實 commit 失敗同樣常見。commit 失敗通常意味著：blockList 不正確、blockId 集合不完整、順序或格式不符合規則、或上傳期間資料狀態被污染。

6.1 commit 前的檢查清單

在執行 commit 前，你應做一些基本檢查：

• 確認「完成的 block 數量」等於「預期的分片數量」。
• 確認每個完成 block 都使用同一個 uploadId 的 blockId 生成規則。
• 確認沒有重複或缺漏（例如序號 0..N-1 是否全覆蓋）。
• 確認 blockList 組裝使用的清單來源是持久狀態或可靠記憶體，而非被競態影響的中間結果。

這些檢查能在「commit 前」就阻止很多問題，讓錯誤更可預測。

6.2 commit 失敗時的處理策略

當 commit 失敗，第一步仍是分類：

• 若是認證/權限（401/403），通常不可恢復：需要更新憑證或權限。
• 若是 blockList 格式或超限，通常是不可恢復：需要修正切分策略或 blockId 生成方式。
• 若是暫時性服務錯誤（5xx）或網路錯誤，可能可恢復：重試 commit，但必須確保 blockList 不變且完整。

對可恢復 commit 失敗，你可以重試 commit，但在重試前不要重新上傳所有分片；只要 commit 所用的 blockList 確認無誤，就能降低成本。

6.3 何時應該放棄並清理

當上傳流程長時間失敗（例如多次 commit 都失敗，或某些 block 永遠無法完成），你需要有清理機制：避免殘留未 commit 的 block 造成未來狀態混亂。你可以：

• 保留上傳狀態，標記為 failed。
• 選擇性清理已上傳但未 commit 的 block（視你實作能力與代價）。
• Azure代理開戶服務 提供一個可重啟的狀態，使下一次上傳能從乾淨狀態開始。

清理不是為了「省空間」而已，更是為了「讓系統行為一致」。

第七章：避免重複上傳與資源浪費

分片上傳常在工程上帶來一個副作用：重試與補齊可能導致重複上傳同一批 block，進而浪費帶寬與儲存交易成本。你不一定要做到絕對避免，但要做到「可控、可估算、可回收」。

7.1 使用 uploadId 與版本化 blob 名稱

如果你的來源文件可能變更（例如同名檔案被更新），就會產生一致性問題。你可以用 uploadId 或文件版本生成 blob 名稱的一部分，讓每次上傳有自己的目標。這樣即使之前的上傳失敗重試，也不會覆蓋到新內容。

如果你必須維持固定 blob 名稱，那就要在 commit 前確認文件一致性（大小、雜湊）並避免來源文件在上傳過程改變。

7.2 對已完成 block 做去重追蹤

狀態持久化後，你就能在重試時只補缺失 block。進一步，如果你有能力對分片做雜湊（例如對每片計算 hash），你可以把 hash 存進狀態，用於驗證來源內容是否一致。雜湊計算會增加 CPU，但對可靠性要求高的系統很值得。

7.3 Transaction 成本與節流的平衡

並行越高，交易越多，越容易觸發 429 或網路不穩。你需要把「目標成功率」和「可接受的成本」設定清楚。例如你可以設定：

• 允許平均重試次數不超過某個值
• 在 429 出現時自動降低並行
• 超過總耗時則標記為失敗並要求人工/系統介入

這些策略讓系統在壓力下仍能保持可預期。

第八章：監控與告警：讓你在失敗前就知道趨勢

Azure代理開戶服務 處理分片上傳失敗，不只是在錯誤發生後補救；更重要是建立早期預警。你可以從三個層面監控：應用層、傳輸層、以及儲存層。

8.1 應用層指標

至少追蹤：

• 上傳成功率（按文件大小分組）
• 平均/分位數耗時（p50、p95）
• 每個 block 平均重試次數
• commit 成功率與 commit 失敗類型分布

若你看到成功率突然下降，或重試次數在某個時間段飆升，就能提前定位是網路、憑證、還是某次部署引入了 bug。

Azure代理開戶服務 8.2 傳輸層與環境因素

若你的服務在特定機房或雲區發生問題，你需要能定位到：是所有環境還是某些節點。你可以追蹤：

• 每個機器/Pod 的錯誤率
• 代理、網關、NAT 的連線重置數
• 可用帶寬與延遲

有時候真正原因不是 Azure，而是你自己的網路元件。

8.3 儲存層錯誤分布與節流訊號

監控 429、5xx 的比例與出現時段。若 429 集中於某些時間，你可能需要調整並行或調整上傳節奏。

同時確認你的憑證是否有到期問題：若失敗集中在某個時間點（例如憑證有效期到），你需要縮短分片流程或刷新憑證。

第九章：實務範例——一個穩健的失敗處理流程應該長什麼樣

假設你有一個上傳服務，需要把大檔案上傳到 Azure Blob。你可以用下面這種「可落地」的流程設計，讓失敗處理變得清楚。

9.1 流程概覽

• 建立 uploadId（固定且可持久化）。
• 計算文件基本資訊：大小、必要時的雜湊（或至少保存大小）。
• 切分文件為固定分片大小，生成每個分片序號對應的 blockId（規則固定可復現）。
• 從持久化狀態讀取：哪些分片已完成。
• 並行上傳缺失分片：針對可恢復錯誤重試（指數退避+抖動），不可恢復則立即中止並回報。
• 上傳完成後，組裝完整的 blockList。
• 執行 commit（Put Block List）。若可恢復錯誤則按 commit 類別重試；不可恢復則停止並回報原因。
• commit 成功後標記為 completed，並可選擇清理狀態與未 commit 殘留。

9.2 針對不同錯誤的分流

• 401/403：立即停止，刷新憑證或修正權限。
• 429/5xx：暫停一段時間、降低並行、用指數退避重試，並記錄是否持續。
• timeout/connection reset：針對該分片重試，並檢查你的並行度與網路環境。
• blockId 格式/超限：停止並回報配置問題（修正切分策略與 blockId 規則）。

9.3 回報與運維

一個成熟的系統不只「把錯誤吞掉然後重試」，而是要把問題交給運維快速處理。回報內容應至少包含：

• uploadId、blobName、文件大小
• 失敗類型（分片上傳 or commit）、失敗的 block 序號或 blockId（若適用）
• 重試次數與最後一次錯誤
• 你當時的並行度與切分大小（用於快速比對）

有了這些資訊，才不需要靠人猜。

第十章：常見坑位與自我檢查清單

最後把最常見、最容易踩的坑整理成清單。你可以在上線前檢查。

10.1 程式碼一致性坑

• blockId 生成依賴非穩定因素（例如隨機數、執行時間）。
• Azure代理開戶服務 重啟後切分策略不同（分片大小、總分片數變了）。
• commit 使用的 blockList 不是完整且未做去重。
• 並行上傳導致狀態競態（commit 早於完成）。

10.2 上傳策略坑

• 重試策略過於粗糙（所有錯誤都重試，包含不可恢復錯誤）。
• 固定並行度、不考慮節流與錯誤回饋。
• 沒有持久化狀態，導致重啟從頭開始。

10.3 運維可觀測坑

• 沒有 uploadId/相關性識別，日誌無法串起來。
• 只記錄 commit 成功或失敗，沒有記錄是哪個 block 失敗。
• 沒有監控成功率與重試次數的分位數，僅靠平均值掩蓋問題。

結語：把失敗處理做成系統能力

Azure Blob 大文件分片上傳失敗的本質，是「分散的請求在真實網路條件下遇到不確定性」。你不能指望一次就完美，但也不必把重試當作唯一解法。真正的解法是：分類錯誤、可觀測、可復現、狀態可持久化、重試有節奏、commit 有檢查，最後再用監控把趨勢提前告訴你。

當你的流程做到這些，失敗就不再是偶然事件，而是被吸收進設計裡的一部分。你會發現：同樣的網路波動，系統仍能穩定完成上傳；同樣的錯誤，也能被快速定位並修復。