Memory 限制設計

觀察 baseline

在限制之前先觀察服務的真實記憶體使用。用 docker stats 看 container 的 MEM USAGE，跑至少 24 小時涵蓋日常操作和定期 job（降採樣、清理）。

Baseline 包含：

• 應用程式本身的 heap + stack
• Runtime 開銷（Go 的 GC metadata、JVM 的 metaspace、Python 的 interpreter）
• 內嵌資料庫的 page cache（如 SQLite 的 PRAGMA cache_size）
• HTTP server 的連線 buffer

設定 limit

1Memory limit = baseline peak × 1.5（安全係數）

安全係數 1.5 是經驗值 — 預留 burst 時的記憶體波動（如大 batch 的 JSON 反序列化、查詢結果集暫存）。安全係數太大浪費資源、太小在 burst 時 OOMKill。

OOMKill 排查

OOMKill 的症狀是 container 突然消失、沒有 application log。排查步驟：

1docker inspect <container> | jq '.[0].State.OOMKilled'
2# true = 被 OOM killer 終止
3
4dmesg | grep -i oom
5# kernel log 中的 OOM 記錄、包含被殺的 process 和當時的記憶體使用

OOMKill 後的處理：提高 memory limit，或找出記憶體使用異常的原因（memory leak、unbounded cache、大結果集查詢）。

不同 runtime 的記憶體特性

CPU 限制設計

--cpus vs --cpu-shares

CPU throttle 症狀

CPU throttle 不會 crash（和 OOMKill 不同）。症狀是延遲上升 — request 處理時間從 10ms 變成 100ms，因為 container 的 CPU time 被 cgroup 暫停。

1cat /sys/fs/cgroup/cpu/cpu.stat
2# nr_throttled: 被限制的次數
3# throttled_time: 累計被暫停的時間（奈秒）

I/O bound 的服務（如監控 collector — 主要時間花在 SQLite 寫入和 HTTP 收發）通常不需要嚴格 CPU 限制。CPU 只在查詢處理（JSON 反序列化、聚合計算）時短暫使用。

磁碟 I/O 考量

Overlay filesystem 的寫入放大

Docker 的 overlay2 storage driver 把 container 的寫入操作分層管理。每次寫入新檔案或修改檔案，overlay 在上層（upper layer）建立副本再修改（copy-on-write）。對 SQLite 這類頻繁 fsync 的嵌入式資料庫，overlay 層增加 20-40% 的寫入延遲。

Volume mount 繞過 overlay

把需要高 I/O 效能的目錄掛載為 host volume（-v /host/path:/container/path），寫入直接到 host 檔案系統、繞過 overlay。

適用 volume mount 的場景：

• 嵌入式資料庫的資料目錄（SQLite、BoltDB）
• 需要持久化的 log 檔案
• 大量小檔案寫入（cache 目錄）

不適用 volume mount 的場景（用 overlay 即可）：

• 暫存檔（處理完就刪）
• 只讀的設定檔（-v config:/config:ro，overlay 讀取開銷小）

tmpfs mount

記憶體中的暫存目錄，不寫磁碟。適合不需要持久化的高頻寫入（如 SDK 的離線 buffer、session 暫存）：

1docker run --tmpfs /tmp:size=64m ...

Health Check 設計

Container 的 health check 告訴 orchestrator「這個 container 是否正常運作」。Process 活著但 HTTP 不回應的場景（deadlock、資源耗盡）只靠 process 監控抓不到。

Dockerfile HEALTHCHECK

1HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
2  CMD wget -q --spider http://localhost:8080/health || exit 1

Docker Compose healthcheck

1healthcheck:
2  test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
3  interval: 30s
4  timeout: 5s
5  retries: 3
6  start_period: 10s

start_period 是啟動寬限期 — container 啟動後前 10 秒的 health check 失敗不算。避免服務還在初始化時就被標記 unhealthy。

