部署失敗疑難排解與根因分析

部署失敗故障排除 (Deployment failure troubleshooting) 是 DevOps 實務中最頻繁的任務，也是 DOP-C02 測試最多的情境之一。網域 5.3 的每個題目背景都是一種變體：「部署失敗了，以下是症狀，請問根本原因是什麼，該如何修復？」多份社群學習報告指出，這個網域是許多考生失分的地方，因為故障排除要求你了解每項部署服務的失敗面 —— 包括 CodePipeline, CodeBuild, CodeDeploy, CloudFormation, ECS, Lambda 別名流量轉移, Auto Scaling 群組部署, Elastic Beanstalk —— 以及每項服務使用的回滾訊號和最常發生故障的生命週期掛鉤 (lifecycle hooks)。

本指南假設你已了解基礎 CI/CD 概念（建置 → 測試 → 部署）和 CodePipeline 的基本結構。它專注於 DOP-C02 的實作深度：CodePipeline 失敗動作診斷（暫時性 vs 永久性，重試策略）、CodeBuild buildspec.yml 階段失敗 (install, pre_build, build, post_build, finally)、CodeBuild 報告與結束代碼、CodeDeploy appspec.yml 生命週期掛鉤 (BeforeInstall, AfterInstall, ApplicationStart, ValidateService, BeforeAllowTraffic, AfterAllowTraffic, BeforeBlockTraffic, AfterBlockTraffic)、CodeDeploy 基於警示的回滾、藍綠部署 vs 就地部署的失敗模式、具備監控期間與警示的 CloudFormation 回滾配置、用於部署前驗證的 CloudFormation 掛鉤 (hooks)、ECS 部署斷路器 (deployment circuit breaker) 以及輪詢 vs 藍綠的失敗語義、具備流量前/後掛鉤的 Lambda 別名流量轉移、作為部署驗證測試的 CloudWatch Synthetics 金絲雀 (canaries)，以及回滾訊號層級（警示觸發 > 結束代碼 > 逾時 > 手動）。網域 5.3（排查系統與應用程式故障）是此內容的核心，且與網域 1.4 有顯著重疊。

為什麼部署失敗故障排除在 DOP-C02 中很重要

DOP-C02 中 SDLC 自動化佔 22%（所有網域中最高），事故回應佔 14%。兩者合計佔考試內容的 36%，而它們之間的重疊部分正是部署失敗。考試期望你能夠：(1) 識別失敗的組件，(2) 找到正確的日誌或訊號，(3) 確定根本原因，(4) 開出即時修復與長期預防的處方。一個典型的題目背景可能是：「向 50 個 EC2 執行個體進行 CodeDeploy 就地部署，其中 12 個執行個體顯示『BeforeInstall』生命週期事件逾時，8 個執行個體在『AllowTraffic』時被負載平衡器健康檢查標記為失敗，其餘 30 個執行個體處於掛起狀態。CodeDeploy 回報部署狀態為失敗。團隊需要即時的回滾動作以及根本的修復方案。」錯誤答案是「重新部署」。正確答案則是對每個批次分別進行診斷：卡在 BeforeInstall 通常是代理程式或指令碼問題（檢查 /opt/codedeploy-agent/deployment-root/.../scripts/... 日誌）；卡在 AllowTraffic 是目標群組健康檢查失敗（驗證健康檢查路徑返回 200，安全群組允許 ALB SG，容器啟動時間符合取消註冊延遲）；掛起的執行個體將不受影響，因為部署已處於失敗狀態。考試測試的就是這種分級診斷 (triage) 的本能。

社群報告特別指出，buildspec.yml 與 appspec.yml 語法是必背內容，因為考試會顯示部分 YAML 並要求你識別損壞的階段或掛鉤。他們還指出 ECS 的部署斷路器和 CodeDeploy 的基於警示的回滾是 DOP-C02 引入的高頻主題，早期的 C01 準備材料可能會遺漏。

白話文解釋部署失敗故障排除

部署失敗的面非常廣，根本原因層級可能讓人感到不知所措。以下三個類比將其轉化為診斷本能。

類比 1：餐廳廚房出餐失敗

