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

章節文章

跟其他模組的關係

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

CORS 限制

瀏覽器的同源政策限制網頁向不同 origin 發送請求。SDK 的 HTTP POST 送到 collector endpoint 時，如果 collector 和網頁不在同一個 origin（protocol + domain + port 都相同），瀏覽器會先發送 preflight OPTIONS 請求確認 server 允許跨域存取。

SDK 端的適配：

使用 navigator.sendBeacon(url, data) 代替 fetch / XMLHttpRequest。sendBeacon 不受 CORS 限制（瀏覽器對 beacon 請求不做 preflight），且在頁面 unload 時仍能可靠送出 — 適合 close flush 場景。

sendBeacon 的限制：payload 大小有上限（通常 64KB），不能自訂 Content-Type header（固定為 text/plain 或 application/x-www-form-urlencoded），沒有回應 — 送出後無法知道 server 是否收到。

如果需要 fetch（例如需要讀取回應或送出大 payload），collector 端需要設定 CORS header：Access-Control-Allow-Origin、Access-Control-Allow-Methods: POST、Access-Control-Allow-Headers: Content-Type。

Service Worker 攔截

Service Worker 可以攔截頁面發出的所有 HTTP 請求（包括 SDK 的 POST 請求到 collector）。如果應用程式的 Service Worker 有 cache 策略（cache-first、network-first），SDK 的監控請求可能被快取而非送到 collector。

SDK 端的適配：

在 fetch 請求中加 cache: 'no-store' 防止 Service Worker 快取監控請求。或在請求 URL 加唯一的 query parameter（?_t=timestamp）讓每次請求的 URL 都不同，繞過 cache 比對。

如果 SDK 本身提供 Service Worker 模組（在 Service Worker 內攔截 error），需要注意 Service Worker 的生命週期和頁面不同 — Service Worker 可能在頁面關閉後仍在執行，也可能在空閒時被瀏覽器終止。

SPA 路由變換偵測

Single Page Application 的路由變換（React Router、Vue Router、Angular Router）不觸發頁面重新載入。從監控角度看，使用者在不同「頁面」之間切換，但 window.onload 只在首次載入時觸發一次。

SDK 需要偵測 SPA 路由變換來記錄 lifecycle.view.change 事件。偵測方式：

History API 攔截：monkey-patch history.pushState 和 history.replaceState，在呼叫前後記錄路由變換。同時監聽 popstate 事件處理瀏覽器的上一頁/下一頁。

MutationObserver：監聽 DOM 變化偵測頁面內容更新。但 MutationObserver 觸發頻率高，需要 debounce 並搭配 URL 變化檢查，避免把 DOM 微調誤判為路由變換。

框架特定的 hook：如果 SDK 提供框架整合套件（React / Vue / Angular plugin），可以用框架的 router 事件（useNavigate hook、router.afterEach guard）直接取得路由變換資訊，比 monkey-patch History API 更可靠。

JS/TS 的平台限制理解後，其他平台各有各的挑戰 — Flutter 平台適配處理 isolate 和 platform channel 的問題。所有平台共同面對的 timestamp 一致性問題（時區、精度、clock drift）在獨立章節中展開。SDK 的跨平台公開 API 設計見模組三 SDK 公開 API。

流程定位

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

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

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

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

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

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

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

Plan review 判讀

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

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

Drift 處理路由

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

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

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

常見反模式

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

下一步路由

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

Isolate 安全

Dart 的 Isolate 是獨立的記憶體空間，Isolate 之間不共享記憶體，只能透過 message passing 溝通。SDK 的記憶體 buffer 存在於 main isolate 中，其他 isolate 產生的事件需要透過 port 傳送到 main isolate 才能進入 buffer。

SDK 端的適配：

提供 Monitor.eventFromIsolate(SendPort port) 方法，在子 isolate 中透過 port 把事件送回 main isolate。或者提供 isolate-aware 的 Monitor.init() 變體，在子 isolate 中初始化一個輕量的 event forwarder。

如果 SDK 使用 compute 或 Isolate.spawn 做背景任務（例如壓縮 buffer），需要透過 port 把結果送回 main isolate — 背景 isolate 無法直接存取 main isolate 的 HTTP client 或 buffer。

Platform channel 攔截

Flutter 透過 Platform channel 呼叫原生平台功能（iOS 的 Swift/ObjC、Android 的 Kotlin/Java）。Platform channel 的呼叫可能失敗（原生端未實作、參數格式錯誤、原生端拋出例外），這些錯誤在 Dart 端表現為 PlatformException。

SDK 可以攔截 Platform channel 的呼叫記錄每次呼叫的方法名稱、參數、結果和耗時。攔截方式是替換 ServicesBinding.defaultBinaryMessenger 的處理器，在轉發前後記錄事件。

攔截的價值是：Platform channel 的錯誤通常難以 debug（stack trace 跨越 Dart 和原生兩層），監控記錄提供「呼叫了哪個 channel method、傳了什麼參數、在哪一層失敗」的完整 context。

注意：攔截 Platform channel 會增加每次呼叫的延遲（記錄事件的開銷）。對高頻的 Platform channel 呼叫（例如每幀都呼叫的渲染相關 channel），攔截可能影響效能。SDK 應該提供 channel 過濾機制 — 只攔截特定 channel 或只在 debug mode 攔截。

App lifecycle 事件

Flutter 的 WidgetsBindingObserver 提供 app 生命週期回呼：

• didChangeAppLifecycleState(AppLifecycleState state) — app 在 resumed（前景）、inactive（部分可見）、paused（背景）、detached（即將關閉）之間切換。

