這個模組處理的是升級的操作框架與各類型的專屬風險，跟成熟度階梯平行而非串行——升級可能發生在任何成熟度階段。跟接手維運的關係是：接手後的下一步常常就是升級（接手一個 PHP 5.6 的站台，穩定維運後第一個任務就是升 PHP 版本）。

章節文章

跟其他模組的關係

• → 接手維運：接手後穩定維運的下一步常是升級
• → 模組負一：還沒有 infra 的環境：升級過程中建立的操作紀律可以對齊這裡
• → 模組一：最小可行 IaC：升級是導入 IaC 的好時機——新環境用 IaC 建、舊環境手動退役
• → 模組五：核心服務上 IaC：資料庫和運算平台的升級涉及 stateful 資源的特殊處理

這個模組處理的是接管的操作流程，跟成熟度階梯平行而非串行 — 接手可能發生在任何成熟度階段：接手一個只有 FTP 存取的 PHP 站、接手一個有 SSH 但沒有 IaC 的雲端環境、接手一個有半套 IaC 但文件缺失的專案。每種情境的約束不同，但操作原則相通：先拍現況、再建維運能力、最後逐步正規化。

章節文章

跟其他模組的關係

接手維運的終點是把環境帶到模組負一（可控的手動）或模組一（最小可行 IaC）的狀態。接手流程本身不做 IaC 導入 — 它的責任是讓接手者理解環境、建立維運能力、確認什麼能動什麼不能動。IaC 導入是接手完成之後的下一步。

• → 模組負一：還沒有 infra 的環境：接手完成後，環境的操作紀律對齊這裡
• → 模組零：infra 是什麼：成熟度階梯作為接手後評估現況的座標
• → 模組二：身分與憑證：接手時的 credential 盤點與輪替
• → 模組八：治理好習慣：接手後的 tagging 與 secret 管理

把手動環境做成「可控的手動」

可控的手動指的是一種中間狀態：資源還是手點的，但關鍵變更有痕跡、高風險操作有護欄、現實長什麼樣有紀錄。它的責任是降低兩種成本 — 當下出事的成本，以及未來把資源 import 進 IaC 的成本。手動起家是絕大多數服務的常態起點，從一個人驗證想法到小團隊接手都會經過這一階，把它當成需要管理的階段、而不是需要修正的錯誤。

判讀自己是否「可控」的訊號很具體：能不能在五分鐘內說出 production 有哪些對外開放的 port、上週誰動過資料庫參數、刪掉某台機器會不會連帶弄壞別的東西。任何一題答不出來，代表這個手動環境的不可見區域正在擴大，下面幾節就是把這些區域逐一收斂。

先守住代價最高的底線

護欄要先上在「一次失誤就難以挽回」的操作上，因為手動環境沒有 IaC 的 plan / diff 當預檢，人為操作直接生效。優先級看的是失誤的回退代價、不是操作頻率。

長期憑證外洩是回退代價最高的一類。手動環境常見的反模式是把長期 access key 寫進腳本、CI 變數或開發者筆電，一旦外流，攻擊者拿到的是不會過期的權限。在還沒有完整 IAM 設計之前，最低成本的護欄是：對人改用會過期的登入工作階段（如 AWS IAM Identity Center 的臨時憑證），對自動化盡量改用平台原生的角色綁定，把還在用的長期 key 列一張清單、設定定期輪替。身分與憑證的完整地基在「模組二：身分與憑證地基」展開，這裡先擋住最容易致命的那一個。

刪除 production 資源是第二類。手動操作沒有「先看會影響什麼」的步驟，刪一個 security group 或 volume 可能瞬間讓服務失聯。對承載狀態的資源（資料庫、儲存桶、有持久資料的磁碟）開啟平台的刪除保護（如 termination protection、deletion protection），讓誤點多一道阻力。網路規則的大改是第三類 — 調整 VPC 路由、subnet 或對外規則時，先確認回退方式存在再動手，網路地基的系統性設計在「模組三：網路地基」。

這三類的共同點是：護欄成本低、失誤代價高，所以即使還沒有 IaC，CP 值也足以先做。

讓變更留下痕跡

變更留痕的責任是讓「誰、在什麼時候、改了什麼、為什麼」事後可追溯，這是手動階段最接近版本控制的替代品。IaC 的 git history 天然提供這件事，手動環境得靠人為紀律補上。

最低限度是一份變更日誌，可以只是 repo 裡的一個 CHANGELOG 或團隊共用文件，每次動 production 就追加一行：時間、操作者、改了哪個資源、原因。它不需要漂亮，需要的是每次都寫。和它互補的是平台的稽核日誌（如 AWS CloudTrail），稽核日誌記錄 API 層級「發生了什麼」，人寫的日誌補上「為什麼」— 前者你查得到某個 security group 在幾點被改，後者你才知道那次改動是為了什麼需求。兩者一起，事故排查時才能從「哪裡變了」一路追到「能不能安全回退」。

常見陷阱是只在「大改動」時才記錄，結果真正出事的往往是某次以為無關緊要的小調整。判準簡化成一句：只要這個操作別人事後可能需要知道，就記。

命名與 tagging 從手動階段就開始

命名規範與資源標籤是降低未來 import 成本的最低成本投資，它的責任是讓每個資源自帶「我是誰、屬於哪個服務、誰負責、哪個環境」的身分資訊。手動點出來的資源若名稱是 test-2、new-db-final，日後納管時得靠人逐一辨認哪個還在用、屬於哪條業務線，這個考古成本遠高於當初多打幾個字。

從手動階段就固定一套規則：資源名稱帶上服務與環境（如 payments-api-prod），標籤至少包含 service、env、owner 三個維度。這套規則在還沒 IaC 時靠人手動填，等到導入 IaC，這些標籤直接成為 Terraform 把現有資源對應到程式碼的依據，也是模組八治理習慣裡成本歸因與批次操作的基礎（見「模組八：治理好習慣」的 tagging 段）。先建立規範的價值在於：早一天統一，需要回頭重命名的資源就少一批。

盤點現有資源作為納管輸入

資源盤點的責任是把「現實長什麼樣」寫成一份清單，它是日後納管的直接輸入 — 不知道有什麼，就無法決定先 import 什麼。手動環境最危險的是沒人記得還開著的資源。

盤點不必一次到位，先用平台工具把現況拉出來，存成可比對的形式：

1# 列出某區域所有 EC2 instance 與其關鍵標籤
2aws ec2 describe-instances \
3  --query 'Reservations[].Instances[].[InstanceId,Tags,State.Name]' \
4  --output table
5
6# 列出所有 security group 與開放規則，找出對外開放的 port
7aws ec2 describe-security-groups \
8  --query 'SecurityGroups[].[GroupId,GroupName,IpPermissions]' \
9  --output json

把輸出存進 repo，定期重跑比對差異，就能看出環境在背景悄悄長出了什麼。這份清單同時服務三件事：當下的安全盤查（有沒有不該開的對外 port）、未來 IaC import 的範圍界定、以及成熟度評估時「全手動到底有多少資源」的事實基礎（成熟度階梯的定位見「模組零：infra 是什麼」）。

資源與信任不足下的高槓桿取捨

當時間、人力或上層信任都不足，無法一次把上面每件事做齊時，取捨原則是先做「失誤代價高且護欄成本低」的少數幾件。在這個情境下，最划算的通常是兩件：先擋長期憑證外洩，因為一次外洩可能拖垮整個帳號；再開啟有狀態資源的刪除保護，因為資料一旦刪除多半無法復原。

變更日誌與資源盤點屬於累積型投資 — 越早開始，未來省的考古成本越多，但晚一週開始不會立刻出事，所以在資源極度受限時可以排在護欄之後。命名與 tagging 的取捨點在於：新建資源時順手套規則幾乎零成本，回頭重整存量資源才貴，所以策略是「新的一律照規範、舊的等有餘力再補」，而不是停下來先整理全部存量。資源不足時怎麼跟上層談這些工作的優先級，在「模組九：怎麼把 infra 推動起來」展開。

該開始導入 IaC 的訊號

手動環境到了某些訊號出現時，繼續手動的邊際成本會超過導入 IaC 的一次性成本，這就是該往模組一跨進去的時機。訊號是規模與協作的函數，不是時間的函數。

第一個訊號是環境數量變多：當你需要 dev、staging、production 三套幾乎一樣的環境，手動複製會在環境之間留下難以察覺的差異，而 IaC 的價值正是用同一份程式碼複製環境。第二個是多人同時動資源：一個人手動操作還能靠記憶維護，兩三個人並行時，沒有 plan / review 的手動變更會互相覆蓋、互相破壞。第三個是環境爆炸頻率上升：如果「改一個設定結果弄壞別的東西」這類事故開始每月發生，代表手動環境的隱性依賴已經超過人腦能追蹤的上限。

任一訊號穩定出現，就是把第一個資源納入 IaC 的起點 — 前面做的命名、tagging、資源盤點此時直接成為 import 的輸入，第一步怎麼跨進去在「模組一：最小可行 IaC」。在訊號出現前過早導入 IaC 也有代價：單人、單環境、低變更頻率時，IaC 的學習與維護成本可能高於它省下的手動工，所以這裡的判準是等訊號、不是趕進度。

章節文章

跨分類引用

• → 模組零：infra 是什麼：成熟度階梯上「全手動」這一階的定位
• → 模組一：最小可行 IaC：訊號出現後，第一步怎麼跨進 IaC
• → 模組二：身分與憑證地基：長期憑證護欄的系統性設計
• → 模組三：網路地基：手動階段網路大改的回退考量、之後的系統性設計
• → 模組八：治理好習慣：tagging 在成本歸因與批次操作的後續價值
• → 模組九：怎麼把 infra 推動起來：資源不足時怎麼跟上層談優先級
• → 接手維運：別人建的環境怎麼接管：接手前人的專案時的盤點與接管流程

Phase 1：差異評估

差異評估的產出是一份 change manifest——列出所有已知的新舊差異、每項的風險等級、以及需要的應對措施。這份清單是後續所有階段的依據：平行環境要驗證清單上的每一項、切換策略要先處理高風險項、退役前要確認清單上的所有相容性問題都已解決。

差異的三個維度

第一個維度是目標本身的變化。版本升級要看 changelog、breaking changes list、deprecated features list。平台遷移要看兩個平台的功能差異（共享主機沒有的 cron 彈性、VPS 有的 SSH 存取）。資料庫升級要看 SQL 語法差異、預設行為變更（如 MySQL 8.0 的 caching_sha2_password 預設認證方式）。

第二個維度是依賴關係。升級 PHP 版本時，所有 Composer 套件都可能受影響；升級 MySQL 時，ORM 的 SQL 生成可能不相容；遷移平台時，原本靠主機面板設定的 cron job 要改用系統 crontab 或雲端排程。依賴關係沒列完整，平行環境的測試就會漏掉受影響的元件。

第三個維度是過渡期的雙版本相容性。升級不是瞬間完成的——在切換的過程中，系統的某些部分跑新版本、某些部分跑舊版本。這段期間兩個版本必須能共存：資料庫的 schema 要同時相容新舊版本的程式碼、API 的回應格式要讓新舊版本的客戶端都能處理、session 格式要能跨版本延續。

風險分級

每一項差異分級後，高風險和阻塞項決定升級的可行性與時程。阻塞項超過團隊能處理的量時，升級可能需要拆成多個階段（先升到中間版本、再升到目標版本）或延後。

時程與管理層報告

差異評估的時程通常佔整個升級的 20-30%——看起來「還沒開始做」但這段時間的產出（change manifest）決定了後面所有階段的範圍。向管理層報告時用 change manifest 的風險分級表：「共 N 項差異，其中 X 項低風險、Y 項中風險、Z 項高風險、W 項阻塞。中高風險項的處理估計 M 天，阻塞項的替代方案評估需要額外 K 天。」

Phase 2：平行環境驗證

平行環境驗證的責任是用事實證明「新版本在跟 production 相同的條件下能正常運作」。它的產出是一份驗證報告——每一項 change manifest 上的差異都標上「已驗證通過 / 有問題待修 / 不影響」。沒有這份報告就切換，等於在賭新版本會正常。

建立平行環境

平行環境跟 production 越相似，驗證結果越可信。理想狀態是完全複製 production 的架構（同規格、同設定、同網路拓撲），只差目標元件的版本不同。成本限制下的折衷是用縮小版（較小的 instance、較少的資料量），但關鍵設定（PHP 模組、MySQL 參數、安全設定）必須跟 production 一致。

資料的處理要特別注意。用 production 的資料副本驗證最可靠（能觸發真實的邊界狀況），但如果資料含 PII，需要先脫敏處理。另一個選項是用 staging 環境的資料，但要確認 staging 的 schema 跟 production 一致——schema drift 會讓驗證結果失真。

驗證清單

平行期的時間長度

平行環境跑多久才能切換？取決於業務週期。如果系統有月結、季結的批次處理，平行環境至少要跑過一次完整週期。電商系統要跑過至少一個促銷活動。沒有明顯週期的系統，一到兩週的平行驗證通常足夠發現主要問題。

Phase 3：分批切換

分批切換的核心原則是不一次切 100%——先把最低風險的流量導到新環境，觀察一段時間確認正常，再逐步增加比例。

切換策略

共享主機通常只能用維護窗口策略——沒有 load balancer 做流量分配、沒有 DNS 權重可調。維護窗口的關鍵是時間規劃：備份（15 分鐘）→ 切換（30 分鐘）→ 驗證（30 分鐘）→ 恢復或回退（15 分鐘），在窗口內必須完成全部步驟，超時就回退。

切換期間的監控

切換開始後要密切觀察的指標：

• 錯誤率：5xx / 4xx 比例相對於切換前的基線
• 回應時間：p50 和 p99 相對於基線
• 業務指標：轉換率、訂單數、付款成功率（如果適用）
• 外部整合：第三方 callback 是否正常

回退觸發條件

在切換前就定義好回退條件，避免事故發生時還要開會決定要不要退：

• 錯誤率超過基線的 2 倍持續 5 分鐘 → 回退
• 核心業務流程失敗（登入、結帳、金流） → 立刻回退
• 回應時間超過基線的 3 倍持續 10 分鐘 → 回退

回退不是失敗——它是風險控制機制的正常運作。回退後排查問題、修正、重新走 Phase 2 驗證、再嘗試切換。

切換的通知

Phase 4：退役舊環境

切換完成後不要立刻刪掉舊環境——保留 1-2 週的冷備。這段時間處理長尾問題：DNS 快取還沒更新的客戶端、排程任務還指向舊 endpoint 的外部系統、舊環境上可能還有未遷移的資料。

退役前的檢查

• 舊環境的存取 log 是否歸零？（有流量代表還有東西指向它）
• 所有 cron job 是否都已在新環境運行？
• 外部系統的 webhook / callback URL 是否都已更新？
• 舊環境上有沒有需要歸檔的資料？（log、上傳檔案、備份快照）

退役步驟

1. 停止舊環境的應用服務（但不刪除）
2. 觀察 1 週——如果有問題可以快速重啟
3. 匯出需要保留的資料（log、uploaded files）
4. 刪除舊環境的運算資源（VM、容器）
5. 保留舊環境的最後一份備份 30 天，作為最後的保險
6. 清理舊環境的 DNS 記錄、SSL 憑證、IAM 角色

貫穿全程的升級紀律

一次只升一個東西

同時升級 PHP 版本 + 遷移到新主機 + 重構資料庫 schema，出問題時無法判斷是哪個變更造成的。每次升級只改一個主要元件，穩定後再升下一個。如果業務壓力要求一次完成，至少在 Phase 2 的驗證環境裡逐一引入、逐一確認。

每個階段轉換前備份

Phase 1 結束前備份 production 現況、Phase 3 切換前備份、Phase 4 退役前備份。三份備份各自獨立、各自有還原驗證。備份不只是「做了」——要實際測試過還原，確認備份的完整性。

記錄每一步

每個升級操作記錄在 repo 的 changelog 裡：什麼時間、誰做的、改了什麼、觀察到什麼結果。升級出問題時，changelog 是回溯「上一步做了什麼」的唯一依據。

在平行階段就練習回退

不要等到 Phase 3 切換時才第一次嘗試回退。在 Phase 2 的平行環境裡，刻意從新版本切回舊版本一次，確認回退路徑能走通、回退後服務能正常恢復。回退的演練跟升級的驗證同等重要。

跨分類引用

• → 接手維運：接手後穩定維運的下一步常是升級
• → 模組五：核心服務上 IaC：stateful 資源（RDS、S3）的升級涉及特殊的備份與切換策略
• → 模組八：治理好習慣：升級期間的變更紀錄對齊治理紀律
• → 模組七：infra 走 PR 流程：升級涉及的 IaC 變更走 PR review

判讀自己是否可控

可控的手動環境能在五分鐘內回答以下問題：

1. production 有哪些對外開放的 port？
2. 上週誰動過資料庫參數，動了什麼？
3. 刪掉某台機器會不會連帶弄壞別的東西？
4. 現在用了幾把長期 access key，每把用在哪裡？
5. 有沒有一份清單能對照 Console 上的資源，確認沒有漏掉的？

五題都能答的團隊不多，目標也不是一次全通。辨識出哪些區域不可見，按傷害代價從高到低逐一收斂，就是這一章的路線。

護欄先上在回退代價最高的操作

手動環境沒有 IaC 的 plan / diff 當預檢，人為操作直接生效。護欄的優先級看的是失誤的回退代價，不是操作頻率。回退代價最高的三類操作各自有最低成本的防線。

長期憑證外洩

長期 access key 一旦外流，攻擊者拿到的是不會過期的權限。回退代價高的原因不只是撤銷這把 key 本身，而是要找出所有使用它的地方同步更換 — 而「所有使用它的地方」在手動環境裡幾乎沒有完整清單。一把用了半年的 key 可能已經被複製到 CI 環境變數、某個同事的測試腳本、一個早已被遺忘但還在跑的 cron job 裡。

最低成本的護欄分三步。第一步是盤點：列出帳號裡所有長期 access key，記下建立時間、上次使用時間與對應用途。

1aws iam generate-credential-report
2aws iam get-credential-report --output text --query Content | base64 -d

第二步是替換路徑。對人類操作者，改用會過期的登入工作階段（如 AWS IAM Identity Center 的臨時憑證，幾小時後自動失效）。對跑在雲上的自動化（EC2 上的腳本、ECS task），改用平台原生的角色綁定 — instance profile 或 task role 會自動輪替短期憑證，程式碼不需要存任何 key。對跑在雲外的 CI/CD（如 GitHub Actions），改用 OIDC 聯合（見模組二：身分與憑證地基）。

第三步是輪替紀律。把還在用的長期 key 設定定期輪替提醒（60 天或 90 天，對齊 AWS IAM credential report 的建議週期），每次輪替時問自己：這把 key 能不能這次就換成臨時憑證，讓它成為最後一次輪替？

刪除 production 資源

在 Console 選中一個 security group 按刪除，平台可能只問「確定嗎？」就直接執行，不會告訴你有三個 EC2 instance 正在引用這個 group。EBS volume 被刪除後，上面的資料就不存在了 — 除非之前有做 snapshot，而手動環境裡有沒有做 snapshot 通常取決於某個人的記憶。

對承載狀態的資源，最低成本的護欄是開啟平台的刪除保護：

1aws rds modify-db-instance \
2  --db-instance-identifier payments-prod \
3  --deletion-protection \
4  --apply-immediately
5
6aws ec2 modify-instance-attribute \
7  --instance-id i-0abc123 \
8  --disable-api-termination

RDS 有 deletion_protection，EC2 有 termination_protection，S3 bucket 可以開 MFA delete。這些機制把「一鍵刪除」變成「先關保護再刪除」兩步操作，擋不住蓄意刪除，但能擋住手滑跟批次操作的誤傷。

刪除保護之外，備份是另一道防線。手動環境裡至少確認 RDS 的自動備份是開著的（預設保留 7 天），以及 S3 bucket 的 versioning 是開著的。S3 bucket 的 versioning 預設是關的，一個沒開 versioning 的 bucket，覆寫或刪除物件後就回不去了。

網路規則的大改

手動調整 VPC 路由、subnet 關聯的 route table、或 security group 的入站規則，影響範圍跨越多個服務，而且在手動環境裡沒有版本控制可以 diff 改了什麼。一條路由改錯，某些 private subnet 的服務可能瞬間失去出站能力。

最低成本的護欄是「改之前先把現況存下來」：

1aws ec2 describe-security-groups \
2  --group-ids sg-0abc123 \
3  --output json > sg-backup-$(date +%Y%m%d).json

用 CLI 把當前的 security group 規則、route table 設定匯出一份 JSON。改完後如果出問題，這份 JSON 就是回退的依據。這不是自動回退 — 手動環境沒有那個能力 — 但至少讓「改回去」有個明確的目標狀態。網路地基的系統性設計在模組三：網路地基展開。

該先做什麼

這三類護欄的共同判準是：護欄成本低（幾條 CLI 指令或 Console 設定）、失誤代價高（憑證外洩、資料遺失、服務中斷）。判讀某個資源該不該現在就加護欄，問自己一個問題：「這個資源出事的回退時間是分鐘級、小時級、還是不可回退？」不可回退的（資料刪除、key 外洩）優先加；分鐘級可回退的（重啟一個 stateless service）可以排後面。

讓變更留下痕跡

變更留痕的責任是讓「誰、在什麼時候、改了什麼、為什麼」事後可追溯。IaC 的 git history 天然提供這件事，手動環境得靠人為紀律補上。

人工變更日誌

最低限度是一份變更日誌，可以只是 repo 裡的一個 markdown 檔或團隊共用文件。一條記錄至少包含四個欄位：

1## 2026-06-20
2
3- **操作者**：alice
4- **資源**：sg-0abc123 (payments-api-prod)
5- **變更**：新增 ingress rule, port 8080 from 10.0.0.0/16
6- **原因**：內部監控服務需要存取 health check endpoint
7- **回退方式**：刪除該 ingress rule

格式不需要精美，需要的是「每次都寫」。常見陷阱是只在「大改動」時才記錄，結果真正出事的往往是某次以為無關緊要的小調整 — 改了一個 parameter group 的值、調了一條路由的目標、把某個 instance 的 security group 換了一個。判準簡化成一句：只要這個操作別人事後可能需要知道，就記。

平台稽核日誌

和人工日誌互補的是平台的稽核日誌（如 AWS CloudTrail、GCP Audit Log）。稽核日誌自動記錄 API 層級「發生了什麼」— 某個 IAM user 在某個時間對某個資源呼叫了哪個 API — 不依賴人為紀律、也不會漏。但它只記錄事實，不記錄意圖。它告訴你 security group 在幾點被改，卻不告訴你改的原因。人寫的變更日誌補上的正是「為什麼」這一段。

1aws cloudtrail describe-trails \
2  --query 'trailList[].{Name:Name,S3Bucket:S3BucketName}'
3
4aws cloudtrail lookup-events \
5  --lookup-attributes AttributeKey=EventName,AttributeValue=AuthorizeSecurityGroupIngress \
6  --max-items 10

CloudTrail 在 AWS 帳號裡預設開啟 management event 的 90 天查閱。手動環境裡至少確認 management event 的 trail 存在且在寫入 — 這是事後回推「到底誰動了什麼」的最後防線。兩者一起，事故排查時才能從「哪裡變了」一路追到「為什麼改、能不能安全回退」。

命名與 tagging 從手動階段就開始

命名規範與資源標籤讓每個資源自帶「我是誰、屬於哪個服務、誰負責、哪個環境」的身分資訊。手動點出來的資源若名稱是 test-2、new-db-final、temp-sg，日後納管時得靠人逐一辨認哪個還在用、屬於哪條業務線，考古成本遠高於當初多打幾個字。

命名規範

從手動階段就固定一套命名規則，讓名稱本身攜帶足夠的上下文。一個實用的格式是 {service}-{component}-{env}：

命名不需要完美或涵蓋所有維度，需要的是一致。同類資源都用同一套格式，人眼掃一頁 Console 就能分辨「這個屬於 payments 的 prod」跟「這個屬於 auth 的 dev」。不一致的命名（有些用底線、有些用連字號、有些帶 env 有些不帶）會在日後盤點時讓每個資源都變成需要考古的謎題。

最小 tag 集合

標籤至少包含三個維度：

手動階段的 tag 靠人工填。在 Console 建資源時順手加 tag 幾乎零成本 — 多打三行字而已。但如果沒有約定「哪些 tag 是必填」，多數人會跳過。最低限度的紀律是：在團隊文件裡寫下「建任何資源前先填這三個 tag」，並在每次盤點時檢查有沒有漏標的資源。

這套規則在導入 IaC 後直接升級成 Terraform 的 default_tags — 自動套用、不靠人記（見模組八：治理好習慣）。先在手動階段建立習慣，導入 IaC 時只是換一個強制機制，而不是從零學起一套分類法。

盤點現有資源作為納管輸入

資源盤點把「現實長什麼樣」寫成一份清單，它是日後納管的直接輸入。接手別人建的環境時，盤點的範圍和方法更完整的版本見接手維運模組。手動環境裡最難管理的是未標記的閒置資源 — 測試用的 EC2、實驗用的 RDS — 持續計費但沒有標籤，無法用查詢系統性找出，也無法確認是否仍有服務依賴。

盤點方法

按資源類型分批拉，每批存一份 JSON 或 CSV 進 repo：

 1aws ec2 describe-instances \
 2  --query 'Reservations[].Instances[].[InstanceId,InstanceType,State.Name,Tags[?Key==`Name`].Value|[0],Tags[?Key==`env`].Value|[0]]' \
 3  --output table
 4
 5aws rds describe-db-instances \
 6  --query 'DBInstances[].[DBInstanceIdentifier,Engine,DBInstanceClass,MultiAZ,DeletionProtection]' \
 7  --output table
 8
 9aws ec2 describe-security-groups \
