流程定位

App 部署的風險集中在不可變 artifact 與外部 gate。IPA、APK、AAB 或桌面安裝包一旦被使用者安裝，團隊需要靠 hotfix、remote config、kill switch 或服務端相容性止血；store review、簽章憑證與 phased rollout 會決定錯誤版本能否快速收斂。

Version 階段負責讓 artifact 可追溯。App crash report、客服回報與 store console 都依賴 version / build number；版本號對應 commit 與 workflow run 時，事故定位可以直接回到發布紀錄。

App signing 階段負責維持發布信任鏈。簽章憑證、provisioning profile、keystore 與 notarization credential 都是發布能力；它們要用 secret 管理、權限隔離、輪替與備援流程保護。

Test 階段負責覆蓋目標裝置條件。App 測試要依實際使用者分佈選擇 OS、裝置、權限狀態、網路條件與升級路徑；只跑 emulator smoke test，通常抓不到真機權限、背景限制或升級資料遷移問題。

Store review 階段負責處理外部 gate。審核可能因 metadata、隱私揭露、權限使用、付款政策或 crash 被拒；CI/CD 文件要記錄誰能處理審核回覆、哪些變更需要重新提交。

Rollout strategy 階段負責控制新版本擴散速度。分批發布的觀察指標包含 crash rate、登入、購買、同步、推播與核心流程完成率；達到停損條件時應暫停 rollout，先讓已受影響範圍維持可控。

Recovery 階段負責處理已安裝版本。App 常見止血工具是 remote config、feature flag、kill switch、server-side compatibility、hotfix build 與要求使用者升級；每個工具都要在事故前實作，事故時才有路可走。

多版本共存契約

多版本共存是 App 發布的基本前提。後端 API、資料格式、推播 payload 與 remote config 都要支援一段時間的新舊 client，因為使用者更新節奏不受團隊完全控制。

這些契約要在 CI 或 release checklist 裡被驗證。若只靠後端「盡量相容」，App 發布失敗會在使用者更新後才暴露，回復成本會比 web 或後端高。

Release checklist

Release checklist 的責任是把外部 gate 與內部 gate 接起來。App 發布牽涉商店、憑證、客服、行銷與後端相容，因此 checklist 應該是流程契約，不只是提醒清單。

1. 確認 version、build number、commit 與 artifact 對應。
2. 確認 signing secret、profile 或 keystore 仍有效。
3. 跑 unit、UI、device matrix 與 upgrade test。
4. 檢查 API / remote config / push payload 多版本相容。
5. 上傳 internal / beta track，跑 smoke test。
6. 提交 store review，記錄審核狀態。
7. 用 phased rollout 推進，觀察 crash-free rate 與核心指標。
8. 觸發停損條件時暫停 rollout、關閉功能或準備 hotfix。

這個順序讓 App 發布從「把包丟上去」變成可觀測流程。每一步都對應一個失敗路由，事故時能知道下一個可執行動作。

下一步路由

• App 部署總覽：回 App 部署 CI/CD。
• 簽章概念：讀 App Signing。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Data pipeline 的風險集中在資料副作用。API 發布錯誤通常會表現成 request failure；資料任務錯誤可能把錯誤結果寫進 warehouse、feature store、報表或下游模型，並在很久之後才被看見。發布流程要把 correctness check 放到 deploy 前後。

Build 階段負責固定執行邏輯。dbt model、Spark job、Flink processor、Airflow DAG 或 SQL transform 都需要能追到 commit 與 dependency，讓歷史資料重跑時能確認使用哪一版邏輯。

Validation 階段負責檢查資料契約。Schema check、sample run、contract test、row count、null ratio、distinct count 與 business invariant 都可以作為 gate；重點是讓輸出變更在下游消費前被看見。

Deploy 階段負責切換任務版本。Scheduler、trigger、checkpoint location 與 credential 都會影響新版本是否真正接管；部署後要確認下一次 run 用的是新版本，並保留舊版本停止或恢復路徑。

Backfill 階段負責補算歷史資料。Backfill 應有時間範圍、節流、checkpoint、停損條件與對帳策略，避免一次掃完整個歷史區間壓垮上游或把錯誤大規模寫入下游。

Rerun 階段負責修復失敗 run 或錯誤區間。Rerun 要定義輸出覆寫、去重、idempotency 與下游通知；同一段資料被跑兩次時，結果應可預期。

Recovery 階段負責處理錯誤資料已被消費的情況。資料 pipeline 的 rollback 常常採用 forward fix、重新計算、標記污染區間與通知下游重新讀取。

Backfill 控制面

Backfill 控制面的責任是限制歷史補算的影響範圍。歷史資料量通常遠大於日常增量；沒有控制面的 backfill 會同時衝擊計算成本、上游讀取、下游寫入與資料正確性。

這些控制項要寫進 workflow 或 runbook。若 backfill 只能靠工程師現場下 SQL，事故時很難保證每次操作都有相同邏輯。

Rerun 判讀

Rerun 判讀的責任是確認重跑是否會造成二次傷害。資料任務失敗後，最危險的動作是未確認輸出語意就直接重跑。

這張表讓 rerun 從「再跑一次」變成有條件的恢復策略。資料正確性比任務綠燈更重要；綠燈只代表 job 完成，不代表輸出可信。

下一步路由

• Data pipeline 部署總覽：回 Data Pipeline 部署 CI/CD。
• Migration 概念：讀 Migration。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Desktop client 的風險集中在作業系統信任鏈與更新通道。macOS、Windows、Linux 對簽章、安裝包格式與安全提示的要求不同；同一份 source 通常會產生多個平台 artifact，因此 workflow 要把平台 matrix、簽章 secret 與 Release Channel 拆清楚。

Build 階段負責產生平台專屬 artifact。Flutter Desktop、Electron 與 Tauri 的輸出格式不同，但共同要求是每個 artifact 都能追到 commit、workflow run 與 dependency lock。

Signing 階段負責讓 OS 信任安裝包。Windows code signing certificate、macOS Developer ID、timestamp server 與 Linux package signing key 都是發布能力；secret 應放在受控環境，並限制能觸發 signing job 的分支與 reviewer。

Notarize 階段負責處理 macOS 信任 gate。macOS app 即使完成簽章，也常需要 notarization 與 stapling；CI 要把 notarization log 保存下來，否則使用者看到 Gatekeeper 警告時很難回溯。

Release 階段負責把 artifact 放到正確 Release Channel。Internal、beta、stable 與 enterprise channel 的 gate 不同；CI/CD 要避免未審核的 beta artifact 被 stable feed 取用。

Update 階段負責維持升級路徑。Update Feed、delta package、signature、minimum supported version 與 rollback channel 要一起設計；更新壞掉時，使用者可能卡在需要人工修復的版本。

Recovery 階段負責止血。桌面客戶端常用方式是撤下 update feed、發布 hotfix、切換 rollback channel、停用 remote feature 或要求最低版本；每種方式都依賴 app 內建相容支援。

平台差異判讀

平台差異判讀的責任是讓 CI matrix 對應真實發布風險。桌面發布除了確認「三平台都 build 成功」，還要確認每個平台的安裝、啟動、更新與卸載行為。

這張表的用途是避免平台細節被單一「desktop build」欄位抹平。每個 OS 的失敗代價不同，CI 應保留平台專屬 gate。

Update feed 契約

Update Feed 契約的責任是讓已安裝使用者安全升級。Auto-update 需要簽章、版本比較、channel、最低版本與回退策略共同成立，才能讓新版本 URL 進入 feed。

1. Feed 只指向已簽章且已驗證的 artifact。
2. Stable feed 只接收 stable release，beta feed 只接收 beta release。
3. App 啟動時能處理 feed 暫時不可用。
4. Delta update 失敗時能 fallback 到 full installer。
5. 錯誤版本要能從 feed 撤下，並讓未更新使用者停止取得。
6. 已更新使用者要有 hotfix 或 rollback channel。

這些條件讓更新通道具備操作性。若 app 只知道「看到新版就下載」，錯誤 feed 會把事故放大到所有啟動中的使用者。

下一步路由

• Desktop 部署總覽：回 Desktop Client 部署 CI/CD。
• App 發布通用觀念：讀 App 簽章、商店審核與分批發布流程。
• 簽章術語：讀 App Signing。

流程定位

IaC 的風險集中在共享狀態與不可逆資源。應用部署失敗常可回退 artifact；基礎設施變更可能刪除資料、替換節點、改掉 IAM 權限或讓 state 與真實環境分叉。發布流程應讓 reviewer 在 apply 前看到「將要改什麼」，並讓 apply 後能確認「環境是否真的符合宣告」。

Plan 階段負責產生可審查差異。Plan 是 reviewer 判斷資源替換、權限擴大、資料刪除與網路暴露的主要材料。CI 應保留 plan artifact，讓 apply 使用同一份輸入與版本。