SDK 在 init 時註冊 observer，記錄每次狀態轉換為 lifecycle 事件。

lifecycle 事件在 flush 策略中有特殊意義：

paused（進入背景）：觸發 flush — 把 buffer 中的事件送出，因為 app 在背景可能被系統殺掉，buffer 中的事件會遺失。iOS 在 app 進入背景後約 5 秒 suspend，flush 必須在這個時間窗口內完成。

resumed（回到前景）：檢查上次 flush 是否成功。如果 paused 時的 flush 失敗（網路超時），在 resumed 時重試。

detached（即將關閉）：呼叫 Monitor.close() 做最後一次 flush 和資源釋放。detached 的時間窗口更短，close flush 可能被截斷。

下一步路由

• Python 平台的適配 → Python 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 自動攔截機制 → 模組三 自動攔截

各平台的攔截點

JavaScript / TypeScript

JS 環境有兩個全域錯誤攔截點：

window.onerror 捕獲同步程式碼中未處理的例外。回呼函式收到 error message、來源 URL、行號、列號和 Error 物件。

window.onunhandledrejection 捕獲未處理的 Promise rejection。回呼函式收到 PromiseRejectionEvent，包含 rejection reason。

SDK 在 init 時註冊這兩個處理器。註冊前先保存原有的處理器（如果有），攔截後先呼叫原有處理器再執行 SDK 的記錄邏輯 — 避免覆蓋應用程式已有的錯誤處理。

限制：onerror 對跨域腳本的錯誤只收到 Script error. 訊息，沒有 stack trace。需要在 <script> 標籤加 crossorigin 屬性，server 端的 CORS header 加 Access-Control-Allow-Origin。

Flutter

Flutter 有兩個攔截層：

FlutterError.onError 捕獲 widget build / layout / paint 過程中的例外。預設行為是在 console 印出錯誤，SDK 替換為記錄 error 事件後再呼叫預設處理器。

PlatformDispatcher.instance.onError 捕獲其他非同步區域的未處理例外（Dart 2.15+）。包含 Isolate 內的未捕獲例外。

runZonedGuarded 是另一個選項 — 在指定的 Zone 內捕獲所有未處理例外。SDK 可以用 runZonedGuarded 包住整個 runApp()，但這和 PlatformDispatcher.onError 有重疊，需要避免同一個例外被記錄兩次。

限制：Flutter 的 release mode 會移除 stack trace 的符號資訊（obfuscation）。需要保留 debug symbols 檔案（.dSYM / mapping.txt），在 collector 端做 symbolication。

Python

sys.excepthook 處理主執行緒的未捕獲例外。回呼函式收到 exception type、value 和 traceback。

threading.excepthook（Python 3.8+）處理子執行緒的未捕獲例外。

atexit.register 用於在 Python 程序退出時 flush 剩餘的 buffer。但 atexit 在 os._exit() 或 SIGKILL 時不會執行。

限制：Python 的 GIL 讓 SDK 的網路操作可能阻塞主執行緒。SDK 的 flush 應該在獨立的 daemon thread 中執行，主執行緒只負責把事件放入 buffer。

攔截後的統一處理

不同平台的錯誤物件格式不同（JS 的 Error、Flutter 的 FlutterErrorDetails、Python 的 sys.exc_info tuple）。SDK 在攔截後把平台特定的錯誤物件轉換為統一的 error 事件格式：

• type: "error"
• name: 從 error class name 推導（TypeError → error.TypeError）
• data: 包含 message、stack trace（字串化）、觸發位置

轉換層是每個平台 SDK 唯一的平台特定程式碼。轉換完成後，事件進入和手動上報相同的 buffer → flush 管線。

和手動上報的分工

自動攔截處理「開發者沒有預期到的錯誤」— 未捕獲的例外、未處理的 rejection。手動上報（Monitor.error()）處理「開發者知道可能發生但想記錄的錯誤」— 已捕獲的例外、業務邏輯的異常狀態。

兩者進入同一個 buffer 和 flush 管線，在 collector 端可以用 data 中的 source: "auto" / source: "manual" 欄位區分。

下一步路由

• SDK 公開 API → SDK 公開 API 設計
• 各平台的深入適配問題 → 模組五 平台適配
• Buffer 和 flush → 攢批送出策略
• 主動感測器設計（和被動攔截互補）→ 前端感測器設計

遷移的核心約束是帶電施工——系統在搬遷過程中要持續服務。這決定了操作模式：在新平台建起平行環境、驗證通過後用 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 設計

GIL 與 threading

Python 的 Global Interpreter Lock（GIL）讓同一時間只有一個 thread 執行 Python bytecode。SDK 的 flush 操作（HTTP POST 到 collector）如果在主 thread 執行，會阻塞主程式的其他工作。

SDK 端的適配：

在 daemon thread 中執行 flush。Daemon thread 在主 thread 結束時自動終止，不需要手動 join。SDK 的 flush 計時器在 daemon thread 中運行，buffer 的存取用 threading.Lock 保護。

GIL 對 SDK 的影響比想像的小：HTTP 請求是 I/O bound 操作，CPython 在等待 I/O 時釋放 GIL。所以 flush 的 HTTP POST 在 daemon thread 中執行時，主 thread 可以繼續工作。GIL 只在 CPU-bound 的操作上造成瓶頸 — SDK 的 buffer 操作和事件序列化是 CPU-bound 但耗時極短（微秒級），影響可忽略。

asyncio 環境