10  --query 'SecurityGroups[].[GroupId,GroupName,IpPermissions]' \
11  --output json > security-groups-$(date +%Y%m%d).json
12
13aws s3api list-buckets --query 'Buckets[].Name'

盤點後的三件事

這份清單同時服務三個目的。

當下的安全盤查：security group 清單裡有沒有不該開的對外 port？有沒有 EC2 直接掛著公網 IP 卻不是 load balancer？用 0.0.0.0/0 搜一遍 security group 的輸出，命中的每一條都要能說出「這個全開是故意的、理由是什麼」。

未來 IaC import 的範圍界定：哪些資源該先 import。判準是「改動頻率」與「改錯代價」的乘積 — 頻繁改動且改錯代價高的（security group、IAM role）先排進來，很少動的（一個已經穩定的 S3 bucket）可以排後面。

成熟度評估的事實基礎：成熟度階梯的定位（見模組零：infra 是什麼）需要知道「全手動到底有多少資源、分布在幾個帳號、跨幾個 region」，這份清單就是評估的輸入。

盤點的節奏

第一次盤點最花時間，因為很多資源的用途需要考古。之後每月或每季重跑一次比對差異 — 重點是看「上次到這次之間長出了什麼新資源」。如果每次比對都發現大量未標記的新資源，這本身就是一個訊號：手動操作的可見性不足，該考慮導入 IaC 了。

資源與信任不足下的高槓桿取捨

當時間、人力或上層信任都不足，無法一次把上面每件事做齊時，取捨原則是先做「失誤代價高且護欄成本低」的少數幾件：

長期憑證盤點與刪除保護兩者加起來的實施時間可能不到一小時。命名與 tagging 的策略是「新的一律照規範、舊的等有餘力再補」，而不是停下來先整理全部存量。資源不足時怎麼跟上層談這些工作的優先級，在模組九：怎麼把 infra 推動起來展開。

該開始導入 IaC 的訊號

手動環境到了某些訊號出現時，繼續手動的邊際成本會超過導入 IaC 的一次性成本。訊號是規模與協作的函數，不是時間的函數 — 一個人運維一個簡單服務，手動可能撐很久；三個人同時動一個稍微複雜的環境，幾週內就會踩到手動的極限。

環境數量變多：當需要 dev、staging、production 三套幾乎一樣的環境，手動複製會在環境之間留下難以察覺的差異。某個人在 staging 加了一條 security group 規則，忘了在 prod 也加，結果 staging 測通了、prod 部署後服務連不上。IaC 用同一份程式碼複製環境，環境差異只存在於參數值。

多人同時動資源：一個人手動操作還能靠記憶維護，兩三個人並行時，沒有 plan / review 的手動變更會互相覆蓋。A 改了一個設定解了自己的問題，B 幾天後改了另一個設定把 A 的修正覆蓋掉，事故原因得靠翻 CloudTrail 才查得到。

環境爆炸頻率上升：如果「改一個設定結果弄壞別的東西」這類事故開始每月發生，代表手動環境的隱性依賴已經超過人腦能追蹤的上限。一個典型的隱性依賴：security group A 被 instance X 和 instance Y 同時引用，改 A 時只想著 X 的需求、忘了 Y 也依賴它，改完 Y 就斷了。

合規或稽核要求：外部稽核（SOC 2、ISO 27001）開始要求「列出所有對外暴露的服務」「提供存取權限的變更紀錄」「證明 production 環境的變更有經過審查」。手動環境回答這些問題時，每次都是一場考古工程。IaC 加上 PR 流程後，答案就在 repo 裡。

任一訊號穩定出現，就是把第一個資源納入 IaC 的起點 — 前面做的命名、tagging、資源盤點此時直接成為 import 的輸入。第一步怎麼跨進去在模組一：最小可行 IaC。

在訊號出現前過早導入 IaC 也有代價：單人、單環境、低變更頻率時，IaC 的學習與維護成本可能高於它省下的手動工 — 寫一份 HCL、配一個 state backend、設一條 pipeline 的固定成本，在只有三個資源的環境裡不一定划得來。這裡的判準是等訊號、不是趕進度。

跨分類引用

• → 接手維運：如果這個手動環境是接手來的，先走接手維運的盤點流程
• → 模組零：infra 是什麼：成熟度階梯上「全手動」這一階的定位
• → 模組一：最小可行 IaC：訊號出現後，第一步怎麼跨進 IaC
• → 模組二：身分與憑證地基：長期憑證護欄的系統性設計
• → 模組三：網路地基：手動階段網路大改的回退考量、之後的系統性設計
• → 模組八：治理好習慣：tagging 在成本歸因與批次操作的後續價值
• → 模組九：怎麼把 infra 推動起來：資源不足時怎麼跟上層談優先級

流程定位

後端部署的主要風險是有狀態依賴。前端 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 邊界。

遷移的核心約束是帶電施工——系統在搬遷過程中要持續服務。這決定了操作模式：在新平台建起平行環境、驗證通過後用 DNS 切換流量、確認沒問題再拆舊環境。每一步都保留回退到舊環境的能力，直到新環境穩定運行一段時間。

遷移路徑的常見組合

每條路徑的遷移工程量級不同：共享主機 → VPS 是最輕的（應用層搬家）、地端 → 雲端是最重的（整個基礎設施重建）。選擇遷移路徑時先確認商業目標——如果目標是「能裝自訂軟體」，共享主機 → VPS 就夠了，不需要一步跳到雲端。

共享主機 → VPS 遷移

遷移前的記錄

把共享主機的所有設定記下來，作為 VPS 上重建的 checklist。需要記錄的項目：

接手維運模組的環境設定拍照有更完整的盤點方法。

VPS 環境建立

VPS 上從零安裝 web stack：

 1# Ubuntu 22.04 為例
 2sudo apt update && sudo apt upgrade -y
 3
 4# Web server
 5sudo apt install nginx -y
 6
 7# PHP（對齊共享主機的版本）
 8sudo apt install php8.1-fpm php8.1-mysql php8.1-curl php8.1-mbstring php8.1-gd php8.1-xml -y
 9
10# MySQL
11sudo apt install mysql-server -y
12
13# SSL（Let's Encrypt）
14sudo apt install certbot python3-certbot-nginx -y
15sudo certbot --nginx -d example.com -d www.example.com

安裝完成後用 php -m 比對共享主機的 phpinfo 記錄，確認所有模組都已安裝。缺少的模組用 apt install php8.1-<module> 補上。

資料搬移

1# 程式碼：從本地 Git repo 部署（不從共享主機直接搬）
2git clone git@github.com:org/site.git /var/www/site
3
4# 資料庫：從備份匯入
5mysql -u root -p site_db < backup-latest.sql
6
7# 使用者上傳檔案：從共享主機 FTP 下載後 rsync 到 VPS
8rsync -avz /local/backup/uploads/ user@vps:/var/www/site/uploads/

.htaccess → nginx 設定轉換

共享主機用 Apache 的 .htaccess，VPS 如果改用 nginx 需要手動轉換。常見的規則對照：

 1# .htaccess: RewriteEngine On / RewriteRule ^(.*)$ index.php/$1
 2# nginx 等價：
 3location / {
 4    try_files $uri $uri/ /index.php?$query_string;
 5}
 6
 7# .htaccess: Options -Indexes
 8# nginx 等價：
 9autoindex off;
10
11# .htaccess: deny from all (某目錄)
12# nginx 等價：
13location ~ /\.env { deny all; }

轉換後在本地或 staging 驗證每條規則的行為是否一致。WordPress、Laravel 等框架有現成的 nginx 設定範例可參考。

Email 處理

共享主機通常附帶 email 服務（用主機面板建 email 帳號）。VPS 預設不含 email。三個處理方式：

• 自架 email server（Postfix + Dovecot）：維運成本高、不推薦除非有特殊需求
• 改用第三方 email 服務（Google Workspace / Zoho Mail）：設定 MX 記錄指向服務商
• 只轉發（不收信）：應用程式的寄信功能改用 SMTP relay（SendGrid / Mailgun）

DNS 的 MX 記錄要在切換前就改好指向新的 email 服務，否則切換後 email 會中斷。

SSL 自動續期

共享主機的 SSL 通常由主機商代管續期。VPS 上用 Let’s Encrypt 的 certbot 會自動設定 systemd timer 或 cron 做續期，但要驗證它確實在跑：

1# 確認 certbot 的自動續期排程存在
2sudo systemctl list-timers | grep certbot
3
4# 模擬續期測試（不實際續期）
5sudo certbot renew --dry-run

VPS → 雲端遷移

服務盤點與雲端對照

VPS 上的每個 process 都需要對應到雲端的服務：

自動化遷移工具

AWS Application Migration Service（MGN）可以自動化 VM workload 的搬遷——把現有 server 的 block-level data 持續複製到 AWS、切換時啟動 EC2 instance。適合大量 VM 的 lift-and-shift，但不處理應用層的重構（nginx config、cron 轉 EventBridge 等仍需手動）。單台 VM 的遷移用 MGN 反而比手動 dump/restore 多一層設定成本，適用場景是同時搬 5 台以上。

IaC 的導入時機

VPS → 雲端是導入 IaC 的最佳時機——新環境從零建起，沒有歷史包袱。用 Terraform 描述 VPC、subnet、RDS、ECS、ALB 等資源，讓新環境可重現（見模組一：最小可行 IaC）。遷移完成後，這套 IaC 直接成為持續維運的基礎。

資料庫遷移

小型資料庫（< 10GB）：mysqldump + 匯入 RDS，遷移期間短暫唯讀即可。

1# 從 VPS dump
2mysqldump -u user -p --single-transaction site_db | gzip > site_db.sql.gz
3
4# 匯入 RDS
5gunzip -c site_db.sql.gz | mysql -h rds-endpoint.region.rds.amazonaws.com -u admin -p site_db

大型資料庫（> 10GB 或需要零停機）：使用 AWS DMS（Database Migration Service）做持續複寫，VPS 上的 MySQL 作為 source、RDS 作為 target，DMS 做初始全量複製後持續同步增量，切換時把應用指向 RDS 端點。

網路設計

雲端環境的網路要在遷移前規劃好。VPC、subnet、security group 的設計見模組三：網路地基。VPS 上的 iptables 規則要映射成 security group 規則——iptables 的每條 accept 對應一條 SG ingress rule，但 SG 不支援 deny（用「不開就是 deny」的白名單模式）。

資料同步策略

選擇策略時先問兩個問題：資料量多大（決定 dump 時間）、業務能接受多長的唯讀或停機窗口（決定要不要持續複寫）。

對於上傳檔案（圖片、文件），遷移到雲端時通常從本地檔案系統搬到 S3：

1# 從 VPS 同步上傳目錄到 S3
2aws s3 sync /var/www/site/uploads/ s3://site-uploads/ --delete

應用程式碼裡的檔案路徑要改成 S3 URL 或用 CDN 代理。

DNS 切換與驗證

切換前準備

遷移前 48 小時，降低 DNS TTL 到 300 秒（5 分鐘）。正常的 TTL 通常是 3600 秒（1 小時）或更長——如果切換出問題需要回退，短 TTL 讓 DNS 傳播更快。

1# 確認當前 TTL
2dig example.com +short +ttlid

切換操作

1# 更新 A record 指向新平台的 IP / ALB endpoint
2# 如果用 Route 53：
3aws route53 change-resource-record-sets --hosted-zone-id Z123 --change-batch '{
4  "Changes": [{"Action": "UPSERT", "ResourceRecordSet": {
5    "Name": "example.com", "Type": "A",
6    "AliasTarget": {"HostedZoneId": "Z456", "DNSName": "alb-xxx.region.elb.amazonaws.com", "EvaluateTargetHealth": true}
7  }}]
8}'

切換後監控

切換後的驗證窗口至少等 2 倍 TTL（短 TTL 設 300 秒的話，至少等 10 分鐘）。在這段時間內：

• 新平台：監控 HTTP 狀態碼、回應時間、錯誤率
• 舊平台：觀察流量是否遞減到零（仍有流量代表 DNS 還沒完全傳播）
• 功能驗證：跑一次關鍵流程（登入、查詢、交易）

回退

如果新平台出問題，回退方式是把 DNS 切回舊平台的 IP。回退的生效時間等於當前的 TTL——這正是切換前降低 TTL 的理由。舊平台在 DNS 切換後要保留至少 72 小時（全球 DNS 快取最慢的清除時間），確認完全沒有流量後再退役。

切換後收尾

穩定運行 1-2 週後：

• 把 DNS TTL 恢復到正常值（3600 秒）
• 退役舊平台（關機 → 保留快照 → 一個月後刪除）
• 更新文件：新環境的存取方式、部署流程、監控端點

時程與管理層溝通

向管理層溝通時的關鍵訊息：「應用程式碼不變、改的是運行環境。風險集中在資料搬移和 DNS 切換這兩個步驟，兩者都有回退路徑。」

成本變化也要提前說明：共享主機 → VPS 的月費通常持平或略增（$5-30/月）；VPS → 雲端的月費取決於資源用量，初期可能增加 50-200%（換到的是彈性和 managed 服務），但可以透過 reserved instance 和 rightsizing 後續優化。

跨分類引用

• → 升級的共通操作框架：評估差異 → 平行環境 → 切換 → 退役的四階段模型
• → 接手維運：無 SSH 的 FTP 環境：遷移前的環境盤點方法
• → 模組一：最小可行 IaC：雲端遷移是導入 IaC 的最佳時機
• → 模組三：網路地基：雲端環境的 VPC / subnet 設計

Vendor lock-in 在遷出日的具體形狀就是這幾條資產線的斷點。0.21 的可遷出保險清單（自有網域、資料定期匯出、客戶聯絡管道自有、金流可攜性、密碼不可攜的預案、業務邏輯文件化）是進場時買的保險、本章是理賠流程 — 保險有買、每條線的斷點都有現成出口；保險沒買、本章每一節都會多一段「先補保險再動手」的前置工。

資產線盤點

動手前先盤點：這個產品在平台上累積了哪些資產、每項資產走哪條線、可攜性如何。盤點的產出是一張「資產 → 線 → 出口 → 斷點」對照、它決定後面所有階段的順序與凍結窗口長度。

資料線

資料線問兩個問題：拿得出來嗎、拿出來之後能直接用嗎。多數平台對第一個問題的答案是肯定的 — Shopify 的商品與訂單歷史有官方 CSV / API 匯出、WordPress 的文章與媒體是最成熟的匯出路徑、Firebase 的 Firestore 有官方 export。真正的工程量在第二個問題：匯出格式是平台資料模型的快照、不是自建系統的 schema。

兩個典型情境。第一、BaaS 的反正規化結構：Firestore 的文件沿查詢需求生長、同一份事實散在多個 collection、而目標端的關聯式 database 要求單一事實單一位置 — 執行順序是先設計目標 schema、再寫轉換管線、而不是把 export 原樣灌進去。第二、半託管 CMS 的外掛私有表：WordPress 官方匯出涵蓋文章與媒體、外掛各自的私有表（會員等級、預約規則、客製欄位）在匯出範圍之外 — 每個外掛要單獨確認資料位置與匯出手段。盤點階段把這兩類「拿得出來但不能直接用」的資產標出來、它們是資料線時程的主要變數。

歷史資料搬完之後、增量是另一個問題：平台在並行期仍持續產生新訂單、新會員、新內容、需要一條增量同步管道（webhook、API 輪詢、排程匯出）把變更餵進新系統 — 角色等同自建世界的 change data capture、只是來源是平台 API 而不是資料庫 log。

資料線還有一類「可放棄、但要快照」的資產：平台內建報表與分析歷史。這類數據多數沒有匯出路徑、平台降級或關站後即消失 — 歷史明細可以放棄、但 cutover 後的健康判讀需要遷移前的基線（自然流量、轉換率、客單價）。盤點階段把基線指標匯出存檔、觀察期的「下滑超過預估」才有對照對象。

身分線

身分線的可攜性在所有資產線中分布最極端。會員的 email 與基本資料幾乎都可匯出；密碼雜湊多數平台拒絕交出 — Firebase Auth 是少數友善案例、官方工具可匯出密碼雜湊、演算法參數從主控台另行取得、自建認證系統照參數驗證即可無感銜接。多數平台（電商會員、網站會員系統）把雜湊留在自己手上、這條線的執行形態於是變成全體重設密碼。

重設密碼遷移要當成產品功能設計、而不是遷移日的告示：分批寄送重設邀請、首次登入時引導重設、保留舊 email 驗證鏈路、把重設高峰排開行銷活動。0.21 可遷出保險裡「密碼不可攜的預案」指的就是這套體驗、執行階段它從預案變成排程上的工作項。

Session 綁定在平台端、cutover 當天全體使用者重新登入是預設行為、要納入切換日的客服與監控預期。第三方登入（Google / Apple 登入）的識別碼可攜性介於兩者之間：識別碼存在 provider 端、但可能綁定在 OAuth client 或開發者帳號的範圍上 — Apple 的 user identifier 以開發者團隊為界、換團隊後同一使用者拿到不同識別碼。遷移前先用測試帳號驗證新舊系統拿到的識別碼一致、再決定第三方登入使用者要走無感銜接還是重新綁定。

身分線的盤點對象除了終端使用者、還有操作者與機器：員工帳號、角色權限、API key 與第三方服務的 OAuth 授權都要在新系統重新佈建、並納入 cutover 演練 — 切換日客服登不進新後台、是這條線最常見的自傷事故。

流量線

流量線的前提是自有網域 — 0.21 可遷出保險清單裡的保險項。網域在自己名下、DNS 自己控制、流量切換就是一次 DNS 變更加一套轉址規則；流量活在平台贈送的子網域上、遷出等於換址、SEO 與既有連結歸零、這條線要先補保險（買網域、在平台上綁定、讓搜尋引擎與外部連結先收斂到自有網域）再談切換。

執行面的關鍵是斷裂面管理。平台的 URL 結構（/products/handle、/blogs/news/slug）跟自建系統的路由幾乎必然不同、而離開平台後、舊 URL 的轉址規則沒有地方住 — 平台停用後它連 404 都不會回、是 DNS 直接指向新系統。所以轉址表（舊 URL 樣式 → 新 URL）要建在新系統自己身上：cutover 後由新系統對舊樣式回 301、搜尋引擎與外部連結沿轉址收斂。配套動作：cutover 前把 DNS TTL 調低、cutover 後重交 sitemap、用搜尋主控台觀察索引替換進度。SEO 累積是按月計的資產、轉址表缺漏的代價以自然流量下滑直接體現。

整合線

整合線收所有由平台出面跟外部世界握手的合約、其中金流是最硬的斷點 — 它在本章盤點順序排最後、執行確認要排最早、答案會改變整場遷移的形狀。一次性收款的遷移成本低 — 換金流串接、新訂單走新管道。訂閱制是另一回事：扣款授權 token 存在金流商的 vault 裡、且常綁定在平台名下的金流帳戶上。遷出時先問金流商「授權能否轉移到商家自有的金流帳戶」— 部分金流商支援處理商之間的卡號資料轉移、談得下來就是一次後台作業；談不下來、全體訂閱者重新授權、流失率直接換算成訂閱營收缺口。執行手段跟重設密碼同構：分批通知、寬限期、必要時用優惠補償授權摩擦。

金流之外、整合線還包括：平台外掛 / app 生態承擔的業務邏輯（Shopify app 做的折扣規則、WordPress 外掛做的預約流程）要逐個盤點、決定重寫進自建系統、換成獨立 SaaS、或趁機放棄；對外 webhook（ERP、出貨、會計系統）的端點切換要跟對方排時程；行銷 email 的寄送信譽綁在平台的寄件網域上、換到自有寄件網域要重建 SPF / DKIM 並逐步暖機、避免遷移週的通知信全進垃圾箱。

並行期設計

並行期是舊平台與新系統共存、用真實資料驗證新系統的階段 — 前提是目標系統已依 模組零的選型順序 建置完成、本章不重複選型推導。它跟 10.2 服務拆分執行 Runbook 的雙寫期同源但形狀不同：服務拆分時、寫入路徑在自己的程式碼裡、可以實作 dual write；託管平台的寫入發生在平台內部 — 顧客在 Shopify 結帳、會員在平台註冊 — 自建程式碼插不進那條寫入路徑。所以並行期的形態是「平台維持 source of truth、單向同步、新系統唯讀驗證」：

1. 增量同步管道（webhook / API 輪詢 / 排程匯出）持續把平台變更餵進新系統
2. 新系統以唯讀 replica 的角色運轉、對帳 job 定期比對兩邊的訂單數、會員數、金額總和
3. 內部使用者先在新系統上工作（報表、後台查詢）、用真實業務流量驗證資料轉換的正確性
4. 差異率收斂並穩定後、才排 cutover 日

Cutover 本身是一段 cutover window、不是一個按鈕：選低流量時段、短暫凍結平台側變更（電商常用「暫停結帳維護頁」幾十分鐘）、跑最後一輪增量同步、切 DNS、然後密集觀察訂單成功率、登入成功率、金流授權成功率 — 觀察清單來自資產線盤點、每條線各有自己的健康訊號。

回切窗口的設計決定這場遷移的失敗代價。cutover 後保留舊平台訂閱與設定、回切動作是 DNS 切回；代價是新系統在窗口內產生的交易要補回平台 — 平台側通常沒有批次匯入訂單的好路徑、補回多半是手動作業、所以回切窗口內要刻意壓低不可逆變更的累積速度（例如窗口前 48 小時內暫停大型行銷活動）。這跟 10.2 寫路徑切換的 point of no return 是同一個判讀：回退成本隨時間墊高、go/no-go 要當成有明確時點的決策執行、判定條件在進入窗口前排定。

關舊站走降級、而不是直接刪除。觀察期過後、平台帳號先降到最低方案、店面關閉但後台保留 — 退款處理、客服查歷史訂單、會計與稅務稽核都還會用到平台側資料。刪除帳號前的檢查條件：所有歷史資料已完整落地自有儲存並驗證可讀、法規要求的交易紀錄保存年限已由自有系統接手、最後一筆平台側退款 / 爭議單已結案。

部分遷出是常見的中繼形態

資產線可以獨立 cutover 的另一面、是遷出可以分期：先撤其中幾條線、其餘留在平台。部分遷出是把遷移風險拆期攤還的標準形態、結構上同 Strangler Fig：新系統從旁長出、逐線取代、平台最後才退役。

常見的中繼形態有四種。資料層先撤：增量同步管道建好之後、自有資料庫先成為報表與分析的 source、前台與結帳留在平台 — 0.21 BaaS 段描述的跨集合報表困境、在這個形態下已經解掉、而最高風險的金流與流量線還沒動。前台先撤（headless）：自建前端體驗層、平台降級為後端引擎（結帳 API、內容 API）— 流量線與 SEO 控制權先回手、金流與資料留在平台的成熟路徑上。身分後撤：認證是使用者感知最強的線、Firebase Auth 這類可攜性好的元件常被留到最後 — 資料與流量都搬完、產品穩定後、再做密碼雜湊匯入或重設遷移。金流後撤（或長期留平台）：訂閱授權轉移談不下來時、資料、前台與流量都遷出、訂閱扣款續走平台帳戶 — 它跟前三種不同、可能由中繼轉成長期形態、去留判讀回整合線的金流斷點確認。

中繼形態的判讀標準是「每個階段結束時、撤出的那條線已經完整脫離平台、由新系統持有唯一事實」。模糊狀態（一半訂單在平台、一半在自建、靠人腦記得哪邊查）是部分遷出最常見的事故源 — 每條線在任一時刻都要有唯一的 source of truth。

判讀訊號

業務邏輯那一列值得展開：平台設定裡長出來的折扣邏輯、會員等級、運費規則、是盤點階段最容易漏的資產 — 它們沒有檔案形態、不會出現在任何匯出工具裡。0.21 可遷出保險清單把「業務邏輯文件化」列為進場保險、沒買這項保險的遷移、第一個階段是考古：對著平台後台逐頁截圖、把規則寫成文件、再評估哪些重寫、哪些放棄。

金流那一列是整場遷移裡少數「工程努力無法繞過」的斷點 — 授權轉移的決定權在金流商與平台的合約上、不在工程團隊手上。所以它在盤點階段就要最先確認：答案直接改變遷移的營收影響模型、甚至可能讓「訂閱線留在平台、其餘遷出」成為長期形態。

定位邊界

本章專注「託管形態 → 自建 / 半託管」的遷出執行。當問題回到「該不該遷、何時該重新評估」、回 0.21 交付形態選型 的升級自建 tripwire 表；遷移目標的自建選型（資料庫、部署、金流接法）走 模組零的選型順序；自建系統之間的資料庫搬遷技術細節（雙寫、shadow read、切換）進 1.6 資料庫轉換實作；服務層的漸進替換紀律進 10.2 服務拆分執行 Runbook。

下一步路由

要回頭確認遷移時機與保險、見 0.21 交付形態選型。要看並行期同源的雙寫與切流紀律、見 10.2 服務拆分執行 Runbook。遷入自建後的第一站、從 0.0 後端需求分類地圖 開始走選型順序。

大量真實案例與轉換原因

案例分組判讀

語言與型別系統轉換

語言轉換常見於「延遲抖動不可接受」或「重構風險不可接受」兩類壓力。前者多是 runtime/記憶體模型問題，後者多是大型程式碼庫可維護性問題。

• 代表案例：Slack PHP -> Hack、Discord Go -> Rust、Dropbox Python 2 -> Python 3、Cloudflare C/NGINX -> Rust
• 主要動機：降低 tail latency、提升記憶體安全、對抗 runtime EOL、引入更強型別訊號