Review 階段負責把風險放到正確 owner。平台、資安、資料庫或服務 owner 應依資源類型參與審核；高風險變更需要額外 gate，例如 maintenance window、人工 approval 或雙人審核。

Apply 階段負責把宣告狀態寫入環境。State Lock、credential、workspace 與環境變數都要固定；partial apply 或 timeout 後，要先判斷 state 與真實資源是否一致，再決定下一步。

Verify 階段負責確認平台可用。Apply 成功只代表 provider API 接受變更；仍需要 connectivity test、policy check、service smoke test、DNS / certificate check 或 cluster health，確認服務真的能跑。

Infrastructure Drift 階段負責發現宣告與現況分叉。手動 hotfix、雲端 console 調整、外部 controller 或 provider 預設值都可能造成 drift；drift detection 要定期執行，並把修復責任導回宣告檔。

Recovery 階段負責處理失敗套用。IaC 回復不一定是 git revert 後 apply；可能需要 import、state mv、taint / untaint、手動修復資料資源或 forward fix。流程要先保護資料與服務，再修正宣告與 state。

Plan review 判讀

Plan review 的責任是讓變更影響在 apply 前被看見。Reviewer 應依資源語意判斷，讓 diff 行數退居輔助訊號。

這張表讓 review 從「有人按 approve」變成風險判讀。IaC review 的價值在於提前看見不可逆或高代價變更。

Drift 處理路由

Drift 處理的責任是把現況重新帶回可管理狀態。Drift 發現後不應直接 apply 覆蓋，因為 drift 可能是事故 hotfix、外部系統自動調整或宣告檔過期。

1. 確認 drift 來源：人工 hotfix、provider 預設、外部 controller 或宣告過期。
2. 判斷 drift 是否仍需要保留：若是真實修復，應回寫到 IaC。
3. 判斷 apply 是否會破壞服務：特別看 replacement、destroy、權限與 network。
4. 修正宣告或 state：必要時使用 import、state mv 或 provider-specific repair。
5. 重新 plan，確認差異收斂到預期。

這個路由讓 drift 修復具備審查性。直接在 console 裡補到看起來正常，會讓下一次 CI apply 把修復覆蓋掉。

常見反模式

反模式的共同問題是把 IaC 降成指令自動化，忽略它承擔的狀態治理責任。

下一步路由

• IaC 部署總覽：回 IaC / Platform 部署 CI/CD。
• 環境保護：讀 Environment Protection。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Image deployment 的風險集中在「看似同名、實際不同」的產物漂移。latest、mutable tag、重新 build 與跨 registry promotion 都可能讓 staging 測過的 image 不等於 production 跑的 image。嚴謹流程應以 Image Digest 或 immutable tag 作為 artifact 身分。

Build 階段負責封裝 runtime。Multi-stage build、dependency cache、base image pinning 與 build secret 處理會直接影響安全性；CI 應能在乾淨 runner 上重建 image，避免開發機狀態被帶入。

Tag 階段負責支援不同查詢情境。Commit SHA 適合事故追溯，semver 適合 release 溝通，Image Digest 適合 runtime 精準鎖定；production 判讀應以 digest 為準，tag 只作為人類入口。

Scan 階段負責把風險分流。Vulnerability scan、secret scan、license scan 與 SBOM 不應只是報表；流程要定義哪些風險阻擋發布、哪些風險允許例外、例外誰審核、何時重新評估。

Container registry 階段負責保存與推進 image。Registry 要處理權限、retention、immutability、promotion 與垃圾回收；若 production 直接從 feature branch push 的 tag 拉 image，供應鏈邊界就失去治理。

Runtime handoff 階段負責把已驗證 image 交給部署平台。Kubernetes、ECS、Compose 或其他 runtime 都應指向已驗證 digest 或 immutable tag，並把 health、readiness、resource limit 與 rollback 連到同一次 release。

Tag 與 digest 策略

Tag 策略的責任是讓人查得到、機器鎖得住。單一 tag 很難同時滿足可讀性、可追溯與不可變三個需求，因此實務上常搭配多個 tag 與 digest。

Production deployment 應能從 running pod 或 task 反查 image digest，再反查 registry metadata、scan report、workflow run 與 source commit。這條查詢路徑是 incident response 的基本能力。

Scan gate 分流

Scan gate 的責任是讓安全訊號變成可操作路由。掃描工具會產生大量結果，沒有分流規則時，團隊會在兩種壞狀態間搖擺：全部阻擋導致發不出去，全部忽略導致掃描失去信任。

這個分流讓 scan 成為 gate。例外流程要有 owner 與到期日，讓例外維持可追蹤、可重新評估。

常見反模式

反模式的共同問題是讓 image 身分失去穩定錨點。當 image 身分漂移，測試結果、掃描結果與 runtime 狀態會彼此分叉。

下一步路由

• Image 部署總覽：回 Docker / Image 部署 CI/CD。
• Registry 術語：讀 Container Registry。
• 後端 runtime 部署：讀 後端部署 CI/CD。

流程定位

Serverless 的風險集中在觸發條件。函式部署成功只代表新版本存在，實際風險會在 HTTP request、queue message、topic event、scheduled job 或 edge request 觸發時出現。發布流程要能區分「版本建立成功」「alias 切流量成功」「事件來源行為正確」三件事。

Package 階段負責產生可執行 bundle。Serverless 常見失敗是本機 dependency 可用，但打包後缺檔、runtime target 不符、native extension 不相容或 layer 版本漂移；CI 應在接近目標 runtime 的環境做 smoke test。

Version 階段負責建立不可變版本。直接覆蓋 $LATEST 會讓事故追溯困難；正式流量應指向 version 或 Function Alias，讓 rollback 能把 alias 切回前一個已知版本。

Function Alias / traffic 階段負責控制流量切換。HTTP function 可以用少量權重 canary；queue trigger 則要觀察 batch failure、retry、dead-letter 與 downstream side effect，因為同一個錯誤 event 可能被重試多次。

Permission 階段負責限制 blast radius。Serverless 函式容易因部署方便而累積過大 IAM 權限；每個 function 應只拿到必要 resource、secret 與 network access，並把 production secret 與 preview / staging 隔離。

Event Source 階段負責定義失敗重送語意。Queue、topic、object storage、HTTP 與 scheduler 的錯誤行為不同；CI/CD 文件要記錄 retry 次數、dead-letter destination、batch size、concurrency limit 與 replay 條件。

Recovery 階段負責止血。Serverless 常見止血方式是 alias rollback、停用 trigger、降低 concurrency、清理毒訊息、重放事件或 forward fix；只回退 code 版本不一定能處理已經排入 queue 的事件。

事件來源判讀

事件來源判讀的責任是找出失敗是否可重試。Serverless 常被誤判為「函式自己失敗」，但實際根因可能是 event schema、權限、上游重試或下游限流。

這張表讓 release failure 能被導向正確 owner。若 event schema 變了，修 function 可能只是表面補丁；真正的 gate 要加在 publisher contract 或 sample event validation。

最小發布 gate

Serverless workflow 的最小 gate 應覆蓋 package、permission、event 與 alias。缺其中一段，部署成功就可能只是建立了一個尚未被驗證的函式版本。

1. Package bundle，固定 runtime target 與 dependency。
2. 對 bundle 執行 unit / contract / sample event test。
3. 用 least privilege policy 做 deploy dry run 或 policy diff。
4. 發布 immutable function version。
5. 用 alias 將少量流量導向新版本。
6. 觀察 error、latency、retry、DLQ 與 downstream 指標。
7. 指標穩定後提高 alias 權重或完成切換。
8. 指標觸發 tripwire 時切回 alias、停用 trigger 或啟動 repair。

這個流程把 Serverless 發布從「上傳函式」提升成可回復流程。對事件驅動函式而言，trigger 與 retry policy 是發布契約的一部分。

下一步路由

• Serverless 部署總覽：回 Serverless 部署 CI/CD。
• Rollout 概念：讀 Rollout Strategy。
• 失敗處理：讀 CI 失敗到修復發布流程。

流程定位

前端部署的風險集中在 build time。後端服務可以在 runtime 讀取設定、檢查資料庫與逐步接流量；前端靜態產物多半在 build 階段就把 route、asset path、環境變數與 feature flag 預先寫入 bundle。CI/CD 的判讀重點因此是「被部署的 artifact 是否就是已驗證的那一份」。

Build 階段負責建立可驗證產物。真實服務裡，npm run dev 成功不代表 production build 能成功；CI 應固定 Node 版本、package manager、lockfile、build command 與必要環境變數，讓 artifact 可以從乾淨環境重建。

Browser test 階段負責驗證使用者實際會看到的頁面。Playwright、visual diff、a11y check 或 smoke test 應盡量對 build 後的靜態站執行，避免 dev server 的 fallback、熱更新或寬鬆路由遮蔽 production 問題。