Kubernetes probe 對應

Docker 的 HEALTHCHECK 只有一種、等同 Kubernetes 的 livenessProbe。Kubernetes 的 readinessProbe 和 startupProbe 在 Docker 單機環境沒有對應物 — 它們是多 pod 場景下的流量控制機制。

下一步路由

• 監控 collector 的 container 部署實例 → Container 部署設計
• 服務探活與自動恢復 → DevOps 服務探活
• 負載平衡設計 → DevOps 負載平衡

流程定位

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

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

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

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

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

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

Tag 與 digest 策略

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

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

Scan gate 分流

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

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

常見反模式

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

下一步路由

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

image 與建置責任

image 的責任是固定依賴、執行入口與檔案結構，讓同一版本在不同環境行為一致。建置流程要回答三件事：基底映像是否可維護、建置產物是否可追溯、敏感資訊是否被隔離。

映像層數、套件來源、編譯參數都會影響啟動時間與安全邊界。部署策略在後面才有效，前提是 runtime 產物本身可預測。

基底映像選擇

基底映像（base image）決定 image 的安全維護基線與啟動時體積。選擇的核心取捨是體積 / 啟動速度與除錯便利性：

• 語言官方映像（python:3.12、node:20）：套件齊全、除錯方便，但體積大（通常 800MB+）、攻擊面廣。適合開發環境與 CI。
• slim / alpine 變體（python:3.12-slim、node:20-alpine）：體積壓到 100-200MB、啟動快、攻擊面小。代價是缺少除錯工具（strace、curl、dig），生產事故時 exec 進容器排查會受限。Alpine 用 musl libc 而非 glibc，某些 C extension 需要額外處理。
• distroless（gcr.io/distroless/base）：只包含 runtime 必要檔案，無 shell、無套件管理器。攻擊面最小，但除錯只能靠 ephemeral debug container 或外部觀測。適合安全要求高且觀測基礎建設完備的生產環境。
• 自建基底：組織統一維護的基底映像，可以固定安全基線、預裝觀測 agent、統一 timezone / locale。代價是基底維護本身是持續工作，版本更新節奏要有明確 owner。

選完基底後要確認兩件事：upstream 的更新節奏是否可追蹤（CVE 修補從上游到自家 image 的時間），以及團隊是否有能力在基底更新後快速重建並驗證所有服務 image。

建置可重現性

同一份 source code 在不同時間建置出不同 image，會讓 rollback 的假設失效——「回退到上一版」回退的是哪一版，取決於當時 build 環境的狀態。

可重現建置的關鍵實踐：

1. 鎖定依賴版本：go.sum、package-lock.json、poetry.lock 要進 git。依賴解析在建置時不從 registry 重新 resolve。
2. Multi-stage build：把建置環境（compiler、dev dependencies）和執行環境分開。最終 image 只包含 runtime 必要檔案，體積小且攻擊面收窄。
3. 避免 image 中殘留敏感資訊：build arg、環境變數、中間層都可能殘留 secret。secret 不進 Dockerfile，用 runtime mount 或 secret manager 注入。
4. image 標記策略：latest tag 不可重現——同一個 tag 指向的 image 會隨時間改變。用 git commit SHA 或語意版本號標記，讓每個 tag 指向唯一 image。

對應 5.C3 Orbitera managed K8s migration：揭露「跨平台遷移本質是能力遷移」。遷移到新平台時，CI/CD pipeline 可能換了 runner 環境、換了 registry——建置可重現性的前提是依賴鎖定與 multi-stage build 本身不依賴特定 CI 環境。

entrypoint 與啟動行為

entrypoint/command 的責任是定義容器如何啟動與退出。啟動流程應顯式處理初始化步驟、配置載入、依賴檢查與失敗退出。退出流程應處理信號中斷、在途請求收斂與資源釋放。