資料層與儲存架構轉換

資料層轉換通常源自單體資料庫在容量、隔離與可恢復性上出現結構性瓶頸，追新技術本身很少是真正驅動力。

• 代表案例：GitLab Main/CI split、Notion Postgres sharding、Shopify Vitess、Meta MyRocks
• 主要動機：解耦不同負載、降低熱點、取得水平擴充、降低儲存成本

平台與部署工具轉換

平台轉換通常發生在部署頻率提升後，原本的人工作業或弱自動化無法承擔發布風險。

• 代表案例：Figma 遷移 Kubernetes、Dropbox RPC 標準化到 gRPC
• 主要動機：統一部署控制面、縮短發布/回滾時間、提升跨語言協作效率

架構邊界重整

架構重整通常是「故障會跨邊界放大」或「團隊邊界與系統邊界失配」時的修正動作。

• 代表案例：Slack cellular architecture、Uber domain-oriented microservice governance
• 主要動機：縮小 blast radius、讓服務責任與組織責任對齊、降低跨團隊耦合

三倍擴充案例池（42）

這份案例池的核心責任是提供「可直接回寫實作」的案例母體，而不是只做公司清單。下面分成兩層：外部官方遷移案例（偏選型與轉換動機）與站內已整理案例（偏實作、驗證、事故教訓）。

A. 外部官方遷移案例（20）

B. 站內可回寫實作案例池（22）

這兩層合計 42 個案例。使用方式是先在 A 層找轉換動機，再到 B 層找可操作證據與失敗模式，最後回寫到 01/04/06/08 的正文。

跨分類覆蓋與缺口

這一段的核心責任是避免案例池被資料庫議題主導。選型與轉換在實務上會同時涉及快取、訊息傳遞、觀測、部署、安全與事故治理，因此案例覆蓋要跨分類配置。

覆蓋門檻與缺口追蹤

這份追蹤表的核心責任是把「案例夠不夠」變成可量化判斷，而不是主觀感覺。

下一輪優先順序

門檻已達標，下一輪優先順序改為：

1. 每分類補「失敗反例」與「轉換失敗回退案例」
2. 每分類補「同議題不同規模企業」對照
3. 把案例回寫到章節正文中的判讀訊號與 tripwire 欄位

回退失敗專題索引

這個索引的核心責任是讓讀者在「已經出錯」時，能快速找到對應回退失敗模式，而不是從頭重讀選型章節。

回退判讀寫法

回退判讀的核心責任是把失敗條件寫回該分類自己的業務語境。快取看的是回源壓力與資料新鮮度；queue 看的是語義、lag 與重播；observability 看的是訊號語意漂移；deployment 看的是切流、draining 與連線生命週期；security 看的是身份、憑證作用域與控制面擴散。

這些判讀不能抽成同一份模板。每次寫案例時，先回答該分類自己的問題：哪個業務路徑受影響、哪個訊號最早失真、哪個回退動作會降低傷害、哪份證據能證明回退有效。

下一輪補查清單（非 DB 優先）

下一輪補查會優先補目前中低密度分類，目標是讓每一類至少有 8 到 12 個可回寫案例。

1. Cache：快取策略遷移與失效治理（multi-layer、eviction、warmup）
2. Queue：broker/語義轉換與 replay 風險控制
3. Observability：監控平台遷移與資料品質治理
4. Deployment：部署平台轉換與灰度/回滾策略
5. Security：控制面信任邊界與憑證機制轉換

第二批外部案例補充（非 DB 類）

這一批的核心責任是把中低密度分類補到可用水位，讓 02/03/04/05/07 都有可引用的真實轉換案例，而不是只有資料庫案例可用。

第二批補查來源

• Meta：Cache consistency / mcrouter / CacheLib / Kangaroo / FOQS / MyRocks migration
• LinkedIn Engineering：Kafka at scale / TopicGC
• AWS：CloudHealth Kafka -> MSK、X-Ray -> OTel migration、ADOT/EKS 實務、EKS 遷移案例
• Google Cloud：OTLP in Cloud Trace、Orbitera -> GKE
• Shopify Engineering：cache serialization migration、write-through cache
• Cloudflare Post-mortem：2023/2026 control-plane 與路由事件

判讀訊號

轉換決策資料要求

轉換前要先回答的三個問題

1. 現有問題是「局部優化可解」還是「結構性不匹配」？
2. 轉換後的收益是性能、可靠性、開發效率哪一項，如何量化？
3. 遷移期間如何維持雙軌可運行與回退能力？

如果三個問題答不清楚，通常代表先做局部治理比全面轉換更穩定。

常見誤區

把「技術新舊」當成轉換理由，容易忽略遷移期成本。可靠做法是先界定症狀與邊界，再決定要換語言、換工具，或只換架構切分方式。

下一步路由

若問題在執行時特性（延遲抖動、記憶體模型），先回 0.2 與 0.5。若是資料庫轉換已進入執行階段，直接進 1.6 資料庫轉換實作；需要把 production migration 寫成 evidence、gate 與 decision log，接 1.7 Schema Migration Rollout 證據；需要放行與回滾治理時，接 6.11 Migration Safety；若要看事故層教訓，接 GitHub 2018 Oct21 MySQL Topology Incident。

引用源

• Hacklang at Slack: A Better PHP：Slack 說明 PHP 到 Hack 的遷移動機與型別收益。
• How Big Technical Changes Happen at Slack：Slack 逐步遷移與組織推進方式。
• Why Discord is switching from Go to Rust：Discord 說明 Go→Rust 的延遲與 GC 觀察。
• Slack’s Migration to a Cellular Architecture：Slack 從單體拓撲轉到 cell 架構的原因。
• The Long-Awaited Python 3 Upgrade at Dropbox：Dropbox 的 Python 2 -> 3 遷移動機與推進方式。
• Rewriting the heart of our sync engine：Dropbox 在核心效能路徑重寫的轉換決策脈絡。
• Courier: Driving the first years of gRPC：Dropbox 內部 RPC 到 gRPC 的演進背景。
• Splitting database into Main and CI：GitLab 的資料庫職責拆分案例。
• Sharding Postgres at Notion：Notion 分片遷移與容量壓力背景。
• Horizontally scaling the Rails backend of Shop App with Vitess：Shopify 導入 Vitess 的原因與方式。
• How Shopify Is Adopting Sorbet：Shopify 在大型 Ruby 程式碼庫導入型別系統。
• Migrating Figma to Kubernetes：Figma 的平台遷移原因與收益。
• A Rust regex engine in NGINX：Cloudflare 在高效能路徑導入 Rust 的案例。
• Domain-Oriented Microservice Architecture：Uber 在規模化後重整服務邊界。
• MyRocks: A space- and write-optimized MySQL database：Meta 導入 MyRocks 的成本與效能動機。

EOL 風險評估

EOL 在操作層面的意義是三件事同時停止：安全修補（CVE 不再被回填到該版本的 patch release）、核心更新（kernel 的錯誤修正與硬體支援停止）、套件庫維護（官方 repository 凍結或下架，新裝套件或更新依賴都做不到）。

風險時間軸

EOL 是一段逐漸惡化的過程，而非單一時間點：

常見的 EOL 情境

CentOS 7 在 2024 年 6 月結束支援，但仍有大量 production 環境在使用。CentOS 8 在 2021 年 12 月被轉向 CentOS Stream，打破了原本預期到 2029 年的支援承諾，迫使使用者重新選型。Ubuntu 18.04 的標準支援在 2023 年 4 月結束，Canonical 提供 ESM（Extended Security Maintenance）付費延長到 2028 年，但 ESM 只涵蓋 main 套件庫。

ESM 或類似的付費延長支援（RHEL 的 ELS、CentOS 的第三方 TuxCare）是「買時間做遷移」的合理策略——付月費取得額外 2-5 年的安全修補，讓團隊有餘裕規劃平行建置而非被迫緊急遷移。Ubuntu Pro 免費涵蓋 5 台 instance 的 ESM，超過才需要付費。ESM 是給遷移專案爭取時間的保險，而非長期方案——延長支援的套件覆蓋範圍通常比標準期窄。

合規的影響很直接：PCI DSS 要求所有面對持卡人資料的系統都執行在有安全修補支援的軟體上；SOC 2 和 ISO 27001 的定期稽核會檢查作業系統的支援狀態。在 EOL OS 上跑的 production 環境會讓稽核結果出現 finding，需要額外的補償控制（compensating control）才能通過——而補償控制的維護成本通常高於遷移本身。

目標 OS 選型

選型看四個維度：LTS 發布週期（支援年限多長）、社群與商業支援（問題能不能查到答案、能不能買付費支援）、套件可用性（應用層需要的 runtime 和 library 在官方 repo 裡有沒有）、團隊熟悉度（操作指令和設定路徑的學習成本）。

常見選擇

同家族 vs 跨家族

CentOS → Rocky Linux / AlmaLinux 是同家族遷移：套件名稱、設定路徑、init 系統（systemd）幾乎不變，應用層的改動最少。CentOS → Ubuntu 是跨家族遷移：套件管理從 yum/dnf 換成 apt、設定路徑從 /etc/httpd/ 變成 /etc/apache2/、某些服務名稱不同。

同家族遷移的優勢是應用層風險低——多數設定檔可以直接搬過去。跨家族遷移的優勢是可以借機切到更活躍的生態（Ubuntu 的社群回答量和第三方套件支援在多數指標上領先），代價是設定檔要全面調整。

選型判準：如果團隊已經有 Ubuntu 經驗、或其他系統已經跑 Ubuntu，統一到 Ubuntu 的長期維護成本較低。如果團隊對 RHEL 系操作更熟、或有 RHEL 付費支援合約，Rocky/Alma 是阻力最小的路。

遷移策略：原地升級 vs 平行建置

原地升級

在現有伺服器上直接換 OS 版本。做法是用 OS 提供的升級工具（如 do-release-upgrade、leapp）在跑著的系統上切換。

風險集中在升級過程中系統處於不確定狀態——kernel 換了但 userland 還沒、init 系統切了但服務設定還指向舊路徑。如果中途失敗、伺服器可能開不了機，而 rollback 意味著從備份還原整台機器。原地升級只在同 OS 家族的小版本升級（如 Ubuntu 20.04 → 22.04）且有完整 VM 快照保底時才值得考慮。

平行建置

在旁邊建一台新 OS 的伺服器、安裝應用層、遷移資料、用 DNS 或 load balancer 切換流量。舊伺服器保留作為 rollback 目標，確認新環境穩定後再退役。

平行建置的成本是短期多付一台伺服器的費用（通常是幾天到幾週）。收益是：升級失敗時舊伺服器完好無損、切回去只需要改 DNS 或 LB 的 target；新伺服器可以在切換前充分測試、不影響線上服務；整個過程可以在非尖峰時段進行。

對多數環境來說平行建置是預設策略。原地升級只在無法多開一台伺服器（預算極度受限、或裸機硬體無備品）時才退而求其次。

應用層的遷移清單

新 OS 上要重建整個應用執行環境。以下是逐項需要確認的面向：

Web 伺服器

如果新舊 OS 都用 Apache，設定檔的路徑可能不同（RHEL 系 /etc/httpd/conf.d/、Debian 系 /etc/apache2/sites-available/），模組載入方式也不同（LoadModule 指令 vs a2enmod 工具）。逐一比對現有的 VirtualHost 設定、rewrite 規則、SSL 設定。

如果同時換成 nginx，見下一節。

Runtime 版本對齊

新 OS 的官方 repo 裡的 PHP / Node / Python 版本可能跟舊 OS 不同。Ubuntu 22.04 預設 PHP 8.1、如果應用需要 PHP 7.4 要加第三方 PPA（如 ondrej/php）。確認所有 PHP extension（mysqli、curl、gd、mbstring、redis）在新 OS 上都有對應的套件名稱且已安裝。

1# 舊伺服器：列出所有已載入的 PHP module
2php -m > old-php-modules.txt
3
4# 新伺服器：比對缺了什麼
5php -m > new-php-modules.txt
6diff old-php-modules.txt new-php-modules.txt

資料庫客戶端程式庫

應用連接 MySQL / PostgreSQL 用的 client library（libmysqlclient、libpq）版本要跟資料庫伺服器相容。跨大版本（MySQL 5.7 client → MySQL 8.0 server）通常向前相容，但反過來可能有驗證方式不匹配的問題（如 MySQL 8.0 的 caching_sha2_password 預設驗證方式）。

Cron jobs

從舊伺服器匯出 crontab（crontab -l），在新伺服器重建。如果舊 OS 使用 /etc/cron.d/ 的檔案式 cron，確認新 OS 的 cron daemon 支援同樣的格式。Cron 的環境變數（PATH、MAILTO）在不同 OS 可能有不同預設。

日誌路徑

Apache 的預設 log 路徑在 RHEL 系是 /var/log/httpd/、Debian 系是 /var/log/apache2/。應用程式如果 hardcode 了日誌路徑，要在新 OS 上對齊。同時確認 logrotate 的設定在新 OS 上存在且正確。

檔案權限與使用者

不同 OS 的 web server 執行使用者不同（RHEL 的 apache、Debian 的 www-data）。如果應用依賴特定使用者名稱的檔案權限（如 upload 目錄的 owner），遷移後要調整 chown。

服務管理

現代 OS 都使用 systemd。但如果舊 OS 還有 sysvinit 腳本（/etc/init.d/），遷移時要轉換成 systemd unit file。轉換的核心是把 init 腳本的 start/stop/restart 邏輯對應到 systemd 的 ExecStart、ExecStop、Restart 欄位。

 1# /etc/systemd/system/myapp.service
 2[Unit]
 3Description=My Application
 4After=network.target mysql.service
 5
 6[Service]
 7Type=simple
 8User=www-data
 9ExecStart=/usr/bin/php /var/www/myapp/worker.php
10Restart=on-failure
11RestartSec=5
12
13[Install]
14WantedBy=multi-user.target

基礎軟體切換（Apache → nginx）

如果已經在為 OS 遷移建新伺服器，同時切換 web server 是成本最低的時機——反正設定檔要重寫、不如一次到位。分開做的話要拆兩次遷移、測兩次、承受兩次風險。

.htaccess → nginx 設定轉換

Apache 的 .htaccess 是分散式設定——每個目錄可以有自己的 .htaccess，Apache 在每次請求時逐層讀取。nginx 沒有這個機制，所有設定集中在 /etc/nginx/ 的設定檔裡。

轉換的第一步是找出所有 .htaccess 檔案：

1find /var/www/ -name ".htaccess" -exec echo "=== {} ===" \; -exec cat {} \;

常見的轉換對應：

平行測試

在新伺服器上同時安裝 nginx（port 80）和 Apache（port 8080）。用 curl 比對兩者的回應：