Preview environment 階段負責把 PR 變成可操作畫面。Preview URL 要能追到 PR、commit 與 workflow run，reviewer 才能把畫面問題回報到正確版本；preview 也要隔離 production 資料與 credential，避免預覽環境變成未受控入口。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。前端部署失敗常出現在 cache policy、SPA fallback、base URL、static route 與 sourcemap 權限；deploy 成功只代表檔案上傳完成，仍需要檢查入口頁、核心路由與 asset 是否能從公開網址載入。

Rollback strategy 階段負責恢復上一份可用靜態產物。前端 rollback 表面上只是切回舊檔案，但若 API schema、build time config 或 CDN cache 已經變動，舊頁面仍可能呼叫不相容的後端，因此 rollback 要搭配 smoke test 與 cache purge。

常見失敗路由

前端 CI 紅燈要先判斷失敗在 build、browser test、preview 還是 production deploy。不同層的修復入口不同；把所有紅燈都當成「重跑 workflow」會掩蓋 artifact 漂移與 cache 問題。

這張表的用途是縮短定位時間。前端部署問題常被誤判成「CDN 壞掉」或「瀏覽器快取」，但更常見的根因是 build artifact、route 與 cache policy 的契約沒有明確寫進 pipeline。

最小 workflow 骨架

前端 workflow 應把 build、test、preview 與 deploy 的資料流顯性化。下面是概念骨架，重點在 artifact handoff 的方向，特定平台語法是次要的。

 1jobs:
 2  build:
 3    steps:
 4      - run: npm ci
 5      - run: npm run build
 6      - uses: actions/upload-artifact
 7        with:
 8          name: web-dist
 9          path: dist
10
11  test:
12    needs: build
13    steps:
14      - uses: actions/download-artifact
15        with:
16          name: web-dist
17      - run: npm run test:e2e:static
18
19  preview:
20    needs: test
21    if: github.event_name == 'pull_request'
22    steps:
23      - uses: actions/download-artifact
24        with:
25          name: web-dist
26      - run: npm run deploy:preview
27
28  deploy:
29    needs: test
30    if: github.ref == 'refs/heads/main'
31    steps:
32      - uses: actions/download-artifact
33        with:
34          name: web-dist
35      - run: npm run deploy:production

這個骨架讓 deploy 依賴 test，也讓 test 與 deploy 使用 build job 產生的同一份產物。若專案需要在不同環境注入設定，要明確區分 build time config 與 runtime config，避免同一份 artifact 被重新 build 成另一份內容。

Tripwire

Tripwire 的責任是提醒前端 workflow 需要重切。當同一類問題反覆出現，局部補命令通常只能暫時遮住資料流錯位。

• Preview 常和 production 不一致：把 preview 改成部署 build artifact，讓 preview job 沿用同一份產物。
• E2E 測試通過但 production 壞：把 E2E 改到 static artifact 或 production-like server 上執行。
• rollback 依賴人工找舊 commit：保留 release artifact 與版本索引，讓回退指向明確產物。
• CDN cache 問題反覆出現：把 HTML cache、asset cache 與 purge 策略寫進 deploy checklist。

下一步路由

• 前端部署總覽：回 前端部署 CI/CD。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 本 blog 靜態站案例：讀 本 blog 專案部署。

流程定位

後端部署的主要風險是有狀態依賴。前端 artifact 可以直接回退上一份靜態檔，後端服務一旦寫入新資料、消費 queue message 或呼叫外部 side effect，rollback 就不再只是換回舊 image。發布流程要先定義新舊版本如何短暫共存，再決定 migration 與流量切換順序。

Build 階段負責產生可部署服務。服務版本要能從 runtime 反查 commit、workflow run、image digest 與 migration 版本，讓事故時能快速定位哪一次變更進入環境。

Contract test 階段負責驗證跨邊界相容。API response、database schema、queue message 與 config key 都是契約；只測 service 內部函式，通常抓不到新舊版本並存時的破壞性變更。

Migration 階段負責推進資料狀態。安全 migration 通常採 expand-and-contract：先加相容欄位或表、部署可讀新舊格式的程式、回填資料，最後移除舊格式。直接在同一次 release 刪欄位與切程式，會讓 rollback 失去空間。

Rollout strategy 階段負責控制新版本接到的流量。Rolling、canary 與 blue-green 都需要可信 readiness；readiness 應檢查服務能否接流量，而不只是 process alive。

Rollback strategy 階段負責定義失敗時的處理路由。後端 rollback 常見做法是 app rollback、config rollback、traffic rollback 或 forward fix；資料已被新程式寫入時，forward fix 往往比直接資料回滾安全。

Migration 順序

Migration 順序的責任是保留相容窗口。資料結構變更應讓至少兩個相鄰程式版本能共存，避免部署中途任何一端先完成都造成服務不可用。

1. 新增向前相容 schema，例如新增 nullable column 或新表。
2. 部署可同時讀舊欄位與新欄位的程式。
3. 執行 backfill 或 background migration。
4. 切換讀取來源或寫入路徑。
5. 觀察穩定後移除舊欄位、舊 index 或舊 message 格式。

這個順序的價值是可停止。若第 3 步回填異常，可以暫停 backfill，不必立即回退 app；若第 4 步切換後錯誤率升高，可以先切回舊讀取路徑，再評估資料修補。

Rollout 判讀

Rollout 判讀要同時看技術指標與業務副作用。服務能啟動不代表能安全接流量；API error、queue lag、database lock、第三方 API 錯誤與核心業務漏斗都可能是發布問題。

這些訊號要先接到發布流程。若指標只存在 dashboard 裡、workflow 不知道如何判讀，團隊仍會在事故當下靠人工臨場決策。

常見反模式

反模式的共同問題是把後端部署當成單一 deploy 動作。後端發布的本質是多個相依狀態的協調流程。

下一步路由

• 後端部署總覽：回 後端部署 CI/CD。
• Migration 術語：讀 Migration。
• Gate 原理：讀 CI gate 與 workflow 邊界。

為什麼需要這條通道

CLI binary 跟函式庫的下游使用脈絡不同。函式庫需要被同語言專案 import，自然走 registry（npm install、pip install、cargo add）。CLI binary 的目標讀者是「只想跑這個工具」的人，他們不一定有對應 toolchain、不想花時間編譯，也不會接受「先裝開發環境才能用」的入場門檻。

Binary release 的契約是：上游負責編譯、下游負責下載。這條契約成立需要三個前提同時滿足：

1. CI 能在多平台 cross-compile 出可執行檔（macOS x64/arm64、Linux x64/arm64、Windows x64）
2. 編譯產物有穩定 URL，下游可以用一行 shell 命令取得
3. 安裝過程不依賴開發環境（不需要 git clone、不需要 build toolchain）

達成這三點需要一個 release 工具鏈把 build matrix、artifact 上傳、installer script 產生包成一個 tag-driven 的 workflow。Rust 生態用 cargo-dist、Go 生態用 goreleaser、語言中性的方案則是手刻 GitHub Actions matrix。三者觸發條件相同（push semver tag）、產物落點相同（GitHub Release assets），只在 build pipeline 細節有差。

Tag-driven release 的鏈路

Tag-driven 的核心設計：push tag 是發版意圖的唯一訊號。這條因果鏈每一環都要實作起來才會通：

1維護者 push tag vX.Y.Z         ↓
2                                →  release.yml workflow 觸發（tag pattern 匹配）
3                                →  cross-compile to N platforms（GitHub Actions matrix）
4                                →  打包成 <pkg>-x86_64-apple-darwin.tar.xz 等 N 個 archive
5                                →  產生 <pkg>-installer.sh / .ps1（內嵌指向上述 archive 的 download URL）
6                                →  建立 GitHub Release vX.Y.Z
7                                →  上傳所有 archive + installer 為 release assets
8                                →  GitHub 自動把 vX.Y.Z 的 assets 也鏡射到 /releases/latest/download/

這條鏈路上每個節點都是一塊要設定的工作：

• Tag pattern：cargo-dist 預設匹配 **[0-9]+.[0-9]+.[0-9]+*，符合 semver 才會觸發
• Build matrix：在 Cargo.toml 的 [workspace.metadata.dist] 宣告 targets = [...]，cargo-dist 會展開成對應的 GitHub Actions runners
• Pre-build hooks：如果編譯前需要產生程式碼或下載資料，要透過 github-build-setup 注入（zhtw-mcp 的案例就是要先跑 gen-s2t-tables.py 產生 s2t_data.rs）
• Installer 範本：cargo-dist 內建 shell / powershell / homebrew / npm 等多種 installer 產生器，在 installers = [...] 設定
• /releases/latest/download/ alias：GitHub 自動提供，指向 latest non-prerelease release 的 asset；prerelease 不會更新這個 alias