Python 的 asyncio 程式（FastAPI、aiohttp）使用事件迴圈而非 threading。SDK 在 asyncio 環境中應該用 asyncio.create_task 而非 threading 執行 flush，避免在事件迴圈中阻塞。

SDK 可以在 init 時自動偵測是否在 asyncio 環境中（檢查 asyncio.get_running_loop() 是否存在），自動切換 flush 的執行方式。

atexit 可靠性

atexit.register 在 Python 程序正常退出時執行註冊的清理函式。SDK 在 init 時註冊 atexit handler 做最後一次 flush。

atexit 不執行的場景：

• os._exit() 直接終止 process，跳過所有清理
• SIGKILL（kill -9）強制終止，作業系統直接回收 process
• 未處理的 fatal signal（SIGSEGV、SIGABRT）導致 crash

對於 SIGTERM 和 SIGINT，Python 預設會執行 atexit handler（前提是 signal handler 沒有被覆蓋）。SDK 可以額外註冊 signal.signal(signal.SIGTERM, handler) 確保在收到 SIGTERM 時觸發 flush。

實務影響：os._exit() 和 SIGKILL 導致的事件遺失無法避免。使用本地 persistence（離線 buffer）可以降低影響 — 事件在寫入本地檔案後，即使 process 被強制終止，下次啟動時仍可補發。

短生命週期腳本

SDK 的預設設計假設長期運行的 app — flush interval 定期觸發、daemon thread 持續運行、atexit 是最後防線。但 Python SDK 的一個重要場景是短命腳本（CI/CD hook、pre-commit hook、CLI 工具的子命令），生命週期可能 < 1 秒。這個場景下 SDK 的行為和長期 app 完全不同。

什麼會壞

flush interval 來不及觸發。預設 30 秒的 flush interval，但腳本在 200ms 內結束。計時器還沒觸發，buffer 中的事件從未送出。

daemon thread 隨主 thread 結束。SDK 用 daemon thread 執行 flush 計時器。Python 的 daemon thread 在最後一個非 daemon thread 結束時被殺 — 不會等待 daemon thread 完成當前工作。如果 flush 正在進行中（HTTP POST 送到一半），daemon thread 被殺，HTTP 請求中斷，事件丟失。

atexit 的執行順序不確定。atexit handler 在 daemon thread 被殺之後執行。如果 SDK 的 atexit handler 嘗試在 daemon thread 中 flush，會失敗（thread 已死）。atexit handler 必須在主 thread 中同步 flush。

正確的短命腳本模式

1from monitor import Monitor
2
3Monitor.init(endpoint="http://localhost:9090/v1/events", app="my-hook")
4
5# 做事...
6Monitor.event("hook.run", {"hook": "branch-check"})
7
8# 結束前必須呼叫 close
9Monitor.close()  # close 內同步 flush，不依賴 daemon thread

close() 是唯一可靠的 flush 時機。close() 的實作在短命腳本場景下必須：

1. 同步執行 HTTP POST，不委託給 daemon thread — 主 thread 呼叫 close() 時直接在當前 thread 送出
2. 設 HTTP timeout — 短命腳本不能等太久，3 秒的 timeout 是合理的
3. flush 失敗時靜默放棄 — 短命腳本的主要職責不是監控，SDK 失敗不應影響腳本的 exit code

atexit 仍然註冊，作為開發者忘記呼叫 close() 的備份。但 atexit 是 best-effort — 在 os._exit() 和 SIGKILL 下不執行。

flush interval 在短命腳本中的角色

flush interval 對短命腳本無意義 — 腳本在第一次 interval 觸發前就結束了。SDK 可以偵測「init 到 close 的間隔 < flush interval」的模式，在 debug log 中提示開發者考慮降低 interval 或直接依賴 close() flush。

但不建議把 flush interval 設為 0（停用）— 同一個 SDK 設定可能同時用於長期 app 和短命腳本，interval 對長期 app 仍然有用。

Subprocess 監控

Python 程式中的 subprocess.Popen 啟動的子程序是獨立的 process，不共享 SDK 的 buffer 和網路連線。子程序的錯誤和事件需要獨立的監控機制。

兩種方式：

子程序獨立初始化 SDK：子程序的 Python 腳本自己呼叫 Monitor.init()，獨立送事件到 collector。適合子程序是長時間運行的 Python 程式。

父程序代理：父程序讀取子程序的 stdout/stderr，從輸出中解析事件（子程序用約定格式印出事件），父程序的 SDK 代理送出。適合子程序是短命的腳本或非 Python 程式。

下一步路由

• Go 平台的適配 → Go 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 離線 buffer 策略 → 模組三 離線 buffer 與重試

Graceful shutdown

Go 程式收到 SIGTERM 或 SIGINT 時需要在退出前完成清理：flush 剩餘的 buffer、關閉網路連線、寫入最後的 lifecycle 事件。

1ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
2defer stop()
3
4<-ctx.Done()
5// signal received, start graceful shutdown
6monitor.Close(context.WithTimeout(context.Background(), 5*time.Second))

graceful shutdown 的時間窗口由部署環境決定。Kubernetes 的預設 terminationGracePeriodSeconds 是 30 秒，Docker 的 stop timeout 是 10 秒。SDK 的 Close 方法接受 context 讓呼叫端控制超時。

HTTP server 的 shutdown 順序

如果 Go 程式同時是 HTTP server 和 monitoring SDK 的使用者，shutdown 順序需要正確：

1. 停止接受新連線（server.Shutdown(ctx)）
2. 等待進行中的請求完成
3. flush 監控 buffer（monitor.Close(ctx)）
4. 關閉 log 和其他資源