1# 比對首頁
2diff <(curl -s http://new-server/) <(curl -s http://new-server:8080/)
3
4# 比對一個有 rewrite 規則的 URL
5diff <(curl -sI http://new-server/old-path) <(curl -sI http://new-server:8080/old-path)

回應一致後再把 Apache 移除。重點比對項：HTTP status code（rewrite 的 301/302）、response body（PHP 輸出）、response header（cache control、security header）。

常見陷阱

.htaccess 的分散式設定在 WordPress 或其他 CMS 中常被用來動態控制 URL rewrite。WordPress 的 permalink 功能依賴根目錄的 .htaccess，切到 nginx 需要在設定檔裡加 try_files $uri $uri/ /index.php?$args; 才能讓 permalink 運作。其他 CMS（Drupal、Laravel）也有各自的 nginx 設定範例，通常在官方文件裡可以找到。

時程與管理層溝通

OS 遷移（平行建置）的時程取決於應用層的複雜度：

跟管理層溝通時用三個框架：

為什麼現在做：「目前的 OS 已經停止安全修補，每個月不遷移等於多一個月的曝險窗口。如果有合規要求（PCI DSS / SOC 2），下次稽核會被標記。」

做什麼：「在旁邊建一台新 OS 的伺服器，把應用搬過去、驗證通過後切換。舊伺服器保留一到兩週作為 rollback。」

花多久和多少錢：「工程師時間 1-3 週（依複雜度）。多一台伺服器的費用只有切換期間的短期成本。不做的隱藏成本是安全事故的潛在損失和合規罰款。」

跨分類引用

• → 升級的共通操作框架：四階段模型（評估差異 → 平行環境 → 分批切換 → 退役）
• → 平台遷移：如果 OS 遷移同時伴隨平台搬遷（地端 → 雲端）
• → Runtime 版本升級：PHP / Node 版本升級常伴隨 OS 遷移
• → 接手維運：接手一個 EOL OS 的環境後的下一步

本章跟 1.12 大規模 DB 遷移實戰 分工：

• 1.6 同 DB 內：schema 演進、資料變更、新舊欄位共存、雙寫驗證、切流。例：加欄位、改欄位、拆表、合表、加 partition。
• 1.12 跨 DB 引擎：換 vendor（PostgreSQL → Aurora、MongoDB → Cosmos DB、TiDB → DynamoDB）。例：9.C20 Zomato、9.C30 Microsoft 365。

兩者用同樣的工程方法論（dual-write、shadow、cutover、rollback）、但 stakes 跟 跨越的邊界 不同。本章先處理 1.6 的同 DB schema 轉換、1.12 處理更大規模的 cross-engine。若來源是託管平台（Shopify / Firebase / WordPress）的匯出而非自建資料庫、整場遷出的資產線盤點與並行期設計見 10.3 託管形態遷出；資料落地自建後的 schema 演進回到本章、跨引擎搬遷走 1.12。

實作流程

Expand-Contract 模式

Expand / Contract（也叫 parallel change）是同 DB schema 演進的核心模式。

為什麼需要這個模式：

• 應用 deploy 跟 DB migration 不能 原子 完成
• 在 deploy window 內、有些 instance 跑舊 code、有些跑新 code
• DB 必須同時容納舊 code 跟新 code 的 schema

Expand 階段（加新欄位、不刪舊）：

• 加 new_column、允許 nullable
• 應用層 dual-write：同時寫 old_column 跟 new_column
• 應用層 read 仍走 old_column

Backfill 階段（資料同步）：

• 把歷史 row 的 new_column 補上值（從 old_column 算出來）
• 分批跑、用 checkpoint 追進度、避開 peak
• 監控：rate、error、progress、unaffected rows count

Migrate Reads 階段（切讀）：

• 應用層 read 改走 new_column
• 仍 dual-write、可以快速 fallback 回 old_column
• 持續 shadow read 驗證一致性

Contract 階段（刪舊）：

• 確認所有 application instance 都跑新 code 後
• 刪 old_column、停止 dual-write
• 移除應用層的 fallback 邏輯

每個階段都是 可獨立 rollback 的、不像 big-bang 一次切完。

同 DB 內常見 migration 類型

Type A：加欄位（最簡單）

• 直接 ALTER TABLE ADD COLUMN（nullable 或 default）
• 應用層後續加寫入、讀取
• 風險：低
• 注意：大表 ADD COLUMN with DEFAULT 在 PostgreSQL 11+ 是 instant、之前要 rewrite

Type B：刪欄位

• 先讓所有 application 不再讀寫該欄位
• 部署完成、確認後再 DROP COLUMN
• 風險：中
• 注意：DROP COLUMN 是 instant、但無法 rollback、必須 backup

Type C：改欄位型別

• 用 expand-contract：加新欄位、dual-write、backfill、切讀、刪舊
• 風險：高（特別是大表）
• 注意：直接 ALTER COLUMN TYPE 可能 rewrite 整表、lock 時間長

Type D：改欄位名 / 表名

• 同型別改名：用 expand-contract、加新名 + dual-write、切讀、刪舊
• DB 端 native rename 是 instant 但 application 需要同步 update — 不適合大規模 deploy

Type E：拆表 / 合表

• 拆：先 dual-write 到新舊表、backfill、切讀、刪舊
• 合：先 dual-write 到新表、backfill、切讀、刪舊
• 風險：高 — 影響面廣

Type F：加 index

• PostgreSQL：CREATE INDEX CONCURRENTLY（不 lock 表、可能 slow）
• MySQL：gh-ost / pt-online-schema-change（ghost table）
• 風險：低-中（看 index 大小）

Type G：加 NOT NULL constraint

• 先確保 application 所有 instance 都不寫 null
• backfill null 為 default
• 加 NOT NULL constraint
• 風險：中

Type H：加 partition

• 先把現有表變成 partition 0
• 加新 partition 接新資料
• 漸進把舊資料 move 到對應 partition
• 風險：高（schema 大變）

Online Schema Change 工具

大表 ALTER TABLE 直接跑會 lock。生產級 migration 用 online schema change 工具：

PostgreSQL：

• CREATE INDEX CONCURRENTLY（內建）
• pg_repack（vacuum + reindex without lock）
• pgroll（zero-downtime migration）
• Atlas（schema-as-code）

MySQL：

• gh-ost（GitHub 開源、無觸發器、推薦）
• pt-online-schema-change（Percona、用觸發器）
• Vitess online DDL（managed via Vitess）

機制概要：

• 建 ghost table（新 schema）
• copy 資料到 ghost table（漸進、avoid peak）
• 用 trigger 或 binlog 同步 ongoing changes
• 切換：原 table → ghost table（atomic rename）

對應 MySQL vendor page 跟 PostgreSQL vendor page 的相關段落。

Validation Query 設計

migration 過程中必須有 validation query 確認資料一致性。

Checksum 對比：

• 跑 MD5(new_column) = MD5(derived_from_old)
• 抽樣 10% 跑、不打全表
• 不一致 → 修轉換函式、不直接修資料

Row count 對比：

• 新欄位 NULL count 跟預期 backfill 進度比對
• 過慢 → 增加 backfill worker
• 不一致 → 找出 backfill 漏跑的 batch

業務指標對比：

• 跟業務 metric 對齊（訂單金額總和、用戶數）
• 比 row-level checksum 更貼近 business correctness

詳見 Validation Query 卡片 跟 1.7 Schema Migration Rollout Evidence。

Backfill 設計

backfill 是 migration 中最 容易出錯 的環節 — 大量寫、影響 production。

設計要點：

1. 節流（throttle）：每秒寫入限制、跟 production peak 錯開
2. Checkpoint：紀錄進度、可 resume
3. 錯誤分類：可 retry 的錯誤 vs 必須人工處理
4. dry-run mode：先看會修改多少、不實際寫
5. monitoring：rate、error、progress、replica lag

backfill 反模式：

• 一個大 transaction 跑全表 → lock 太久、可能 OOM
• 沒 checkpoint → 中途失敗從頭開始
• 沒 throttle → 影響 production read

對應 Backfill 卡片。

各階段監控訊號

每階段都要監控、不只是「最後驗證」：

判讀訊號

常見誤區

把資料庫轉換當成單次 DDL 任務、會讓風險集中在 cutover 當下。穩定做法是把每一階段都做成可驗證、可回退的獨立里程碑。

把 dual-write 當成最終保障也常出錯。雙寫只能保證「兩邊都有寫」、不保證「語意一致」、仍要配 shadow read 與業務對帳。

把 online schema change 工具當「萬能」也是錯。gh-ost / pgroll 仍有 限制（例如 trigger 限制、IO 影響）、要按工具規格操作。

案例回寫

• 選型層案例： 0.C4 營運後技術轉換
• 可靠性治理： 6.11 Migration Safety
• 事故反饋： GitHub 2018 Oct21 MySQL Topology Incident
• 大規模跨 DB 遷移： 1.12 大規模 DB 遷移實戰（Zomato、Netflix、Microsoft 365 等 case）

這組案例主要支撐的是「分段切換與可回退驗證」判讀、不直接支撐快取 TTL 或 broker delivery 參數；若問題核心在快取新鮮度或投遞語意、應轉到 2.x 或 3.x。

跨模組路由

1. 與 1.2 的交接：欄位演進與命名語意回到 schema design。
2. 與 1.3 的交接：交易邊界與副作用切分回到 transaction boundary。
3. 與 1.7 的交接：production rollout 證據實作 — Schema Migration Rollout Evidence。
4. 與 1.12 的交接：跨 DB 引擎遷移 — 大規模 DB 遷移實戰。
5. 與 4.20 的交接：validation query 與一致性證據進入 Observability Evidence Package。
6. 與 6.11 / 6.8 的交接：放行與停損條件進入 Migration Safety 與 Release Gate。
7. 與 8.19 的交接：pause、rollback、fail-forward 決策記錄到 Incident Decision Log。

下一步路由

若你還在判斷是否該轉換、先回 0.C4 看決策訊號。若你要把這套流程寫成 production rollout evidence、接著讀 1.7 Schema Migration Rollout 證據實作示範。若你在設計放行與演練、接著看 6.11 與 6.8。若你在事故回溯、接著看 8.23 Post-incident Review。若你要做 跨 DB 引擎遷移、看 1.12。

服務路徑與狀態責任

這條服務路徑是 checkout-api -> order-db -> payment-callback -> reconciliation-job。Checkout 建立訂單時先寫入訂單主檔與付款待確認狀態；payment callback 會更新付款結果；客服後台與對帳 job 會讀取同一筆訂單狀態來判斷是否需要補償、退款或人工處理。

本篇示範的變更是把原本單一 status 欄位中的付款語意拆到 payment_state。這個欄位屬於正式狀態，會影響使用者看到的訂單結果、付款回呼的冪等更新、客服查詢與對帳流程，因此 rollout 的核心是讓新舊狀態語意在過渡期同時成立；DDL 只是其中一個執行動作。

這條路徑的前置概念來自 1.2 schema design 與資料建模、1.3 transaction 與一致性邊界 與 1.6 資料庫轉換實作。1.2 定義欄位責任，1.3 定義哪些更新要在同一個交易邊界內成立，1.6 定義 expand、backfill、cutover 與 contract 的執行節奏。

Rollout 階段

Migration rollout 的責任是把一次高風險資料變更切成多個可驗證階段。每個階段都要有輸入條件、完成訊號與停止條件，讓團隊能在資料漂移擴大前停下來。

這張表的重點是責任轉移。Expand 保護相容性，backfill 保護歷史資料，cutover 保護線上讀取，contract 保護長期維護成本；四者對應不同 evidence，也需要不同 release gate 判讀。

實作基準：先寫出狀態契約

狀態契約的責任是讓 migration 先有可驗證的語意邊界。這篇的範例把 orders.status 裡混合的訂單生命週期與付款語意拆開：訂單仍用 status 表示 created、fulfilled、cancelled 這類流程狀態，付款結果則交給 payment_state 表示 pending、authorized、captured、failed 與 refunded。

這張 mapping table 是 validation query、backfill job 與 incident decision log 的共同語意來源。Mapping table 留在工程師腦中時，後續 mismatch 會變成「資料看起來怪」；mapping table 進入 artifact 後，gate 就能判斷錯誤集中在哪個付款語意，而不是停在總筆數。

Expand：先建立相容窗口

Expand phase 的核心責任是讓新資料結構先進入 production，同時保留舊程式的可運作性。以 payment_state 為例，常見起點是新增 nullable 欄位、補上必要索引，並讓寫入路徑可以在新欄位缺值時仍使用舊 status 判讀付款狀態。

1ALTER TABLE orders
2  ADD COLUMN payment_state text NULL;
3
4CREATE INDEX CONCURRENTLY idx_orders_payment_state
5  ON orders (payment_state)
6  WHERE payment_state IS NOT NULL;

這段 SQL 的用途是示範 artifact 形狀。Nullable 欄位保留舊資料的相容窗口；partial index 讓新讀取路徑能先被驗證，同時避免把尚未 backfill 的歷史資料全部推進新查詢模型。不同資料庫會有不同線上 DDL 能力，release gate 要把 lock 行為、index build 進度與 replication lag 納入 checks。

應用程式在 expand 階段要支援 read compatibility。相容性較高的寫法是讀取時優先使用 payment_state，缺值時 fallback 到舊 status 的付款語意；寫入時則依交易邊界同步更新舊欄位與新欄位，直到 cutover 前都保留一致性檢查。

 1readPaymentState(order):
 2  if order.payment_state is not null:
 3    return order.payment_state
 4  return mapLegacyStatusToPaymentState(order.status)
 5
 6applyPaymentCallback(order, callback):
 7  nextPaymentState = mapCallbackToPaymentState(callback)
 8  update orders
 9    set status = mapPaymentStateToLegacyStatus(nextPaymentState),
10        payment_state = nextPaymentState
11    where id = order.id

這段相容讀寫的重點是「同一個 callback 只產生一個付款判讀」。舊欄位與新欄位可以同時存在，但它們要由同一份 mapping function 產生，否則 payment callback、客服修復與 reconciliation job 會各自形成一套隱性規則。

這裡要特別看 dual write 的風險。雙寫只表示兩個欄位都有被寫入，仍要用 validation query 驗證兩者語意是否一致。若付款回呼、手動退款與對帳修復走不同程式路徑，雙寫函式也要被這些路徑共同使用。

Dual-write divergence schema

Dual-write 的責任不只是「兩邊都寫」、是「兩邊寫的結果一致」。要證明這件事、需要明確的 divergence schema、否則事故當下無法區分 mapping bug 跟 race condition。

最小 divergence 紀錄欄位：

expected_new 跟 new_value 對不上、表示 mapping function 在某些 path 沒被使用、是 mapping bug。legacy_value 跟 new_value 對不上、且 expected_new == legacy_value 對得上、是 dual-write 本身少寫一筆、可能是 race condition 或部分失敗。兩種情況的修法完全不同、不分類會在事故當下亂修。

Dual-write 失敗回退策略：寫舊欄位成功、寫新欄位失敗時、不能直接 retry 新欄位（會跟主寫入競爭）。實務做法是把 divergence 寫進 outbox / repair queue、由 backfill 同類流程補。對應 9.C16 SeatGeek 的 outbox-style 設計。

線上 DDL 的 vendor 差異

Expand 階段加欄位 / 加索引、不同資料庫的 阻塞行為 差異極大、選錯時機會直接讓 production 鎖表。

• PostgreSQL：ALTER TABLE ADD COLUMN ... NULL 是 metadata-only、不重寫 table。ADD COLUMN ... NOT NULL DEFAULT ... 在 PG 11+ 才是 metadata-only。CREATE INDEX CONCURRENTLY 不阻塞寫入、但更慢、且 transaction 中不能用。ALTER TABLE ALTER COLUMN TYPE 通常會重寫整張表、要先評估規模。
• MySQL / Aurora MySQL：ALTER TABLE ... ALGORITHM=INSTANT 是 8.0+ 的 metadata-only、5.7 則靠 ALGORITHM=INPLACE / LOCK=NONE。Aurora MySQL 還有 fast DDL（部分變更秒級完成、不重寫）。判讀重點是 explicitly 指定 ALGORITHM、不要讓 MySQL 自己選（可能掉回 COPY 算法、整張表複製）。
• Spanner：schema change 預設非阻塞、後端 async 補欄位。新欄位 read 在 schema change 完成前可能讀不到、應用層要容忍。
• DynamoDB：表本身沒 schema、但 GSI（Global Secondary Index）創建是 async、可能跑數小時、且新 GSI 在 backfill 完成前查不到完整資料。判讀重點：cutover 不能假設新 GSI 立即可用、要等 IndexStatus = ACTIVE。
• Cosmos DB：document 級別無 schema、新 indexed path 加進 indexing policy 後、後端 re-index 整個 partition、期間 RU consumption 飆升。

各 vendor 的線上 DDL evidence 都要包含：操作開始時間、預估完成時間、是否阻塞讀寫、實際 lock duration。expand gate 通過條件不能只看 DDL 跑完、要看 所有副效應收斂（index status active、re-indexing 完成、replica 同步）。

對應 vendor pages：PostgreSQL、MySQL、Aurora、Spanner、DynamoDB、Cosmos DB 的線上 DDL 段。

Backfill：把歷史資料變成可驗證進度

Backfill phase 的核心責任是把歷史資料補齊成可追蹤、可暫停、可重試的進度。訂單表通常會同時承擔交易查詢、客服查詢與對帳查詢；backfill 若只追求速度，容易和線上流量競爭 I/O、放大 replication lag 或改變查詢計畫。

Backfill job 應以 checkpoint 管理進度。每批選取固定範圍的訂單，轉換 status 到 payment_state，寫入後立刻產生該批 validation query 結果。批次大小要能依延遲、鎖等待、replication lag 與線上錯誤率調整。

1checkpoint:
2  migration_id: orders-payment-state-2026-05
3  last_order_id: 18420000
4  batch_size: 5000
5  started_at: 2026-05-11T02:10:00Z
6  completed_at: 2026-05-11T02:12:40Z
7  rows_scanned: 5000
8  rows_updated: 4921
9  mismatch_count: 3

Checkpoint 的角色是把 backfill 變成可恢復流程。last_order_id 告訴下一批從哪裡繼續，rows_updated 與 mismatch_count 告訴 gate 這批是否可以被納入放行證據，時間欄位則讓 replication lag、slow query 與錯誤率能回到同一個觀察窗口。

Validation query 的責任是證明語意一致。最小集合包含總筆數、已補筆數、缺值筆數、新舊語意不一致樣本、每批耗時、慢查詢與 replication lag。這些查詢要保留 query link 與 time range，後續才能進入 4.20 Observability Evidence Package。

1SELECT
2  count(*) AS total_rows,
3  count(*) FILTER (WHERE payment_state IS NULL) AS missing_payment_state,
4  count(*) FILTER (
5    WHERE payment_state IS NOT NULL
6      AND payment_state <> map_legacy_status_to_payment_state(status)
7  ) AS mismatch_rows
8FROM orders
9WHERE id BETWEEN 18415001 AND 18420000;

Validation query 要和 mapping table 共用同一個語意。資料庫端缺少同一份 mapping function 時，查詢至少要把 mapping 規則展開成明確 CASE expression，並把 query version 保存在 evidence package；這樣事後才能知道 mismatch 是資料錯誤、mapping 規則改變，還是查詢本身落後。

Cutover：先切讀取，再收斂寫入

Cutover phase 的核心責任是把服務判讀權交給新欄位，同時保留可回退窗口。對訂單付款狀態來說，切換順序通常先從低風險讀取路徑開始，例如客服後台與內部對帳，再進入 checkout 查詢與使用者可見狀態；每一批切換都要有自己的 cutover window。

讀取 cutover 的 stop condition 要比寫入 cutover 更早觸發。新欄位讀取後出現 mismatch、客服查詢結果漂移、對帳 job 補償量異常時，先回到 fallback read，讓錯誤限制在判讀層，再重新驗證寫入收斂條件。

寫入 cutover 要確認所有更新來源都已對齊。付款回呼、手動修復、退款、訂單取消與 reconciliation job 都可能更新付款狀態；只切主 checkout 寫入路徑會留下長尾漂移。完成 cutover 前，要用 audit query 確認仍在寫舊欄位的程式路徑已經歸零或被納入例外清單。

Shadow read pattern：cutover 前的讀取驗證

Shadow read 的責任是讓新讀取路徑在 真實流量 下被驗證、但 不影響使用者結果。這跟 dual-write 是對偶機制：dual-write 證寫入收斂、shadow read 證讀取分歧。

實作模式：

1. 每一筆讀取請求、同時用 舊邏輯 跟 新邏輯 查一次。
2. 回給用戶的仍是舊邏輯結果（用戶體驗不變）。
3. 在背景把兩個結果差異寫進 divergence log。
4. 收集足夠樣本後、再決定切換 cutover。

 1readPaymentStateWithShadow(order):
 2  legacy = mapLegacyStatusToPaymentState(order.status)
 3  new_result = order.payment_state ?? legacy
 4  if legacy != new_result:
 5    asyncLogDivergence({
 6      order_id: order.id,
 7      legacy: legacy,
 8      new: new_result,
 9      sample_at: now(),
10      caller: requestContext.caller,
11    })
12  return legacy  // 用戶仍拿舊邏輯結果

Shadow read 的判讀重點：

• 抽樣率：1% / 10% / 100% — 高流量場景全量 shadow 會雙倍 DB 讀取、要先評估容量。Cosmos DB / DynamoDB 的 RU 成本要乘 2。
• 分歧分類：跟 dual-write 一樣、divergence 要分類（mapping bug / race condition / stale read）、不分類無法定位修法。
• 覆蓋條件：要驗證所有 caller path（checkout / support / reconciliation / external API）都跑過 shadow、否則 cutover 後可能踩到沒測試過的 path。
• 退場條件：shadow read 不該長期跑、會增加負載。設明確 sunset deadline、cutover 完成後一週內移除。

對應 9.C20 Zomato TiDB → DynamoDB migration — migration 期間用 shadow read 持續驗證 mapping 規則、抓到 mapping drift。

Dual-write 跟 shadow read 的選擇不是互斥、是依風險組合：

Multi-region 與跨服務協調

Migration 跨越 region 或多個 service 時、rollout 順序錯誤是最常見的失敗模式。Service A 切到新欄位、service B 還在讀舊欄位、結果整條業務流量看到不一致。

Multi-region rollout 順序

跨 region 的 schema migration 要從 最後寫入點 開始 expand、從 最後讀取點 開始 cutover。先 expand 寫端、再 expand 讀端；先 cutover 讀端、再 cutover 寫端。順序反了會在過渡期讀到沒被寫的新欄位、或寫了沒被讀的新欄位。

實務步驟：

1. Schema expand：所有 region 同步加新欄位（先寫端再讀端、不能跳）。確認跨 region replication lag 在新欄位上收斂、再進下一步。
2. Backfill：可以平行跑、但每 region 各自 checkpoint、不共用。某 region backfill stuck 不應該卡住其他 region。
3. Cutover read：region by region 切讀、用 canary region 先試 24-48 小時、再擴散。
4. Cutover write：所有 region 都切完讀、再統一切寫。寫端切換比讀端更敏感、跨 region 寫差異會放大成跨 region inconsistency。

對應 1.11 全球分散式 OLTP 的跨 region consistency 段。

Cross-service migration 協調

當 schema 變更影響多個 service 時、API contract 是 鬆耦合 介面、不該讓所有 service 同步切換。

協調機制：

• 新欄位先在 API 是 optional：API contract 加新欄位、預設 nullable / optional。下游 service 可選擇何時讀。
• 舊欄位保留至少一個版本週期：API 不能跟 DB schema 同步 contract、否則下游沒時間切。實務上保留 1-2 季、給下游充足 cutover 窗口。
• owner-by-owner cutover roster：明確列出每個下游 service 的 owner、預計 cutover 時間、目前狀態。常用工具是共享 dashboard、不是散落的 ticket。
• Contract test：每個下游 service 對新欄位都要有 contract test、在 CI gate 跑過。避免上游 cutover 後下游才發現沒讀對。

對應案例：9.C20 Zomato TiDB → DynamoDB — 跨多個 service 的 access pattern 變更、必須每個 service 各自驗證、不能假設「DB 切了就好」。

Evidence Package

資料庫 migration 的 evidence package 負責證明資料演進是否可判讀。這份 package 要把 validation query、時間窗、資料限制與 owner 包成後續放行與事故判斷可引用的證據，dashboard 只作為摘要入口。

Source 欄位要保留資料來源的能力邊界。Validation query 能證明欄位語意一致，DB metric 能看出 latency 與 lag，job log 能追進度，audit log 能判斷是否有高權限修復行為。把這些來源混在一起會讓下游誤判證據的用途。

Data quality 欄位要直接寫出限制。若查詢只跑 primary、replica lag 還在回復、某些 tenant 因資料遮罩未被抽樣，這些限制要跟 evidence 一起交給 release gate，讓 gate 能以證據完整度決定是否放行。

 1evidence_package:
 2  name: orders-payment-state-cutover-batch-37
 3  source:
 4    - validation_query: q_orders_payment_state_batch_37
 5    - db_metric: replication_lag_orders_primary
 6    - job_log: backfill_orders_payment_state_2026_05
 7  time_range: 2026-05-11T02:10:00Z/2026-05-11T02:20:00Z
 8  owner:
 9    database: data-platform-oncall
10    service: checkout-oncall
11    reconciliation: finance-ops-owner
12  data_quality:
13    replica_freshness: "primary only; replica lag still recovering"
14    sample_completeness: "tenant tier enterprise covered; sandbox tenants excluded"
15  confidence: suspected
16  known_gap:
17    - "manual refund repair path not yet sampled"

這份 package 故意把 confidence 標成 suspected。原因是 evidence 已能支持 backfill 繼續前進，但還不足以支持使用者可見讀取 cutover；這種中間狀態要被明確寫出，gate 才能做分階段決策。

Release Gate

Schema migration 的 release gate 負責判斷下一階段是否可以放行。它接收 evidence package，但決策語言要回到 6.8 Release Gate 與變更節奏：Gate decision、Checks、Stop condition、Rollback window、Owner。

Gate decision 要用服務語言書寫。migration pass 這種結論對下游不夠具體；放行 10% 訂單 backfill、暫停使用者可見讀取 cutover、維持 fallback read 24 小時 才能讓執行團隊知道下一步。

Rollback window 是資料庫 migration 的關鍵欄位。Expand 與 backfill 階段通常能回到舊讀取；cutover 後仍可 fallback；contract 後舊語意被移除，回退會變成資料修復或 fail-forward。gate 要在每階段說清楚目前還剩哪種退路。

 1release_gate:
 2  gate_decision: "allow next 10% backfill; block customer-visible read cutover"
 3  checks:
 4    mismatch_rate: "0.04%, below 0.1% batch threshold"
 5    replication_lag: "p95 12s, below 30s stop condition"
 6    slow_query: "no new support-admin slow query above 500ms"
 7  stop_condition:
 8    - "mismatch_rate >= 0.1% for two consecutive batches"
 9    - "replication_lag >= 30s for 10 minutes"
10    - "support-admin query drift confirmed by reconciliation owner"
11  rollback_window: "fallback read available until contract phase starts"
12  owner: checkout-oncall

這份 gate record 把「繼續 backfill」和「暫緩讀取 cutover」拆成兩個決策。資料庫 migration 常見的判讀問題是 evidence 只支撐下一批資料修補，還支撐不了使用者可見行為切換。

Incident Decision Log

Migration 進入 production 後，pause、rollback 與 fail-forward 都是事故決策。這些決策要同步寫入 8.19 Incident Decision Log，讓事中交班與事後復盤能回放當時的證據與限制。

常見決策包括暫停 backfill、降低 batch size、回到舊讀取、停止 contract、手動修補 mismatch、選擇 fail-forward。每筆都要保留 Timestamp、Decision、Context、Evidence、Owner、Expected effect 與 rollback condition。

例如 cutover 後發現客服查詢 mismatch 升高，decision log 可以寫成：

 1incident_decision:
 2  timestamp: 2026-05-11T03:05:00Z
 3  decision: "rollback support-admin read path to legacy status fallback"
 4  context: "support-admin mismatch increased after internal read cutover"
 5  evidence:
 6    - query: q_orders_payment_state_support_mismatch
 7    - window: 2026-05-11T02:35:00Z/2026-05-11T03:05:00Z
 8    - interpretation: "suspected callback mapping drift"
 9  owner: checkout-incident-commander
10  expected_effect: "support ticket misclassification returns to baseline"
11  rollback_condition: "mismatch remains above threshold after 15 minutes"

這種記錄能避免事後只剩「當時有回退」的模糊敘事。後續 8.23 Control Plane Decision Log and Write-back 實作示範 可承接同一組決策紀錄，把缺少 validation、owner 或 runbook 的地方回寫成改善項。

判讀訊號

判讀訊號的責任是讓讀者知道何時該繼續、何時該停、何時該改路線。Migration 訊號要同時看資料正確性、線上健康度與回退窗口。

這些訊號要放回服務路徑判讀。Mismatch 要看集中在哪個業務入口；若 mismatch 只出現在延遲付款 callback，它代表外部 provider 回呼語意未對齊。Replication lag 要看是否和 backfill 批次對位；若它只在 backfill 批次出現，gate 應調整 migration 節奏，再判斷 schema 設計是否需要修正。

Dual-write 跟 shadow read 的 divergence 要分開看 — 兩者偵測不同層的問題。Dual-write divergence 偏向 mapping bug 或 race condition；shadow read divergence 偏向讀取邏輯漂移或 stale read。混在同一個 dashboard 會讓 reviewer 看不出問題真正在哪一層。

常見誤區

把 schema migration 寫成 DDL 任務，會讓風險集中在切換當下。穩定做法是先建立相容窗口，再用 evidence 證明資料語意已經跟上，最後才收斂舊路徑。

把 validation query 當成事後對帳，也會削弱 rollout 控制。Validation query 適合在 expand、backfill、cutover 每一階段都產生證據，讓 release gate 能在風險擴大前停下來。

把 rollback 寫成單一動作容易誤導團隊。資料庫 migration 的 rollback 會隨階段改變：expand 可回退 schema 使用，backfill 可暫停與重跑，cutover 可回到 fallback read，contract 後多半只能做資料修復或 fail-forward。

把 dual-write 跟 shadow read 當成同一個工具。兩者偵測不同層、結合使用可以互補、互相替代會留下盲點。Dual-write 不跑 shadow read、cutover 後可能踩到沒驗過的讀取 path；shadow read 不跑 dual-write、新欄位可能在某些寫路徑根本沒被寫進去。

把線上 DDL 當「一個 SQL 跑完就好」。各 vendor 的 DDL 語意差異大、PostgreSQL 的 ADD COLUMN NOT NULL DEFAULT 在 PG 10 重寫整張表、PG 11+ 是 metadata-only；MySQL 不指定 ALGORITHM=INSTANT 可能掉回 COPY。Expand evidence 要包含 實際 lock duration、不是只看 DDL 是否回傳成功。

只在主寫入路徑切 cutover、忘記補償流程跟 reconciliation job 也會寫舊欄位。這些長尾寫入會在 contract 階段才暴露、那時候已經沒有 fallback 可走。Cutover 前要 audit 所有寫舊欄位的程式路徑、不只看主流程。

案例回寫

0.C4 營運後技術轉換 可以回寫這篇的決策層。當服務營運後需要拆欄位、拆庫、分片或升級儲存引擎，先用 0.C4 判斷「為什麼要換」，再用本篇判斷「進入 production 後如何證明每一步成立」。

GitHub 2018 Oct21 MySQL Topology Incident 可以回寫這篇的事故層。該事件顯示資料一致性優先時，團隊需要可回放的 fail-forward / fail-back 判準；本篇則把這個需求落到 migration rollout 的 evidence、gate 與 decision log。

這兩個案例共同支撐的是「資料狀態演進需要證據閉環」。0.C4 提供轉換動機與選型壓力，GitHub 事故提供資料一致性與恢復決策的代價；兩者都不直接替代 validation query、release gate 與 decision log 的實作細節。

跨模組路由

1. 與 1.2 的交接：欄位責任、命名與查詢模型回到 schema design。
2. 與 1.3 的交接：付款回呼、手動修復與對帳更新的交易邊界回到 transaction boundary。
3. 與 1.6 的交接：expand、backfill、cutover 與 contract 的執行流程回到 資料庫轉換實作。
4. 與 4.20 / 4.22 的交接：validation query、row count、lag 與 slow query 進入 Observability Evidence Package 與 Checkout API Evidence Package。
5. 與 6.11 / 6.8 / 6.25 的交接：migration 可逆性與放行條件進入 Migration Safety、Release Gate 與 Provider Dependency Release Gate。
6. 與 8.19 / 8.23 的交接：pause、rollback、fail-forward 與 write-back 進入 Incident Decision Log 與 Control Plane Decision Log and Write-back。

下一步路由

要把資料庫 migration 的 evidence 交給 release gate，接著讀 6.25 Provider Dependency Release Gate 實作示範，並把 provider 依賴示範中的 gate 欄位改寫成 migration gate 欄位。要看下一條分類服務路徑，接著進 02 Cache / Redis 模組 的 Cache migration and stampede rollback 服務路徑。

跨 vendor schema migration 深入：

• Spanner interleaved table 的 schema migration — 全球分散式表結構變更的 evidence shape
• Aurora 從自管 PostgreSQL / MySQL 遷入 — schema 比對與 dual-write 證據鏈
• Cosmos DB MongoDB API vs SQL API — multi-API document 在 rollout 階段的相容性 evidence

跟模組零的責任分工

模組零（服務選型）處理設計階段：辨識需求、比較能力、決定要不要引入某類服務。模組十（系統演進）處理執行階段：拆服務、跨服務重構、schema 大型變更、雲端切換、capacity ramp 的劇本與回退條件。兩者銜接點是「決策完成、執行待動」 — 模組零的結論「應該拆某個服務」進到模組十、變成「怎麼拆、用什麼 pattern、何時切流、回退條件是什麼」。

跟其他模組的邊界

模組十收的是「跨服務、跨模組、跨環境的演進劇本」、不是「該技術的小範圍變更」。常見的容易誤判邊界：

判別問題是「這個變更失敗時、回退範圍跨幾個服務 / 模組？」。跨多模組的演進劇本進模組十、單模組內的小範圍變更留原模組。

章節列表

後續擴充方向

本模組目前收服務拆分與託管形態遷出議題。未來會擴充的演進類議題：

• 跨服務 schema 演進：API contract migration、event schema versioning、跨服務的 backfill 策略
• 大型雲端遷移：on-prem → cloud、跨雲遷移的 cutover 劇本、流量切換策略
• 基礎設施替換：資料庫引擎切換（如 MySQL → Postgres、自建 → managed）、cache vendor 切換、queue broker 切換的執行紀律
• 容量重平衡：拆分後的服務間流量分佈、shard 重分佈、tenant 隔離調整

這些議題的共同特徵：跨多個技術模組、失敗代價遠超「該技術的小範圍變更」、需要獨立的執行劇本跟回退條件。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

本文是跨 vendor migration playbook、cross-link 到 DragonflyDB（source）跟 Redis / Valkey（target）。反向路徑見 Redis → DragonflyDB。跑 6 維 diff dimension audit 後判定為 Type B drop-in（RESP 協定相容），但 HA 和持久化有差異需要處理。

為什麼從 DragonflyDB 遷回

DragonflyDB 遷回 Redis/Valkey 的 driver 跟正向遷移互為鏡像：

• Redis Modules 需求：業務開始需要 RedisJSON、RediSearch 或 RedisTimeSeries，DragonflyDB 不支援 Redis Modules 生態
• Cluster mode 需求：DragonflyDB 設計為單機 scale-up，當資料量超過單機記憶體上限（數 TB）或需要跨 node sharding 時，Redis Cluster 或 Valkey Cluster 是成熟選擇
• Sentinel / HA 生態：DragonflyDB 的 HA 用自家 replication，不支援 Sentinel。若團隊已有 Sentinel 或 Operator 基礎設施，回到 Redis/Valkey 整合成本更低
• BSL 授權疑慮：DragonflyDB 是 BSL 1.1（4 年後轉 Apache 2.0），部分組織偏好 BSD（Valkey）或即使是 RSALv2（Redis）的已知授權

6 維 diff dimension audit

全域 Low-Medium → Type B drop-in，工作重心在 HA 架構切換和持久化模式對齊。

相容性確認

DragonflyDB → Redis 的相容方向跟 Redis → DragonflyDB 相反 — Redis 是 superset，回到 Redis 不會有功能缺失。但有幾個操作面差異需要處理：

階段一：資料匯出

DragonflyDB 支援 SAVE / BGSAVE 產生 RDB 格式 snapshot，跟 Redis RDB 相容。

1# 在 DragonflyDB 觸發 snapshot
2redis-cli -h dragonfly-host BGSAVE
3
4# 等 BGSAVE 完成
5redis-cli -h dragonfly-host LASTSAVE
6
7# 複製 snapshot 檔案到 Redis 資料目錄
8cp /dragonfly-data/dump.rdb /redis-data/dump.rdb

RDB 載入驗證：

1# 啟動 Redis 載入 RDB
2redis-server --dbfilename dump.rdb --dir /redis-data
3
4# 驗證 key count
5redis-cli DBSIZE

若 DragonflyDB 跑的是較新版本產出的 RDB，先在測試環境驗證 Redis 能正常載入。DragonflyDB 的 RDB 基於 Redis 6.x 格式，Redis 7.x 和 Valkey 8.x 向下相容無問題。

階段二：HA 架構重建

DragonflyDB 回到 Redis/Valkey 後，HA 需要從 DragonflyDB replication 切換到 Sentinel 或 Cluster。

Sentinel 路徑（適合非分片場景）

1 primary + N replica + 3 Sentinel nodes。配置見 Sentinel HA Failover。

Cluster 路徑（適合需要分片的場景）

最小 3 primary + 3 replica。配置見 Redis Cluster Resharding。

選擇依據：資料量 < 單機記憶體的 70% 用 Sentinel，需要水平擴展用 Cluster。

階段三：Client 切換

Application 的 Redis client 不需要改 API — DragonflyDB 跟 Redis 用同一套 RESP 協定。需要改的只有：

1. Endpoint：從 DragonflyDB host:port 改為 Redis primary（或 Sentinel/Cluster endpoint）
2. 認證：若 DragonflyDB 用 requirepass，Redis 同參數；若要升級到 ACL 趁此機會配置
3. Sentinel/Cluster 配置：client library 需要啟用 Sentinel discovery 或 Cluster mode

1# 切換前：直連 DragonflyDB
2r = redis.Redis(host="dragonfly-host", port=6379, password="secret")
3
4# 切換後：Sentinel 模式
5sentinel = redis.Sentinel([("sentinel-1", 26379), ("sentinel-2", 26379), ("sentinel-3", 26379)])
6r = sentinel.master_for("mymaster", password="secret")

階段四：效能 baseline 與回退

效能預期

回到 Redis 後，單機 throughput 會低於 DragonflyDB（Redis 單主線程 vs DragonflyDB 多線程）。建立 baseline 時要跟 Redis 的歷史數據比，不是跟 DragonflyDB 比。

回退路徑

回退到 DragonflyDB：把 Redis 的 RDB dump 回 DragonflyDB 載入，endpoint 改回。Cache 資料可重建，即使 RDB 不搬，DragonflyDB 重啟後 cache miss 回源到 DB 即可。

DragonflyDB 在遷移完成後保留 7 天再下線。

交接路由

• Source vendor：DragonflyDB
• Target vendor：Redis / Valkey
• 反向路徑：Redis → DragonflyDB
• HA 重建：Sentinel HA Failover、Cluster Resharding
• 持久化注意：Persistence Fork Latency

本文是跨 vendor migration playbook、cross-link 到 KeyDB（source）跟 Redis / Valkey（target）。跑 6 維 diff dimension audit 後判定為 Type B drop-in（KeyDB 是 Redis fork、RESP 相容、RDB/AOF 相容），但 active-active replication 跟 multi-threading 特性回退需要額外處理。

為什麼從 KeyDB 遷回

KeyDB 是 Snap 維護的 Redis fork，主要差異化在多線程和 active-active replication。遷回的 driver：

• 維護活躍度疑慮：KeyDB 的 release cadence 跟 Redis/Valkey 主線比較慢，部分組織擔心長期維護與安全 patch 的及時性
• Valkey 生態收斂：Valkey 在 Linux Foundation 治理下快速演進（8.x 多線程改進），KeyDB 的多線程優勢逐漸縮小
• Active-active 不再需要：業務不再需要跨 region active-active、或改用 application 層處理衝突解析
• 社群與工具生態：Redis/Valkey 的 client library、monitoring exporter、Operator 支援度更廣

6 維 diff dimension audit

Type B drop-in，工作重心在 active-active replication 拆除和效能 baseline 對齊。

KeyDB 特有功能的處理

FLASH storage 的處理取決於冷資料比例。如果多數資料在 FLASH 上（用 OBJECT FREQ 確認），遷移後的 Redis 記憶體需求會大幅上升 — 要提前計算純記憶體所需容量，調整 instance 規格或改用更積極的 eviction policy。Subkey expires 和 EXPIREMEMBER 的影響範圍通常較小，但一旦 application 依賴就需要重構資料結構（用 top-level key + TTL 或 sorted set 模擬過期）。

Active-active 拆除

若 KeyDB 的 active-active replication 正在使用，遷移前需要先收斂為單主寫入：

1. 選定一個 region 的 KeyDB 為 primary，其他 region 停止寫入
2. 等資料同步完成（replica 追上 primary offset）
3. 從 primary 做 RDB export
4. 用 RDB 建立 Redis/Valkey instance
5. 各 region 的 application 切到新的 Redis/Valkey（Sentinel 或 Cluster）

資料搬遷

KeyDB 的 RDB 和 AOF 與 Redis 格式相容，搬遷流程跟 DragonflyDB 回退類似：

1# KeyDB 端觸發 BGSAVE
2redis-cli -h keydb-host BGSAVE
3
4# 複製 RDB 到 Redis/Valkey 資料目錄
5scp keydb-host:/data/dump.rdb redis-host:/data/dump.rdb
6
7# Redis/Valkey 載入
8redis-server --dbfilename dump.rdb --dir /data

如果使用了 FLASH storage，RDB 只包含記憶體中的資料。FLASH 上的冷資料需要先用 OBJECT FREQ 確認存取頻率，決定是要 warm up 到記憶體再 export，還是接受遷移後冷資料 cache miss 回源。

效能差異預期

回退路徑

Cache 資料可重建，回退方式：

1. Application endpoint 改回 KeyDB
2. 若 KeyDB 已下線，重啟 KeyDB 載入 Redis 的 RDB（格式相容）
3. Cache miss 回源到 DB 自然 warm up

KeyDB 保留 7 天再下線。

交接路由

• Source vendor：KeyDB、KeyDB Active-Active Replication
• Target vendor：Redis / Valkey
• HA 重建：Sentinel HA Failover
• 效能參考：Persistence Fork Latency、Connection Pipeline Latency

本文是跨 vendor migration playbook、cross-link 到 AWS SQS 跟 Google Pub/Sub。這是一個 跨雲 managed-to-managed 遷移：兩端都是 cloud-managed、運維負擔都低、但 資料拓樸 跟 消費抽象 不同 — SQS 是 region-scoped 的單一 pull queue、Pub/Sub 是 global topic + 多個 first-class subscription。主結構走 operational redesign hybrid（Type C）、額外為 components / data topology 兩個高維度抽獨立段。

SQS 跟 Pub/Sub 不是同一種訊息抽象

SQS 跟 Pub/Sub 都是 cloud-managed 非同步訊息服務、都解「解耦 producer / consumer、不自管 broker」這個問題、application 程式碼裡都是「發訊息、收訊息、處理完確認」的形狀。從這層看兩者可互換、遷移像是換 SDK。

差別在 消費抽象 跟 資料拓樸。SQS 的核心實體是 queue：一條 region-scoped 的訊息隊列、訊息被一個 consumer 領走（in-flight）就對其他 consumer 隱形、處理完 DeleteMessage 就消失。要讓同一筆事件送給多個下游、SQS 端的做法是在 SNS 前面 fan-out、再各接一條 SQS queue。Pub/Sub 的核心實體是 topic + subscription 兩層：topic 收訊息、subscription 是 first-class 的消費端點、一個 topic 可掛 N 個 subscription、每個 subscription 各自維護消費進度、fan-out 是模型內建而不是外接。

這個差別決定了遷移的形狀。如果原系統只是「一條 queue、一群 worker 競爭領取」、那 Pub/Sub 端是「一個 topic、一個 pull subscription」、對位乾淨、application 改動小。如果原系統靠 SNS-to-many-SQS 做扇出、那 Pub/Sub 端是「一個 topic、多個 subscription」、整個 fan-out 拓樸要重畫、這不是換 SDK、是重設計訊息流。先判斷自己屬於哪一種、再決定 playbook 的重量。

為什麼會跨雲遷這條路徑

跨雲從 SQS 遷到 Pub/Sub 的 driver 跟同雲 vendor 切換不同、通常不是「Pub/Sub 比 SQS 好」、而是 整體 workload 的重心移到 GCP：

1. 資料平台落在 GCP：下游分析走 BigQuery、streaming 走 Dataflow、容器跑 Cloud Run。事件如果留在 AWS、每筆都要跨雲搬到 GCP 才能進 BigQuery、跨雲 egress 費用跟延遲都是常態成本。把訊息層也移到 Pub/Sub、事件可以用 BigQuery subscription 直接落地、省掉中間搬運。
2. 需要 global topic、不想管 region：SQS queue 綁 region、跨 region 要自己複製或在前面架路由。Pub/Sub topic 沒有 region 概念、publish 進去全球可訂閱、多區域服務的事件分發是 first-class。
3. fan-out 從外接變內建：原本靠 SNS + 多條 SQS 維護的扇出拓樸、在 Pub/Sub 是「一個 topic 掛多個 subscription」、少一層 SNS、扇出關係在 subscription 列表一覽。

這三條 driver 都假設 重心已經或即將在 GCP。如果系統長期紮根 AWS、只為了「換個 queue」跨雲、會付出跨雲 IAM 重對位、雙雲計費、跨雲網路延遲的代價、ROI 通常不成立。遷移前先確認 driver 是 workload 重心轉移、不是單純偏好。

結構為什麼是 operational hybrid 加兩個高維度獨立段

寫這篇前先跑 diff dimension audit、6 維評級如下：

主導維度是 operational model（跨雲身份與監控全換）、所以主結構走 Type C operational redesign hybrid。但 components 跟 data topology 也是 High — 不是把它們塞進 operational 段就能講清楚的、消費抽象從「一條 queue」變「topic + 多 subscription」是讀者最容易踩雷的地方。按 migration 方法論的 multi-axis 規則、高維度抽成獨立段補充、不硬塞進單一 type 標籤。所以本篇結構是：operational 對位主軸 + 「消費抽象重設計」獨立段（components / topology 軸）+ 跨雲特有的 IAM 與網路段。

Operational 對位：機制名詞換、語意要逐一確認

跨雲遷移最容易出錯的環節、是 找到語意相近的功能、卻假設行為一致。SQS 跟 Pub/Sub 多數機制都有對位、但每一組都有行為差、找得到對應功能只是第一步。下表先給對照、後面逐項展開語意陷阱。

Visibility timeout → ack deadline

Visibility timeout 跟 ack deadline 都回答同一個問題：consumer 領走訊息後、多久沒確認就視為失敗、把訊息重新投遞。語意對位成立、但兩端的數字與延長機制不同。

SQS visibility timeout 預設 30 秒、上限 12 小時、consumer 要延長就主動呼叫 ChangeMessageVisibility。Pub/Sub ack deadline 預設 10 秒、上限 600 秒（10 分鐘）、而且 client library 預設會 自動 在背景延長 deadline（lease management）。這個自動延長是最容易踩到的差異：在 SQS 端習慣「設一個夠長的 visibility timeout、處理完再 delete」、搬到 Pub/Sub 如果只把 ack deadline 設成 600 秒上限、卻沒意識到 client library 在背景幫忙延長、長任務的行為會跟預期不同；反過來、如果關掉自動延長又設了預設 10 秒、處理稍久就重投。對位的正確做法是先理解 client library 的 lease 行為、再決定 ack deadline 跟 MaxAckPending、而不是把 SQS 的 timeout 數字直接搬過去。

maxReceiveCount / redrive → dead-letter topic

兩端都用「重試 N 次仍失敗就隔離」防止 poison message 阻塞 pipeline、但隔離後的容器不同。SQS 的 DLQ 是另一條 queue、用 maxReceiveCount 控制門檻、修好下游後用 redrive policy 把訊息放回原 queue。Pub/Sub 的 dead-letter topic 是另一個 topic、用 subscription 的 max delivery attempt 控制門檻、超過就 publish 到 DLT。

差別在重處理路徑。SQS redrive 是把 DLQ 訊息搬回 main queue、是一個 queue-to-queue 的搬移動作。Pub/Sub 的 DLT 是 topic、要重處理得在 DLT 上再開一個 subscription 來消費、沒有內建的「放回原 topic」按鈕。Mercari item feed 的案例就是用 DLT 把重試多次仍失敗的訊息隔離、讓後續訊息優先處理、同時把 topic 當突發流量的 load-leveling buffer。從 SQS 搬過來時、redrive 的心智模型要換成「DLT 是一個獨立 topic、重處理是另開 subscription」、不是「按一個按鈕放回去」。設定 DLT 還需要給 Pub/Sub service account 對 DLT 的 publisher 權限跟對原 subscription 的 subscriber 權限、漏設會讓訊息卡住不進 DLT。

Long polling → streaming pull

這一組不是等價對位、是機制不同。SQS long polling 是 consumer 發一個 ReceiveMessage 請求、最多等 20 秒、有訊息就回、沒有就空回、本質仍是 輪詢、只是把空輪詢的頻率降下來省 cost。Pub/Sub 的 pull 在 client library 預設是 streaming pull：consumer 跟 Pub/Sub 建一條長連線、訊息一到就推過來、不是 consumer 反覆問。

對位時不要把 long polling 的「WaitTimeSeconds 20 秒」翻譯成某個 Pub/Sub 參數 — 沒有對應參數、因為機制不同。要關注的是 flow control：streaming pull 因為訊息會主動推來、要用 MaxOutstandingMessages / MaxAckPending 控制同時在處理的訊息量、否則 consumer 會被一次塞太多訊息壓垮。SQS 端「一次拉最多 10 條」的批次節流、在 Pub/Sub 端變成 flow control 設定。Spotify autoscaling 的案例揭露了相關陷阱：下游失敗時 consumer 不 ack 仍持續消耗 CPU、autoscaling 反而把資源越拉越高 — autoscale 訊號要看處理成功率、不是 backlog 加 CPU。

IAM policy → Service Account

跨雲遷移裡、身份模型是 重對位 而不是改語法的部分。SQS 的存取控制是 IAM policy（identity-based、掛在 user / role）加 queue policy（resource-based、掛在 queue）兩層、cross-account 靠這兩層互動。Pub/Sub 是 GCP IAM role（publisher / subscriber / viewer 等）加 Service Account、push subscription 要用 Service Account 認證到目標 endpoint。

兩套身份模型沒有自動轉換工具、要逐條重畫：誰能 publish 對應誰有 topic 的 publisher role、誰能消費對應誰有 subscription 的 subscriber role。跨雲場景還多一層 — 如果遷移期 AWS 端的服務要 publish 到 GCP 的 topic、得用 workload identity federation 或 service account key、讓 AWS 的工作負載拿到 GCP 身份。這部分沒有 case 可引、依 GCP 官方 IAM 文件加最小權限原則設計：每個 service account 只給它實際需要的 role、不要為了遷移方便給 broad role 再說以後收緊、那個「以後」通常不會來。

CloudWatch → Cloud Monitoring

監控訊號要重建、不是改名。SQS 在 CloudWatch 看 ApproximateNumberOfMessagesVisible（queue 深度）跟 ApproximateAgeOfOldestMessage（lag）。Pub/Sub 在 Cloud Monitoring 看 num_undelivered_messages（backlog）跟 oldest_unacked_message_age（最老未確認訊息年齡）。語意相近、但 alarm 邏輯要重寫、而且 Pub/Sub 的 backlog 數字要配合 subscription 維度看 — 同一個 topic 的不同 subscription 各自有 backlog、一個堵住不代表全部堵住。遷移時要把原本對 queue 深度的告警、改成對每個 subscription 的 backlog 與 age 告警。

消費抽象重設計：從一條 queue 到 topic 加多 subscription

這是 components 跟 data topology 兩個高維度的核心、也是從 SQS 搬到 Pub/Sub 最需要重新畫圖的地方。SQS 的世界裡、一條 queue 對應一群競爭領取的 worker；要扇出就在前面架 SNS、SNS 後面接多條 SQS、每條 queue 各一群 worker。Pub/Sub 把這個拓樸壓平：一個 topic 收訊息、掛多少個 subscription 就有多少條獨立的消費流、每個 subscription 各自記進度、彼此不影響。

重設計從盤點現有拓樸開始。先列出：哪些是「單一 queue、一群 worker」的簡單情境、哪些是「SNS fan-out 到多條 SQS」的扇出情境。簡單情境對位乾淨 — 一個 topic、一個 pull subscription、原本競爭領取的 worker 改成同一個 subscription 的多個 consumer、Pub/Sub 自動把訊息分給它們。扇出情境要把 SNS + 多 SQS 換成「一個 topic + 多 subscription」、原本每條 SQS queue 變成一個 subscription、SNS 那一層消失。

扇出情境裡有個方向相反的陷阱要避免：不要把「多個下游」誤設計成「多個 consumer 共用一個 subscription」。同一個 subscription 的多個 consumer 是 競爭 關係、訊息只會給其中一個 — 那是負載分攤、不是扇出。要每個下游都收到完整一份、就要每個下游一個 獨立 subscription。這跟 SQS 端「一條 queue 一個下游、扇出靠 SNS 複製」的直覺方向一致、但實體換了：在 SQS 是多條 queue、在 Pub/Sub 是多個 subscription。畫遷移圖時、SQS 的每條 fan-out queue 一對一映射到 Pub/Sub 的一個 subscription、不要合併。

Application 重設計範例：SQS receive-delete 換成 Pub/Sub pull-ack

 1// SQS 端：long polling receive、處理完 DeleteMessage
 2svc := sqs.NewFromConfig(cfg)
 3for {
 4    out, _ := svc.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
 5        QueueUrl:            &queueURL,
 6        MaxNumberOfMessages: 10,
 7        WaitTimeSeconds:     20, // long polling
 8    })
 9    for _, m := range out.Messages {
10        process(m.Body)
11        svc.DeleteMessage(ctx, &sqs.DeleteMessageInput{
12            QueueUrl:      &queueURL,
13            ReceiptHandle: m.ReceiptHandle,
14        })
15    }
16}