一道新菜傳到了出餐口，出餐員 (expediter) 拒絕了它 (部署未通過金絲雀測試)。失敗源自哪裡？診斷需要沿著生產線往回走：是擺盤錯誤 (CodeDeploy AfterInstall 掛鉤)，還是醬汁不對 (BeforeInstall 指令碼未準備好環境)，還是蛋白質未煮熟 (實際的應用程式二進位檔案)，還是點單輸入錯誤 (CodePipeline 來源動作發送了錯誤的成品)，或者是上游準備錯誤 (CodeBuild pre_build 階段)。每次交接都有清晰的記錄；出餐員的工作是按順序往回查。警示是經理收到的第一個客戶投訴 (基於警示的回滾)；斷路器是廚師說「我們已經連續燒焦了 3 盤，停止送單」 (ECS 部署斷路器自動回滾)。金絲雀是經理在每批菜出餐前先嚐一盤 (CloudWatch Synthetic canary 在轉移流量前執行)。生命週期掛鉤是出餐口的標準化檢查：每盤菜在離開前都要經過擦邊、裝飾檢查、溫度探測、拍照存證 —— 漏掉任何一項檢查，這盤菜就是失敗。

類比 2：飛機起飛前檢查清單級聯

在飛行之前，機組人員會執行多階段的起飛前檢查清單：維修簽署 (CodeBuild build 階段)、加油 (CodeBuild post_build 成品上傳)、登機 (CodeDeploy BeforeInstall)、引擎啟動 (CodeDeploy AfterInstall)、滑行 (ApplicationStart)、起飛滾行 (AllowTraffic) 以及爬升 (負載平衡器切換時的 BeforeAllowTraffic / AfterAllowTraffic)。在任何階段，檢查失敗都會導致中止並退回登機門。警示是駕駛艙的警告燈 —— 引擎溫度過高、液壓過低 —— 這些與回滾決策相連。斷路器是自動油門：如果振動感測器偵測到異常則撤回動力。金絲雀是提前 5 分鐘在該航線上飛行的導航機並回報情況。Synthetics canaries 正是如此 —— 腳本化的飛行，在正式流量飛行前驗證航線安全。

類比 3：手術室 Time-Out 協定

手術團隊在多個時間點使用 Time-Out 協定：切開前 (BeforeInstall)、器械清點後 (AfterInstall)、縫合前 (BeforeAllowTraffic，病患即將離開手術室進入恢復室)，以及最終縫合檢查 (AfterAllowTraffic，簽署病歷)。每個 Time-Out 都有檢查清單；檢查失敗則停止程序。CloudFormation 回滾組態是術後監控視窗 —— 在手術後的 N 分鐘內，如果病人的生命徵象 (CloudWatch 警示) 惡化，我們就回退到術前狀態 (還原堆疊更新)。ECS 斷路器是手術室的政策：如果同一個團隊連續 3 次手術出現併發症，該團隊將自動停職直到審查完成 (連續 N 次失敗後自動回滾)。生命週期掛鉤指令碼就是手術檢查清單本身 —— 經過版本控制、同行評審的文件，防止操作與協定之間出現偏差。

CodePipeline 失敗診斷

管線在動作 (action) 層級失敗。主控台會顯示失敗的動作及失敗訊息。常見模式：

• 來源動作 (Source action)：來源存儲庫無法連線、分支已刪除、缺少 IAM 權限。
• 建置動作 (Build action)：CodeBuild 專案失敗；點擊進入建置日誌查看。
• 測試動作 (Test action)：通常是另一個使用不同 buildspec 的 CodeBuild；診斷方式相同。
• 部署動作 (Deploy action)：CodeDeploy / CloudFormation / ECS / Lambda / Beanstalk 失敗；需深入部署服務。
• 核准動作 (Approval action)：逾時（預設 7 天）或明確拒絕。
• 叫用動作 (Invoke action)：Lambda / Step Functions 錯誤；檢查函數日誌。

失敗的管線可以在失敗的階段使用相同的輸入成品重試 (retry)，或從原始碼重新啟動。對於暫時性的基礎設施問題 (如 ECR 速率限制)，重試是正確的。對於程式碼或組態 Bug，則需修復並重新提交。

CodeBuild buildspec.yml 階段失敗

version: 0.2
phases:
  install:
    runtime-versions:
      python: 3.11
    commands:
      - pip install -r requirements.txt
  pre_build:
    commands:
      - aws ecr get-login-password | docker login ...
  build:
    commands:
      - docker build -t myapp:$CODEBUILD_RESOLVED_SOURCE_VERSION .
  post_build:
    commands:
      - docker push ...
artifacts:
  files:
    - imagedefinitions.json
reports:
  unit-tests:
    files:
      - test-results.xml
    file-format: JUNITXML

每個階段會在第一個非零結束代碼時失敗。常見失敗：