如果先 close monitor 再 shutdown server，進行中的請求產生的事件會在 monitor 已關閉後嘗試送出，被靜默丟棄。

Signal handling

Go 的 signal.Notify 和 signal.NotifyContext 是接收 OS signal 的標準方式。SDK 在 init 時不應該自己註冊 signal handler — 這會和應用程式的 signal handling 衝突（Go 的 signal handler 是先到先得，後註冊的覆蓋先註冊的）。

SDK 端的適配方式是提供 Close 方法讓應用程式在自己的 signal handler 中呼叫，而非 SDK 內部攔截 signal。應用程式控制 shutdown 流程，SDK 只負責在被告知關閉時 flush 和清理。

panic recovery

Go 的 panic 會終止當前 goroutine。如果 panic 發生在 main goroutine 且沒有 recover，程式直接退出，SDK 的 buffer 中的事件遺失。

SDK 可以提供 monitor.RecoverAndReport() 讓開發者在 goroutine 的入口用 defer monitor.RecoverAndReport() 攔截 panic，記錄 error 事件後再 re-panic（保持原有的 crash 行為）。

HTTP handler 的 panic 可以用 middleware 攔截：

1func monitorMiddleware(next http.Handler) http.Handler {
2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
3        defer monitor.RecoverAndReport()
4        next.ServeHTTP(w, r)
5    })
6}

HTTP server 自身監控

Go 常用來寫 collector 本身。Collector 需要監控自己的健康狀態 — 請求處理速率、錯誤率、goroutine 數量、記憶體使用量。

Collector 的自身監控和接收外部事件是兩個獨立的管線。自身監控的 metric 可以寫入獨立的 JSONL 檔案（和外部事件分開），或透過 Go 的 expvar / runtime.ReadMemStats 暴露為 HTTP endpoint。

自身監控的關鍵指標：

• collector.events.received：每秒收到的事件數
• collector.events.invalid：schema 驗證失敗的事件數
• collector.storage.write_duration_ms：寫入 JSONL 的耗時
• collector.goroutines：goroutine 數量（洩漏偵測）
• collector.memory.alloc_mb：記憶體使用量

下一步路由

• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• Collector 的架構設計 → 模組四 Collector 設計
• SDK 公開 API 的 Close 方法 → 模組三 SDK 公開 API

統一格式：ISO 8601 + 時區偏移

所有平台的 SDK 統一使用 ISO 8601 格式，包含毫秒精度和時區偏移：

12026-06-19T14:30:00.123+08:00

避免使用 Unix timestamp（秒或毫秒）作為僅有的時間表示 — Unix timestamp 沒有時區資訊，如果 SDK 端和 collector 端在不同時區，需要額外的 metadata 才能正確轉換。

避免使用「本地時間不帶時區」的格式（2026-06-19T14:30:00）— 無法區分 UTC+8 的 14:30 和 UTC+0 的 14:30。

各平台的 timestamp 來源

JavaScript

Date.now() 回傳毫秒精度的 Unix timestamp。new Date().toISOString() 回傳 UTC 時間的 ISO 8601 字串。

SDK 應該用 Intl.DateTimeFormat 或手動計算時區偏移，產生帶本地時區的 ISO 8601 字串 — collector 端需要知道事件的本地時間，以便做使用者時區的分析。

performance.now() 提供微秒精度的高解析度時間，但起點是頁面載入時間，無法用來產生絕對 timestamp。用於計算 duration（兩個時間點的差值），不用於記錄事件時間。

Flutter / Dart

DateTime.now() 回傳本地時間的 DateTime 物件。DateTime.now().toUtc() 轉成 UTC。DateTime.now().toIso8601String() 產生 ISO 8601 字串，但不包含時區偏移（Dart 的 ISO 8601 格式不包含 offset）。

SDK 需要手動附加時區偏移：DateTime.now().timeZoneOffset 取得偏移量，手動格式化為 +08:00 格式附加到 ISO 8601 字串後面。

Python

datetime.now(timezone.utc) 取得 UTC 時間。datetime.now().astimezone() 取得本地時間帶時區。.isoformat() 產生帶時區偏移的 ISO 8601 字串。

Python 3.2+ 的 datetime 原生支援 timezone-aware 的 ISO 8601 輸出，是各平台中最完整的。

Go

time.Now() 回傳帶時區的 Time 值。time.Now().Format(time.RFC3339Milli) 產生帶毫秒和時區偏移的字串。

Go 的 time.RFC3339Nano 提供奈秒精度，但監控事件不需要這個精度 — 毫秒足夠。

Clock drift

不同裝置的系統時鐘可能有偏差（clock drift）。使用者手機的時鐘比 collector server 快 5 分鐘，SDK 產生的 timestamp 會比 collector 收到時間早 5 分鐘。

Clock drift 的影響：

• 排序錯亂：裝置 A（時鐘快）和裝置 B（時鐘慢）的事件混合排序時，時間順序可能和真實發生順序不一致
• 告警延遲計算錯誤：collector 用「事件 timestamp 到收到時間的差值」計算延遲，clock drift 讓延遲值不準確

處理策略：

Collector 記錄 receive_timestamp：每筆事件除了 SDK 端的 timestamp，collector 在收到時附加 receive_timestamp。兩者的差值用於估算 clock drift 和網路延遲。

容忍而非修正：在數秒到數分鐘級的 drift 範圍內，容忍 drift 帶來的排序不精確。跨裝置的事件排序本身就不需要毫秒精度 — 分析的粒度通常是秒或分鐘。