若啟動行為隱藏在 shell script 且無可觀測訊號，部署平台很難判斷 readiness 與失敗原因。

PID 1 與信號處理

容器內 PID 1 有特殊語意：它是 init process，負責接收平台送來的 SIGTERM / SIGINT 並轉發給子進程。PID 1 的問題出在三種情境：

Shell 作為 PID 1：ENTRYPOINT ["sh", "-c", "java -jar app.jar"] 讓 sh 成為 PID 1。SIGTERM 送到 sh、sh 預設不轉發、java 進程收不到信號、等到 terminationGracePeriodSeconds 到期後被 SIGKILL 強殺。修法是用 exec 或直接用 exec form：ENTRYPOINT ["java", "-jar", "app.jar"]。

多進程容器：一個容器跑多個進程時，PID 1 要負責信號轉發與子進程回收（zombie reaping）。如果 PID 1 不做 wait()，結束的子進程會變成 zombie。解法是用 tini 或 dumb-init 作為輕量 init，或在 Kubernetes 設 shareProcessNamespace: true 讓 kubelet 處理。

啟動腳本的信號遮蔽：entrypoint script 在初始化階段（下載 config、等依賴就緒）捕捉 SIGTERM 做清理，但如果清理邏輯卡住，整個 shutdown 會被阻塞。啟動腳本的 trap handler 要有 timeout，避免把 graceful shutdown 變成 ungraceful hang。

啟動時間對部署策略的影響

啟動時間直接影響 rollout 的最短觀察窗。一個啟動需 60 秒的服務，rollout 每批至少要等 60 秒 + 觀察窗口才能確認新版本穩定。啟動時間的組成與壓縮策略見 5.6 Platform Lifecycle Contract。

image 體積也影響啟動時間——image pull 在冷啟動（節點上沒有這個 image 的快取）時占啟動時間的顯著比例。1GB image 在 100Mbps 網路下需要 ~80 秒 pull。壓縮 image 體積同時改善啟動速度與節省 registry 頻寬。

resource limit

CPU/memory Resource Limit 隔離資源競爭並保護叢集穩態。限制過低會導致頻繁節流與重啟，過高會壓縮同節點容量並放大鄰近工作負載風險。

限制設計要依服務流量型態與 GC/執行時特性調整，並與 autoscaling、rollout 批次策略一起評估。

CPU request 與 limit 的設定策略

CPU 限制有兩個參數：request（排程保證）與 limit（硬上限）。兩者的關係決定服務在負載變動下的行為：

• request = limit（guaranteed QoS）：CPU 用量穩定可預測，不會被 throttle 也不會超用。代價是無法在閒時借用節點剩餘 CPU。適合延遲敏感的 API 服務。
• request < limit（burstable QoS）：平時用 request 保證的份額，高峰時可用到 limit。代價是當節點 CPU 競爭激烈時，所有 burstable pod 同時被 throttle，延遲會一起劣化。適合批次處理或對延遲要求不高的服務。
• 不設 limit（只設 request）：服務可用到節點全部剩餘 CPU。Kubernetes 社群近年傾向這個做法——CPU throttle 常比 CPU contention 更難排查。代價是需要良好的觀測來偵測 noisy neighbor。

Memory limit 與 OOM 的判讀

memory limit 是硬邊界——超過就 OOM kill，不走 graceful shutdown。OOM kill 的判讀分兩種情境：

真正的 memory leak：記憶體使用量隨時間單調上升，GC 無法回收。修法在程式碼層。memory limit 只是延後問題爆發，不是解法。

memory limit 設太低：服務在高峰流量下的正常記憶體使用超過 limit。常見於 JVM 服務——JVM heap + metaspace + native memory + thread stack 的總和超出 container memory limit。設 limit 時要用「峰值實際使用 + headroom」而非「平均使用」。