• install：缺失執行階段版本、套件安裝錯誤。
• pre_build：對 ECR 或其他登錄檔的身份驗證失敗。
• build：編譯錯誤、測試失敗、Docker 建置失敗。
• post_build：推送失敗、成品上傳失敗。

無論先前階段結果如何，finally 區塊都會執行；用於清理。artifacts 區段定義要發送到下一個管線動作的內容。報告 (Reports) 將測試結果彙整到 CodeBuild 報告群組視圖中。

CodeDeploy 生命週期掛鉤失敗

任何執行個體上的生命週期事件失敗都會導致該執行個體的部署失敗。部署組態決定了一個執行個體的失敗是否會導致整個部署失敗：

• CodeDeployDefault.OneAtATime：一個失敗 → 跳過後續執行個體 → 部署失敗。
• CodeDeployDefault.HalfAtATime：最多允許 50% 的失敗。
• CodeDeployDefault.AllAtOnce：風險最高；一個失敗則全體失敗。

在 EC2 上，掛鉤指令碼日誌位於 /opt/codedeploy-agent/deployment-root/<deployment-group>/<deployment-id>/logs/scripts.log。CodeDeploy 主控台會連結到每個失敗執行個體的指令碼輸出。

常見掛鉤失敗

• BeforeInstall 逾時：掛鉤指令碼太慢；預設逾時 30 分鐘，可在 appspec 中按掛鉤設定。
• ApplicationStart 失敗：應用程式無法啟動；通常是缺失組態、連接埠衝突或依賴項無法連線。
• ValidateService 失敗：冒煙測試 (如 curl localhost) 返回非 200；這是捕捉流量進入前損壞部署的最有用掛鉤。

CodeDeploy 基於警示的回滾

為部署群組配置 CloudWatch 警示清單。在部署期間，如果任何警示進入 ALARM 狀態，部署將自動回滾。常見警示：ALB 目標群組 UnHealthyHostCount > 0、應用程式 5xx 比率超過閾值、P95 延遲超過閾值。

CloudFormation 回滾組態

針對 CFN 堆疊建立與更新：

• 回滾組態 (Rollback configuration)：CloudWatch 警示清單與監控期間 (預設 0，建議 5-15 分鐘)。
• 在監控期間，如果任何警示進入 ALARM 狀態，堆疊會回滾到先前的狀態。
• 堆疊失敗選項：ROLLBACK (預設)、DO_NOTHING (保留資源供偵錯)、DELETE (建立失敗時完全拆除)。

常見 CFN 失敗原因：

• IAM 角色缺少建立資源所需的權限。
• 資源名稱衝突 (例如 S3 儲存桶名稱已被佔用)。
• 配額限制 (VPC 限制、EIP 限制)。
• 自定義資源 (Custom Resource) Lambda 逾時。
• WaitCondition 逾時。

堆疊事件 (events) 索引標籤會顯示失敗的資源與原因。CFN 掛鉤 (Hooks) (獨立功能) 會攔截資源操作以執行政策強制執行；掛鉤失敗 = 資源被阻斷 = 堆疊回滾。

ECS 部署失敗與斷路器

ECS 支援兩種類型的部署：

• 輪詢更新 (預設)：根據 minimumHealthyPercent 和 maximumPercent 逐漸用新任務替換舊任務。
• 透過 CodeDeploy 進行藍綠部署：並行執行完整的新任務集，然後轉移流量。

部署斷路器 (Deployment circuit breaker) (僅適用於輪詢更新) 會在連續任務失敗超過閾值 (預設為 3) 時自動回滾。透過 deploymentCircuitBreaker: { enable: true, rollback: true } 啟用。若無斷路器，損壞的映像將會逐一替換健康任務，直到整個服務癱瘓。

常見 ECS 部署失敗：

• 任務無法啟動：映像提取失敗 (ECR 授權、網路)、任務定義無效、缺少 IAM 角色。
• 任務已啟動但健康檢查失敗：應用程式啟動時崩潰、連接埠不匹配、依賴項無法連線。
• CapacityProviderStrategy 失敗：所選供應商沒有容量。

透過以下方式深入調查：

1. ECS 服務事件索引標籤 (服務級失敗)。
2. 任務停止原因 (單個任務級失敗)。
3. CloudWatch Logs (awslogs 驅動) 查看應用程式日誌。
4. Container Insights 查看更深層的資源指標。

Lambda 別名流量轉移與掛鉤

Lambda 別名流量轉移 (線性, 金絲雀) 需要 CodeDeploy。配置：