1// Pub/Sub 端：streaming pull、處理完 Ack、用 flow control 節流
2sub := client.Subscription("orders-sub")
3sub.ReceiveSettings.MaxOutstandingMessages = 100 // flow control、取代「一次拉 10 條」
4err := sub.Receive(ctx, func(ctx context.Context, msg *pubsub.Message) {
5    process(msg.Data)
6    msg.Ack() // 取代 DeleteMessage；client library 在背景自動延長 ack deadline
7})

差異：

• SQS 主動輪詢（ReceiveMessage 迴圈）→ Pub/Sub 回呼模型（Receive 把訊息推進 callback）
• SQS DeleteMessage → Pub/Sub msg.Ack()、語意都是「確認處理完、別重投」
• SQS WaitTimeSeconds 控制輪詢等待 → Pub/Sub MaxOutstandingMessages 控制 flow control
• SQS 一次最多 10 條的批次上限 → Pub/Sub 沒有這個上限、改用 flow control 設同時在途量
• ack deadline 的延長在 SQS 要主動 ChangeMessageVisibility、在 Pub/Sub 由 client library 自動處理

application 邏輯的商業處理部分（process 函式）多數可保留、改動集中在收訊息的框架跟確認語意、估計 20-40% 程式碼。

Production 故障演練

Case 1：fan-out 設計成共用 subscription、下游各收到一部分

徵兆：把原本 SNS fan-out 到 3 條 SQS 的拓樸搬到 Pub/Sub、為了省事建一個 topic + 一個 subscription、讓 3 個下游服務都連這個 subscription。上線後發現每個下游只收到大約三分之一的訊息、不是各收完整一份。

根因：同一個 subscription 的多個 consumer 是負載分攤關係、Pub/Sub 把訊息分給其中一個 consumer、不是每個都送。這對應到 SQS 端「一條 queue 多個 worker 競爭領取」的行為、但被誤用在需要扇出的場景。SQS 端的扇出靠 SNS 複製訊息到多條 queue、那個複製動作在 Pub/Sub 應該由「多個 subscription」承擔、不是多個 consumer 共用一個 subscription。

修法：

1. 每個下游一個獨立 subscription：3 個下游就建 3 個 subscription 掛同一個 topic、每個各收完整一份
2. 遷移圖一對一映射：SQS 的每條 fan-out queue 對應一個 Pub/Sub subscription、不合併
3. 負載分攤跟扇出分開設計：同一下游要多 worker 分攤、是同一 subscription 多 consumer；不同下游各收一份、是多 subscription

Case 2：ack deadline 沿用 SQS 數字太短、長任務反覆重投

徵兆：SQS 端 visibility timeout 設 5 分鐘跑得好好的、搬到 Pub/Sub 隨手把 ack deadline 設成預設或一個小數字、結果處理時間稍長的訊息被反覆重投、同一筆訊息處理多次、下游出現重複副作用。

根因：Pub/Sub ack deadline 預設 10 秒、上限 600 秒、跟 SQS visibility timeout 上限 12 小時差很多。如果關掉 client library 的自動 lease extension、又把 ack deadline 設小、處理時間一超過就被判定失敗重投。SQS 的「設一個夠長的 timeout」直覺搬過來不適用、因為 Pub/Sub 的上限低很多、且延長機制是 client library 自動做。

修法：

1. 理解 client library 的 lease 行為：多數 client library 預設會背景自動延長 ack deadline 到處理完、優先依賴這個而不是手動設超長 deadline
2. 長任務拆短或改架構：單筆處理超過 10 分鐘上限的、考慮拆成多階段或把長任務移出訊息處理路徑
3. 下游做 idempotency：跟 SQS 一樣、Pub/Sub 是 at-least-once、重投本來就會發生、下游用 message ID 去重才是根本解

Case 3：FIFO 順序需求對位到 ordering key、吞吐落差超出預期

徵兆：原系統用 SQS FIFO queue + MessageGroupId 保證同一群訊息順序處理、搬到 Pub/Sub 啟用 ordering key 對位、上線後吞吐比預期低很多、且某些情境順序仍亂。

根因：SQS FIFO 跟 Pub/Sub ordering key 都提供順序、但取捨點不同。SQS FIFO 同時給「順序」跟「5 分鐘去重窗口」、吞吐受限（每 MessageGroupId 串行）。Pub/Sub ordering key 給「同一 key 的訊息按 publish 順序送達」、但要 publish 端跟 subscription 端都正確設定（publish 要設 ordering key、subscription 要 enableMessageOrdering）、漏一邊順序就不保證；而且啟用 ordering 後同一 key 串行、吞吐同樣受限。把 FIFO 的「去重 + 順序」一包功能、誤以為 ordering key 也一包提供、是落差來源。

修法：

1. 拆開「順序」跟「去重」兩個需求：Pub/Sub ordering key 只管順序、去重要 application 端自己用 message ID 做
2. publish 跟 subscription 兩端都設 ordering：缺一邊順序不保證、遷移檢查清單要把兩端都列上
3. 重新評估是否真需要全域順序：FIFO 常被過度使用、很多場景只需要 per-entity 順序、用 ordering key 按 entity 分 key、比強制全域串行吞吐高很多

Case 4：跨雲遷移期雙雲都在跑、egress 成本與延遲被低估

徵兆：漸進 cutover 期間 AWS 跟 GCP 兩邊都在處理訊息、為了對帳把訊息在兩雲之間搬、月底帳單跨雲 egress 費用遠超預估、且跨雲呼叫的尾延遲拖慢端到端處理。

根因：SQS 在 AWS region 內、Pub/Sub 在 GCP、遷移期的 dual publish 或對帳如果讓資料反覆跨雲、每一筆出 AWS 的訊息都計 egress 費。跨雲不只是錢、跨雲網路的延遲跟抖動比同雲高、放在同步處理路徑上會放大尾延遲。同雲 vendor 切換沒有這個維度、跨雲遷移必須把它列進成本模型。

修法：

1. 縮短雙雲並行窗口：dual publish 的對帳期越短越省、設明確的並行截止日、不要無限期雙跑
2. 對帳用抽樣不用全量搬運：驗證一致性用抽樣比對 message ID / count、不要把所有訊息都搬到對面雲比對
3. 生產者就近落點：遷移後讓 producer 直接 publish 到 Pub/Sub、不要繞 AWS 再跨雲、消除穩態的跨雲 egress

Case 5：dead-letter topic 權限沒配齊、毒訊息卡住不進 DLT

徵兆：subscription 設了 dead-letter topic 跟 max delivery attempt、預期重試超限的訊息進 DLT、實際上毒訊息一直在原 subscription 反覆重投、DLT 是空的、後續訊息被堵。

根因：Pub/Sub 要把訊息送進 DLT、是由 Pub/Sub 的 service account 代為 publish 到 DLT topic；同時它也要對原 subscription 有 subscriber 權限才能 ack 掉原訊息。這兩個權限漏任一個、forwarding 到 DLT 就失敗、訊息卡在原 subscription。SQS 端 DLQ 是 queue 屬性、不需要額外給 service 權限、所以這個跨雲差異容易被漏掉。

修法：

1. 配齊 DLT 雙權限：給 Pub/Sub service account 對 DLT topic 的 publisher role、跟對原 subscription 的 subscriber role
2. 遷移後做毒訊息演練：故意 publish 一筆會失敗的訊息、確認它真的在 max attempt 後進 DLT、不是卡在原 subscription
3. 監控 DLT backlog：DLT 開一個 subscription 監控其 num_undelivered_messages、確認毒訊息有被導流且有人處理、對照 Mercari DLT 案例的設計