GC-based runtime（JVM、.NET、Go）要注意 container-aware memory 設定。早期 JVM 不認 cgroup memory limit，會按宿主機記憶體計算 heap 大小，導致 heap 配置超過 container limit。現代 JVM（Java 10+）預設啟用 container awareness（-XX:+UseContainerSupport），Go runtime 1.19+ 支援 GOMEMLIMIT。

資源設定與 autoscaling 的協同

resource request 同時決定 HPA（Horizontal Pod Autoscaler）的觸發基線。request 設太高時，CPU utilization % 會偏低，HPA 不會觸發擴容，導致服務在真正需要擴容前已經出現延遲。request 設太低時，utilization % 容易衝高，HPA 頻繁擴容，造成 pod 數量抖動。

穩定做法是先在 staging 環境跑負載測試確認服務的實際資源消耗曲線，再以 p90 負載的 CPU / memory 使用作為 request 基線。

runtime config

環境差異要顯式化才能追蹤——Runtime Config 承擔這個責任。配置來源、版本、更新節奏都應可追蹤。高風險設定需配合 Config Rollout 策略，避免同批大規模變更。

runtime 配置與映像版本要保留相容窗口，讓部署與回退可分步進行。

配置注入方式與取捨

配置注入容器有三條路徑，各自有不同的版本追蹤與更新語意：

環境變數最簡單但更新需要 restart。ConfigMap mount 可以動態更新但應用要能偵測檔案變化並 reload。外部 config store（Consul KV、AWS AppConfig、Feature Flag service）最靈活但引入了額外依賴。

設定變更跟 image 變更走不同路徑時，要確保兩者的版本可以交叉相容。版本 v2 的 image 搭版本 A 的 config 能跑、版本 v1 的 image 搭版本 B 的 config 也能跑——rollback image 但 config 沒回退、或 rollback config 但 image 沒回退的情境下、服務不應崩潰。這個相容窗口的設計責任見 5.7 Config Boundary。

遷移期的 Runtime 穩定性

對應 5.C5 Miro managed EKS 遷移：揭露「平台託管化的價值在讓團隊把心力從底層維護轉到交付效率與可靠性策略」。遷移到 managed 平台後，runtime 層面的變化包含 container runtime 版本（containerd vs Docker shim）、node OS、storage driver、network plugin。這些變化可能改變 image pull 速度、filesystem 行為、DNS 解析路徑。

遷移前後的 runtime 驗證應包含：

1. image pull 時間比較：新 registry / 新 node 的 pull 速度是否在 startup timeout 內。
2. filesystem 行為：log 寫入路徑、tmp 目錄、volume mount 行為在新 runtime 下是否一致。
3. DNS 解析：新叢集的 CoreDNS / node-local DNS 設定是否影響服務的依賴連線建立速度。
4. resource 行為：新 node type 的 CPU 架構（x86 vs ARM）、memory page size 是否影響服務性能特性。

判讀訊號

常見誤區

Container 常被簡化成「打包完就好」的步驟，結果是部署風險被後移到 rollout 階段。runtime 產物穩定性不足時，後續 probe、canary、rollback 都只能被動補救。

把資源限制設成平台預設值，也常造成高峰期不穩。限制應反映服務真實耗用模式，不應只追求表面資源利用率。

把 latest tag 當成版本標記，會讓 rollback 指向無法預測的 image。image tag 在 registry 上是 mutable——同一個 tag 可以被覆蓋指向新 image。用 immutable tag（commit SHA、content digest）才能保證 rollback 的確定性。

把所有配置都用環境變數注入，會讓設定變更跟 image 部署綁在一起。需要動態更新的設定（feature flag、rate limit 閾值）應該用 ConfigMap mount 或外部 config store，讓設定變更不需要 pod restart。

案例回寫