• 線性 (Linear)：每 Y 分鐘轉移 X% (例如 LambdaLinear10PercentEvery1Minute)。
• 金絲雀 (Canary)：先轉移 X% 然後等待 Y，再轉移到 100% (例如 LambdaCanary10Percent5Minutes)。
• AllAtOnce：全面切換，不進行漸進式轉移。

流量前 (Pre) 與後 (Post) 掛鉤 (Lambda 函數) 分別在轉移前後執行。使用流量前掛鉤來驗證新版本 (合成叫用)，使用流量後掛鉤進行清理。掛鉤函數透過 PutLifecycleEventHookExecutionStatus API 向 CodeDeploy 回報成功/失敗。

轉移期間觸發 CloudWatch 警示會導致自動回滾 (別名指向先前的版本)。

Auto Scaling 群組部署失敗

ASG 部署在以下情況失敗：

• 生命週期掛鉤逾時：執行個體啟動掛鉤 (Pending:Wait) 未收到訊號。
• 健康檢查失敗：ELB 健康檢查或 EC2 狀態檢查在執行個體進入服務前失敗。
• 引導 (Bootstrap) 失敗：cfn-init 或使用者資料指令碼錯誤。

CodeDeploy + ASG：部署組態必須考慮 ASG 擴展事件；透過新執行個體進行滾動部署很常見。應避免在 ASG 上進行就地部署，因為部署期間產生的新執行個體可能無法獲得新程式碼。

CloudWatch Synthetics — 部署前與部署後金絲雀

Synthetics 金絲雀是按排程執行的腳本化瀏覽器測試 (Puppeteer/Selenium)。金絲雀會發出指標（成功/失敗、延遲、斷鏈計數），你可以針對這些指標設定警示。使用金絲雀進行：

• 部署前驗證：針對暫存 (staging) 環境執行。
• 部署後驗證：部署後針對生產環境執行。
• 持續合成監控：偵測部署之間的衰退。

CloudWatch 中金絲雀的 SuccessPercent 指標是標準的門檻 —— 如果低於 95% 則觸發警示，並觸發 CodeDeploy 回滾或 CloudFormation 回滾組態。

高頻考試陷阱

陷阱 1：生命週期掛鉤順序

EC2 就地部署：ApplicationStop → DownloadBundle → BeforeInstall → Install → AfterInstall → ApplicationStart → ValidateService。考試會顯示部分序列並詢問缺失的掛鉤。

陷阱 2：CodeBuild 階段中的 runtime-versions 僅限於 install

runtime-versions 僅在 install 階段有效。放在其他地方會導致建置失敗。

陷阱 3：CloudFormation 使用 DO_NOTHING 停用了回滾

在堆疊建立時將 OnFailure 設為 DO_NOTHING 是為了偵錯；它會讓資源保持在失敗狀態。這不適用於生產環境。

陷阱 4：ECS 斷路器僅適用於輪詢更新

透過 CodeDeploy 進行的藍綠 ECS 部署使用 CodeDeploy 警示回滾，而不是 ECS 斷路器。它們是不同的機制。

陷阱 5：Lambda 流量前掛鉤必須呼叫 PutLifecycleEventHookExecutionStatus

掛鉤函數必須明確呼叫 API 來報告成功或失敗。僅正常返回是不夠的。

陷阱 6：Synthetic Canary 權限

金絲雀以 Lambda 函數形式執行；其 IAM 角色需要 S3 寫入權限以存儲螢幕截圖、CloudWatch Logs 寫入權限，以及在測試需要驗證的端點時所需的任何應用程式端權限。

陷阱 7：CodePipeline 跨區域動作需要跨區域複寫儲存桶

要在不同區域執行動作，必須配置跨區域成品儲存桶。若沒有這些儲存桶，跨區域部署動作會導致管線默默失敗。

DOP-C02 考試模式與案例解析

情境 1：ASG 就地部署失敗且出現新執行個體

題目背景：「向擁有 20 個執行個體的 ASG 進行就地部署；ASG 在部署中途擴展到 25 個；部署回報成功，但新執行個體執行的是舊程式碼。」正確做法：切換到具有新替換 ASG 的藍綠部署；或轉換為啟動範本版本控制，確保所有新執行個體都以新程式碼開機。

情境 2：Buildspec 在 pre_build 階段因 ECR 授權失敗

題目背景：「CodeBuild 在 pre_build 階段失敗，錯誤為 denied: User: arn:... is not authorized to perform: ecr:GetAuthorizationToken。」正確做法：向 CodeBuild 服務角色加入 ecr:GetAuthorizationToken 和 ecr:BatchCheckLayerAvailability 權限；驗證映像是否與建置位於同一區域。