這也解釋了為什麼 git tag dev 或單純 commit 到 main 都不會發版 — 那不符合 tag pattern、不是發版意圖。

第一次搭 cargo-dist 的實作步驟

從零開始的維護者視角，Rust binary 專案要搭 cargo-dist 大致是這幾步：

1. 裝 cargo-dist CLI：cargo install cargo-dist（或從它自家的 installer 裝）
2. 跑 dist init：互動式問答，選 targets、installers、CI provider（GitHub Actions），它會在 Cargo.toml 寫入 [workspace.metadata.dist] 並產生 .github/workflows/release.yml
3. 檢查產出：release.yml 是 auto-generated、開頭會標 # This file was autogenerated by dist，不要手改，下次 dist generate 會被覆蓋
4. 設定 pre-build hook（如果需要）：在 Cargo.toml 加 github-build-setup = "build-setup.yml"，把編譯前要跑的步驟寫在 .github/build-setup.yml（這個檔不會被 dist generate 覆蓋）
5. 設定 preflight gate（重要）：把現有的 main CI workflow 加上 workflow_call trigger，在 Cargo.toml 設 plan-jobs = ["./.github/workflows/main.yml"]，讓 release pipeline 在 cross-compile 前先確認測試全綠
6. 推第一個 prerelease tag 試水溫：git tag v0.1.0-alpha.1 && git push origin v0.1.0-alpha.1，看 release.yml 跑出來的 matrix 是不是全綠
7. 確認 installer script 可用：在乾淨機器上跑 curl ... /releases/download/v0.1.0-alpha.1/<pkg>-installer.sh | sh（注意 prerelease 要用完整 tag URL、不是 latest）
8. 推第一個正式 tag：跑 v0.1.0，這時 /releases/latest/download/ alias 才會生效
9. 更新 README：把 installer 安裝命令寫上去；正式版發出後就能用 latest URL，prerelease 階段要寫完整 tag URL
10. 後續維護：bump version → tag → push，cargo-dist 自動處理；只有改 [workspace.metadata.dist] 時才需要重跑 dist generate

第 5 步的 preflight gate 是新手最容易漏的關。沒有它的話、main 紅燈時你還是能 push tag、cargo-dist 還是會跑 cross-compile、爛 binary 還是會推到所有人。workflow_call 反向 reuse 這個 pattern 在 CI gate 與 workflow 邊界 有更完整討論。

Installer script 模式的契約

curl ... | sh 是這條通道的常見下游入口。這個入口要成立，前提是上游提供可驗證產物、下游執行前有最小安全檢查。

cargo-dist 產生的 installer 命令長這樣：

1curl --proto '=https' --tlsv1.2 -LsSf \
2  https://github.com/<owner>/<repo>/releases/latest/download/<pkg>-installer.sh | sh

逐項拆解 curl 的 flag：

-f 那個 flag 是這條鏈路的安全點：沒有它的話、如果 release URL 暫時 404，GitHub 的 404 HTML 會被 pipe 到 sh 然後爆出一堆語法錯誤；有 -f 時 curl 會直接 exit 22、sh 不會被呼叫，使用者看到的是清楚的錯誤碼。這就是為什麼 cargo-dist 產生的範本預設帶 -f、不能省。

PowerShell 版本（irm | iex）的等價契約相同 — Invoke-RestMethod 對 404 也會丟 exception、不會把 HTML 餵給 Invoke-Expression。

Installer script 自己的內部行為：偵測平台、下載對應 archive、解壓、放到 ~/.local/bin 或 ~/.cargo/bin、視需要更新 PATH。這部分由 cargo-dist 範本生成、跨專案幾乎一致、維護者不需要手寫。

最小安全基線（教學案例版）

教學案例可以示範 curl | sh，但可維護版本要同時提供「下載、驗證、執行」路徑，讓使用者在高風險環境可切換到可審計流程。

 1# 1) 下載 installer 與 checksum
 2curl --proto '=https' --tlsv1.2 -LsSf \
 3  -o /tmp/<pkg>-installer.sh \
 4  https://github.com/<owner>/<repo>/releases/download/vX.Y.Z/<pkg>-installer.sh
 5curl --proto '=https' --tlsv1.2 -LsSf \
 6  -o /tmp/<pkg>-checksums.txt \
 7  https://github.com/<owner>/<repo>/releases/download/vX.Y.Z/<pkg>-checksums.txt
 8
 9# 2) 驗證 checksum（sha256sum 或 shasum 擇一）
10sha256sum -c /tmp/<pkg>-checksums.txt --ignore-missing
11# shasum -a 256 -c /tmp/<pkg>-checksums.txt
12
13# 3) 執行 installer
14sh /tmp/<pkg>-installer.sh

這條路徑的責任分工是：

1. 上游：發布 installer 與對應 checksum（或 provenance）。
2. 下游：先驗證再執行。
3. 文件：同時提供快速路徑與可審計路徑，並標明適用情境。

Pre-release（early adopter）通道

第一個正式 release 之前，pipeline 本身需要先被驗證。這時 prerelease tag（v0.1.0-alpha.1、v0.1.0-rc1 之類）就派上用場：

• 作為 pipeline 自身的測試：tag 推下去能跑出多平台 binary，代表 cargo-dist 設定正確
• 給 early adopter 試用：願意當先驅者的使用者可以用完整 tag URL 取得 binary
• 不污染 latest alias：GitHub 的 releases/latest/download/ 只指向 non-prerelease，所以 prerelease 不會「假發版」

代價是 prerelease 沒有 stable URL — 每個版本要寫完整 tag、不能用 latest。所以 README 安裝段落在 v0.1.0 出來之前要寫：

1# Pre-release example（給 early adopter）
2curl --proto '=https' --tlsv1.2 -LsSf \
3  https://github.com/<owner>/<repo>/releases/download/v0.1.0-alpha.1/<pkg>-installer.sh | sh

正式 v0.1.0 出來之後再切回 latest URL。這是 zhtw-mcp issue #35 討論裡 hydai 提的折衷方案，能讓社群在 pipeline 完備前先試用、又不誤導不明就裡的使用者以為正式版已就位。

zhtw-mcp 案例：社群協作把 release pipeline 搭起來

zhtw-mcp 的 issue #35 跟 PR #40 是這條搭建過程的活案例。整個討論的時間軸：

1. dlackty 提 issue #35：建議導入 cargo-dist + Homebrew、列出建議 targets、指出 s2t_data.rs 需要 pre-build hook
2. 作者 jserv 回應：認同方向，但坦承自己 Rust 經驗有限、這個專案部分目的就是為了學 Rust 生態，邀請社群提 PR 推進
3. hydai 開 PR #40：第一次用 cargo-dist，自己也在學，誠實表示「想知道方向對不對，希望熟手能接手」，並引用自己之前用 knope 手刻 release 的另一個 repo 作為對照
4. jserv 提到 installer URL 失效：README 已經寫了 releases/latest/download/...，但還沒有正式 release，建議用 pre-release 給 early adopter
5. hydai 提議 v0.1.0-alpha.1：作為 early adopter 通道、提醒 prerelease 沒有 latest alias、要用完整 tag URL

這個討論留下幾個值得學的點：

• 公開承認還在學是好事：jserv 直接說「我 Rust 經驗有限、我也在學」、hydai 說「我第一次用 cargo-dist」，這比假裝專家有效率多了。社群協作的核心是大家都看到同一個未完成狀態、一起補。
• README 先寫安裝命令再補 release 是常見順序：把 release 路線當作目標釘出來、再倒推實作，是刻意的設計。先寫文件再補 pipeline 的順序也讓 issue #35 / PR #40 更容易聚焦。
• 特殊 build hook 是 cargo-dist 的明確支援點：zhtw-mcp 需要在編譯前跑 gen-s2t-tables.py 產生 s2t_data.rs，這正好是 github-build-setup 設計給的場景。如果你的 repo 有類似「編譯前要產生程式碼／下載資料」的需求、不必為此放棄 cargo-dist。
• Pre-release 是 pipeline 學習期的合理工具：先用 v0.1.0-alpha.1 把 pipeline 跑通、把問題暴露出來，比等到一切完美才發版更有效率。

跟著這個 issue 串看完一輪、可以得到一個從零搭 cargo-dist 的真實參照框架，比官方文件更貼近實際遇到的問題。

Homebrew 通道：cargo-dist 怎麼幫你出 formula

brew install 是 macOS 使用者最熟的安裝路線，但 Homebrew 有兩種發版形式：

cargo-dist 預設支援的是後者（tap）。設定方式是在 [workspace.metadata.dist] 加：

1installers = ["shell", "powershell", "homebrew"]
2tap = "<your-github-username>/homebrew-<tap-name>"