runtime 穩定性可用 5.C1 Tradeshift：self-managed K8s -> EKS 回寫。先看遷移期內啟動行為與資源限制如何影響切流，再對照本章檢查 image、entrypoint、limit 與 config 相容窗口。這個案例主要支撐的是「執行環境可重現性」判讀——遷移到新叢集時，image 不變但 runtime 環境變了（node OS、container runtime 版本、network plugin），runtime 穩定性的前提是 image 本身不依賴特定宿主環境的行為。

5.C5 Miro managed EKS 遷移 從另一個角度支撐：managed 平台接管 runtime 基礎設施後，container runtime 版本升級由平台控制，團隊要能驗證自家 image 在新 runtime 版本下行為一致。

若同版容器在不同節點出現分歧行為，先追建置來源與 runtime config 版本鏈，確認是依賴漂移還是環境漂移，再把關鍵證據收斂到 4.20 Observability Evidence Package。不直接支撐 service discovery TTL 或 queue replay 邏輯；若根因在定位鏈路或重播流程，應轉到 5.4 或 3.4。

跨模組路由

1. 與 5.2 的交接：部署批次與探針策略回到 Kubernetes 部署策略。
2. 與 5.3 的交接：流量進出與連線收斂回到 load balancer 合約。
3. 與 5.6 的交接：startup / readiness / drain 的生命週期定義回到 Platform Lifecycle Contract。
4. 與 4.20 的交接：啟動與資源證據回到 Observability Evidence Package。
5. 與 6.8 的交接：放行與回退條件回到 Release Gate。
6. 與 7.3 的交接：image 安全基線與攻擊面回到 7.3 入口治理與伺服器防護。

下一步路由

要把 runtime 行為接到部署收斂，接著讀 5.2 Kubernetes 部署策略。要看切流與退場條件，接著讀 5.3 load balancer 合約。要看 runtime 層的生命週期如何被平台表達，接著讀 5.6 Platform Lifecycle Contract。

Private Registry

隔離網路裡需要一個容器映像倉庫，讓內部的 Docker host / Kubernetes 節點能 pull image。

Harbor

Harbor 是 VMware 開源的企業級 registry，功能包含：映像儲存、漏洞掃描（整合 Trivy）、存取控制（RBAC）、映像簽章（Cosign / Notary）、複製策略。適合中大規模的斷網環境。

離線安裝：Harbor 提供 offline installer（.tgz，約 600MB），包含所有需要的容器映像。搬進隔離網路後解壓、跑 install.sh。

1# 外部：下載 offline installer
2wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
3
4# 搬運後，在內部解壓安裝
5tar xzf harbor-offline-installer-v2.11.0.tgz
6cd harbor
7cp harbor.yml.tmpl harbor.yml
8# 編輯 harbor.yml：設定 hostname、HTTPS 憑證、admin 密碼
9./install.sh

Docker Registry（官方輕量版）

如果不需要 Harbor 的進階功能（RBAC、掃描），官方的 Docker Registry 是單一容器、設定最簡單：

1# registry image 也要先搬進來
2docker load < registry-2.8.3.tar
3docker run -d -p 5000:5000 --restart=always --name registry \
4  -v /data/registry:/var/lib/registry \
5  registry:2.8.3

內部機器的 Docker daemon 要設定信任這個 registry（如果是 HTTP 而非 HTTPS）：

1{
2  "insecure-registries": ["registry.internal:5000"]
3}

映像搬運

docker save / load

最直接的搬運方式——把映像匯出成 tar 檔、搬運後匯入：

1# 外部：匯出
2docker pull nginx:1.25-alpine
3docker save nginx:1.25-alpine -o nginx-1.25-alpine.tar
4
5# 搬運後，內部匯入
6docker load < nginx-1.25-alpine.tar
7# 重新 tag 指向內部 registry
8docker tag nginx:1.25-alpine registry.internal:5000/nginx:1.25-alpine
9docker push registry.internal:5000/nginx:1.25-alpine

多個映像可以打包成一個 tar：docker save img1 img2 img3 -o bundle.tar。

skopeo copy