異常值偵測：timestamp 比 receive_timestamp 早超過 1 小時，或晚超過 5 分鐘，標記為可疑的 clock drift — 可能是使用者手動調整了系統時鐘。

下一步路由

• JS 平台適配 → JS/TS 平台適配
• Flutter 平台適配 → Flutter 平台適配
• Log schema 中的 timestamp 欄位 → 模組二 event.schema.json 欄位解說
• 各平台的 error 攔截差異影響 test 設計 → testing 模組五 測試設計判斷

待寫章節

• JS/TS 平台：CORS 限制、Service Worker 攔截、SPA 路由變換偵測
• Flutter 平台：isolate 安全、Platform channel 攔截、app lifecycle
• Python 平台：GIL 與 threading、atexit 可靠性、subprocess 監控
• Go 平台：graceful shutdown、signal handling、HTTP server 自身監控
• 跨平台 timestamp 一致性（時區、精度、clock drift）

跨分類引用

• → testing 模組五 測試設計判斷：各平台 error 攔截差異影響 test 設計

Vendor / Platform 清單

實作時的常用選擇見 vendors — T1 收錄 Kubernetes / Docker / systemd / nginx / Envoy / AWS ELB / Terraform / Traefik / Consul，每個 vendor 有定位、適用場景、取捨與預計實作話題的骨架。

Deep article（vendor 自身的配置、故障、容量）跟 migration playbook（跨 vendor 遷移流程）的撰寫進度見 vendors/ 的「內容覆蓋進度」段。

暫定分類

建議閱讀順序

章節編號是主題分類，不是閱讀順序。建議先讀 5.6 Platform Lifecycle Contract 理解 startup / readiness / liveness / shutdown / drain 的責任分類，再按 5.1 → 5.2 → 5.3 → 5.4 進入平台實作層。5.5（威脅建模）和 5.7（boundary 分類）適合讀完 5.1-5.4 後做概念整理。5.8（實作示範）是 5.2 + 5.3 的操作化，適合最後讀。

選型入口

部署平台選型的核心判斷是服務如何被啟動、更新、接流量、擴容與停止。當問題集中在 container image、rolling update、health check、load balancer、service registry、service discovery 或 Runtime Config 時，應先評估部署平台能力。

Container 解決服務包裝與 runtime 依賴；Kubernetes 解決多 instance 調度、probe、rolling update 與 resource limit；systemd 適合單機或 VM 上的 service lifecycle；load balancer 解決流量入口、draining、idle timeout 與 health check；service registry 解決實例狀態維護；service discovery 解決服務彼此如何找到 Internal Endpoint；Runtime Config 解決環境差異、Secret Management 與 Feature Flag。

接近真實網路服務的例子包括發版時 request 失敗、pod 尚未 ready 就接流量、長連線 shutdown 清理不完整、服務擴容後 Internal Endpoint 更新延遲。這些場景的共同問題是程式與平台合約，因此本模組會先處理生命週期、流量入口與平台訊號。

與語言教材的分工

語言教材處理程式內的生命週期與訊號。Backend deployment 模組處理 Kubernetes、systemd、load balancer 與 container 平台如何觸發、解讀與限制這些訊號。

與資安概念層的交接

本模組承接 07 模組的概念判讀，並在服務實體層落地。交接基線如下：

• 來自 7.3 入口治理與伺服器防護：承接入口分級、管理平面分離、修補窗口節奏。
• 來自 7.5 傳輸信任與憑證生命週期：承接 TLS/mTLS 與憑證佈署節奏。
• 來自 7.6 秘密管理與機器憑證治理：承接 runtime secret 與機器憑證交付模型。

這個交接讓部署模組聚焦實體配置與平台語意，同時保持與資安判讀一致。

案例驅動讀法

部署平台案例的核心讀法是先確認切換單位（服務、流量、叢集），再定義可回退邊界。

跨語言適配評估

部署平台使用方式會受語言的啟動時間、process model、signal handling、thread/task lifecycle、runtime memory behavior 與 liveness 支援影響。啟動慢的 runtime 要調整 readiness 與 rollout 節奏；長連線或背景 worker 要支援 draining；使用 GC 的 runtime 要觀察 memory limit 與 pause 行為；多 process 模型要確認 signal、log 與 metrics 如何聚合。

章節列表

反例與規模對照入口： 5.C9 反例 / 5.C10 對照。

回退判讀寫法見 0.C4 回退判讀寫法，部署案例要優先保留切流批次、draining、連線生命週期與回退時間。

觀念網路補完方向

部署平台章節下一輪的核心責任是把平台能力寫成服務契約。現有章節已經有 container、Kubernetes、load balancer 與 service discovery，但還需要補上 runtime contract、lifecycle contract、traffic contract、rollout contract 與 control-plane contract 的關係，讓讀者知道部署是一組流量、連線、設定、資源與回退條件的連續切換。

這些方向要用部署平台自己的服務壓力展開。短 request API、長連線服務、背景 worker、control plane config push 與多租戶平台的生命週期不同，寫作時要分別處理它們的 rollout 與 drain 條件。

知識卡補強方向

部署模組的 knowledge card 缺口集中在「平台契約」與「切換完成訊號」。已有 readiness、draining、config rollout 與 rollback strategy 可以作為第一批錨點。

下一批候選卡片包括 startup probe、drain completion、rollout batch、rollback window、config freeze、environment protection 與 deployment contract。這些卡片要讓讀者能分辨「服務已啟動」和「服務可安全接流量」分屬不同責任。

實作探討入口