然後在 GitHub 開一個叫 homebrew-<tap-name> 的 repo（命名規則是 Homebrew 強制的），cargo-dist 會在每次 release 自動 push 一個更新過的 formula 到那個 repo。下游使用者只要：

1brew tap <your-github-username>/<tap-name>
2brew install <pkg>

要走 homebrew-core 是另一個層級的事 — 需要套件夠成熟、有穩定使用者基數、有清楚的 license、過 homebrew-core maintainer 的 review。多數新專案先做 tap、累積使用者跟成熟度後再考慮 core。

上線前的最後檢查

第一個正式 v0.1.0 推出去之前最後跑一遍：

• Prerelease tag（v0.1.0-alpha.1 之類）跑過 release.yml、cross-compile matrix 全綠
• 從乾淨機器跑 README 寫的 installer 命令、從下載到執行整條順
• Pre-build hook（如果有）在所有 platform 都能跑、不依賴特定 OS
• Preflight gate 的 workflow_call reuse 確實 block 住紅燈 main
• README 的 installer URL 跟實際 asset 命名規則一致（cargo-dist 會用 <pkg>-installer.sh、不要寫成 install.sh）
• Changelog 跟 tag 對齊（cargo-dist 會把 changelog 抓進 release notes）
• 有提供可審計安裝路徑（下載 + checksum/provenance 驗證 + 執行）

第一條 v0.1.0 推出去後 releases/latest/download/... alias 才會生效、那時就能把 README 改成 latest URL、徹底完成這條通道的搭建。

來源與規格

• cargo-dist 官方文件：https://opensource.axo.dev/cargo-dist/
• cargo-dist GitHub Action / 生成流程：https://github.com/axodotdev/cargo-dist
• GitHub Releases 與 latest 行為：https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
• zhtw-mcp 案例 issue：https://github.com/sysprog21/zhtw-mcp/issues/35
• zhtw-mcp 案例 PR：https://github.com/sysprog21/zhtw-mcp/pull/40

下一步路由

• 想理解整體 release 類型分類：回 Package / Library Release CI/CD。
• 想理解 workflow_call 的反向 reuse：讀 CI gate 與 workflow 邊界。
• 想理解 release workflow 紅燈時的處理：讀 CI 失敗到修復發布流程。
• 想理解 artifact 可信度：讀 Artifact Provenance。

概念位置

CD Pipeline 位在 CI 驗證之後，負責 artifact promotion、部署執行、環境保護與回復路徑。

可觀察訊號

• 同一份 artifact 需要在多個環境推進。
• 發布步驟需要審核、權限或時間窗控制。
• 發布失敗時需要可回退或可修復路徑。

接近真實服務的例子

靜態站會在 CI 成功後上傳 artifact 到 hosting。後端服務會推進同一個 image tag 到 staging 與 production，並以 rollout strategy 控制風險。

設計責任

CD Pipeline 要明確定義放行條件、部署順序、例外流程與回復策略，確保發布節奏與風險控制一致。

概念位置

Environment Protection 位在部署 job 與目標環境之間，包含 reviewer、wait timer、branch policy 與 secret scope。

可觀察訊號

• 測試綠燈後仍需要人工批准才能進 production。
• 不同環境需要不同發布權限與審核規則。
• 發布失誤常來自權限配置或保護規則缺失。

接近真實服務的例子

GitHub Actions deploy job 指向 production environment，需指定 reviewer 批准後才可部署。staging 則採自動放行。

設計責任

Environment Protection 要定義環境分層、審核責任、發布時窗與例外流程，讓高風險發布有明確控制面。

概念位置

Rollout Strategy 位在部署執行與正式流量切換之間，常見型態包含 rolling、canary、blue-green 與 phased rollout。

可觀察訊號

• 發布後需要觀察一段時間再擴大流量。
• 高風險變更不適合一次全量切換。
• 團隊需要把監控訊號綁定到擴大量決策。

接近真實服務的例子

後端 API 先以 10% canary 流量觀察錯誤率與延遲，再逐步推進。App 發布以 phased rollout 控制商店推送比例。

設計責任

Rollout Strategy 要定義推進節點、觀察指標、阻擋條件與升降級節奏，讓部署風險可被量化管理。

概念位置

Rollback Strategy 位在 deploy、rollout 與 incident handling 之間，通常要和資料遷移、feature flag 與流量切換一起設計。

可觀察訊號

• 發布後錯誤率或延遲快速升高。
• 新舊版本存在相容性風險。
• 團隊需要在分鐘級別恢復核心功能。

接近真實服務的例子

靜態站可回退前一版 artifact。後端服務可回退 image tag 並暫停新 migration。App 場域可先用 remote config 關閉新功能，再走 hotfix 發版。

設計責任

Rollback Strategy 要定義觸發條件、責任人、回退動作與回復後驗證，並定期演練。

概念位置

Deployment Dry Run 位在 build / test 完成後、production deploy 之前，通常以 preflight check、模擬發布或目標環境校驗實作。

可觀察訊號

• 正式部署常失敗於權限、路徑或配置差異。
• 團隊需要在不影響使用者前提下驗證部署條件。
• 發布流程包含高成本動作或不可逆步驟。

接近真實服務的例子

部署腳本先驗證 artifact 存在、環境密鑰可讀、目標 bucket 或 registry 可寫，再進入正式 deploy。

設計責任

Deployment Dry Run 要定義檢查範圍、成功條件、失敗回饋與執行時機，並和正式部署命令保持一致語意。

概念位置

Migration 位在 build 之後、deploy 與 rollout 之前後的關鍵路徑，常與 release gate、rollback strategy 一起設計。

可觀察訊號

• 新舊版本需要共存一段時間。
• 發布步驟包含 schema 或資料形狀變更。
• 部署失敗時要判斷是否可回退或需要 forward fix。

接近真實服務的例子

後端服務先擴充 schema，再讓新版本寫入新欄位，最後收斂舊欄位讀取；整個過程需要 migration gate 與回退方案。

設計責任

Migration 要定義相容策略、執行順序、觀測指標與異常回復路由，避免部署成功但資料邏輯失效。

場域定位

前端部署和後端部署的差異在於 runtime 責任位置。前端產物通常在 build time 完成大部分工作，發布後由 browser、CDN 或 static hosting 提供服務；後端服務則要在 runtime 處理連線、資料庫、migration、狀態與 rollback。

Build 階段負責產生 browser 實際會執行的內容。真實服務常見訊號是 bundle size、asset hash、base URL、環境變數與 static route 是否穩定；若 build 只能在開發機成功，CI 就要把 Node 版本、package lock、build command 與環境變數收斂成固定入口。

Test 階段負責驗證使用者可見行為。前端常見測試包含 component test、browser regression、accessibility check 與 layout check；測試應盡量靠近 production artifact，讓 dev server 的寬鬆行為不會蓋掉實際部署問題。

Artifact 階段負責保存可發布產物。靜態檔、搜尋索引與 sourcemap 都可能影響使用者體驗與除錯能力；測試與發布共用同一份 artifact，可以避免「測試通過的是 A，發布出去的是 B」的漂移。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。真實風險通常集中在 HTML cache、asset cache、SPA fallback、preview URL 與 production domain 是否對齊。

Rollback Strategy 階段負責讓上一個可用 artifact 能重新服務使用者。前端 rollback 通常比後端快，但若 build time 環境變數、資料 schema 或 CDN cache 已變更，回退仍需要驗證頁面路由與 API 相容性。

常見注意事項

• CDN cache 要和 asset hash、HTML cache policy 分開看。
• Preview environment 要能對應 PR，讓 reviewer 看到真實 build。
• 前端測試要跑在 production-like artifact 上，避免 dev server 行為遮蔽問題。
• 環境變數若在 build time 注入，重新發布才會生效。
• SPA route 需要 fallback 設定，靜態站 route 需要檔案路徑與 base URL 對齊。

學習路線

下一步路由

• 前端 artifact 流程：讀 前端 artifact 與 preview deployment 流程。
• 本 blog 的靜態站案例：讀 本 blog 專案部署。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。

場域定位

後端部署的主要風險來自有狀態依賴與長時間執行。API、worker、scheduler 與 consumer 會連到資料庫、queue、cache 與第三方服務；部署流程需要確認程式、資料與流量切換順序。

Build 階段負責產生可部署服務。後端 build 常見形式是 binary、package 或 container image；判讀重點是版本是否能追到 commit、依賴是否固定、產物是否能在乾淨環境重建。

Test 階段負責驗證服務契約。單元測試只能覆蓋局部邏輯，integration、contract 與 migration 測試才會揭露資料庫、queue、cache 與外部服務之間的相容性風險。

Migration 階段負責推進資料結構與資料狀態。真實服務要支援新舊程式短暫共存，因此 migration 應偏向可漸進、可重試、可觀測，必要時用 forward fix 取代直接回滾資料。