skopeo 是不需要 Docker daemon 的映像操作工具，適合 CI 環境或沒有裝 Docker 的工作站：

1# 外部：從 Docker Hub 複製到本地目錄
2skopeo copy docker://nginx:1.25-alpine dir:/path/to/export/nginx-1.25
3
4# 搬運後，從本地目錄推送到內部 registry
5skopeo copy dir:/path/to/export/nginx-1.25 docker://registry.internal:5000/nginx:1.25-alpine

skopeo 的優勢是不需要 pull 整個映像到本地 Docker（省磁碟空間）、支援 OCI layout、且可以在沒有 root 權限的環境執行。

搬運清單管理

映像搬運容易變成「需要什麼才搬什麼」的臨時操作。建議維護一份搬運清單（manifest），列出所有需要的 base image 和版本：

 1# image-manifest.yaml
 2images:
 3  - name: nginx
 4    tag: 1.25-alpine
 5    source: docker.io/library/nginx
 6  - name: postgres
 7    tag: "16.3"
 8    source: docker.io/library/postgres
 9  - name: node
10    tag: 20-alpine
11    source: docker.io/library/node

搬運腳本讀這份清單自動 pull + save，確保每次搬運的內容一致且可追蹤。

Base Image 更新週期

斷網環境的 base image 不會自動更新——nginx:1.25-alpine 搬進去之後就是那個版本，裡面的 Alpine 套件不會收到安全補丁。需要定期用新版 base image 替換舊的。

更新流程

1. 外部：pull 最新版 base image
2. 外部：用 Trivy 掃描漏洞（見下一節）
3. 搬運：走 content ferry 帶進內部
4. 內部：push 到內部 registry、更新 tag
5. 內部：重新 build 所有依賴這個 base image 的應用映像
6. 內部：部署更新後的應用映像

更新頻率：安全敏感環境月更、一般環境季更。每次更新都要記錄哪些 base image 換了、從哪個版本換到哪個版本。

Helm Chart 離線

如果內部有 Kubernetes 且使用 Helm，chart 也要離線管理：

1# 外部：下載 chart
2helm pull bitnami/postgresql --version 15.5.0
3
4# 搬運後，內部用本地檔案安裝
5helm install pg ./postgresql-15.5.0.tgz -f values.yaml

或架設 ChartMuseum 作為內部 Helm repo：chart 搬進來後 push 到 ChartMuseum，helm repo add 指向它。

離線漏洞掃描

連網環境的 Trivy 會自動下載漏洞資料庫（CVE DB）。斷網環境要先在外部下載 DB、搬進來。

1# 外部：下載 Trivy 漏洞資料庫
2trivy image --download-db-only --cache-dir /path/to/trivy-db/
3
4# 搬運 DB 檔案（~30MB）
5# db.tar.gz 在 /path/to/trivy-db/db/ 裡
6
7# 內部：用離線 DB 掃描
8trivy image --skip-db-update --cache-dir /path/to/trivy-db/ registry.internal:5000/nginx:1.25-alpine

掃描結果的處理方式跟連網環境相同——critical 和 high 的 CVE 要評估是否影響、是否有 base image 更新可修。差別是斷網環境的修復週期更長（要走搬運流程），所以掃描要更頻繁（至少跟 base image 更新同步）。

Harbor 整合 Trivy 後可以在 push 時自動掃描——Trivy DB 的更新同樣需要定期搬運。

時程參考：Private registry 建置（Harbor offline）約需 1 天。映像搬運流程建立約需半天。第一批 base image 搬運 + 掃描約需半天。之後每次更新約 2-4 小時。

跨分類引用

• → 斷網環境的通用原則：映像搬運走 content ferry 模式
• → 模組五：核心服務上 IaC — 運算：連網環境的容器部署
• → ECS 知識卡：容器編排的基礎概念

Dockerfile 設計