部署平台的第一條實作路徑是 5.8 Deployment Rollout with Drain and Rollback（實作示範）。這篇以 checkout service rollout 為例，說明 rollout plan、canary evidence、drain signal、rollback condition 與 incident decision route 如何一起成立。

這條路徑的前置引用應該是 5.2 Kubernetes deployment、5.3 load balancer contract、5.C9 反例、6.8 Release Gate 與 8.19 Incident Decision Log。完成後可依 Backend 學習路線 進入下一條服務路徑。

部署路徑的 artifact 對齊重點是「每一批切換都能被觀測、被放行、被回退」。對 4.20 要交 Source/Time range/Query link/Owner/Data quality，並覆蓋 per-version error rate、latency、drain completion 與 reconnect 訊號；對 6.8 要交 Gate decision/Checks/Stop condition/Rollback window/Owner，呈現 canary 批次與停損規則；對 8.19 要交 Timestamp/Decision/Context/Evidence/Owner/Expected effect/Rollback condition，記錄 freeze、回退與重啟切流的決策條件與時間序列。

跨分類引用

• → infra 模組五：核心服務上 IaC：ECS / EKS 的 IaC 描述（subnet 接線、IAM task role、映像版本解耦）是部署平台的地基層

Lifecycle Contract

Lifecycle contract 定義平台如何啟動、檢查、接流量、停止與回收服務實例。它包含 runtime、startup、readiness、liveness、shutdown 與 drain。

這些狀態分開後，部署事故才能定位是啟動、接流量、退場還是平台判讀問題。

runtime 與 startup 決定服務能否形成可運行實例。readiness 與 liveness 決定平台何時導入流量與何時重建實例。shutdown 與 drain 決定版本退場時是否能保護在途工作。這些狀態都屬於生命週期合約，卻對應不同的事故處理路徑。

Startup 與 Readiness

startup 的責任是確認服務初始化完成。readiness 的責任是確認服務可承接實際流量。啟動完成不代表依賴已就緒，也不代表背景任務、config、secret 或 connection pool 都可用。

慢啟動服務需要 startup gate，避免 liveness 在初始化期間反覆重啟。依賴敏感服務需要 readiness gate，避免尚未連上資料庫、cache 或 queue 時就接收請求。

啟動時間的組成與壓縮

服務啟動時間的長短決定 rollout 節奏的下限。啟動時間由四段組成，每段有不同壓縮策略：

1. runtime 初始化：語言 VM、GC 初始化、class loading（JVM warmup 可達 10-30 秒）。壓縮手段是 ahead-of-time compilation（GraalVM native image、Go 靜態編譯啟動速度快）或 CDS（Class Data Sharing）。
2. 依賴建立：資料庫連線池、cache 連線、queue consumer 註冊。壓縮手段是 lazy initialization（按需建立）或 connection pool pre-warming（啟動時建好但不阻擋 readiness）。
3. 資料預載：config 同步、feature flag 初始拉取、本地快取預熱。壓縮手段是區分必要載入與非必要載入——必要的阻擋 readiness，非必要的平行載入。
4. 就緒驗證：自我健康檢查、依賴可達性驗證。壓縮手段是平行驗證多個依賴，避免串行等待。

啟動時間超過平台預設 startup timeout 時，先拆成這四段分析瓶頸，再決定調大 timeout 還是壓縮啟動流程。盲目調大 timeout 會掩蓋啟動退化問題，讓單次 rollout 的最短觀察窗拉長。

Readiness 設計的核心取捨

readiness 太鬆（只檢查 HTTP port 是否可達）會讓尚未就緒的實例接到流量。readiness 太緊（檢查所有下游可達性）會讓非自身問題的下游故障觸發連鎖 not-ready，放大故障面。

取捨的判讀框架是「這個依賴不可用時，服務是否仍能提供有意義的回應」：

• 必要依賴：資料庫、auth service——不可用時服務完全無法處理請求。這類依賴的可達性應納入 readiness 條件。
• 可降級依賴：推薦引擎、非關鍵 cache——不可用時服務可回傳降級結果。這類依賴不應納入 readiness，改用 circuit breaker 或 fallback 處理。
• 觀測依賴：metrics collector、log shipper——不可用不影響業務流量。這類依賴進 readiness 是常見誤判，會讓觀測基礎設施故障擊倒整個服務。

對應 5.C3 Orbitera managed K8s migration：揭露「跨平台遷移本質是能力遷移、部署 / 觀測 / 恢復與團隊流程都需要同步重建」。遷移到新平台時，舊平台的 readiness 條件不能直接搬——新平台的依賴可達路徑、DNS 解析速度、secret 注入方式可能改變，readiness 條件要重新驗證。

Liveness 與 Restart

liveness 的責任是偵測無法自我恢復的狀態。短暫下游故障適合交給 readiness、circuit breaker 或 fallback 處理，否則平台會用重啟放大故障。

liveness 太敏感會造成 restart loop；liveness 太寬鬆會讓壞實例長期留在線上。設計時要先定義哪些錯誤可由服務內部恢復，哪些才需要平台重建。

Liveness 適合偵測的失敗模式

liveness 的工程價值在於捕捉服務自己無法修復的狀態。把 liveness 當成通用健康檢查是過度使用，會讓正常的瞬態故障觸發不必要的重建。

適合 liveness 偵測的狀態：