漸進 cutover：dual publish 加雙消費對帳

跨雲遷移風險高、不適合一次切換、走漸進 cutover 把可逆邊界拉長：

1. Phase 0：拓樸盤點 — 列出所有 SQS queue、標記哪些是單一 queue、哪些是 SNS fan-out、各自映射到 Pub/Sub 的 topic / subscription 結構
2. Phase 1：Pub/Sub 端建好對位資源 — 建 topic / subscription / DLT、配齊 IAM 與 service account、重建 Cloud Monitoring 告警、application 寫好 Pub/Sub consumer 但先不收流量
3. Phase 2：dual publish — producer 同時 publish 到 SQS 跟 Pub/Sub、兩邊 consumer 都跑、Pub/Sub 端的處理結果先寫到隔離區或標記、不影響正式下游
4. Phase 3：雙消費對帳 — 抽樣比對兩邊處理的訊息 ID 與數量、確認 Pub/Sub 端沒漏、沒重複到無法接受的程度、ack deadline / fan-out / ordering 行為都符合預期
5. Phase 4：流量切換 — 對帳通過後、把正式下游切到 Pub/Sub 端、SQS 端轉成備援、保留一段觀察期可回切
6. Phase 5：下線 SQS — 觀察期穩定後停掉 dual publish、移除 SQS 資源、消除穩態跨雲 egress（這是不可逆階段、不要在對帳沒過時提前做）

對帳期是這套流程的核心保險、也是 Case 4 跨雲成本的來源 — 對帳用抽樣、並行窗口設明確截止日、平衡「驗證信心」跟「雙雲成本」。

Capacity / cost 對照

判讀：穩態成本兩者量級相近、真正的成本差在 遷移期 — dual publish 雙雲並行加跨雲對帳搬運是一次性高峰、不是穩態。把這段窗口縮短、是控制跨雲遷移成本的關鍵、不是去比 SQS 跟 Pub/Sub 的單價。扇出重度的系統遷到 Pub/Sub 後、少掉 SNS 那一層、扇出的計費結構也變簡單。

整合 / 下一步

遷移後事件可直接落 GCP 資料平台

遷到 Pub/Sub 的一個結構性好處、是事件可以用 BigQuery subscription 直接寫進 BigQuery、不需要再寫 Dataflow pipeline 搬運；或用 Cloud Storage subscription 批次落 GCS。這正是「workload 重心在 GCP」這條 driver 的回報 — 事件層跟資料平台同雲、省掉跨雲搬運。這也是評估是否該跨雲遷移時、要放進 ROI 的一邊。

跟 Kafka 遷移的結構對照

結論：SQS → Pub/Sub 不是 paradigm shift（兩端都是 cloud-managed 訊息服務、可收斂成單一目標）、是 operational redesign 為主、消費抽象重設計為輔的跨雲遷移；結構由主導差異維度（operational）決定主軸、高維度（components / topology）抽獨立段補充。

相關連結

• Source / target vendor：AWS SQS / Google Pub/Sub
• 平行 vendor：Kafka / RabbitMQ / NATS
• 平行 migration playbook：Kafka ↔ NATS
• 引用案例：3.C64 Mercari Item Feed DLT / 3.C61 Spotify autoscaling
• Methodology：Migration Playbook 寫作方法論
• 上游概念：0.3 非同步選型 / 6.12 idempotency / replay

本文是跨 vendor migration playbook、cross-link 到 RabbitMQ 跟 Kafka。跟同類產品的 drop-in 或 operational 遷移不同、本篇是 paradigm shift — 兩端不是「同類 broker 的不同實作」、是 不同責任模型的 messaging system：RabbitMQ 是「處理即承諾」的 work queue、Kafka 是「寫入即承諾、可長期 replay」的 event log。

RabbitMQ → Kafka 不是把 queue 換成 topic

RabbitMQ 跟 Kafka 都被歸在「message queue」這個傘狀詞下、但兩者承擔的責任不同。RabbitMQ 的可靠性建立在 consumer 處理完才 ack、未 ack 的訊息 broker 重新投遞；訊息一旦被成功消費就從 queue 移除、broker 是「任務分派 + 重試」的中介。Kafka 的可靠性建立在 訊息寫進 partition log 就持久化、consumer 各自維護 offset；訊息在 retention 期內一直留著、broker 是「事件儲存 + 多方各自讀取」的 log。

把 RabbitMQ「migration」成 Kafka 的字面理解通常是：queue 對 topic、exchange 對 producer key、consumer 對 consumer group。這個對映在 transport 層成立、在責任層不成立。RabbitMQ 一個 message 被 ack 後就消失、Kafka 一個 message 寫進 log 後對所有 consumer group 都還在；RabbitMQ 的 routing 由 broker 端 exchange + binding 決定、Kafka 的「routing」由 producer 端 partition key 決定、broker 不做內容路由。先確認這層差異、再決定哪些 workload 值得遷。

6 維 diff dimension audit

跨 vendor 遷移前先盤點 source 跟 target 在六個維度的落差、用最大落差維度決定 playbook 結構、而不是反過來套既有模板。RabbitMQ → Kafka 的 audit 結果：

三個維度 High：paradigm、application change、data topology。其中 paradigm 是主導維度 —— application change 跟 data topology 的落差都是 paradigm 落差的下游結果。consumer 要重寫，是因為「ack 後即刪」變成「offset 不刪」；資料拓樸要重劃，是因為「broker 路由到 queue」變成「producer 決定 partition」。

主導維度是 paradigm、對映 Type E paradigm shift 結構：先講「字面 migration 不成立」、再講適配度（什麼能遷什麼不能）、再講 application 重設計與部分 cutover、最後是長期混合架構。application change 跟 data topology 這兩個高維度不另起 playbook、而是落在 application 重設計段與故障演練段裡展開。

為什麼 paradigm 是主導、不是 application change

application change 看起來工作量最大（consumer / producer 都要改），直覺會把它當主導維度。但 application change 的方向跟難度是由 paradigm 決定的：如果只是 AMQP client 換 Kafka client、心智模型不變，那 application change 是機械式翻譯、屬於 Schema/API 維度。實際上 consumer 不只是換 SDK、是要把「處理完才 ack、失敗就 nack 重投」的設計改成「拉一批、處理、commit offset、失敗自己重試或寫 DLQ topic」—— 這是責任模型的改變，不是 API 的改變。所以主結構走 paradigm、application change 是它的展開。

什麼 workload 真該遷、什麼不該

判讀的核心問題是：這個 workload 需要的是「處理一次就完成的任務」、還是「被多方各自讀取、可回放的事件」。

任務分派場景不該遷。寄信、轉檔、生成縮圖這類 workload 的本質是「有一個工人池、把任務做完就結束」、RabbitMQ 的 manual ack + prefetch + DLX 對這條路徑是貼合的設計。把它搬到 Kafka 會引入不需要的複雜度：partition 數要規劃、consumer group rebalance 要管、offset commit 時機要自己設計、而換來的 replay 能力在「任務做完就丟」的場景根本用不到。單純 work queue 不需要 Kafka 是這篇 playbook 最該先說清楚的判讀。

事件流場景該遷。當同一份事件要被 analytics pipeline、search index sync、audit log、下游微服務各自消費、而且各自進度不同、偶爾要回放過去 N 天重算 —— RabbitMQ 的「ack 後即刪」就會逼出「為每個 consumer 複製一份 queue」的反模式，這正是 Kafka 的 consumer group + retention 要解的問題。

複雜 routing 場景要重新設計、不是平移。RabbitMQ 的 topic exchange 用 order.*.created 這種 binding pattern 在 broker 端做內容路由、consumer 訂閱 binding 就收到符合的訊息。Kafka broker 不做內容路由，要嘛把路由邏輯前移到 producer（按內容決定寫哪個 topic / partition key），要嘛 consumer 端全收後自己 filter。直接平移會發現 Kafka 沒有 exchange 這個概念，routing 拓樸必須重新設計。

為什麼會考慮這個 paradigm shift

實務上從 RabbitMQ 評估遷往 Kafka 通常由三條 driver 觸發：

1. 同一事件要 fan-out 給愈來愈多 consumer：初期一個 queue 一個 worker、後來下游團隊一個個來要「也給我一份」。RabbitMQ 要嘛加 fanout exchange + 每團隊一個 queue、要嘛 consumer 互搶。Kafka 的 consumer group 天然支援「N 個獨立團隊各自從頭讀」、這是最常見的 driver。
2. 需要 replay 重算：下游邏輯出 bug、要重跑過去 7 天的事件修資料；RabbitMQ ack 後訊息已刪、無從回放。Kafka retention 期內可以從任意 offset 重讀。
3. 吞吐量壓到 RabbitMQ 的設計邊界：單 queue 的 throughput 受限於單一 queue 的處理模型、量大時要拆 queue 手動分流；Kafka 的 partition 並行是 first-class。

這三條 driver 都指向 event streaming 的特性、不是「Kafka 普遍比較好」。任務隊列場景套不上這三條 driver、就不該被這個評估帶著走。

Migration 結構：application 重設計 + 部分 cutover + 長期混合

RabbitMQ → Kafka 不是一次性 cutover，是按 workload 拆分、漸進遷移、長期共存：

1. Phase 0：workload 盤點 — 把現有 queue / exchange 逐一分類「適合 Kafka（event 性質）」vs「保留 RabbitMQ（task 性質）」。盤點輸出是清單，不是「全遷」。
2. Phase 1：application code 重設計 — 對判定要遷的 workload，重寫 producer（exchange routing → topic + partition key）跟 consumer（manual ack → offset commit + 自管重試 / DLQ）。這是 paradigm 翻譯，不是 SDK 替換。
3. Phase 2：dual-write 並行 — producer 同時寫 RabbitMQ 跟 Kafka、新 consumer 從 Kafka shadow consume 驗證行為對齊、舊 consumer 持續從 RabbitMQ 消費。
4. Phase 3：cutover 個別 workload — shadow 驗證通過後、把該 workload 的真正消費切到 Kafka、停掉 RabbitMQ 端的對應 consumer 與 dual-write。
5. Phase 4：長期混合 — task 性質的 workload 永遠留在 RabbitMQ、event 性質的在 Kafka。兩者共存是終態、不是過渡。

整體不是「把 RabbitMQ 換成 Kafka」、是「把適合 event log 的部分搬到 Kafka、其餘留在 RabbitMQ」。多數環境的終態是兩者並存。

Application 重設計範例：manual ack → offset commit

RabbitMQ consumer 的核心是 每個 message 處理完顯式 ack、broker 才認定投遞成功；失敗就 nack、broker 重投或進 DLX。Kafka consumer 沒有 per-message ack 的概念、是 批次拉取、處理、commit offset；commit 的是「讀到哪了」、不是「哪幾條成功了」。

 1# RabbitMQ 端：manual ack、per-message 成敗
 2channel.basic_qos(prefetch_count=10)
 3
 4def on_message(ch, method, properties, body):
 5    try:
 6        process(body)
 7        ch.basic_ack(delivery_tag=method.delivery_tag)
 8    except Exception:
 9        # 拒絕並不重新入列、由 DLX 接住
10        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
11
12channel.basic_consume(queue="orders", on_message_callback=on_message)
13channel.start_consuming()

 1# Kafka 端：批次 poll、處理後 commit offset
 2consumer = KafkaConsumer(
 3    "orders",
 4    group_id="orders-worker",
 5    enable_auto_commit=False,        # 關掉 auto commit、自己控制時機
 6    auto_offset_reset="earliest",
 7    max_poll_records=10,             # 對應 RabbitMQ 的 prefetch
 8)
 9
10for batch in iter_batches(consumer):
11    for msg in batch:
12        try:
13            process(msg.value)
14        except Exception:
15            send_to_dlq_topic(msg)   # 自建 DLQ topic、Kafka broker 不提供 DLX
16    consumer.commit()                # commit 的是 offset、不是個別 message

差異的關鍵不在 API 形狀、在責任邊界：

• RabbitMQ 一條失敗就 nack 一條、其餘正常 ack；Kafka commit 的是 offset 這個「水位線」、水位線以下視為已處理。失敗的單條訊息無法「跳過不 commit 但繼續往後」—— 要嘛阻塞、要嘛自己寫 DLQ topic 後讓 offset 照常前進。
• RabbitMQ 重試由 broker 負責（重投 / DLX）；Kafka 重試要 application 自己設計（原地重試 / 寫 retry topic / 寫 DLQ topic）。
• RabbitMQ prefetch 控制「broker 一次推幾條未 ack 的給我」；Kafka max.poll.records 控制「我一次 poll 拉幾條」—— 方向相反，一個是 broker push、一個是 consumer pull。

Production 故障演練

Case 1：manual ack 觀念帶到 offset commit、誤判「已處理」

徵兆：cutover 後某 worker crash 重啟、發現一批訊息被重複處理；或反過來、一批訊息明明沒處理成功卻再也讀不到。RabbitMQ 端跑了多年的 ack 邏輯搬過來就出事。

根因：把 RabbitMQ 的「per-message ack」心智直接套到 Kafka 的 offset commit。常見錯法是 enable.auto.commit=true + 預設 auto.commit.interval.ms、消費迴圈還沒處理完、背景 thread 已經把 offset commit 出去了 —— crash 後 offset 已前進、未處理的訊息永遠跳過（資料遺失）。或反過來、處理完才 commit 但 commit 失敗、重啟後從舊 offset 重讀（重複處理）。RabbitMQ 的 ack 是「這一條我處理完了」、Kafka 的 commit 是「這個 offset 之前我都讀過了」—— 後者是水位線、不是逐條確認。

修法：

1. 關掉 auto commit、手動 commit：enable.auto.commit=false、在一批訊息確實處理完之後才 commit()。
2. 接受 at-least-once、設計 idempotency：Kafka 的預設語意是 at-least-once、重啟重讀無法完全避免、consumer 端要用 message key + dedup store 顯式去重。對應 6.12 idempotency / replay。
3. commit 時機對齊處理邊界：批次處理完才 commit、不要一邊處理一邊讓背景 commit 跑在前面。

Case 2：routing key → partition key、ordering 邊界悄悄改變

徵兆：cutover 後同一個訂單的 created / paid / shipped 事件偶爾亂序到達 consumer；RabbitMQ 端用 consistent hash exchange 跑了兩年、同一訂單的事件一直是有序的。

根因：RabbitMQ 用 consistent hash exchange 把同 key 的訊息路由到同一個 queue、單一 consumer 順序處理就有序。Kafka 的 ordering 保證範圍是 單一 partition 內、跨 partition 無序。如果 producer 沒設 partition key、或設了但 key 選得不對（例如用 event type 當 key 而不是 order id）、同一訂單的事件就散到不同 partition、被不同 consumer 並行處理、ordering 就斷了。RabbitMQ 的 ordering 邊界是「queue」、Kafka 的 ordering 邊界是「partition key」—— 邊界從 broker 端的 binding 移到了 producer 端的 key 選擇。

修法：

1. ordering 單位當 partition key：需要保序的單位（order id / user id）設成 partition key、同 key 落同 partition。
2. 盤點現有 RabbitMQ 的保序假設：哪些 queue 隱含「同 key 有序」、把那個 key 顯式提升為 Kafka partition key。
3. 接受 partition 數限制並行：保序的代價是同 key 只能單一 partition、partition 數是並行上限；保序需求跟並行度需要一起設計。對應 Partition 卡。

Case 3：DLX → 自建 DLQ topic、毒訊息卡住整個 partition

徵兆：某條訊息 application 處理永遠拋例外、consumer 不斷在這條上重試、整個 partition 後面的訊息全卡住、consumer lag 暴增；RabbitMQ 端這種毒訊息會被 nack 進 DLX、不影響後面。

根因：RabbitMQ 有原生 DLX、處理失敗的訊息 nack 後自動進 dead-letter exchange、queue 繼續往下。Kafka broker 沒有 DLX 概念、也沒有「跳過這一條」的機制 —— offset 是連續水位線、要往後就得處理掉當前這條。如果 application 在毒訊息上無限重試、offset 永遠不前進、後面所有訊息餓死。把 RabbitMQ「broker 幫我處理毒訊息」的假設帶過來、就會卡死。

修法：

1. 自建 DLQ topic：consumer 端設重試上限、超過上限把訊息寫進專屬的 orders.DLQ topic、然後 commit offset 讓主流程前進。對應 Dead-letter queue 卡。
2. retry topic 分層：仿 RabbitMQ 的延遲重試、可以設 orders.retry.5s / orders.retry.1m 多層 retry topic、由獨立 consumer 延遲後重投主 topic。
3. DLQ 要有人看：自建 DLQ topic 不像 RabbitMQ management UI 有現成可視化、要主動監控 DLQ topic 的訊息數、否則毒訊息靜默堆積。

Case 4：prefetch → max.poll.records，poll 間隔超時觸發 rebalance

徵兆：consumer 處理一批訊息花的時間偏長、Kafka 突然判定這個 consumer 死了、觸發 rebalance、partition 被重新分配、同一批訊息被另一個 consumer 重複處理；RabbitMQ 端用 prefetch 控制併發從沒這問題。

根因：RabbitMQ prefetch 只控制「broker 一次最多推幾條未 ack 給這個 consumer」、處理多久 broker 不管。Kafka 用 max.poll.interval.ms 監控「兩次 poll 之間最多隔多久」、如果一批 max.poll.records 拉太多、處理超過 max.poll.interval.ms 還沒回來 poll、broker 認定 consumer 卡死、踢出 group 觸發 rebalance。把 prefetch 的數值直接套成 max.poll.records、又沒考慮單批處理時間、就會超時。

修法：

1. max.poll.records 配合單條處理時間設：一批的總處理時間要明顯小於 max.poll.interval.ms；處理慢就把 batch 設小。
2. 長處理 workload 調大 max.poll.interval.ms：單條本來就慢（呼叫外部 API）的、把 interval 放寬、或把處理移到另一個 thread pool、poll 迴圈只負責拉取。
3. 理解 push vs pull 的差異：RabbitMQ 是 broker push、consumer 慢只是堆積；Kafka 是 consumer pull、consumer 慢會被誤判為死亡。這層差異是 prefetch 跟 max.poll.records 不能直接對映的根因。對應 Consumer group 卡。

Case 5：RabbitMQ 即刪 vs Kafka retention、replay 行為差異炸出資料量

徵兆：團隊以為 Kafka「跟 RabbitMQ 一樣處理完就沒了」、結果 disk 持續長大；或反過來、需要 replay 時才發現 retention 設太短、要回放的事件已經被清掉。RabbitMQ 心智下「訊息消費完就不佔空間」的假設不成立。

根因：RabbitMQ ack 後訊息即刪、queue 的空間隨消費釋放。Kafka 寫進 log 後在 retention 期內一直留著、不管有沒有被消費 —— 這正是 replay 能力的來源、也是 disk 成本的來源。沒設好 retention，要嘛留太久 disk 爆、要嘛留太短該 replay 時沒得 replay。RabbitMQ 沒有「retention」這個旋鈕（它是 ack 即刪），Kafka 必須顯式設 retention policy。

修法：

1. 按 replay 需求設 retention：event sourcing 要回放幾天就設幾天的 retention.ms、不是抄 RabbitMQ 的「處理完即刪」心智。
2. 算清 retention 的 disk 成本：retention × 寫入速率 = 佔用空間、納入容量規劃；對比 RabbitMQ 只佔「未消費」的量、Kafka 佔「retention 期內全部」的量。
3. compact topic 給狀態類資料：如果只需要「每個 key 最新值」（像 RabbitMQ 不存在的場景）、用 cleanup.policy=compact 而非 time-based delete、避免無限長大。對應 Topic 卡的 retention policy。

漸進 cutover：dual-write 與 shadow consume

paradigm shift 不能一次切換、因為 consumer 行為（offset 語意、ordering、DLQ、重試）全變了、需要在真實流量下驗證新 consumer 跟舊 consumer 結果一致才敢切。漸進 cutover 用兩個機制：

dual-write：producer 同時往 RabbitMQ 跟 Kafka 寫同一份事件。RabbitMQ 端維持舊 consumer 正常生產、Kafka 端讓新 consumer 接收。dual-write 期間 RabbitMQ 仍是 source of truth、Kafka 只是並行驗證。要處理的細節是雙寫的一致性 —— 寫了 RabbitMQ 但 Kafka 寫失敗時怎麼辦、實務上通常容忍 Kafka 端短期缺漏（因為還沒切過去）、但要監控雙端的訊息數落差。

shadow consume：新的 Kafka consumer 跑完整處理邏輯、但 side effect 導到影子環境（寫影子 DB、不發真實 webhook、不寄真實信）。把 Kafka consumer 的處理結果跟 RabbitMQ consumer 的真實結果比對、確認 ordering、去重、DLQ 行為都對齊。shadow 期是 paradigm 翻譯正確性的驗證窗口、不是效能測試。

cutover 是 per-workload 的：某個 workload shadow 驗證通過、就把它的真實消費切到 Kafka、停掉該 workload 的 RabbitMQ consumer 與 dual-write；其他 workload 維持原狀繼續驗證。不是全站一次切。

Capacity / cost 對照

判讀：純 work queue 場景 RabbitMQ 的運維成本顯著低、Kafka 的 storage 跟運維是為了 replay 與高吞吐付的價。如果 workload 用不到 replay 跟跨 consumer group fan-out、遷到 Kafka 是用更高的成本換用不到的能力。

整合 / 下一步

混合架構是 long-term default

多數環境的終態是 RabbitMQ 與 Kafka 共存、各管各的責任：

1[task 分派：寄信 / 轉檔 / webhook]        [event log：CDC / 事件總線 / replay]
2         RabbitMQ                                    Kafka
3         │                                            │
4         └──────── Bridge（Connect source / 自寫）────┘

RabbitMQ 跑「處理即承諾」的任務隊列、Kafka 跑「寫入即承諾」的事件流。需要從任務流產生事件記錄時、用 Kafka Connect 的 RabbitMQ source connector 或自寫 bridge 把選定的訊息搬到 Kafka topic。

跟 outbox pattern 對位

從 RabbitMQ 遷往 Kafka 常伴隨 資料庫交易與事件發布一致性 的需求 —— 因為 event sourcing 場景要求事件不能丟。直接在交易中寫 Kafka 有雙寫一致性問題、應該走 3.3 outbox pattern：交易內只寫 outbox 表、再由 Debezium CDC 把 outbox 變更發到 Kafka topic。

跟其他 migration 結構的對照

兩篇都是 paradigm shift、都是 partial migration + 長期混合。差別在落差的方向：Kafka ↔ NATS 是 log vs subject messaging 的抽象層差異、RabbitMQ → Kafka 是 work queue vs event log 的責任模型差異 —— 後者的核心翻譯是「處理即承諾」如何重新表達成「寫入即承諾 + offset replay」。

相關連結

• Source / target vendor：RabbitMQ / Kafka
• 平行 vendor：NATS / Redis Streams
• 平行 migration playbook：Kafka ↔ NATS / Kafka → MSK
• 關鍵概念卡：Partition / Topic / Consumer group / Dead-letter queue / Ack/nack
• 下游能力：3.3 outbox pattern / 3.4 consumer 設計 / 6.12 idempotency / replay
• Methodology：Migration Playbook 寫作方法論

本文是跨 vendor migration playbook、cross-link 到 Redis（source）跟 Valkey（target）。跑 6 維 diff dimension audit 後判定為 Type B drop-in（全維度 Low），結構走 6-section + 相容性 audit 前置。實機驗證於 valkey/valkey:8（valkey_version 8.1.8、redis_version 7.2.4）、最後檢查日 2026-06-16。

同一份程式碼、不同授權

多數 migration 的工作量在「source 跟 target 不一樣」——schema 要翻譯、API 要改、資料要轉。Redis → Valkey 幾乎沒有這個問題：Valkey 是 2024 年從 Redis 7.2.4 直接 fork 出來的，那一刻它跟 Redis 是 bit-for-bit 同一份程式碼。RDB 與 AOF 檔案格式相同（可以直接把 Redis 的資料目錄拷給 Valkey 載入）、RESP 協定相同、所有 Redis client library 不改一行就能連。技術上，這是 cache 領域最容易的遷移。

那為什麼要寫一篇 playbook？因為這個遷移的工作量不在資料層，在兩個別的地方。第一是授權——Redis 2024 改成 RSALv2 / SSPL（非 OSI 認可），Valkey 是 BSD 3-clause（OSI、Linux Foundation 治理），這個遷移的整個 driver 是授權合規，而合規驗證有它自己的流程。第二是fork 後的分歧——fork 那一刻兩者相同，但之後各自演進：Redis 加了 7.4+ 的新功能、Valkey 加了自己的（如 8.x 多執行緒），用到 fork 之後 Redis 新功能的部署會有相容缺口。

INFO server 上看得到這個「同源但分歧」的事實：

1valkey-cli INFO server | grep -E "redis_version|valkey_version"
2# redis_version:7.2.4    ← fork 點、client 以此判斷相容性（裝成 Redis 7.2.4）
3# valkey_version:8.1.8   ← Valkey 自己的演進線

redis_version:7.2.4 是相容性的保證（client 看到就以 Redis 7.2.4 行為運作）；valkey_version 是分歧的證據。這篇 playbook 處理的就是「資料層幾乎零工作、工作在授權與分歧盤點」的 drop-in 遷移。

6 維 diff dimension audit：為什麼是 Type B

跑 diff dimension audit，Redis → Valkey 全維度 Low：