Rollout Strategy 階段負責把流量安全導向新版本。Rolling、canary 與 blue-green 都需要可靠的 health、readiness、metrics 與 log；若 readiness 只檢查 process alive，流量仍可能被送到尚未準備好的服務。

Rollback Strategy 階段負責在新版本失效時縮小影響範圍。後端 rollback 要同時考慮程式、資料、queue message、外部 side effect 與 config；只回退 image tag，通常不足以處理已寫入的資料變化。

常見注意事項

• Migration 要和 app rollout 分開設計，避免新舊版本不相容。
• Health check 只代表 process alive，readiness 才能判斷能否接流量。
• Worker / consumer 部署要考慮重複處理、idempotency 與 consumer lag。
• Config rollout 需要版本化與回退路徑（深入見 Config Rollout）。
• Rollback 不只回程式，也要處理資料與外部副作用（深入見 Rollback Strategy）。

學習路線

下一步路由

• 後端發布主流程：讀 後端 migration、rollout 與 rollback 流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• Backend reliability：讀 模組六：可靠性驗證流程。
• Release gate：讀 6.8 Release Gate 與變更節奏。

場域定位

App 部署的風險集中在 artifact 不可變、簽章憑證、store review 與版本分佈。後端可以快速 rollback，前端靜態站可以重新部署，但已安裝的 App 需要靠更新、feature flag 或服務端相容性管理。

Build 階段負責產生可安裝 artifact。Mobile 常見產物是 IPA、APK 或 AAB，desktop 則可能是 installer 或 signed package；版本號、build number 與 commit 對應關係會決定後續除錯與回報能否追溯。

Signing 階段負責證明 artifact 由可信來源發布。憑證、profile、keystore 與 signing secret 都屬於發布能力；它們需要輪替、權限控管與備援流程，避免單一憑證問題中斷發布（安全治理延伸見 Secret Management）。

Test 階段負責驗證不同裝置與作業系統組合。App 測試常見風險是 emulator 通過但真機失敗、特定 OS 權限模型不同、背景執行限制不同；device matrix 要依使用者分佈與高風險功能選擇。

Release 階段負責把 artifact 送進發行通道。Store review、phased rollout、internal testing、beta track 與 production track 都是 gate；發布節奏要把審核時間與分批比例納入 rollout strategy 的風險控制（backend 延伸見 Config Rollout）。

Rollback Strategy 階段負責處理已安裝版本。App 發布後會長期存在多個使用者版本，因此 hotfix、remote config、kill switch 與後端相容性要一起設計（相容治理延伸見 API Contract）。

常見注意事項

• 簽章憑證是發布能力的一部分，要用 Secret Management 管理。
• 版本號與 build number 要可追溯到 commit 與 artifact。
• Store review 會讓 rollback 和 hotfix 變慢，風險要提前用 feature flag 控制。
• Client / server contract 要支援多版本共存。
• Crash reporting 與 phased rollout 是發布後 gate 的一部分。

學習路線

下一步路由

• App 發布主流程：讀 App 簽章、商店審核與分批發布流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。

概念位置

Readiness / Health Check 位在 rollout、load balancer 與 runtime platform 之間，是流量切換前的核心 gate。

可觀察訊號

• 部署後健康檢查綠燈但請求仍大量失敗。
• 新版啟動中就提早接到流量。
• rollout 失敗時缺少可觀測放行條件。

接近真實服務的例子

Kubernetes liveness 通過只代表 process 存活；readiness 通過才代表連線池、依賴服務與必要資料都已準備完成。

設計責任

Readiness / Health Check 要定義檢查內容、容錯窗口與失敗處理，讓 rollout decision 有可信訊號。

概念位置

Container Registry 位在 image build、scan、promotion 與 runtime deploy 之間，連接 CI 產物與環境發布。

可觀察訊號

• 同一 tag 在不同環境對應內容不一致。
• 部署因拉取權限或鏡像不存在失敗。
• 線上 image 缺少來源與掃描紀錄的反查路徑。

接近真實服務的例子

團隊以 immutable digest 推進 staging 與 production，並透過 registry policy 控制 retention、pull 權限與 promotion 路徑。

設計責任

Container Registry 要定義命名策略、權限模型、保留策略與來源追溯，讓 image 發布具備可審計性。

場域定位

Image 部署常出現在後端、worker、batch job 與自架服務。它把「在哪個環境跑」前移到 build 階段，但也引入 registry、tag、base image、vulnerability scan、SBOM 與 promotion 流程（platform 概念可對照 Container）。

Build 階段負責把 application 與 runtime 封裝成 image。Multi-stage build、dependency cache、base image 與 layer 順序會影響速度、安全性與可重現性；CI 應能從 Dockerfile 與 lockfile 重建同一類產物。

Tag 階段負責讓 image 可追溯。Commit SHA、release tag 與 semver 各自服務不同查詢情境；production 需要能從 running image 反查 source、workflow run 與掃描結果。

Scan 階段負責讓 image 風險可見。Vulnerability scan、secret scan 與 SBOM 能把 base image、OS package 與 dependency 風險顯性化；阻擋門檻要和例外流程一起定義，讓掃描結果能被分流處理。

Registry 階段負責保存與推進 image。真實流程通常需要 retention、immutability、promotion 與權限控管；production image 應來自已驗證 artifact handoff，讓各環境推進同一份產物（供應鏈治理可對照 Artifact Provenance）。

Runtime 階段負責把 image 轉成可運行服務。Kubernetes、Compose、ECS 或其他平台都需要 health check、readiness、resource limit、secret injection（可對照 Secret Management）與 rollback 設計，否則 image 成功不等於服務可用。

常見注意事項

• latest 不適合當 production 追溯依據。
• Base image 要有更新節奏，否則掃描結果會持續惡化。
• Build secret 不應留在 image layer。
• Scan gate 要區分阻擋門檻與可接受例外。
• Promotion 應推進同一份 image，讓 staging 與 production 的差異集中在設定與流量。

學習路線

下一步路由

• Image 供應鏈流程：讀 Image build、scan、registry 與 promotion 流程。
• 後端部署：讀 後端部署 CI/CD。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• Backend deployment platform：讀 模組五：部署平台與網路入口。

概念位置

App Signing 位在 app build 與 release channel 之間，涉及 certificate、provisioning profile、keystore 與 secret 管理。

可觀察訊號

• 發布因簽章失敗中斷。
• 憑證過期導致發版中斷。
• 金鑰輪替缺乏演練造成交付風險。

接近真實服務的例子

iOS 發版需匹配正確 certificate 與 provisioning profile，Android 發版需維護 keystore 一致性與安全儲存。

設計責任

App Signing 要定義密鑰保存、輪替節奏、權限分離與緊急回復流程，確保發布能力可持續。

場域定位

Serverless 發布通常以函式版本為單位，並透過 Function Alias 或流量權重切換。部署步驟看起來短，但對權限、Event Source、重試政策與 observability 欄位要求很高。

常見注意事項

• 部署前要先驗證 runtime 與依賴版本，避免 deploy 成功但 invocation 失敗。
• 事件觸發型函式要明確設定 retry、dead-letter 或回放策略。
• 權限設定要收斂到最小範圍，避免函式擴權風險。
• 冷啟動與併發上限要納入發布後觀測指標。

學習路線

下一步路由

• Serverless 發布主流程：讀 Serverless function 版本、事件來源與回復流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。
• Backend 相關概念：讀 Serverless / worker 相關知識卡。

場域定位

Data pipeline 常包含 batch job、stream processor、dbt model 或 workflow scheduler。部署判斷不只看程式可執行，還要看資料是否可追溯、可對帳、可修復。

常見注意事項

• schema 變更要先定義相容窗口，再切換 downstream。
• Backfill 要有節流與 Checkpoint，避免壓垮上游與儲存層。
• 部署後需比對新舊輸出一致性，建立 correctness check。
• 重跑流程要有 runbook，避免人工臨場判斷失誤。

學習路線

下一步路由

• Data pipeline 發布主流程：讀 Data pipeline backfill、checkpoint 與 rerun 流程。
• 後端資料遷移概念：讀 Migration。
• 資料修補與比對：讀 Backfill 與 Correctness Check。
• Gate 原理：讀 CI gate 與 workflow 邊界。

概念位置

Backfill 位在資料 schema、transform logic 或歷史資料修補之後，常出現在 data pipeline、database migration、search index rebuild 與 feature store 更新。

可觀察訊號

• 新欄位需要從既有資料補值。
• 歷史 partition 需要用新版邏輯重新計算。
• 補算任務需要節流、停損與對帳。

接近真實服務的例子

訂單報表新增 net_revenue 欄位時，pipeline 先讓新資料寫入新欄位，再分批 backfill 過去 12 個月的 partition，並用 row count 與金額總和比對結果。

設計責任