• deadlock：所有 worker thread 被卡住，無法處理新請求也無法回傳錯誤。liveness endpoint 設在獨立 goroutine / thread 上，如果 worker pool 卡住但 liveness goroutine 能回應，問題在業務邏輯而非 deadlock。
• memory leak 導致的 OOM 前兆：記憶體使用率持續上升不回落，GC 已無法回收。此時主動回報 unhealthy 讓平台在 OOM kill 前重建，比被動等 OOM 更可控——OOM kill 不走 graceful shutdown，在途請求直接中斷。
• essential background task 永久停止：必要的定期任務（如 license renewal、session cleanup）超過預期間隔仍未執行。這類失敗靜默發生，只有 liveness 主動偵測能發現。

不適合 liveness 偵測的狀態：下游資料庫短暫不可用、外部 API timeout、cache miss 率升高。這些由 readiness 或 circuit breaker 處理——用 liveness 重建不會修好下游，只會用重啟放大問題。

Restart 的代價量化

每次 liveness 觸發的重啟會產生四類代價：

1. 在途請求中斷：被重啟的實例正在處理的請求直接失敗。
2. 連線重建成本：資料庫連線池、cache 連線、queue consumer 重新建立。
3. 啟動期間的容量缺口：重啟到 readiness 通過之間，整體服務容量降低。
4. thundering herd 風險：多實例同時被 liveness 判定失敗並重啟時，同時重建連線、同時搶資源、下游壓力瞬間放大。

對應 5.C7 Airbnb Istio 升級治理：揭露「基礎平台元件升級若缺乏分批治理、會形成全域風險放大器」。以下基於通用工程知識展開：Istio 等 service mesh 升級期間的 sidecar 重啟可觸發大量服務的 liveness 暫時失敗，若 liveness 太敏感會放大成全域 restart storm。升級期的 liveness 閾值應比穩態更寬鬆，或在升級批次中暫時加大 liveness failure threshold。

Shutdown 與 Drain

shutdown 的責任是讓服務停止接新工作並完成資源釋放。draining 的責任是讓平台在移除實例前，讓 in-flight request、長連線或背景工作有時間收束。

短 request API、長連線服務與 background worker 的 drain 條件不同。短 API 主要看在途請求歸零；長連線看 reconnect 節奏；worker 看已領取工作能否完成或重新排隊。tunnel 入口的 startup / readiness / drain 對齊見 5.10 Outbound Tunnel 入口。

三種 Workload 的 Drain 差異

不同 workload 類型的 drain 完成條件與時間尺度完全不同，用同一套 drain 設定覆蓋所有 workload 會在至少一類服務上出事。

短 request API（HTTP REST、gRPC unary）：drain 窗口通常在 5-30 秒。核心條件是在途請求數歸零。風險點是 load balancer 的 deregistration delay——LB 可能在服務已標記 not-ready 後仍送幾秒流量（取決於 health check interval 與 deregistration delay），所以服務端 drain 窗口要覆蓋這段延遲。endpoint 摘除的傳播窗口與 preStop 等待策略見 5.4 摘除節奏與 Drain 的配合。

長連線服務（WebSocket、gRPC streaming、SSE）：drain 窗口通常在 30 秒到數分鐘。核心條件是現有連線收斂且 reconnect 波形穩定。風險點是客戶端 reconnect 策略——服務端 drain 完成不代表客戶端已連上新實例。若客戶端沒有 backoff 或 reconnect 目標選擇邏輯，會形成 reconnect storm。drain 設計要跟客戶端 reconnect 策略一起規劃。

Background worker（queue consumer、定時任務、batch job）：drain 窗口取決於單一工作的最長執行時間。核心條件是已領取的工作完成處理或安全重新排隊。風險點是不可中斷工作——某些 job 做到一半無法重試（例如外部 API 呼叫已發出但回應尚未確認），drain 時序要覆蓋這類 job 的最長完成時間，否則 job 被中斷後產生不一致狀態。

對應 5.C9 反例：平台切流未先 Draining：揭露「切流失敗常在 connection lifecycle 管理」「drain / idle timeout / health check / client retry 沒有同一節奏」。反例中的事故擴大機制正是不同 workload 類型的 drain 條件被忽略——短 API 的 drain 完成了，長連線的 reconnect 仍在震盪，worker 的 job 被中斷重試造成重複處理。

Shutdown 信號的傳遞路徑

platform 到 application 的 shutdown 信號傳遞有多個可能斷點。信號從平台送到容器 PID 1、PID 1 轉發到應用進程——PID 1 的信號處理語意與常見陷阱見 5.1 PID 1 與信號處理。本段聚焦 lifecycle 層的時序問題：

• preStop hook 與 SIGTERM 時序：Kubernetes 先執行 preStop hook、再送 SIGTERM。preStop hook 可用來等 LB 摘流量（sleep 幾秒讓 endpoint 從可用集合移除），讓 SIGTERM 到達時在途流量已經減少。
• terminationGracePeriodSeconds：平台等待的最長時間。超過後 SIGKILL 強制結束，不走 graceful shutdown。這個值要覆蓋 preStop + drain + 資源釋放的總時間。

shutdown 信號傳遞的驗證方式是在 staging 環境觸發 pod delete，觀察應用 log 中是否出現 shutdown handler 的紀錄。沒看到 shutdown log 代表信號沒傳到、要先修傳遞路徑再談 drain 設計。

不同 Workload 的 Lifecycle 特性對照

生命週期合約的參數設定要依 workload 類型調整。以下是三類常見 workload 的特性差異。

這張表是選型前判準的操作化：先確認服務屬於哪類 workload，再套用對應的 lifecycle 參數基線。混合 workload（例如同時提供 HTTP API 和 WebSocket）要取各層的嚴格值——drain 窗口取最長的、readiness 取最嚴格的。

平台如何表達 Lifecycle 差異