情境 3：Lambda 別名金絲雀回滾

題目背景：「Lambda 金絲雀部署轉移了 10% 到新版本；使用者回報 500 錯誤增加。」正確做法：為 CodeDeploy 配置該函數 Errors 指標的 CloudWatch 警示；觸發警示會自動將別名恢復到先前的版本。

情境 4：ECS 服務卡在替換任務中

題目背景：「ECS 輪詢部署不斷殺死健康的舊任務並啟動健康檢查失敗的新任務；服務正在惡化。」正確做法：啟用 部署斷路器 並設定 rollback: true；在連續 3 次任務失敗後會自動回滾。

情境 5：CloudFormation 堆疊更新已回滾

題目背景：「CFN 堆疊更新進行到一半失敗；團隊需要知道哪個資源失敗以及原因。」正確做法：查看堆疊事件 (events) 索引標籤找到失敗的資源與訊息；對於資源建立問題，檢查 IAM 角色權限；對於自定義資源 Lambda 問題，檢查該函數的 CloudWatch Logs。

FAQ

Q1：如何找到失敗的 CodePipeline 的實際錯誤訊息？ 點擊進入失敗動作的「Details」連結。對於 CodeBuild，查看建置日誌 (CloudWatch Logs)。對於 CodeDeploy，查看每個執行個體的日誌 (/opt/codedeploy-agent/...)。對於 CloudFormation，查看堆疊事件。對於 ECS，查看服務事件和任務停止原因。

Q2：CodeDeploy 就地部署與藍綠部署的失敗模式有什麼區別？ 就地部署失敗會讓原始部署群組處於部分更新的狀態；回滾會在失敗的執行個體上重新部署先前的修訂版。藍綠部署失敗只需終止新 (綠色) 環境；原始 (藍色) 環境從未被觸動，繼續提供流量。藍綠部署雖然成本較高但更安全。

Q3：如何防止錯誤的映像摧毀我的 ECS 服務？ 對於輪詢更新，請啟用具備 rollback: true 的部署斷路器。為了更高的安全性，對 ECS 使用 CodeDeploy 藍綠部署，它會同時保持兩組任務執行，直到驗證通過。

Q4：Lambda 流量轉移如何自動回滾？ 配置一個帶有警示列表的 CodeDeploy 部署。在轉移期間，如果任何警示進入 ALARM，CodeDeploy 會將別名的路由組態恢復為指向先前的版本。此時不會執行流量後掛鉤。

Q5：如何排除 CloudFormation 中自定義資源 Lambda 逾時的問題？ 檢查 Lambda 函數的 CloudWatch Logs 以獲取實際錯誤。常見原因：VPC 子網沒有 NAT 閘道 (Lambda 無法連線到 AWS API 端點以發送回應)、函數逾時時間短於 API 呼叫持續時間、缺少 IAM 權限。務必在 try/finally 區塊中發送回應訊號，以避免 CFN 一直等到其 1 小時的逾時上限。

Q6：我應該使用 CloudWatch Synthetics 還是 ALB 健康檢查來進行部署驗證？ 兩者都應使用。ALB 健康檢查驗證基礎連通性 (目標已啟動、連接埠已開啟、HTTP 返回 OK)。CloudWatch Synthetics 驗證端到端使用者旅程 (登入可用、結帳流程完成、第三方整合有回應)。Synthetics 可以捕捉到 ALB 看不到的損壞。

Q7：如何避免在 ASG 上進行就地部署的風險？ 切換到藍綠部署，它會產生一個新的替換 ASG，在驗證後轉移流量。或者使用透過啟動範本版本更新的不可變部署 (immutable deployments)，新執行個體總是帶著新程式碼啟動，而舊執行個體則逐漸退出。

交叉參考

• EventBridge 自動修復執行手冊 可以將回滾步驟封裝為文件化程序；請參閱 eventbridge-auto-remediation-runbooks。
• CloudWatch 警示與 EventBridge 提供驅動回滾的警示訊號；請參閱 cloudwatch-alarms-eventbridge-integration。
• 事故管理員 (Incident Manager) 與 Health 在發生嚴重部署失敗時將其升級到值班回應計畫；請參閱 systems-manager-incident-manager-health。
• CloudWatch 指標與 Logs Insights 是尋找失敗根本原因的診斷工具；請參閱 cloudwatch-metrics-logs-insights。
• CloudTrail 與 Config 儀表板 揭示了是誰發起的部署以及發生了什麼組態變更；請參閱 cloudtrail-config-audit-dashboards。