全 Low → Type B drop-in（6-section + 相容性 audit 前置、週期 1-4 週）。跟同模組的 Redis → DragonflyDB 對照：DragonflyDB 是 C++ 重寫（drop-in 但 Lua / encoding / module 有差異），Valkey 是 fork（同源、連 RDB 檔都相容）——Valkey 的相容度比 DragonflyDB 更高，是 Type B 裡最純粹的一端。

這個遷移的特殊之處是 driver 在資料層之外：它是授權 / 合規驅動。依 migration 方法論 的漏類處理，政策 / 合規驅動的遷移資料層仍走 Type B，但 audit 重點多一塊授權驗證與證據收集。

相容性 audit：cutover 前要確認的清單

Valkey 號稱 100% 相容 Redis 7.2.4，但「100%」的邊界在 fork 之後的分歧。Pre-migration 必跑的 audit：

audit 的關鍵 output：兩份清單——(1) 用到的 Redis 7.4+ 功能（fork 後新增、Valkey 可能沒有）、(2) 載入的 Redis Stack module。這兩塊是僅有的相容風險，其餘資料層零工作。盤點方法：

1# 盤點載入的 module（最大相容風險）
2redis-cli MODULE LIST
3
4# 盤點是否用到 7.4+ 功能（抓 production traffic 對照 Redis 7.4 changelog）
5redis-cli MONITOR    # 限時抓樣、grep 可疑的新命令

Step-by-step cutover

因為 RDB 檔案相容，cutover 比 DragonflyDB 更簡單（無版本轉換風險）：

 1# 1. 部署 Valkey（同 Redis 配置、可直接沿用 redis.conf）
 2docker run -d --name valkey -p 6380:6379 \
 3  -v /data/valkey:/data \
 4  valkey/valkey:8 valkey-server /etc/valkey/valkey.conf
 5
 6# 2. Redis 端 BGSAVE 產生 RDB
 7redis-cli -h redis-primary BGSAVE
 8redis-cli -h redis-primary INFO Persistence | grep rdb_last_save_time
 9
10# 3. 把 dump.rdb 拷給 Valkey（檔案格式相容、無需轉換）
11scp redis-primary:/var/lib/redis/dump.rdb valkey-host:/data/valkey/
12
13# 4. 重啟 Valkey 載入 RDB
14docker restart valkey
15
16# 5. 驗證資料一致 + 版本
17valkey-cli -h valkey-host -p 6380 DBSIZE          # 對齊 Redis DBSIZE
18valkey-cli -h valkey-host -p 6380 INFO server | grep redis_version  # 7.2.4
19
20# 6. 替代方案（零停機）：用 replicaof 讓 Valkey 當 Redis 的 replica、即時同步後 promote
21#    valkey-cli -h valkey-host REPLICAOF redis-primary 6379
22#    重要邊界：此路徑只在 source 是 Redis 7.2 或更早版本時成立。
23#    Redis 7.4+（Community Edition）改了複製格式、Valkey 無法當其 replica
24#    → source 為 7.4+ 時改走上面的 RDB 拷貝路徑（步驟 2-4）。
25
26# 7. Cutover：client 配置切到 Valkey endpoint、Redis 留 standby

關鍵時間點：

• RDB 拷貝 + load：100GB 約 5-15 分鐘（無版本轉換、比 DragonflyDB 少一道風險）
• replicaof 路徑：要零停機可讓 Valkey 當 Redis replica 即時同步、確認 lag 趨零後 promote + 切 client（僅限 source 為 Redis 7.2 或更早；7.4+ 複製格式已分歧、不適用、改走 RDB 拷貝）
• Cutover：client 配置切換（單次完成、硬邊界）、Redis 留 standby 1-2 週
• Decom：無相容問題後關閉 Redis

Production 故障演練

Case 1：用到 Redis 7.4+ 功能、Valkey 沒有

徵兆：cutover 後某功能報 unknown command 或行為不同，命令是 Redis 在 7.4 之後（fork 點之後）才加的。

根因：Valkey fork 自 Redis 7.2.4，Redis 7.4+ 新增的功能 Valkey 不一定跟進。pre-migration audit 漏掉了這些 fork 後的新功能。

修法：

1. pre-migration 對照 Redis 7.4+ changelog 盤點用到的新功能（audit 清單第一項）
2. Valkey 有對應就確認版本、沒有就評估改寫或留在 Redis 商業版
3. 多數標準 cache 用法不碰 7.4+ 新功能，這個風險集中在用了較新進階功能的部署
4. Valkey 自己的 roadmap（valkey.io）會逐步補上 Redis 新功能，可追蹤

Case 2：載入了 Redis Stack 商業 module

徵兆：cutover 後 JSON.SET / FT.SEARCH 報 unknown command，application 部分功能失效。

根因：用了 Redis Stack 的商業 module（RedisJSON / RedisSearch），這些不在 fork 範圍。Valkey 有自己的 valkey-search / valkey-bloom，但不是同一套命令、要另外安裝。

修法：

1. pre-migration MODULE LIST 盤點所有載入的 module（audit 清單第二項）
2. 確認 Valkey 對應替代（valkey-search 對 RedisSearch）、確認命令相容度
3. 沒有對應的評估改 module-free 設計（JSON 操作拉回 application 層）或留在 Redis Inc 商業版
4. 對應 Valkey 相容性 deep article 的三層相容邊界

Case 3：以為換 Valkey 解決了記憶體 / fork 問題

徵兆：因為 Redis 的 OOM 或 fork 延遲尖峰而遷 Valkey，遷完發現同樣問題還在。

根因：Valkey fork 自 Redis 7.2.4，繼承了完全相同的記憶體模型、eviction 演算法、AOF/RDB fork 機制。這些行為在 Valkey 上一模一樣——遷移沒有改變它們。

修法：

1. 記憶體 / fork 調校在 Valkey 上跟 Redis 完全相同，直接套用 Redis 記憶體調校 與 persistence / fork latency
2. 遷 Valkey 的理由應是授權合規 / 多執行緒吞吐 / managed 成本，不是記憶體問題
3. fork 尖峰要根治走 DragonflyDB 的 fork-less，不是換 Valkey
4. 遷移前釐清痛點是授權（Valkey 解）還是架構（Valkey 不解）

Case 4：授權合規驗證沒做完整、合規卡關

徵兆：技術遷移完成、但法務 / 合規 review 要求證明「不再使用 RSALv2 / SSPL 授權的軟體」，缺少證據。

根因：這個遷移的 driver 是授權合規，但團隊只做了技術 cutover、沒收集合規證據。Redis 的 binary / image / 相依套件若還殘留在某些環境，合規目標沒真正達成。

修法：

1. 盤點所有環境（dev / staging / prod / CI）的 Redis binary / image / 相依，確認全部換成 Valkey
2. 收集合規證據：image SBOM、套件清單、部署 manifest 顯示 Valkey BSD 授權
3. 把「不再使用非 OSI 授權 cache」寫成可驗證的 CI 檢查（掃 image / 依賴）
4. 依 migration 方法論 的合規驅動漏類，audit 重點就是 evidence collection

Case 5：監控 dashboard 部分指標斷掉

徵兆：cutover 後 RedisInsight 或某監控 dashboard 部分面板空白、vendor-specific 命令回錯。

根因：RedisInsight 等 Redis Inc 工具有部分偏商業版的命令，Valkey 不一定實作。核心指標通用，但進階面板可能缺。

修法：

1. 監控改用通用工具：valkey-cli INFO、Prometheus + redis_exporter（相容 Valkey）、Grafana
2. 核心指標（used_memory / keyspace_hits / connected_clients）在 Valkey 完全相容、覆蓋不受影響
3. 把監控相容性納入 cutover 前驗證、不要遷完才發現面板空白
4. RedisInsight 連 Valkey 多數仍可用、只是部分 vendor 進階面板缺

Capacity / cost 對照

判讀：合規敏感（公部門 / 企業 OSI 政策）或想降 managed 成本 → 遷 Valkey（drop-in、風險集中在 module / 7.4+ 盤點）；重度依賴 Redis Stack 商業 module → 留 Redis Inc 商業版。

整合 / 下一步

跟 ElastiCache for Valkey 對位

AWS 已把 ElastiCache default engine 設為 Valkey（約低 Redis 20%）。自管 Redis → ElastiCache for Valkey 是「換授權 + 轉 managed」一次到位，但要同時處理 managed 責任邊界（failover / cluster mode / client 重連）。

跟 client / 監控整合

client library 零改（透過 redis_version 協商）；監控把 exporter 指向 Valkey 即可（redis_exporter 相容）、RedisInsight 部分面板需換通用工具。

跟 Valkey 8 多執行緒對位

遷移後可評估開 Valkey 8 的 io-threads 榨多核吞吐（Redis 7.2.4 沒有的能力），見 Valkey 相容性與 io-threads deep article。

下一步議題

• 反向遷移（Valkey → Redis）：僅在重度依賴 Redis 7.4+ 功能或 Stack 商業 module 時需要、同樣 drop-in
• 跨雲 managed Valkey：GCP Memorystore / Azure Cache 的 Valkey 支援陸續推出、評估 vendor boundary
• 授權合規 CI 化：把「不使用非 OSI 授權 cache」寫成持續檢查

相關連結

• Source vendor：Redis
• Target vendor：Valkey
• 平行 migration playbook：Redis → DragonflyDB（重寫型 drop-in）、Redis → Memcached
• Methodology：Migration playbook methodology（Type B drop-in + 合規驅動漏類）

本文是跨 vendor migration playbook、cross-link 到 Redis Streams 跟 Kafka。對位 Kafka ↔ NATS 的 paradigm shift 模板 — 兩端不是同類產品的不同實作、是不同抽象層的系統：一個是 Redis 行程內的 append-only log data structure、一個是專用的 distributed event streaming platform。

Redis Streams 跟 Kafka 是不同抽象層的東西

Redis Streams 是 Redis 行程內的一個 data structure、Kafka 是一整套獨立的 distributed event streaming platform。這個區別決定整趟遷移的性質：要把 messaging 能力從「既有 Redis 行程的一塊記憶體」搬到「自成一格、要獨立運維的多節點叢集」，遠超過換個相容 broker 的工作量。

Redis Streams 的責任邊界是「在已經跑著的 Redis 裡多一個 append-only log」。它共用 Redis 的記憶體、持久化（AOF / RDB）、failover（Sentinel / Cluster）跟運維團隊。寫入用 XADD、消費用 XREADGROUP，consumer group 跟 pending entries list（PEL）都活在同一個 Redis 行程。它的設計取捨偏向「低延遲、低運維增量、跟 Redis 生命週期綁定」。

Kafka 的責任邊界是「成為跨系統的事件總線」。它把訊息寫成 partition 化的 log、落在獨立 broker 的磁碟、用 replication 保護、用 consumer group offset 追蹤各 consumer 進度，可長期保留並隨意 replay。它的設計取捨偏向「寫入即承諾、磁碟級長期保留、多 consumer 各自重播、水平擴展吞吐」。

關鍵在「拓樸單位」這列。Redis Streams 的一個 stream key 只能落在單一 shard、沒有 partition 概念，吞吐與資料量受單 shard 的記憶體與單執行緒處理能力封頂。Kafka 的 topic 天然切成多 partition、分散到多 broker，這是兩者在規模上的分水嶺，也是後面所有對位與故障演練的根。

先確認是不是真的該遷：多數中小規模不該遷

決定遷移前先做反向確認：在中小規模、且團隊已熟 Redis 的情境，Redis Streams 往往已經夠用，把它換成 Kafka 多半是引入運維負擔而非解決問題。遷移的正當理由來自規模或保留需求真的超出 Redis Streams 的能力邊界，而不是 Kafka 更主流。

Arcjet 的方向恰好相反、值得當反向參照。Arcjet 的 security / bot detection 平台需要低延遲請求處理，原本評估 Kafka，發現 managed Kafka 要六位數美元年費、自管運維難度也高；他們把既有的 Redis cache 層升級成 Streams，總成本掉到約一千美元年費。代價是 Redis Streams 沒有自動 retention，他們自寫一個 Janitor process，依約每分鐘一百則的實際處理速度監測 stream 長度跟 consumer group 狀態、selectively trim。

Arcjet 的判讀對遷移方向的啟示：當 workload 是低延遲、資料量留在記憶體可承受的範圍、團隊本來就在跑 Redis，Redis Streams 是務實且便宜的選擇；願意自寫 retention 工具就能補上它缺的治理能力。這條路成立時，遷去 Kafka 是用六位數年費跟一整套叢集運維，去換一個現有方案已能覆蓋的需求。

Bitso 是另一個 Redis Streams 站得住的高壓案例。Bitso 的撮合引擎微服務要扛每秒上千則訊息、亞毫秒延遲、撐住 BTC 價格暴動的尖峰；他們先後評估 Kafka（延遲不符）跟 SQS（vendor lock-in + 延遲）後選 Redis Streams，自建一層 Reliable Streams 抽象封裝 PEL + retry + DLQ，走 idempotent processing 接受重複勝過遺失。Bitso 揭露 Redis Streams 是「資料結構」而非「broker 系統」，可靠性責任在 application 層；但在亞毫秒延遲是硬指標的撮合場景，這個取捨反而讓 Redis Streams 勝過 Kafka。

兩個案例共同點：當延遲是硬指標、資料量在 RAM 可承受範圍、團隊能自建缺的治理層，Redis Streams 就站得住。遷去 Kafka 的決策該建立在這些前提不再成立之上，而不是建立在 Kafka 更有名之上。

真正該遷的訊號

決定遷移的依據是 Redis Streams 的三個能力邊界被實際 workload 突破：retention 需求超出 RAM 的成本曲線、需要長期 replay、consumer group 或 partition 規模超出單一 Redis 行程。三個訊號中任一個被觸發、且自建工具補不回來時，遷去 Kafka 才划算。

第一個訊號是 retention 超出 RAM 的成本翻轉。Redis Streams 的資料活在記憶體，保留越久、stream 越長、佔的 RAM 越多，而 RAM 是 Redis 叢集裡最貴的資源。當 retention 需求從「幾小時的緩衝」長到「數天到數週的事件保留」，把這些資料留在 RAM 的成本會快速超過 Kafka 把同樣資料留在 broker 磁碟（甚至 tiered storage 到 S3）的成本。Learning.com 退場案例就是這條線被突破的反例 — 把 Redis 當長期事件儲存（Stream 是其中一塊），事件量每週以 GB 成長、AOF fsync 與 EBS I/O 變成 latency 痛點，最終退回 PostgreSQL。成本曲線翻轉是最常見、也最該觸發遷移的訊號。

第二個訊號是需要長期 replay。事件溯源（event sourcing）或合規稽核場景，需要保留並重播數週、數月甚至數年的歷史事件。Redis Streams 的 replay 只能重讀 retention 內還在的資料，而 retention 受 RAM 限制無法拉得很長；Kafka 的磁碟保留加 tiered storage 讓長期 replay 變成 first-class 能力。當 replay 視窗的需求超出 RAM 能承受的 retention，這個訊號成立。

第三個訊號是 consumer group 或 partition 規模超出單一 Redis。Redis Streams 的單一 stream key 綁在單一 shard，吞吐受單 shard 封頂、沒有 partition 可以水平拆分並行度；要跨 shard 只能手動用 hash tag 切成多個獨立 stream，application 自己路由。當單一邏輯 stream 的吞吐需求、或 consumer 並行度需求超過單 shard 能給的，且手動切 stream 的複雜度已經失控，Kafka 的原生 partition 才值得換。

這三個訊號之外，還有一個放大條件：是否需要 Kafka 生態（Schema Registry、Connect / Debezium CDC、Streams 流處理）。如果遷移同時要接上 CDC pipeline 或 schema 強制治理，那 Kafka 帶來的不只是 retention 跟 partition、而是整套生態，這會讓遷移的價值天平更傾向 Kafka。但若只是想要更長 retention、生態用不到，先評估 Redis tiered 方案或自建 Janitor 是否更便宜。

概念對位：XADD/XREADGROUP/XACK/MAXLEN/XCLAIM

遷移的核心工作是把 Redis Streams 的五個核心操作對應到 Kafka 的等價概念、並理解每個對位背後語意的偏移，這比換 SDK 重得多。直接照字面搬會在 retention、消費進度、失敗接管三處踩雷，這三處正是後面故障演練的來源。

XADD 對 producer.send 的最大偏移是 partition key。Redis 的單一 stream key 沒有 partition，所有 entry 都在同一條序列上嚴格有序；Kafka 把訊息依 key 雜湊分到不同 partition，只有同一 partition 內保證有序。遷移時要決定哪個欄位當 partition key、這個決定同時決定了 ordering 的範圍跟 hot partition 的風險。

XREADGROUP 對 consumer group 的偏移在 rebalance。Redis consumer group 沒有自動 rebalance，consumer 掛掉後它名下未 ack 的訊息留在 PEL，要靠其他 consumer 主動 XCLAIM 接管；Kafka 的 consumer group 有 rebalance protocol，consumer 加入或離開時 broker 自動把 partition 重新分配。從手動接管搬到自動 rebalance，application 端負責接管的那段邏輯可以刪掉、但要改成理解 rebalance 行為。

XACK 對 offset commit 是最容易誤用的一處，獨立成下一節的故障演練。MAXLEN 對 retention policy 是成本模型翻轉的核心，也獨立成故障演練。

Production 故障演練

Case 1：Retention 模型從 RAM 限制翻成 log 成本，磁碟與成本失準

徵兆：團隊把 Redis Streams 的 MAXLEN 100000（保留最近十萬則、控制 RAM）習慣直接對映成 Kafka 的某個數字，結果 cutover 後不是 broker 磁碟暴漲超出預期、就是資料保留遠短於業務需要、replay 視窗對不上。

根因：Redis Streams 的 MAXLEN 是 application 在每次 XADD 主動修剪的「條數上限」，目的是壓住 RAM 佔用，是一個 count-based 的記憶體預算旋鈕。Kafka 的 retention 是 broker 端被動執行的 policy、預設是 time-based（retention.ms）或 size-based（retention.bytes），目的是控制磁碟保留窗，而磁碟比 RAM 便宜一到兩個數量級。兩者的單位、執行主體、成本曲線都不同 — 把「保留十萬則以省 RAM」直接搬成 Kafka 設定，會錯估磁碟用量，也會把 Redis 時代「為了省 RAM 而被迫短保留」的限制錯誤地帶進一個本來就能長保留的系統。

修法：

1. 從業務需求重算 retention、不沿用 Redis 的 RAM 預算：Redis 的 MAXLEN 數字是 RAM 成本的妥協、不是業務的真實保留需求；遷移時回到「業務需要 replay 多久」重新算 retention.ms，這正是遷移要解鎖的能力。
2. 改用 time-based 為主、size-based 當保險絲：Kafka 設 retention.ms 對齊業務 replay 窗、再設 retention.bytes 防單 partition 磁碟失控。
3. 長保留接 tiered storage：retention 需求拉到數週數月時，把冷資料分層到 S3、熱資料留本地磁碟，成本曲線進一步壓平，而這在 Redis 的 RAM 模型下做不到。

Case 2：PEL 觀念被帶進 offset，造成重複或漏消費

徵兆：遷移後 consumer 出現「明明處理過的訊息又被重新消費」或「某些訊息整批沒被處理」；團隊照 Redis 時代「逐則 XACK」的心智模型管理 Kafka offset commit，結果對不上。

根因：PEL 跟 offset 是兩個不同的進度模型。Redis Streams 的 PEL 是 broker 維護的「逐則待 ack 集合」，每則訊息獨立追蹤是否已 ack，consumer 可以亂序 ack 某幾則、其他留在 PEL；XACK 是針對特定 entry ID 的點狀確認。Kafka 的 offset 是 per partition 的單調位移、代表「這個位置之前都算消費完」，commit offset N 意味著 0 到 N-1 全部視為已處理。把 PEL 的逐則語意套到 offset 上會出兩種錯：一是處理完亂序的訊息後 commit 了較大的 offset，中間沒處理完的訊息被當成已消費而漏掉；二是 commit 時機錯置（auto-commit 在處理前就 commit），crash 後從錯誤位置重讀造成重複。

修法：

1. 理解 offset 是區間承諾、不是逐則確認：commit offset 前確保該 offset 之前的訊息都已處理完、不要對亂序處理的批次 commit 最大 offset。
2. 關 auto-commit、改 manual commit 在處理之後：enable.auto.commit=false，處理完一批再 commit，對齊 at-least-once。
3. 保留 application 端 idempotency：這點從 Redis 時代就該有、遷到 Kafka 仍成立 — at-least-once 下重複難免，用 message ID + dedup store 顯式去重，對位 idempotency 卡跟 Bitso 的 idempotent processing。

Case 3：單 stream key 換成多 partition，ordering 假設破裂

徵兆：遷移前所有事件在單一 Redis stream 上嚴格有序、downstream 依賴這個順序（例如同一筆訂單的 created → paid → shipped）；切到 Kafka 多 partition 後，同一筆訂單的事件被分到不同 partition、處理順序錯亂。

根因：Redis Streams 的單一 stream key 綁單一 shard、所有 entry 在一條序列上全域有序，application 不需要思考 ordering 範圍就免費得到全序。Kafka 把 topic 切成多 partition 來換取水平吞吐，代價是只保證 同一 partition 內 有序、partition 之間無序。遷移時若沒指定 partition key、訊息會被 round-robin 或依預設雜湊散開，同一個業務實體（訂單、帳戶、裝置）的事件落到不同 partition，全序假設就破了。

修法：

1. 用業務實體當 partition key：把需要保序的實體 ID（訂單 ID、帳戶 ID）當 Kafka message key，同 key 雜湊到同 partition、partition 內保序，把「全域有序」收斂成「per-entity 有序」這個多數業務真正需要的粒度。
2. 辨識哪些流真的需要全序：若某條流真的需要全域嚴格有序且無法拆成 per-entity，設單 partition topic（犧牲該 topic 的水平吞吐）；這也是個訊號 — 若大量流都需要全序，遷 Kafka 的吞吐優勢用不上、該重新評估遷移。
3. 規劃 partition 數對齊並行度跟 hot key：partition 數決定 consumer 並行上限，同時注意熱門 key 造成的 hot partition，對位 Kafka topic 設計的 key 策略段。

Case 4：Redis 既有低延遲被 Kafka 吞吐換掉，延遲敏感路徑受傷

徵兆：遷移後某些原本靠 Redis Streams 亞毫秒延遲的路徑（即時風控判斷、撮合前置）延遲跳到數十毫秒，下游 SLA 破線。

根因：Redis Streams 的亞毫秒延遲來自記憶體操作 + 行程內 data structure；Kafka 為了長期保留跟高吞吐，訊息要落磁碟、過 replication、走網路到獨立 broker，單則訊息延遲落在 5-50ms 區間，這是它換吞吐跟持久性付出的代價。把延遲敏感路徑無差別搬上 Kafka，等於用一個為吞吐優化的系統去服務一個為延遲優化的需求。

修法：

1. 按延遲需求分流、不要全遷：把延遲敏感的即時路徑留在 Redis Streams（或 Redis 其他結構）、把需要長保留 / 高吞吐 / replay 的事件流遷到 Kafka，這正是 Bitso 在撮合場景堅持 Redis Streams 的理由。
2. 接受混合架構是常態：Redis Streams 跟 Kafka 共存、各自服務適配的 workload，不追求「全部統一到 Kafka」；對位 Kafka ↔ NATS 的混合架構是 long-term default 思路。
3. 若 Kafka 延遲必須壓低：調 producer linger.ms=0 + acks=1、consumer fetch.min.bytes=1 換取較低延遲，但這會犧牲吞吐與部分可靠性、是 trade-off 不是免費午餐。

Migration 結構：漸進 cutover + 長期混合

這趟遷移的結構是漸進拆分而非一次性切換：先按 workload 性質分流、再對需要遷的事件流做 dual-write 並行、逐流 cutover、最終留下 Redis Streams 跟 Kafka 共存的混合架構。一次性把所有 stream 搬上 Kafka 既無必要、也會把延遲敏感路徑拖下水。

1. Phase 0：scope 分流 — 對每條 stream 跑前面三個訊號的判讀，分成「該遷 Kafka」（retention / replay / 規模超界）跟「留 Redis Streams」（延遲敏感 / 規模在範圍內）兩類。這一步直接決定後續工作量、也避免無差別遷移。
2. Phase 1：Kafka 叢集與 topic 設計 — 建 broker 叢集、依 Case 3 的 partition key 設計建 topic、依 Case 1 的業務需求設 retention，這時做的是基礎設施準備、還沒碰流量。
3. Phase 2：dual-write 並行 — producer 同時寫 Redis Streams 跟 Kafka、新 consumer 接 Kafka 驗證正確性、舊 consumer 持續吃 Redis Streams，這是可逆階段、出問題退回只讀 Redis 即可。
4. Phase 3：逐流 cutover — 逐條 stream 把流量切到 Kafka、確認 consumer 進度（offset）跟 idempotency 都對、再停掉該 stream 的 Redis 端寫入；cutover 以 stream 為單位、不是整批。
5. Phase 4：長期混合 — 留在 Redis Streams 的延遲敏感流跟遷到 Kafka 的事件流共存、各自運維；需要時用 bridge（消費 Redis Streams 寫入 Kafka、或反向）同步必要資料。

dual-write 階段的可逆性是這個結構的安全邊界：在 Phase 2 之前一切可退回純 Redis、Phase 3 逐流 cutover 把不可逆動作（停 Redis 寫入）切到最小粒度，單條 stream 出問題不影響其他流。

Capacity / cost 對照