不同部署平台表達生命週期合約的能力不同。選型時要問的是「這個平台能不能分別設定 startup、readiness、liveness 與 drain」。

Kubernetes 在 lifecycle 表達力上最完整，但參數最多也最容易配錯。systemd 靠 sd_notify 協議明確宣告 readiness，在單機部署場景下反而比 K8s 的 probe 直接。Docker 和 ECS 不分離 readiness 與 liveness，需要在應用層自行實作降級邏輯。

選平台不只看功能清單，要看它表達 lifecycle 差異的粒度是否覆蓋服務需求。若服務需要分離 startup 和 readiness 但平台只有一個 health check，這個差距要在應用層補——代價是複雜度從平台設定轉移到程式碼。

遷移期的 Lifecycle 重新驗證

對應 5.C6 Airbnb Kubernetes 叢集擴縮演進：揭露「擴縮策略版本化與可回放」「不同 workload 區分擴縮政策」。以下基於通用工程知識展開：叢集演進過程中，lifecycle 參數的假設會改變——workload 從穩態變成高波動、從單一類型變成混合類型、從小規模變成大規模。lifecycle contract 的參數不是設一次就好，要隨叢集演進重新驗證。

對應 5.C10 對照：規模差異下的平台遷移：揭露「小型組織最容易漏掉回退腳本化」「中型組織依賴錯位、服務切過去但資料面 / 認證面 / 觀測面沒同步」。lifecycle contract 在遷移後的完整性驗證不只看 probe 設定——secret 注入時序、資料庫連線池的 endpoint 是否切到新叢集、observability pipeline 的 readiness 是否對齊，都是 lifecycle 合約的一部分。

遷移後的 lifecycle 驗證清單：

1. startup 時序重測：新平台的 image pull 時間、secret mount 時間、DNS 解析路徑可能不同，原本的 startup timeout 可能不夠。
2. readiness 依賴路徑檢查：readiness 檢查的依賴是否仍可達（新叢集到舊資料庫的 latency 是否增加、跨叢集 service discovery 是否對齊、DNS TTL 與快取行為是否改變）。
3. drain 行為驗證：在新平台觸發 pod delete、觀察 drain 完成時間與在途請求處理是否符合預期。
4. 信號傳遞驗證：在新平台觸發 shutdown、確認 SIGTERM 到達應用進程並觸發 graceful shutdown handler。

選型前判準

部署平台選型前要先回答：

1. 服務啟動需要多久，哪些依賴是 readiness 條件。
2. 服務失敗時應由自己恢復，還是由平台重建。
3. 服務停止時有哪些 in-flight request、connection 或 job。
4. 平台是否能表達 startup、readiness、liveness 與 drain 的差異。

這些問題決定後續要比較 Kubernetes probe、systemd restart policy、load balancer health check 或 service mesh drain 能力。

判讀訊號

常見誤區

把所有 probe 設成同一個 /health endpoint，會讓 startup、readiness 與 liveness 的語意混在一起。三種 probe 回答不同問題：startup 問「初始化完了嗎」、readiness 問「可以接流量嗎」、liveness 問「還活著嗎」。同一個 endpoint 無法同時回答三個問題，因為初始化完成不代表依賴就緒，依賴暫時不可達不代表服務本身壞了。

把 drain 窗口設成固定值不分 workload 類型，會在某一類服務上出事。5 秒對短 API 足夠、對長連線不夠、對 batch job 遠遠不夠。drain 窗口要依服務實際 workload 設定，不是用平台預設值。

把 liveness 失敗當成「服務壞了」而不問代價，會忽略重啟本身的連鎖效應。每次重啟都有在途請求中斷、連線重建、容量缺口的代價——特別是多實例同時被判定 liveness 失敗時，代價會被放大。

案例回寫

lifecycle contract 的完整性可用多個案例交叉驗證。5.C3 Orbitera managed K8s migration 揭露遷移後 readiness 依賴路徑改變的風險。5.C9 反例 揭露不同 workload 的 drain 條件被忽略造成的事故擴大。5.C7 Airbnb Istio 升級治理 揭露基礎平台元件升級缺乏分批治理會形成全域風險放大器。5.C10 對照 揭露不同規模下 lifecycle 驗證的缺口模式。

這些案例共同支撐的判讀是「lifecycle contract 的每個狀態都有不同的失敗模式，混在一起處理會在事故時無法定位」。流量切換或連線生命週期問題路由到 5.3 load balancer 合約。runtime 產物穩定性問題路由到 5.1 container 與 runtime。

跨模組路由

lifecycle contract 是部署模組的概念基底，後續章節都會引用本篇的狀態分類。

1. 與 5.1 的交接：runtime 與 entrypoint 定義 startup 行為回到 container 與 runtime。
2. 與 5.2 的交接：probe 設定與 rollout 節奏回到 Kubernetes 部署策略。
3. 與 5.3 的交接：drain 與流量退場回到 load balancer 合約。
4. 與 5.10 的交接：tunnel 入口的 readiness 與 drain 對齊回到 Outbound Tunnel 入口。
5. 與 4.20 的交接：lifecycle 事件的證據收集回到 Observability Evidence Package。
6. 與 6.8 的交接：lifecycle 狀態作為 release gate 判定條件回到 Release Gate。

下一步路由

要看 Kubernetes 如何承接這組生命週期，接著讀 5.2 Kubernetes 部署策略。要看流量退場如何和 LB 對齊，接著讀 5.3 load balancer 合約。要看不同平台的 lifecycle 表達力比較，接著讀 vendors/。

場域定位

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

常見注意事項

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

學習路線

下一步路由

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

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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