Multi-stage build 把編譯環境和執行環境分離。Build stage 用 Go 官方 image 編譯 binary，runtime stage 只包含 binary 和必要的 CA 憑證。

 1FROM golang:1.22-alpine AS build
 2WORKDIR /src
 3COPY go.mod go.sum ./
 4RUN go mod download
 5COPY . .
 6RUN CGO_ENABLED=0 go build -o /collector ./cmd/collector
 7
 8FROM alpine:3.20
 9RUN apk add --no-cache ca-certificates tzdata
10COPY --from=build /collector /usr/local/bin/collector
11RUN adduser -D -u 1000 monitor
12USER monitor
13EXPOSE 8080
14ENTRYPOINT ["collector"]

最終 image 包含 Go binary（~15MB）+ alpine base（~7MB）+ ca-certificates，總大小目標 < 25MB。用 scratch 替代 alpine 可以再小 7MB，但失去 shell debug 能力。

SQLite 在 Container 中的 I/O 考量

Docker 的 overlay2 storage driver 在每次 fsync 時經過 overlay 層。SQLite 的 WAL mode 依賴 fsync 確保寫入持久性 — 每筆 transaction commit 觸發一次 fsync。Overlay 層增加的延遲讓每筆 fsync 慢 20-40%（取決於 host 的 storage driver 和檔案系統）。

Volume mount 繞過 overlay

把 SQLite 的資料目錄掛載為 host volume（-v /host/data:/data），SQLite 直接寫 host 檔案系統、繞過 overlay 層。寫入效能和同機部署的 binary 版本相當。

不用 volume mount 的風險：container 刪除時 overlay 層的資料一起消失。docker rm = 所有事件資料消失。即使只是 docker run 新版本的 image 也會建立新 container，舊 container 的資料不會自動遷移。

Volume Mount 設計

兩個目錄分開掛載，職責和權限不同：

Container 內用非 root user（UID 1000）執行。Host 的 volume 目錄 ownership 需要對應：

1mkdir -p monitor-data monitor-config
2chown 1000:1000 monitor-data

Graceful Shutdown

docker stop 送 SIGTERM → collector 收到後執行 shutdown 序列：

1. 停止接受新的 HTTP request（listener close）
2. 等待 in-flight request 完成（5 秒 context timeout）
3. Flush pending writes（尚未寫入 storage 的事件，5 秒）
4. 停止定期 job（downsample / purge / rule engine 定期評估）
5. SQLite WAL checkpoint（TRUNCATE mode，15 秒）
6. 關閉 DB connection
7. 退出

步驟 2-5 合計超時上限 25 秒。這個序列對應 Backend 5.6 Platform Lifecycle Contract 的 shutdown → drain 狀態：步驟 1-2 是 drain（停接新工作、等在途完成），步驟 3-6 是 shutdown（flush 狀態和釋放資源）。Collector 屬於短 request API 的 workload 類型（drain 窗口 5-30 秒），但多了 WAL checkpoint 步驟，讓 shutdown 時間可能超過一般 HTTP 服務。PID 1 信號處理的設計考量（exec form、避免 shell 攔截 SIGTERM）見 Backend 5.1 PID 1 與信號處理。

docker stop 預設等 10 秒後送 SIGKILL。如果 WAL checkpoint 在大量未 checkpoint 的資料下需要超過 10 秒，Docker Compose 可以調 stop_grace_period: 30s。

SQLite 的 WAL 設計支援 crash recovery — SIGKILL 後 WAL 檔案仍在，下次開啟 DB 時自動 replay。但非 graceful shutdown 可能丟失 channel 中尚未寫入的事件（已收到 HTTP 202 但還在 buffer 中的事件）。

資源限制

Memory 限制設太緊會觸發 OOMKill — container 突然消失且無 log。設定 memory limit 前先觀察 collector 的 baseline 記憶體使用（docker stats），再乘以 1.5 安全係數。CPU request/limit 的設定策略（guaranteed vs burstable QoS）和 memory limit 與 OOM 的判讀見 Backend 5.1 Resource Limit。