Backfill 要定義補算範圍、批次大小、checkpoint、停損條件與對帳方式，讓歷史資料修補成為可停止、可接續、可驗證的流程。

場域定位

IaC 流程通常分成 plan、review、apply 三段，並依環境分層推進。部署成功不只代表指令完成，還代表資源狀態符合預期且未引入漂移。

常見注意事項

• plan 與 apply 要用同一份輸入與版本，避免結果漂移。
• state backend 要有鎖定與權限隔離，避免併發覆寫。
• 高風險資源變更需要額外 gate（人工審核或變更時窗）。
• Infrastructure Drift 偵測要定期執行，並有修復責任人。

學習路線

下一步路由

• IaC 發布主流程：讀 IaC plan、apply、drift 與 recovery 流程。
• 環境保護：讀 Environment Protection。
• 部署合約：讀 Deployment Contract。
• 變更放行：讀 Release Gate。

概念位置

Checkpoint 位在長時間 job、stream processor、batch pipeline 與 migration 任務之間，常以 partition、offset、run id、cursor 或 processed marker 呈現。

可觀察訊號

• 任務執行時間長，失敗後需要接續。
• 重跑同一區間可能造成重複寫入。
• streaming consumer 需要保存 offset 或 event position。

接近真實服務的例子

資料回填每次處理一個日期 partition，完成後寫入 backfill_runs 表。任務中斷時，下一次從最後成功 partition 的下一段開始。

設計責任

Checkpoint 要定義進度格式、提交時機、失敗恢復、重跑覆寫與觀測欄位，讓長時間任務具備可恢復性。

場域定位

Desktop client 常見於 Flutter Desktop、Electron、Tauri。部署流程通常要分平台建置（macOS、Windows、Linux），並處理安裝體驗、Release Channel 更新節奏與版本共存。

常見注意事項

• 不同 OS 的簽章與公證流程需分開治理。
• Auto-update 要有版本相容策略與 fallback feed。
• 崩潰回報與更新成功率應列為發布後 gate。
• 若與 Flutter App 共用程式碼，要明確區分 mobile 與 desktop 的發布管線。

學習路線

下一步路由

• Desktop 發布主流程：讀 Desktop client 簽章、公證與自動更新流程。
• 行動與客戶端通用觀念：讀 App 部署 CI/CD。
• 簽章治理：讀 App Signing 與 Secret Management。
• 失敗處理：讀 CI 失敗到修復發布流程。

概念位置

Rerun 位在測試失敗、部署預演失敗、資料任務失敗或 pipeline repair 之後，負責判斷重新執行是否會改變輸出或擴大副作用。

可觀察訊號

• 同一 commit 的測試結果前後不一致。
• 資料任務部分成功、部分失敗。
• 部署 dry run 失敗後需要確認是否可安全再跑。

接近真實服務的例子

每日營收 pipeline 第三個 partition 寫入失敗。團隊先確認前兩個 partition 已完成且輸出可覆寫，再指定 run id 與 partition 範圍 rerun，避免重複計算全部歷史資料。

設計責任

Rerun 要定義可重跑條件、輸出覆寫規則、idempotency、觀測結果與人工審核門檻，讓「再跑一次」成為受控恢復策略。

場域定位

套件發佈常見於 NPM、PyPI、Maven、Crates 等生態。發布後會被多個下游專案依賴，因此每次 release 都是公共契約變更。

Release 發布類型分類

「發版」在中文討論裡常被當成單一動作，但實際上有五條互不重疊的通道，每條的觸發條件、產物形式、下游取用方式都不一樣。下游使用者讀 README 時若沒分清楚自己在走哪條通道，很容易踩到「文件寫了安裝指令，但對應通道還沒被建立」的情況。

這五類常常組合出現（例如同時推 source、registry、binary release）。組合愈多、上游維護成本愈高，但下游能用的入口也愈廣。判讀訊號：

• README 寫的是 pip install x → 屬 registry，去 PyPI 確認版本
• README 寫的是 curl ... /releases/latest/download/...sh | sh → 屬 binary release + installer，去 GitHub Releases 確認 asset 存在
• README 寫的是 git clone 後 make → 只走 source，沒任何打包通道
• README 寫的是 docker pull ghcr.io/... → 屬 container image，去 registry 確認 tag

常見注意事項

• 發版前要明確區分 breaking / feature / fix，避免版本語意錯置。
• 發版流程應固定化（tag 規則、changelog 來源、artifact provenance）。
• 對外 SDK 要維持 contract 測試，避免下游升級破壞。
• 套件來源與 token 權限要最小化，並定期輪替。
• README 安裝段落寫的通道，發版前要實際跑過一次 — 「workflow 寫好」不代表「通道已上線」。

安裝路徑分層

Package release 的文件建議同時提供兩條安裝路徑，讓不同風險場景有對應入口。

這個分層能避免單一路徑綁死全部使用者。上游維護者要確保兩條路徑都可用，且文件清楚標示使用時機。可審計路徑的具體範例可直接沿用 Binary release 與 installer 模式 的最小安全基線。

學習路線

下一步路由

• 想理解 binary release + installer 模式（curl … | sh）：讀 Binary release 與 installer 模式。
• 供應鏈與產物可信度：讀 Artifact Provenance。
• 版本契約：讀 API Contract 與 Contract。
• 失敗處理：讀 CI 失敗到修復發布流程。

概念位置

Image Digest 位在 image build、scan、registry promotion 與 runtime deploy 之間，通常以 sha256:... 形式標識 image manifest 或 image index。

可觀察訊號

• latest 或 mutable tag 造成 staging 與 production 內容分叉。
• production runtime 需要反查實際跑的 image。
• 掃描結果需要和部署內容精準對齊。

接近真實服務的例子

CI build image 後推到 registry，scan 報告綁定 digest。Kubernetes manifest 在 production 使用同一個 digest，事故時可從 running pod 反查 workflow run 與 source commit。

設計責任

Image Digest 要納入 deployment manifest、scan report、release note 與 rollback 記錄，讓 image 發布具備可追溯與可審計能力。

概念位置

SBOM 位在 build、scan、release 與 compliance review 之間，常見格式包含 SPDX、CycloneDX 或工具自訂輸出。

可觀察訊號

• 團隊需要知道 image 或 package 包含哪些 dependency。
• 漏洞公告需要快速判斷受影響 artifact。
• 高治理環境要求 release 產物附帶供應鏈證據。

接近真實服務的例子

Container image 發布時同時產生 SBOM，scan gate 依 SBOM 對照 CVE 與 license policy。若 base image 發現 critical vulnerability，團隊可查哪些 release digest 受影響。

設計責任

SBOM 要定義產出時機、格式、保存位置、artifact 對應關係與例外審核流程，讓供應鏈風險可以被查詢與治理。

專案定位

本專案的部署產物是靜態網站。Hugo 負責產生 HTML，Pagefind 負責產生搜尋索引，GitHub Pages 負責 hosting，Playwright 負責驗證搜尋與版面行為。

與通用 CI/CD 的關係

本資料夾是實例層。通用 gate 原理、不同部署場域差異與失敗處理流程放在上層文章；本資料夾只回答「這個 blog 專案現在怎麼部署、失敗時要看哪裡」。術語定義統一回連 CI 知識卡片。

下一步路由

• 本專案 workflow：讀 GitHub Actions workflow。
• 前端部署通用注意事項：讀 前端部署 CI/CD。
• CI gate 原理：讀 CI gate 與 workflow 邊界。
• Markdown CI 規則：讀 Blog Markdown 寫作規範與 mdtools 檢查。

概念位置

Release Channel 位在 artifact 發布與使用者取得之間，常見通道包含 internal、alpha、beta、stable、enterprise、nightly 與 rollback channel。

可觀察訊號

• 同一產品需要內測、公開測試與正式版本分流。
• 錯誤版本需要停止擴散或切回回復通道。
• 客戶端更新需要依風險分批推進。

接近真實服務的例子

桌面 app 先把 signed installer 推到 internal channel，驗證更新成功率後再推 beta channel，最後推 stable channel。若 stable 版本出現 crash，feed 可切回 rollback channel 或暫停更新。

設計責任

Release Channel 要定義通道用途、進入條件、artifact 命名、可見範圍、停損條件與回復路徑，讓版本擴散具備控制面。

概念位置

Update Feed 位在 signed artifact、release channel 與已安裝 app 之間，常包含版本號、下載 URL、signature、checksum、release notes 與最低支援版本。

可觀察訊號

• 客戶端需要自動偵測新版本。
• beta 與 stable 使用者需要看到不同版本。
• 錯誤版本需要從更新來源撤下。

接近真實服務的例子

Electron app 啟動時讀取 stable feed，取得最新 signed installer 與 signature。若新版本 crash rate 升高，團隊先撤下 feed 指向，讓未更新使用者停止取得錯誤版本。

