deployment-pipeline-design

部署管線設計

多階段 CI/CD 管線的架構模式，包含核准關卡、部署策略與環境提升工作流程。

目的

設計穩健且安全的部署管線，透過適當的階段組織、自動化品質關卡與漸進式交付策略，在速度與安全性之間取得平衡。此技能涵蓋管線架構的結構設計，以及可靠生產部署的運作模式。

輸入 / 輸出

您提供的資訊

• 應用程式類型：語言/執行環境、容器化或裸機、單體或微服務
• 部署目標：Kubernetes、ECS、VM、Serverless 或平台即服務
• 環境拓撲：環境數量（開發/暫存/生產）、區域佈局、氣隙需求
• 發布需求：可接受的停機時間、回滾 SLA、流量分割需求、金絲雀或藍綠偏好
• 關卡限制：核准團隊、必要的測試覆蓋率門檻、合規掃描（SAST、DAST、SCA）
• 監控堆疊：用於自動化提升決策的 Prometheus、Datadog、CloudWatch 或其他指標來源

此技能產出的內容

• 管線設定：階段定義、作業相依性、平行處理與快取策略
• 部署策略：選擇的發布模式及附註說明（金絲雀權重、藍綠切換、滾動更新參數）
• 健康檢查設定：淺層與深層就緒探測、部署後煙霧測試腳本
• 關卡定義：自動化指標門檻與手動核准工作流程
• 回滾計畫：自動化回滾觸發條件與手動操作手冊步驟

使用時機

• 為新服務或平台遷移設計 CI/CD 架構
• 在環境之間實作部署關卡
• 設定多環境管線並強制執行安全掃描
• 透過金絲雀或藍綠策略建立漸進式交付
• 除錯管線中階段成功但生產行為異常的情況
• 透過指標惡化時自動回滾來縮短平均恢復時間

詳細模式與實作範例

詳細的模式文件位於 references/details.md。當上述導覽層級不足時，請閱讀該檔案。

疑難排解

健康檢查在管線中通過，但服務在生產環境中不健康

管線健康檢查是打到淺層的 /ping 端點，即使資料庫無法連線仍回傳 200。請使用驗證實際相依性的深層就緒檢查（請參閱上方健康檢查章節）。

金絲雀部署永遠不會提升到 100%

Argo Rollouts 需要有效的 AnalysisTemplate 才能自動提升。如果 Prometheus 查詢沒有回傳資料（例如指標名稱變更），分析會停留在無結論狀態，導致提升停滯。請加入 inconclusiveLimit 讓發布快速失敗而非懸掛：

spec:
  metrics:
  - name: error-rate
    failureCondition: "result[0] > 0.05"
    inconclusiveLimit: 2   # 2 次無結論後失敗，而非無限期懸掛
    provider:
      prometheus:
        query: |
          sum(rate(http_requests_total{status=~"5.."}[2m]))
          / sum(rate(http_requests_total[2m]))

暫存部署成功，但生產作業從未啟動

請檢查生產環境保護規則是否已設定——缺少審查者指派會導致核准關卡無限期等待且無通知。在 GitHub Actions 中，請確保在 Settings → Environments → production 中將 Required reviewers 設為現有的使用者或團隊。

Docker 層快取每次執行都失效，導致建置緩慢

如果 COPY . . 出現在相依性安裝之前，任何原始碼檔案變更都會使相依性層失效。請重新排序，先複製相依性清單：

# 良好做法：相依性與原始碼分開快取
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

回滾後資料庫遷移仍套用在舊程式碼上

服務回滾但未回滾資料庫遷移，會導致綱目/程式碼不符錯誤。務必讓遷移至少一個發布週期保持向後相容（僅新增），並將復原腳本與遷移腳本一起版本化：

# migrations/V20240315__add_nullable_column.sql       （向前）
# migrations/V20240315__add_nullable_column.undo.sql  （向後）

在舊版程式碼完全從所有環境退役之前，絕不執行破壞性遷移（DROP COLUMN、ALTER NOT NULL）。

進階主題

針對特定平台的管線設定、多區域提升工作流程，以及進階 Argo Rollouts 模式，請參閱：

• references/advanced-strategies.md — 擴展的 YAML 範例、特定平台設定（GitHub Actions、GitLab CI、Azure Pipelines）、多區域金絲雀模式，以及資料庫遷移回滾策略

相關技能

• github-actions-templates - 用於 GitHub Actions 實作模式與可重複使用工作流程
• gitlab-ci-patterns - 用於 GitLab CI/CD 管線實作
• secrets-management - 用於 CI/CD 管線中的機密處理