Docker Compose 範例

 1services:
 2  collector:
 3    image: tarrragon/monitor:latest
 4    ports:
 5      - "8080:8080"
 6    volumes:
 7      - ./monitor-data:/data
 8      - ./monitor-config:/config:ro
 9    environment:
10      - MONITOR_STORAGE=sqlite
11      - MONITOR_DB_PATH=/data/events.db
12    restart: unless-stopped
13    stop_grace_period: 30s
14    deploy:
15      resources:
16        limits:
17          memory: 256M
18          cpus: '0.5'
19    healthcheck:
20      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
21      interval: 30s
22      timeout: 5s
23      retries: 3

restart: unless-stopped 讓 container 在 crash 或 host 重啟後自動恢復。healthcheck 讓 Docker 偵測 collector 是否真的在回應 — 只有 process 活著但 HTTP 不回應的場景也會被標記為 unhealthy。

和同機部署的效能對照

Volume mount 後效能差異只有 ~10%（Go HTTP handler 的 overhead 大於 volume mount 的 overhead）。不用 volume mount 時 overlay fs 的 fsync 開銷顯著 — 寫入吞吐降 40%。

何時用 container、何時用 binary

斷網環境的部署考量

Collector 在斷網環境（air-gapped）裡的部署跟連網環境的主要差異有三點。第一，SDK 的 endpoint 從外部 URL（https://collect.example.com）改為內網地址（http://collector.internal:8080），SDK 設定檔裡的 endpoint 要能按環境切換。第二，Collector 的 container image 無法從 Docker Hub 拉取——需要透過 content ferry 搬運映像、推送到內網的 private registry（Harbor 或 Docker Registry），Dockerfile 的 base image 來源也要改指 private registry。第三，Collector 的 storage backend 只能用本地磁碟或 NFS，不能用雲端物件儲存——SQLite backend 在斷網環境反而是優勢（零外部依賴），儲存容量規劃要在部署前就確定，因為斷網環境的磁碟擴容流程可能需要數週。

SDK 的 offline buffer（見SDK 設計：offline-buffer）在斷網環境更重要——如果 Collector 重啟或暫時不可達，SDK 端的 buffer 是唯一能保住事件的機制。

斷網環境的 infra 層監控（Prometheus / Grafana / Loki）設定見斷網環境的監控與可觀測性。

下一步路由

• SQLite 效能基準的詳細數字 → SQLite Backend 效能基準
• 可插拔 Storage Backend 架構 → 規模演進
• Container runtime 通用原則（base image 選擇、build 可重現性、PID 1 信號處理）→ Backend 5.1 Container 與 Runtime
• 生命週期合約（startup / readiness / drain / shutdown 的責任分類）→ Backend 5.6 Platform Lifecycle Contract
• 容器化資源設計的通用原則 → DevOps 容器化資源設計
• 服務探活和自動恢復 → DevOps 服務探活

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

場域定位

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

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

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

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

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

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

常見注意事項

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

學習路線

下一步路由

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

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

概念位置

Container 位在 build、deploy、runtime 與 platform 之間，是服務交付與資源限制的基本單位。 可先對照 Resource Limit。

可觀察訊號

系統需要 container 化的訊號是服務需要一致的啟動方式、相同的 runtime 環境、可複製的部署流程，或多個 instance 要共用同一套交付模型。

接近真實網路服務的例子

當服務要被放進 Kubernetes、CI pipeline 或 VM 上的標準化部署流程時，container 可以把 binary、system dependency 與啟動參數打包成固定形狀，降低環境差異。

設計責任

設計時要定義 image 內容、啟動命令、resource limit 與環境變數來源。Container 是讓服務交付、擴容與回滾更一致的手段，目的在服務層面。