設計責任

Update Feed 要定義簽章驗證、channel 分流、版本比較、fallback installer、撤版策略與 telemetry，讓已安裝客戶端安全升級。

概念位置

Infrastructure Drift 位在 IaC state、cloud resource、手動 hotfix 與外部 controller 之間，常由 console edit、事故修復、provider 預設值或自動調整造成。

可觀察訊號

• plan 顯示大量非預期變更。
• production 資源和 repository 宣告不一致。
• 下次 apply 可能覆蓋事故 hotfix。

接近真實服務的例子

事故中工程師在雲端 console 手動放寬 security group。服務恢復後，IaC plan 顯示 security group 與宣告檔不同；團隊需要判斷這個變更是短期 hotfix 還是應回寫成正式規則。

設計責任

Infrastructure Drift 要定義偵測頻率、owner、修復路由、state repair 與回寫規則，讓平台狀態重新回到可審查流程。

概念位置

State Lock 位在 IaC state backend、plan / apply workflow 與平台資源之間，常由 Terraform backend、Pulumi state 或平台鎖定機制提供。

可觀察訊號

• 多個 pipeline 同時 apply 同一個 workspace。
• state file 出現併發覆寫或 partial apply 後不一致。
• apply 長時間卡住需要判斷 lock 是否仍有效。

接近真實服務的例子

兩個 PR 同時修改 production network。第一個 workflow 取得 state lock 後進入 apply，第二個 workflow 等待或失敗，避免兩次變更同時寫入 state。

設計責任

State Lock 要定義 lock backend、timeout、人工解鎖條件、環境隔離與失敗處理，讓 IaC apply 保持序列化。

概念位置

Function Alias 位在 function version、traffic weight、event source 與 invocation entrypoint 之間，常見於 Lambda alias 或其他 serverless 平台的版本別名。

可觀察訊號

• 新舊 function version 需要短暫共存。
• 部分流量需要導向新版本做 canary。
• 事故時需要把入口切回上一個版本。

接近真實服務的例子

HTTP function 的 prod alias 先把 5% 流量導向 version 42。若錯誤率穩定，逐步提高權重；若錯誤率升高，alias 切回 version 41。

設計責任

Function Alias 要定義版本命名、流量權重、觀測指標、事件來源綁定與回復條件，讓函式發布具備可控入口。

概念位置

Event Source 位在 queue、topic、HTTP gateway、object storage、scheduler 與 function / worker 之間，負責把外部事件轉成執行請求。

可觀察訊號

• 函式部署成功，但 invocation 因 trigger 設定失敗。
• Queue event 重試造成同一筆資料被重複處理。
• 事件 schema 漂移導致 subscriber 解析失敗。

接近真實服務的例子

Queue 觸發的 function 以 batch 方式處理訊息。新版本解析失敗時，訊息進入 dead-letter queue；團隊先停用 trigger，再修復 function 或重放事件。

設計責任

Event Source 要定義 trigger 條件、batch size、retry、dead-letter、replay、權限與 schema 契約，讓事件驅動發布具備可觀測回復路徑。

概念定位

Artifact 是 CI/CD 流程中的交付單位。前端可能是 dist/，後端可能是 binary 或 image，App 可能是 IPA / AAB，資料任務可能是 DAG 或 query package；不同形式的 artifact 都承擔同一個責任：把 source change 轉成可驗證、可保存、可推進的產物。

Build once 的責任是降低環境漂移。若 test job 與 deploy job 各自 build，一個 lockfile、環境變數或 base image 差異就能讓兩份產物不同；此時 CI 綠燈不再能證明 production 內容可信。

Verify once 的責任是把測試結果綁到具體產物。測試應輸出 artifact identity，例如 checksum、Image Digest、release asset name 或 bundle version，讓 reviewer 能確認紅綠燈對應哪份內容。

Artifact handoff 的責任是在 job 邊界保留身分。Upload / download artifact、registry digest、release asset、package registry 與 object storage 都可以做 handoff；重點是交接時沿用既有產物。

Promote same artifact 的責任是讓環境差異集中在設定與流量。Staging 驗證過的 image、package 或 static artifact 應被推進到 production；若 production 重新 build，就需要重新驗證 production 那份產物。

Recover artifact 的責任是讓 rollback 有實體目標。沒有保留 artifact 的 rollback 會變成「從舊 commit 重新 build」，這會受到依賴、base image、registry、toolchain 與時間漂移影響。

可重播性檢查

可重播性檢查的責任是確認產物身分與建置條件足夠明確。嚴格 reproducible build 很難在所有專案做到，但 CI/CD 至少要達到「同一次 workflow 的產物可以被查詢、保存、驗證與重新部署」。

這張表讓團隊知道自己目前在哪個成熟度。初期可以先做到 source、dependency、identity；高治理場景再補 SBOM、signature 與 provenance。

常見反模式

反模式的共同問題是讓「綠燈」失去指向性。當綠燈不知道對應哪份產物，CI/CD 只剩下命令執行紀錄。

下一步路由

• Artifact 術語：讀 Artifact。
• Artifact handoff：讀 Artifact Handoff。
• Gate 邊界：讀 CI gate 與 workflow 邊界。

CI/CD 的責任是提供一致的判讀入口。當 workflow 顯示失敗時，團隊需要能快速判斷是 lint、test、build、package、Artifact Handoff、deploy 還是 Rollback Strategy 階段出問題，並知道下一步該回到本機重現、修正、重新提交，還是暫停發布。

前置知識卡片

用原子化卡片整理 Artifact、Required Checks、Artifact Handoff、Environment Protection、Preview Environment、Rollout Strategy、Rollback Strategy、Migration、Backfill、Image Digest、Release Channel、Infrastructure Drift、Function Alias 與 Flaky Test 等核心術語。流程文章專注情境判讀與決策順序，術語背景交由卡片維持一致。

學習路線

學習路線先從失敗處理與 gate 邊界開始，因為 CI/CD 的價值會在紅燈時最清楚。當讀者能判讀失敗位置與下一步路由，再依部署場域進入前端、後端、App、Docker 或本 blog 專案案例。

與其他教學的分工

CI/CD 教學負責日常工作流程與部署場域差異，Backend 可靠性模組負責系統層可靠性判斷。讀者想知道 workflow 失敗後怎麼修、發布 gate 怎麼切、前端與後端部署流程差在哪裡，讀本系列；想知道 CI 在 release gate、SLO、load test 與可靠性治理中的位置，回到 模組六：可靠性驗證流程。

Go、Python 或其他語言教材只需要保留測試寫法與本機命令。當內容開始涉及 workflow event、required checks、preview deployment、container registry、mobile signing、artifact、cache 或 branch protection，就應該移到本系列，讓不同語言共用同一套 CI/CD 操作語意。

判讀訊號

• GitHub Actions 紅燈後，不知道該看哪個 job。
• 本機測試通過，但 CI 失敗。
• 測試失敗後仍有部署 workflow 啟動。
• deploy 失敗時，團隊分不清 build artifact、部署權限與測試 gate 的責任。
• 前端、後端、App 與 Docker 使用同一套發布說明，導致場域細節混在一起。
• workflow 只有命令清單，沒有說明失敗後的處理路由與部署場域邊界。

下一步路由

• 想處理 GitHub Actions 紅燈：讀 CI 失敗到修復發布流程。
• 想理解 CI gate 原理：讀 CI gate 與 workflow 邊界。
• 想理解前端部署：讀 前端部署 CI/CD。
• 想理解後端部署：讀 後端部署 CI/CD。
• 想理解 App 發布：讀 App 部署 CI/CD。
• 想理解 Docker / image 流程：讀 Docker / Image 部署 CI/CD。
• 想理解 Serverless 發布：讀 Serverless 部署 CI/CD。
• 想理解資料處理任務發布：讀 Data Pipeline 部署 CI/CD。
• 想理解 IaC / 平台變更發布：讀 IaC / Platform 部署 CI/CD。
• 想理解 Flutter/Electron/Tauri 類客戶端發布：讀 Desktop Client 部署 CI/CD。
• 想理解 SDK / NPM / PyPI 發版：讀 Package / Library Release CI/CD。
• 想維護本 blog 的 workflow：讀 本 blog 專案部署。
• 想讓測試與發布共用同一份產物：讀 Artifact 與可重播性。
• 想治理不穩定測試：讀 Flaky test 治理。
• 想理解可靠性層的 CI 分層：讀 6.1 CI pipeline。
• 想理解發布 gate：讀 6.8 Release Gate 與變更節奏。
• 想理解 infra 變更的 plan / apply 流程怎麼走 CI：讀 Infra 走 PR 流程與自動化護欄。

核心術語

卡片與流程文章分工清楚。卡片負責名詞與邊界，流程文章負責情境判讀與操作路由。