判讀：成本的核心翻轉在「儲存成本曲線」這列。Redis Streams 把資料壓在最貴的 RAM、retention 越長越貴，所以實務上被迫短保留；Kafka 把資料攤到便宜的磁碟、再分層到 S3，讓長保留變得可負擔。但這個翻轉只在「retention 需求真的長」時成立 — 若 retention 只需數小時、資料量小，Redis Streams 沒有獨立叢集跟 0.5-2 FTE 的運維增量，總成本反而低，這正是 Arcjet 的處境。遷移划不划算取決於 retention 跟規模需求落在這條曲線的哪一段。

整合 / 下一步

混合架構是常見終態

多數從 Redis Streams 起步、因規模長出 Kafka 需求的系統，終態是兩者共存而非取代：

1[延遲敏感即時路徑]                    [長保留 / replay / 高吞吐事件流]
2   Redis Streams                              Kafka
3        │                                       │
4        └──────────── Bridge（雙向同步）────────┘

Redis Streams 服務亞毫秒延遲的即時路徑（風控、撮合前置）、Kafka 服務需要長保留與 replay 的事件流；需要打通時寫一段 bridge 同步必要 stream。這跟 Kafka ↔ NATS 的混合架構是 long-term default 是同一個 paradigm shift 結論的兩個實例。

接上 Kafka 生態

遷到 Kafka 後可解鎖 Redis Streams 沒有的生態能力：

• Schema 治理：用 Schema Registry 強制 producer / consumer 契約，補上 Redis Streams 缺的 schema enforcement（對位 Bitso 自建抽象層的紀律性責任）。
• CDC pipeline：接 Debezium 把資料庫變更流進 Kafka topic，做事件溯源主軸。
• 長期 replay：tiered storage 把冷事件分層到 S3、支援數年 replay。

反向確認的 tripwire

遷移後若觀察到：延遲敏感路徑 SLA 破線、Kafka 叢集運維成本超出省下的 RAM 成本、實際 retention 需求遠短於規劃 — 這些是「該遷的訊號其實不成立」的回溯訊號，應重新評估該 stream 是否該退回 Redis Streams，對位 Arcjet 的成本判讀。

相關連結

• Source / target vendor：Redis Streams / Kafka
• 反向案例：Arcjet Redis Streams 取代 Kafka / Bitso Reliable Streams / Learning.com 退場
• 平行 migration playbook（同 paradigm shift）：Kafka ↔ NATS
• 平行 vendor：RabbitMQ / NATS
• Methodology：Migration Playbook 寫作方法論（Type E paradigm shift）

本文是 Firestore overview 的 migration playbook。寫作參照 Migration Playbook 寫作方法論。BaaS 託管平台整場遷出的資產線盤點與並行期總覽見 10.3 託管形態遷出；本文聚焦資料層的跨 paradigm 重建模。

「我們把 Firestore 整包匯出，匯進 PostgreSQL 就好。」這句話低估了遷移的真正內容 — Firestore 遷往自建 relational 的難點是反轉整個存取模型，搬資料只是其中最容易的一條線。Firestore 是 client 用 SDK 直連資料庫、授權寫在 Security Rules；自建 relational 是 client 打自己的後端 API、授權在後端中介層。資料可以匯出，但反正規化的 document 形狀、沿查詢限制長出來的資料模型、realtime listener 與 offline 同步能力，都沒有 1:1 的對應物。字面意義的「匯出再匯入」只搬走了最容易的那部分。本文走 paradigm shift 結構：先講為何字面遷移不成立、再講哪些該遷哪些先留、最後才是階段化執行。

遷移的 driver：三面牆，不是「relational 比較好」

Firestore 遷往自建很少因為「relational 比較好」這種空泛動機，而是撞到 0.21 BaaS 段描述的三面具體的牆。先確認 driver 真的成立、再啟動遷移：

No-go condition：產品仍以多裝置 realtime 同步與 offline-first 為核心賣點、且查詢需求簡單、成本仍在舒適區 → 先不要遷。這些正是 Firestore 的主場，硬遷會把 realtime / offline 這層平台白送的能力變成自己要重建的工程。遷移前先問「撞的是哪面牆」，三面牆都沒撞到就是 0.22 講的偽自建。

逐能力遷出是常態而非整包搬離：0.22 的「成長期 SaaS」例子 就是只把撞牆的資料層搬到自管 PostgreSQL、認證留在原平台。本文預設的也是這種逐能力遷出 — 遷的是資料層，不一定連認證、儲存一起搬。

6 維 diff audit：主導維度是 paradigm + application change

遷移前先盤點 source 跟 target 的差異落在哪幾維、決定 playbook 結構：

主導維度是 paradigm 與 application change：六維裡五維落在 High。這定義了結構 — Type E paradigm shift（排除 schema 翻譯 Type A 和 drop-in Type B）：存取模型反轉、部分能力重建、可能長期混合（資料層自建、認證仍留平台）。

為什麼字面遷移不成立：存取模型反轉

Firestore 的存取模型是 前端即客戶端、資料庫直接面向公網、授權在規則層；自建 relational 是 前端打後端、後端面向資料庫、授權在服務層。這個反轉是遷移的核心難點，不在資料搬運。

反正規化 document → 正規 schema：

• Firestore 為了繞開查詢限制，常把關聯資料冗餘寫進同一 document（一份資料複製多處）
• 遷往 relational 要把冗餘拆回正規化 table、重建外鍵關係，這是逆向工程：要先讀懂當初為什麼這樣存
• 反過來說，有些 document 的巢狀結構在 relational 用 JSONB 保留更省事（見 PostgreSQL jsonb）— 不是所有 document 都要拆成 table

Security Rules 授權 → 後端授權：

• Firestore 的授權邏輯散在 Security Rules DSL 裡，遷移要把每一條規則翻譯成後端 API 的權限檢查
• 這層翻譯是安全敏感的：漏一條規則等於開一個越權查詢的洞，對應 1.5 資料層紅隊

SDK 直連 → API 中介：

• 前端原本用 Firestore SDK 直接讀寫，遷移後要拔掉 SDK、改打自建 API
• 這是 application 層的大改，不是資料庫換連線字串

realtime listener / offline persistence → 自己重建：

• snapshot listener 的即時推送、offline 讀寫快取，是平台白送的能力
• 自建要用 WebSocket / SSE 重建即時層（見 03 訊息佇列 與 presence 設計）、用前端本地儲存重建 offline — 這是遷移最容易被漏估的工作量

所以遷移的第一步不是匯資料，是盤點 application 對 Firestore 的所有依賴面：查詢路徑、授權規則、realtime 訂閱、offline 行為。這份清單決定哪些能直接遷、哪些要重建、哪些先留在平台。

哪些該遷、哪些先留（逐能力混合）

Type E 的本質是不收斂 — 不必把所有 Firebase 能力一次搬完。判讀標準：

0.22 的成長期 SaaS 是這個判讀的 case anchor：撞牆的是資料層的 query 複雜度與成本，遷的就是資料層，認證留在原地。混合不是過渡失敗，是逐能力選型的穩態。

Phase plan：存取模型反轉的階段化

paradigm shift 的階段化把不可逆動作放到最後、每階段有獨立驗證門檻：

Phase 1：依賴面盤點

列出 application 對 Firestore 的所有讀寫路徑、Security Rules 授權條件、realtime 訂閱點、offline 行為。標每項的頻率、安全敏感度、是否可重建。這份清單不完整不進下一階段。

Phase 2：relational 重建模

把反正規化 document 設計回正規 schema、決定哪些巢狀結構用 JSONB 保留。同步設計後端 API 的端點與授權檢查、把 Security Rules 逐條翻譯成服務層權限。對應 1.2 schema design 與 1.5 資料層紅隊。

Phase 3：自建後端 + dual-write

立起自建後端 API 與資料庫，前端關鍵寫入路徑同時寫 Firestore 與新後端。Firestore 仍是 source of truth、新庫累積資料。dual-write 要處理一邊失敗的補償（對應 1.9 Reconciliation）。

Phase 4：backfill 歷史資料

把 Firestore 既有 document 按新 schema 轉換寫入新庫。backfill 與 dual-write 並行時要處理覆蓋順序，backfill 不能蓋掉 dual-write 的新值。轉換過程記 checksum / row count 對照。

Phase 5：shadow read 驗證

讀路徑同時打 Firestore 與新後端、比對結果、記錄差異但仍以 Firestore 回應用戶。差異率降到可接受才進 cutover。對應 1.7 Schema Migration Rollout 證據 的 evidence 方法。

Phase 6：漸進 cutover + 重建即時層

前端逐步把讀寫從 Firestore SDK 切到自建 API（按比例 / 按功能模組），保留切回能力。若產品需要 realtime，這階段要把 snapshot listener 換成自建即時層（WebSocket / SSE）並驗證延遲與斷線重連。cutover 完成後資料層的 source of truth 轉到自建；未遷的能力（認證、儲存）仍在平台 — 混合架構成立。

Evidence：每階段的前進依據

每個階段用資料證明可前進、不靠感覺：

這些 evidence 對齊 4.20 Observability Evidence Package（Source / Time range / Query link / Owner / Data quality）與 6.8 release gate。授權翻譯這項要特別當成 gate 條件 — 它是安全邊界、不只是功能正確性。

Cutover 與 rollback 決策

資料庫切流失敗代價高、加上這裡牽涉授權正確性，決策權責要寫清楚：

• cutover window：選低流量時段、明確切流比例階梯（如 1% → 10% → 50% → 100%），按功能模組切比按全站切安全
• rollback condition：新 API error rate / latency 超閾值、shadow read 差異率異常、或發現授權翻譯漏洞 → 切回 Firestore
• decision owner：誰有權喊停、依據什麼 evidence、記錄在 8.19 incident decision log
• realtime 連續性：若即時層同步切換，要驗證切換期間訂閱不中斷、或明確告知短暫降級

對應 rollback window、rollback condition。

Cleanup 與長期混合

Type E 的 cleanup 通常不是「關掉整個 Firebase」— 多數情況認證、儲存仍留平台：

• 已遷資料路徑的 Firestore collection、Security Rules、dual-write code path 退役
• shadow read 比對 code 移除
• 前端殘留的 Firestore SDK 依賴清掉（資料層已不走它）
• 但 Firebase Auth / Storage 若仍在用，保留；明確標示哪條資料路徑的 source of truth 是自建庫、哪條仍在平台
• Firestore 的資料匯出備份保留到確認新庫穩定，對應 10.3 的並行期退役判準

混合架構不是遷移失敗、是逐能力選型的穩態 — 撞牆的資料層自建、沒撞牆的認證 / 儲存留在平台。

失敗模式

production 常見的 5 個踩雷：

Case 1：只匯資料、漏了存取模型反轉

把 Firestore 匯出匯進 PostgreSQL 就以為遷完、忘了前端還在打 SDK、授權還在 Security Rules。修法：依賴面盤點是 Phase 1、資料搬運只是其中一條線，存取模型反轉才是主體。

Case 2：Security Rules 翻譯漏洞

把規則翻成後端授權時漏一條、開了越權查詢的洞、上線後資料外洩。修法：授權翻譯要逐條對照 + 紅隊驗證（1.5）、當成 cutover gate 條件、不是功能 bug。

Case 3：反正規化還原錯誤

document 的冗餘副本拆回 table 時還原錯關係、新庫資料關聯接錯。修法：Phase 2 先讀懂當初為何反正規化、backfill 後抽查還原正確性、shadow read 比對抓出建模差異。

Case 4：低估 realtime / offline 重建工作量

以為遷資料庫就好、上線才發現 snapshot listener 與 offline 同步整層要自己重建、進度爆炸。修法：依賴面盤點就把 realtime 訂閱點與 offline 行為標出來、列入工作量、必要時這層最後遷或先保留。

Case 5：dual-write 一邊失敗沒補償

dual-write 時新庫寫成功 Firestore 失敗（或反之）、兩邊分歧、cutover 後資料不完整。修法：dual-write 要有失敗補償（記錄、重試、標記人工對帳），對應 1.9 Reconciliation。

Anti-recommendation：產品仍重度依賴 realtime / offline、或團隊還沒有自建後端與資料庫的營運能力（backup、failover、授權設計）→ 先不要遷。可先把一塊撞牆最明顯、realtime 需求最低的資料（例如報表來源資料）試點、累積自建營運經驗再擴大。

容量與成本：crossover 判讀

遷移的成本判讀關鍵是 遷移後的總帳、不是只看 Firestore 帳單：

• 遷移當下：高 read 流量下，自管資料庫 + 應用層快取的單位成本常低於 Firestore 的 per-read 計費
• 但要加回自建的隱性成本：後端服務的開發與維運、資料庫的 backup / failover / 擴容、realtime 層的重建與維護、團隊人力
• 判讀分層：撞到成本牆且已有後端團隊 → 自建總帳通常划算；仍是小團隊、realtime 是核心、流量不大 → Firestore 的「平台白送能力」可能仍比自建總帳便宜

Scope warning：crossover 隨流量形狀、region pricing、團隊成本結構變動、無通用閾值。遷移省下的 Firestore 帳單要扣掉自建後端 + 資料庫 + 即時層的維運成本後再比，不是直接拿兩邊資料庫帳單對照。

接回 0.6 成本、風險與選型取捨、1.10 KV / Document DB 容量規劃。

邊界與整合

跟其他遷移路徑的關係

• 保留 document model：若只是要逃離 Firestore 的查詢限制、但 document 形狀仍適合，遷 MongoDB 比遷 relational 的 paradigm 跨度小、不必反正規化還原
• 整包託管遷出：若連認證、儲存一起搬離 Firebase，整場資產線盤點與並行期走 10.3 託管形態遷出、本文是其中資料層那一條
• 反向視角：哪些資料當初就不該進 Firestore（報表來源、強一致交易），見 Firestore overview 的不適用場景

Sibling 與 cross-link

• Firestore overview — 服務定位與查詢邊界
• 1.6 資料庫轉換實作 — 通用 dual-write / shadow read / cutover 框架
• 1.5 資料層紅隊 — Security Rules 授權翻譯的安全驗證
• 1.9 Reconciliation 與 Data Repair — dual-write 失敗補償與資料對帳
• 從 RDS / MongoDB 遷往 DynamoDB — 同為 Type E paradigm shift 的對照（方向相反：遷入 NoSQL vs 遷出 BaaS）
• 0.21 交付形態選型 / 0.22 能力級買 vs 建 — 遷移 driver 的選型層背景

本文是跨 vendor migration playbook、cross-link Docker Swarm 跟 Kubernetes。跑 migration-playbook-methodology 6 維 audit 後對映 Paradigm = High（Swarm 簡單 container orchestration → K8s declarative resource model）→ Type E paradigm shift。

5 個 Swarm production cluster 撞牆數據

從 2020-2024 觀察 5 個中型 organization 的 Swarm production cluster lifecycle、典型撞牆點：

5 個共同 pattern：

• Swarm 簡單但 ceiling 100-200 service / 20-40 node
• 跨 service 治理（mesh / RBAC / secret / autoscale）需要 外掛 工具、複雜度反超 K8s
• 無 multi-region native、災備受限
• 生態縮、社群活躍度低、新 feature 緩

撞牆點不是「Swarm 跑不動」、是「Swarm 不會幫你解 跨 service 治理 問題、要自寫」。Kubernetes 不是 simpler、是 把治理問題納入框架。

為什麼遷：ceiling / ecosystem / multi-region 三條 driver

反向 driver（K8s → Swarm）：

• 純 internal tool / 小規模（< 30 service）、K8s 過度複雜
• Edge / IoT scenario、Swarm footprint 小

6 維 audit

Schema + Paradigm 雙 High → Type E paradigm shift 為主、Schema 高維獨立段。

Paradigm 對位

Schema gap：docker-compose vs K8s YAML

 1# Docker Swarm stack.yml
 2version: '3.8'
 3services:
 4  webapp:
 5    image: myapp:1.0
 6    deploy:
 7      replicas: 3
 8      update_config:
 9        parallelism: 1
10      restart_policy:
11        condition: on-failure
12    networks:
13      - frontend
14    ports:
15      - "8080:8080"

 1# K8s equivalent (Deployment + Service + Ingress)
 2apiVersion: apps/v1
 3kind: Deployment
 4metadata:
 5  name: webapp
 6spec:
 7  replicas: 3
 8  strategy:
 9    type: RollingUpdate
10    rollingUpdate:
11      maxSurge: 1
12      maxUnavailable: 0
13  selector:
14    matchLabels: { app: webapp }
15  template:
16    metadata:
17      labels: { app: webapp }
18    spec:
19      containers:
20        - name: webapp
21          image: myapp:1.0
22          ports:
23            - containerPort: 8080
24          readinessProbe:
25            httpGet:
26              path: /healthz
27              port: 8080
28          resources:
29            requests:
30              cpu: 100m
31              memory: 128Mi
32            limits:
33              cpu: 500m
34              memory: 512Mi
35---
36apiVersion: v1
37kind: Service
38metadata:
39  name: webapp
40spec:
41  selector: { app: webapp }
42  ports:
43    - port: 8080
44      targetPort: 8080

1 Swarm service → 2-3 K8s resource（Deployment + Service + 可能 Ingress / HPA）；application 不改但 deployment 端工作量 5-10x。

Migration 流程

Partial migration + 混合架構

跟 Kafka ↔ NATS / etcd → Consul 同 Type E pattern：

 11. Audit application：列所有 Swarm stack + service
 22. 分類處理 plan:
 3   - 簡單 stateless: 先切 K8s (低風險)
 4   - Stateful (DB / queue): 評估 K8s operator 或保留 Swarm
 5   - Critical service: 雙跑期確認 K8s 行為對等
 63. K8s cluster 建置:
 7   - Managed (EKS / GKE / AKS) vs self-host (kubeadm)
 8   - 配 ingress controller / cert-manager / monitoring
 94. Application 遷移 (per stack)
10   - 寫 K8s YAML / Helm chart
11   - 配 readiness/liveness probe / resource request
12   - Networking + secret 對位
135. Cutover + Swarm decommission
14   - 部分 stack 切完、評估 Swarm 是否保留 (legacy / edge)
15   - 多數 organization 完全 decommission Swarm

整體 3-6 個月、依 stack 數量跟 application 複雜度。

Production 故障演練

Case 1：Networking model 差、cross-service connectivity 失效

徵兆：cutover 後 service A 連 service B 失敗、Swarm 端 tasks.service_b DNS 對位 K8s 端 service-b.namespace.svc.cluster.local 不通。

根因：Swarm overlay network 內 service-to-service 用 short name (service_b)、K8s 用 FQDN；application 端 service URL 寫死。

修法：

1. Application 端用 short name + cluster DNS search domain
2. K8s 端設 dnsPolicy: ClusterFirst 預設、確認 kubectl get svc -A 對應
3. NetworkPolicy 預設 deny-all、明示 allow rule

Case 2：Secret rotation 從 Swarm secrets 換 Vault / Secrets Manager

徵兆：原本 Swarm 用 docker secret 旋轉 secret、切 K8s 後 K8s Secret 是 static value、rotation 不自動。

根因：K8s Secret 是 K8s-native 但 not auto-rotated、需要外部 Vault / Secrets Manager + agent (vault-agent-injector / external-secrets-operator)。

修法：

1. K8s 端 deploy external-secrets-operator + AWS Secrets Manager / Vault integration
2. Application 端 mount file or env variable、不在 code 寫死
3. Rotation 走 vendor-side、K8s 端 sidecar 自動 reload

Case 3：Readiness probe 沒設、rolling update 期間 traffic loss

徵兆：cutover 後 deploy 期間 application 5-10% request 失敗；發現 pod startup 完成前就接 traffic。

根因：Swarm 簡單 restart_policy 沒對等 probe 概念；K8s 預設 deploy 後 immediate ready、若沒 readiness probe、startup 時間長的 application 會在未 ready 時接流量。

修法：

1. 必加 readiness probe：HTTP / TCP / exec check
2. 配 initial delay：JVM application 預留 30-60s
3. 配 minReadySeconds：deployment 端設 30s 確保 stable

Case 4：HPA 預設不啟、autoscaling 失效

徵兆：Swarm 端寫了 cron-based autoscale script、切 K8s 後 script 失效、流量高峰沒 scale up。

根因：K8s HPA 不是預設啟動、需要 明示配置 + metrics-server install。

修法：

 1apiVersion: autoscaling/v2
 2kind: HorizontalPodAutoscaler
 3metadata:
 4  name: webapp-hpa
 5spec:
 6  scaleTargetRef:
 7    apiVersion: apps/v1
 8    kind: Deployment
 9    name: webapp
10  minReplicas: 3
11  maxReplicas: 20
12  metrics:
13    - type: Resource
14      resource:
15        name: cpu
16        target:
17          type: Utilization
18          averageUtilization: 70

裝 metrics-server / Keda（event-driven autoscaling）+ 配 HPA per Deployment。

Case 5：YAML 維護地獄、Helm / Kustomize 配置遲

徵兆：cutover 後 K8s YAML 從 5 個檔（Swarm stack）變 50+ 個 K8s manifest；每個 application 端要改一個 config 都要動 N 個 file。

根因：K8s YAML 是 very verbose、不像 docker-compose 簡潔；缺 templating 跟 environment 抽象。

修法：

1. Helm chart：對 application 包成 chart、用 values.yaml 抽象環境差異
2. Kustomize：base + overlay pattern、不靠 templating
3. GitOps with Argo CD / Flux：宣告式部署、降 manual kubectl 操作

Capacity / cost

判讀：< 30 service 小 organization 可不切；50+ service 開始撞 Swarm ceiling、值得評估；100+ service / multi-region 必切。

整合 / 下一步

跟 Service mesh 整合

Cutover 後 順便 評估 Istio / Linkerd / Cilium service mesh、cover mTLS / observability / traffic policy；不要在 Swarm migration 後立刻上 mesh、分階段。

跟 GitOps 整合

K8s + Argo CD / Flux 是 natural pair；migration 時直接走 GitOps、避免 manual kubectl 操作累積。

跟 Vault → AWS Secrets Manager 對齊

Swarm secrets → K8s Secret → external secrets management 是 3-step 演進、不是 1-step；migration 期間先用 K8s Secret、之後切 Vault / Secrets Manager。

相關連結

• Target vendor：Kubernetes
• 平行 migration playbook (Type E)：Kafka ↔ NATS / Redis → Memcached / etcd → Consul / Sentry → Honeycomb
• Methodology：Migration playbook methodology

本文是 DynamoDB overview 的 implementation-layer deep article。同時是 #128 self-aware limitation 第 1 點「6 維仍可能漏類（identity / consistency / residency 三軸候選）」的 consistency 軸驗證。

Same protocol, different contract：consistency model 對照

DynamoDB 的 read 操作支援兩種 consistency：

兩者 同 protocol, same API, same table — 唯一差異是 application contract：能否接受 0-100ms 的 staleness。

跑 6 維 diff dimension audit 對「strongly consistent → eventually consistent」遷移：

6 維 audit 抓不到「Consistency contract = High」這軸。用既有 6 維歸類、會走 Type B drop-in + application change 中維獨立段；但這個歸類 漏掉真正的工作量：

• Application code change（加 ConsistentRead flag）：~10%
• Operational verification：~5%
• Application contract review（每個 read site 評估 staleness 是否可接受）：~85%

工作量主軸在 contract semantic 重審、不在既有 6 維任一個。Consistency 是 候選的第 7 維（或 8 維、跟 identity 並列）。

Consistency axis 是否獨立：3 個論據

Yes、consistency 是獨立軸：

1. Schema / paradigm / operational 不變 → consistency 仍可變：同 DynamoDB table、同 application、同 IAM、只改 ConsistentRead flag、cost 砍半但 application contract 改；其他 6 維皆 Low、但工作量 80%+ 在 contract review
2. Paradigm 是 high-level、consistency 是 low-level：Kafka ↔ NATS 是 paradigm 差（log-based vs subject-based）；DynamoDB strong → eventual 是 同 paradigm 內的 consistency 子議題；歸 paradigm 維度太粗
3. 可獨立發生：PostgreSQL READ COMMITTED → SERIALIZABLE migration 同 vendor 同 schema 同 operational、只改 isolation level；Cassandra LOCAL_QUORUM → EACH_QUORUM 同 vendor、只改 consistency level — 都是 consistency 獨立變動的 case

No、consistency 可塞 paradigm：

• 反論：consistency 是 paradigm 的子議題
• 拒絕：paradigm 涵蓋 核心抽象（OLTP / log / pub-sub / document）、consistency 是 正確性 contract 屬不同 axis

實證：本文 migration 工作量 85% 在 contract review、確認 consistency 是 獨立工作量主軸。

結構：類 Type B + consistency contract review 獨立段

跟既有 Type B Redis → DragonflyDB 對照、本文多出 consistency contract review 獨立段：

11. Same protocol, different contract（consistency axis 對照表開頭）
22. Consistency axis 是否獨立的論據
33. 結構 differentiator（類 Type B + contract review）
44. Read site audit (per-call site review)
55. Migration 流程（dual-read 觀察 + canary cutover）
66. Production 故障演練
77. Capacity / cost
88. 整合 / 下一步

8 章節、200-260 行。比標準 Type B 多 1 段（contract review）+ 1 段（axis 獨立論據）。

Read site audit：per-call site contract review

不是 table-level 決定 consistency、是 call site-level 決定。每個 GetItem / Query / Scan 必須單獨 audit：

 1# Pre-audit application code
 2# Find all DynamoDB read sites
 3$ grep -r "table.get_item\|table.query\|table.scan" src/
 4
 5# Per-site contract review template:
 6# - Site: src/order_service.py:123 - get_item by order_id
 7# - Context: 顯示 order detail page、user 剛點「我的訂單」
 8# - Contract: user 可接受 100ms 內 stale data?
 9# - Decision: YES → ConsistentRead=False, saves 50% RCU
10#             NO  → keep ConsistentRead=True

Audit 分類矩陣（典型 application）：