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。

三種服務管理方案

Process.start（直接啟動程序）

在 test 的 setUp 中用 Process.start 啟動服務程序，tearDown 中用 process.kill 停止。

適合的前提：服務是單一二進位檔（不需要 Docker），啟動速度快（< 2 秒），不需要持久化狀態。

app_tunnel 的 ttyd 就是這個模式。ttyd bash 一行指令啟動，不需要設定檔，不需要資料庫，啟動到可接受連線約 500ms。Test harness 只需要：

1setUp: process = Process.start('ttyd', ['--port', '7681', 'bash'])
2       await waitForPort(7681, timeout: 3s)
3tearDown: process.kill()

Docker Compose

用 Docker Compose 定義服務堆疊，CI 的 before_all 階段 docker compose up，after_all 階段 docker compose down。

適合的前提：服務有依賴（database + cache + app server）、需要特定 OS 環境、需要精確的版本控制。

Docker Compose 的成本是 image pull 時間（首次或 image 更新時）和容器啟動時間。CI 中可以用 image cache 減少 pull 時間，但冷啟動仍比直接啟動程序慢。

Testcontainers

在 test 程式碼中用 testcontainers 套件管理 Docker 容器。每個 test class 或 test suite 啟動自己的容器，test 結束後自動清理。

適合的前提：和 Docker Compose 類似，但需要更細粒度的控制（不同 test 用不同的服務設定），或需要在 test 程式碼中動態決定服務的啟動參數。

Testcontainers 的優勢是 test 和 fixture 在同一個程式碼檔案中，容易理解每個 test 需要什麼環境。缺點是每個 test suite 啟動自己的容器，比共用容器慢。

健康檢查

服務啟動後到可以接受請求之間有延遲。直接在啟動後發送 test request 會因為服務尚未 ready 而失敗。

健康檢查的方式依服務類型而定：

TCP port 可達：waitForPort(port, timeout) 反覆嘗試 TCP 連線，成功即表示服務在監聽。最簡單，適合所有 TCP 服務。

HTTP health endpoint：對 /health 或 /ready 發送 GET request，收到 200 表示服務 ready。比 port check 更可靠 — port 監聽不代表應用層 ready。

特定操作成功：執行一個輕量的業務操作（例如 WebSocket 連線 + 簡單指令），成功表示服務完全 ready。最可靠但最慢。

服務狀態隔離

不同 test 之間的服務狀態需要隔離 — test A 在服務中建立的資料不應該影響 test B。

三種隔離策略：

每 test 重啟服務：最強隔離，最慢。適合服務啟動快（< 1 秒）的場景。

每 test 重設狀態：服務持續運行，test 開始前清理狀態（truncate tables, flush cache）。適合服務啟動慢但重設快的場景。

每 test 用獨立 namespace：服務持續運行，每個 test 使用獨立的 database schema / topic / channel。適合支援多租戶的服務。

app_tunnel 的 ttyd 是無狀態服務（每次連線是獨立的 terminal session），不需要狀態隔離。每個 test 建立新的 WebSocket 連線 = 新的 session。

下一步路由

• 什麼時候值得建 protocol integration test 基礎設施 → 成本判斷表
• Protocol integration test 的定義 → Protocol integration test 定義
• WebSocket 的 protocol test 實作 → WebSocket 協議測試實作

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 服務探活

場域定位

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：讀 模組五：部署平台與網路入口。

官方文件查核放過的五類落差

content/cli/ 五類終端機工具文章（監控 / 圖表 / 多工器 / 檔案管理 / SQL 客戶端）在實機驗證時抓到、純靠 docs 查核會放過的落差：

1. 旗標改名

zellij web 文件寫有 --bind，實際 0.43.1 是分開的 --ip 與 --port。讀者照文件下指令會得到 unknown flag error、但不知道正確旗標是什麼。

2. 設定鍵 migrate

lazygit 的 pager 設定文件寫 git.paging.pager，新版 0.62.2 改成 git.pagers（list）。舊鍵啟動時會被自動 migrate、改寫設定檔 — 讀者照舊文件設定後發現設定檔被工具自己改掉。

3. 隱含 schema prefix

dblab 的查詢編輯器要 schema 限定（SELECT * FROM public.products），裸 products 會報 relation 不存在。原因是編輯器連線的 search_path 不含 public — 文件沒提。

4. 平台特定 segfault

nvtop 在 Apple Silicon mac 裝得起來，但 snapshot 模式直接 segfault。GPU 後端不穩。裝成功不代表能用 — 文件只說「支援 macOS」。

5. Driver 差異

同一個 Postgres，lazysql（Go pq driver）連無 SSL 的 DB 要 ?sslmode=disable，pgcli / harlequin（Python psycopg）不用。同樣的連線字串在不同工具會有不同行為、文件各自不提對方。

共通模式

這五類落差有個共通點：讀者照文件走會撞牆、卻在文件裡找不到答案。實機跑一次就現形，而且現形的正是文章最該寫的內容 — gotcha 段落省下讀者各自撞一次的時間。

官方文件的 fact-check 只能驗證「文件說的是否正確」，驗不了「文件沒說的是否存在」。實機驗證補的是後者。

相關連結

• Verification-driven CLI skill（.claude/skills/verification-driven-cli/）— 操作步驟
• 終端機圖形化工具總覽 — 用此流程生產的工具文章
• #199 一篇文章只承擔一種功能 — 本文精簡的依據