Lou Stack Base

把同一個工具同時做成 CLI 和 MCP 之後, 我學到的事

louChang.tw@gmail.com (Lou Chang) — Sun, 17 May 2026 22:00:00 -0400

這篇記錄 content-i18n 同時支援 CLI 和 MCP server 時的 system design

重點不是 MCP protocol 本身, 而是同一個 workflow 要怎麼被兩種 entrypoint 共用

核心問題:

CLI 是什麼
MCP 是什麼
它們各自應該負責什麼
為什麼不能各自長一套 workflow
content-i18n 最後怎麼切 core, CLI, MCP

什麼是 CLI

CLI 是 command-line interface, 也就是人透過 terminal 下 command 操作程式

例如:

content-i18n review --config ./content-i18n.yaml --file target.md --source source.md

這個 command 裡有幾個部分:

content-i18n: 要執行的程式
review: 要執行的 action
--config: config file path
--file: target file
--source: source file

CLI 的使用者通常是人, shell script, CI job, 或其他 automation

一個好的 CLI 通常要處理:

command name 清楚
flag 好理解
error message 看得懂
exit code 可以給 script 判斷
output 可以給人讀, 也可以給 shell 接

CLI 是 human-facing entrypoint

CLI 怎麼運作

CLI 大概是這條 flow:

command
  -> argument parsing
  -> config loading
  -> core workflow call
  -> human-facing output

以 content-i18n review 來說:

讀 command 和 flags
載入 content-i18n.yaml
找到 source 和 target file
呼叫真正的 review workflow
把結果印給使用者
根據結果回傳 exit code

CLI 可以決定 output 怎麼印, 錯誤訊息怎麼呈現, command 怎麼命名

但 review 檢查什麼, queue state 怎麼算, sync-status 什麼時候能更新, 不應該放在 CLI layer

CLI layer 要怎麼設計

CLI layer 適合負責:

command tree
flag parsing
config path loading
shell-friendly output
human-readable error
exit code

CLI layer 不適合負責:

prepare 的 business rule
review 的 business rule
queue state 推導
sync-status 判斷
batch orchestration
source / target mapping rule

CLI 是 adapter:

human
  -> CLI
  -> internal/core

它把人的 command 轉成 core workflow 可以吃的 input, 再把 core workflow 的 result 轉成人看得懂的 output

什麼是 MCP

MCP 是 Model Context Protocol

在這個專案裡, MCP 讓 agent runtime 可以用 structured tool call 操作本機工具

如果 CLI 是 human 跟 local program 之間的 contract, MCP 就是 agent runtime 跟 local program 之間的 contract

CLI call:

content-i18n review --config ./content-i18n.yaml --file target.md --source source.md

MCP tool call:

{
  "tool": "content_i18n_review_translation",
  "file": "target.md",
  "source": "source.md"
}

CLI 是 command + flags

MCP 是 tool name + structured arguments

形式不同, 但最後要做的事情可以是同一件事

MCP 怎麼運作

MCP layer 大概是這條 flow:

tool definition
  -> request decoding
  -> core workflow call
  -> structured response

一支 MCP tool 通常要定義:

tool name
description
input schema
handler
response shape

以 content_i18n_review_translation 來說:

宣告這支 tool 存在
定義它需要哪些 arguments
接 agent runtime 傳進來的 request
decode 成 core workflow 可以用的 input
呼叫 review workflow
回傳 structured response 給 agent

MCP 的 output 要讓 agent 可以接著做下一步

所以 response 通常要包含:

issue list
file path
source path
sync readiness
next action hint

但 MCP 不該自己實作 review

MCP layer 要怎麼設計

MCP layer 適合負責:

public tool contract
argument schema
request decoding
handler registration
structured response
agent-friendly result shape

MCP layer 不適合負責:

自己決定 review rule
自己推導 queue state
自己判斷 completion
自己處理 source / target mapping
自己補 batch orchestration rule

content-i18n 的 MCP server 後來整理成:

internal/mcp/
  server.go
  tools.go
  tool_defs.go
  tool_handlers.go
  resources.go
  resource_defs.go
  resource_handlers.go
  response.go

這個結構讓責任比較清楚:

definition 放 tool contract
handler 接 request 並呼叫 core
registration 負責把 tool 掛到 server
response 負責 agent-facing output shape

registration 也改成 registry / spec pattern

這樣 public contract 不會藏在一大段手工註冊裡, 新增或移除 tool 時也比較不容易漏掉

為什麼 CLI 和 MCP 要共用同一個 core workflow

同一個工具支援 CLI 和 MCP 時, 最大風險是兩邊慢慢變成兩個產品

如果兩邊各自實作邏輯, 很快就會 drift:

CLI review pass, MCP review fail
MCP sync 成功, CLI queue 還是 stale
batch path 和 single-file path 檢查不一致
agent 繞過 review, 直接改 target file
completion rule 在不同入口有不同解釋

所以 workflow 必須只有一個 authority

在 content-i18n 裡, 這個 authority 是 internal/core

CLI / MCP = interface
internal/core = workflow owner

CLI 和 MCP 可以有不同 input / output

但 prepare, review, sync, queue, batch 的 meaning 只能有一份

`content-i18n` 的 core boundary

最後比較穩定的分層:

consumer repo
  ├─ content roots
  ├─ content-i18n.yaml
  ├─ glossary
  └─ style pack
        │
        ▼
CLI / MCP
        │
        ▼
internal/core
  ├─ init
  ├─ prepare/review/sync
  ├─ queue
  ├─ batch orchestration
  └─ site validation entrypoint
        │
        ├─ validator
        ├─ structure
        ├─ frontmatter
        ├─ content
        └─ providers

責任切分:

Layer	Responsibility
CLI	command parsing, flags, config path, exit code, human-readable output
MCP	tool definition, request decoding, handler registration, structured response
internal/core	prepare, review, sync, queue, batch, validation workflow
validator / structure / frontmatter / content	low-level document rules
providers	DeepL, Google, ai-harness provider boundary

CLI 和 MCP 呼叫 internal/core

internal/core 不需要知道 caller 是 CLI 還是 MCP

Review rule 改一次, CLI 和 MCP 都會吃到同一個行為

MCP tool surface 要怎麼設計

MCP tool surface 不能太碎

早期如果把 tool 拆成 low-level primitive, 看起來很有彈性:

read source
create work packet
validate translation
write translation target
next translation
repair translation

但這對 agent 反而危險

因為 tool surface 不只是 API 清單, 它也在暗示 agent 應該怎麼做事

raw primitive 太多, agent 很容易自己組 workflow:

read source
  -> inspect file
  -> edit target directly
  -> run partial validation
  -> skip sync-status

這就是 tool bypass

所以 content-i18n 後來把 public MCP surface 收斂成 workflow-level tools:

content_i18n_status
content_i18n_prepare_translation
content_i18n_review_translation
content_i18n_sync_status
content_i18n_translation_queue
content_i18n_translate_batch
content_i18n_validate_site

這 7 支 tool 比 low-level primitive 更適合 agent:

prepare_translation 比 read_source + create_work_packet 更接近真實 workflow step
translation_queue 已經能帶出 candidate, 不需要額外 next_translation
review_translation 回 structured issue 和 sync readiness, 比單純 validator wrapper 更完整
translate_batch 保留 batch orchestration, 不讓 agent 自己拼 batch loop
sync_status 把 completion 變成正式狀態, 不只是檔案存在

比較好的 MCP tool design:

public tool 少
operation 高階
response 完整
caller 不容易自己補 workflow

Queue state 怎麼運作

Queue model 讓 translation workflow 從一次性任務變成可維護系統

content-i18n 用三種 state:

completed
stale
missing

這些 state 從下面資料推導:

source discovery
expected target path
source hash
translation status

三種 state 的意思:

State	Meaning
`missing`	source exists, expected target does not exist
`stale`	target exists, but source changed after last sync
`completed`	review / validation passed, target synced with source

翻譯不是 once-and-done

今天完成的 target, 只要 source 改了, 明天就可能 stale

所以 queue 不只是列出待翻譯檔案, 它是在回答:

哪些 target 不存在
哪些 target 已經跟 source 不同步
哪些 target 真的完成
下一個該處理哪一篇

MCP tool 也要尊重 queue model

如果 agent 可以跳過 queue, review, sync, workflow authority 會失效

Failure modes 和最後規則

這個設計主要避免幾種 failure mode

CLI / MCP drift

CLI 和 MCP 如果各自實作 review, 很快就會不一致

修法:

CLI 和 MCP 都只呼叫 core
review rule 只放一份
queue state 只從 core 推導

Wrapper logic leak

MCP wrapper 如果開始補 workflow rule, wrapper 會越來越厚

修法:

MCP handler 只 decode request
handler 呼叫 core
handler format structured response
不在 handler 裡重新判斷 business rule

Low-level tool bypass

low-level tools 太多, agent 會自己組 workflow

修法:

public surface 收斂成 workflow-level tools
response 帶足夠資訊
review 和 sync-status 成為 official path

Fuzzy completion

如果 completion 只是 target file exists, queue 會失真

修法:

review / validation 要 pass
source-language leftover 要清掉
sync-status 要成功

Duplicated state logic

如果 queue state 在 CLI, MCP, batch 各算一次, 結果會不一致

修法:

queue state 推導集中在 core
caller 只使用 core result

最後規則:

CLI 和 MCP 是 entrypoint, 不是兩個產品
internal/core 是唯一 workflow owner
MCP tool 要偏 workflow-level
Public surface 要少, response 要完整
Queue state 必須由系統推導
Completion 要有正式 path
Tool design 要防 agent bypass

這樣 CLI 和 MCP 才能共用同一個工具核心, 不會慢慢長成兩套系統

References

從即時翻譯到真正的英文內容, 為什麼做 content-i18n

louChang.tw@gmail.com (Lou Chang) — Sat, 16 May 2026 22:00:00 -0400

我的 Blog 原本已經有 cmpt-translate, 也就是頁面可以即時翻譯成英文

但在多倫多 coffee chat 的時候, 有人直接建議我: 如果 Blog 要當作品集的一部分, 預設語言應該是英文

這句話點到的不是功能問題, 而是內容主體問題

即時翻譯可以把頁面轉成另一種語言, 但它不等於我真的有英文內容, 也不等於我有一套可以長期維護英文文章的 workflow

所以我開始做 content-i18n

目標很明確: 把 Blog 從 “中文為主, 英文靠即時翻譯” 變成真的有英文文章可以維護

問題不是翻得更快

如果只是要先拿到英文草稿, 方法很多:

直接貼到 AI Chat
用 Google Translate 或 DeepL
call translation API 產生初稿
讓 agent 幫忙改成英文

這些方法都能用, 速度也快

但技術 Blog 不是只有 prose

一篇文章通常會混在一起:

heading 和 section 順序
code block
inline command
config key
product name
error string
table
blockquote
argument flow

我要保留的是同一篇文章, 不是只把文字換成另一種語言

所以核心規則很簡單:

same article
different language only

Fidelity-first 的意思

fidelity-first 不是逐字翻譯, 也不是讓英文變得很僵

它處理的是一個取捨: 當 “讀起來更順” 和 “保住原文” 開始衝突時, workflow 要先保哪一邊

我的答案是先保原文

所以 content-i18n 會檢查這些東西:

heading hierarchy
section order
paragraph coverage
list structure
table structure
code block
technical inline literal
link 和 reference
argument flow
conclusion scope

如果英文讀起來很順, 但少了一個 caveat, 壓掉一個例子, 或把 command 改成另一種說法, 那就不是我要的結果

這也是為什麼我後來把 translation 當成 validation problem, 而不是只看 generation quality

即時翻譯不夠的地方

最麻煩的不是模型翻得完全錯

更常見的是看起來差不多, 但內容慢慢 drift

我遇過的問題包括:

opening paragraph 被翻得比原文更曲折, 甚至多出原文沒有的內容
heading 變得像文章標題, 但原本要強調的點不見了
code block 還在, 但 surrounding sentence 意思偏掉
某一段被 AI 覺得重複, 就自己幫我精簡
英文稿裡還殘留中文

這些問題不一定會讓文章看起來壞掉, 但會讓文章慢慢變成另一篇

所以我不想要每次都靠 copy-paste, 再自己從頭檢查一次

Workflow 設計

最後我需要的是 workflow, 不是一個 prompt

prepare
  -> write target
  -> review
  -> fix
  -> sync-status

每一步都有自己的責任

prepare

prepare 不只是讀 source file

它在定義 translation unit:

source path
target path
structure fingerprint
glossary
style pack
prompt context
target metadata

這一步會影響輸出穩定性

如果每次給 AI 或 provider 的 context 都不一樣, target 很難穩定

write target

write target 是產生草稿

草稿可以來自人, AI model, 或 provider-backed workflow

但 target file 存在不代表完成

草稿永遠只是草稿

review

review 是整條 workflow 最重要的一步

它不能只看英文順不順或文法對不對

它要檢查:

heading 有沒有對齊
blockquote 和 table 還在不在
code block 有沒有被改
technical inline literal 有沒有 drift
應該翻譯的地方還有沒有 source language

對知識管理內容來說, 這種 review 比單純看文法更有用

sync-status

sync-status 會把 completion 寫成正式狀態

沒有這一步, queue 很難分辨:

只是有人改過的草稿
還是真的 review 過, 且仍然跟 source 同步的 translation

Queue state

Queue state 讓這個工具開始不像一堆 command, 而比較像一個 system

content-i18n 用三種 state:

completed
stale
missing

這些 state 不是手動標記, 而是從這些資料推導:

source discovery
expected target file
source hash
translation status

翻譯不是一次性任務

今天 complete 的 target, 只要 source 改了, 明天就可能 stale

我的 Blog 文章本來就會一直修: 改句子, 補段落, 調例子, 修結構

所以 workflow 不能只問有沒有翻過

它還要問現在還有沒有 match source

Completion rule

Completion 不能模糊

我最後把規則定成這樣:

review 或 validation 要 pass
應該翻譯的地方不能殘留 source language
sync-status 要成功

這比 “看起來差不多” 窄很多

我常遇到 structure 看起來沒問題, 但 heading, metadata, inline note 裡還殘留沒翻完整的內容

這種東西如果不擋, 很容易混進正式內容

sync-status 的價值就在這裡

它把 completion 從主觀感覺, 變成系統可以推導和追蹤的狀態

為什麼做成 standalone tool

如果只是翻譯 Blog, 幾支 script 也能用

但後來我需要這些東西:

queue model
provider option
repeatable prepare / review / sync step
stricter validation
MCP interface 給 agent 用

這些需求一多, script 就不夠清楚

做成 standalone tool 之後, boundary 比較乾淨:

config 留在 consumer repo
provider secret 留在 repo 外
workflow 邏輯留在工具裡
site routing 和 theme 不跟 translation engine 混在一起

這樣它才比較像可以長期維護的工具, 不是只在 Blog 裡湊合著用的 script

最後整理

content-i18n 一開始要解的問題很單純: 讓 Blog 從 runtime translation, 變成真的有英文內容可以維護

但實作後, 問題變成:

如何保持同一篇文章
哪些東西必須被保住
什麼才算真的完成
queue 要怎麼追蹤 translation state

最後我需要的不是一次產生英文稿, 而是一套可以長期維護英文內容的 workflow

References

ArgoCD GitOps 實作：從安裝到完整 CD 流程

louChang.tw@gmail.com (Lou Chang) — Tue, 21 Apr 2026 21:00:00 -0400

這篇記錄把 ArgoCD 裝到 k3s cluster, 建立 ArgoCD Application, 讓整個 CD 流程從「GitHub Actions 直接 kubectl apply」換成「git 是 source of truth, ArgoCD 負責 sync」。

Push-based vs Pull-based CD

flowchart TD
    subgraph Push-based
        P1[Developer push] --> P2[GitHub Actions]
        P2 -->|kubectl apply + K8s credentials| P3[K8s Cluster]
    end

    subgraph Pull-based GitOps
        G1[Developer push] --> G2[GitHub Actions]
        G2 -->|push image + update YAML| G3[Git Repo]
        G3 -->|ArgoCD polls every 3min| G4[ArgoCD in Cluster]
        G4 -->|kubectl apply internal| G5[K8s Cluster]
    end

	Push-based	Pull-based (ArgoCD)
CI 需要 K8s 權限	是	否
Drift 偵測	無	自動偵測並修正
Rollback	手動跑舊 workflow	UI 一鍵或 git revert
可視性	CI log	ArgoCD UI 完整 sync 狀態

Push-based 的根本問題是安全邊界模糊——CI runner 持有 K8s credentials, 一旦 credentials 外洩, 攻擊者可以直接操作 cluster。Pull-based 把控制權留在 cluster 內部, CI 只需要寫 git 的權限。

ArgoCD 架構

flowchart LR
    Git["Git Repo<br/>k8s/base/"] -->|clone + render| RS[argocd-repo-server]
    RS -->|desired state| AC[argocd-application-controller]
    AC <-->|compare| K8s["k3s Cluster<br/>actual state"]
    AC -->|diff found: sync| K8s
    Redis["argocd-redis<br/>cache"] --- AC
    Server["argocd-server<br/>UI + API"] --- AC

各組件的職責：

組件	職責
`argocd-server`	UI + API, 操作入口
`argocd-repo-server`	clone git repo, render YAML（Helm/Kustomize/plain）
`argocd-application-controller`	核心, 每 3 分鐘比對 desired vs actual state
`argocd-applicationset-controller`	批量管理多個 Application
`argocd-dex-server`	SSO 認證（GitHub OAuth、LDAP）
`argocd-redis`	cache application state, 加速比對
`argocd-notifications-controller`	發通知（Slack、email）

Render YAML 是指 ArgoCD 把 Helm template 或 Kustomize overlay 展開成合法的 K8s YAML。Plain YAML 不需要 render, 所見即所得。

安裝 ArgoCD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl get pods -n argocd -w

等所有 pod Running 後存取 UI：

kubectl port-forward svc/argocd-server -n argocd 8080:443

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

瀏覽器開 https://localhost:8080, 帳號 admin。

k8s 目錄結構設計

ArgoCD 監控的路徑只能包含要被管理的 YAML。練習用的 test 資源和 production 資源混在同一個目錄, ArgoCD 無法區分：

k8s/
  base/            <- ArgoCD managed
    deployment.yaml
    service.yaml
    configmap.yaml
    hpa.yaml
    secret.yaml
  argocd/          <- Application manifest
    application.yaml
  test/            <- excluded from ArgoCD
    test-namespace.yaml
    test-liveness.yaml
    test-probe.yaml

base/ 是 ArgoCD 的 source of truth。test/ 完全排除在 GitOps 流程之外。

Application Manifest as Code

ArgoCD Application 應該在 git 裡, 不是只在 UI 點出來。UI 建立的設定沒有版本控制, 違反 GitOps 原則：

# k8s/argocd/application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: go-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/your-repo
    targetRevision: HEAD
    path: k8s/base
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Field	意義
`namespace: argocd`	Application 本身住在 argocd namespace, 固定
`project: default`	ArgoCD Project, 用來做 RBAC 和資源隔離
`targetRevision: HEAD`	永遠跟最新 commit
`path: k8s/base`	監控這個目錄下的所有 YAML
`server: kubernetes.default.svc`	ArgoCD 所在的 cluster 本身
`automated.prune: true`	git 裡刪掉的資源, cluster 上也刪
`automated.selfHeal: true`	有人手動改了 cluster, 自動改回 git 的狀態

kubectl apply -f k8s/argocd/application.yaml

如果 Application 已經從 UI 建立, kubectl apply 會更新現有的, 以 YAML 為準。之後 UI 只用來觀察。

imagePullSecret：讓 k3s pull Artifact Registry

k3s 是本機 cluster, 沒有 GCP Workload Identity, 需要明確的 credentials 才能 pull private registry 的 image。

用 Service Account key 建立不會過期的 imagePullSecret：

gcloud iam service-accounts keys create /tmp/ar-pull-key.json \
  --iam-account=YOUR_SA@YOUR_PROJECT.iam.gserviceaccount.com

kubectl create secret docker-registry ar-secret \
  --docker-server=us-east1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat /tmp/ar-pull-key.json)" \
  --namespace=default

rm /tmp/ar-pull-key.json

SA key 建完就刪——K8s Secret 裡已經有完整內容, 本機留著是不必要的風險。

在 deployment.yaml 加上 imagePullSecrets：

spec:
  imagePullSecrets:
    - name: ar-secret
  containers:
    - name: go-api
      image: us-east1-docker.pkg.dev/YOUR_PROJECT/go-api/go-api:prod-7639a24

GKE 上不需要這個, node 透過 Workload Identity 天生有 AR pull 權限。ar-secret 是 k3s 本機環境的限制。

完整 GitOps 流程

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub Actions
    participant AR as Artifact Registry
    participant Git as Git Repo
    participant Argo as ArgoCD
    participant K8s as k3s Cluster

    Dev->>GH: push to main
    GH->>GH: go test + go build
    GH->>AR: docker push prod-{sha}
    GH->>Git: update deployment.yaml image tag
    GH->>Git: push gitops/update-image-{sha} branch
    Dev->>Git: merge PR to main
    loop every 3 minutes
        Argo->>Git: poll for changes
        Git-->>Argo: deployment.yaml changed
    end
    Argo->>K8s: kubectl apply k8s/base/
    K8s->>K8s: rolling update

為什麼 CI 不能直接 push main：main 有 branch protection rule, 要求 PR。CI 用 gitops branch 繞過這個限制, 同時保留 code review 流程。

Drift detection：有人手動 kubectl edit deployment go-api 改了 replicas, ArgoCD 的 selfHeal 會在下次輪詢時自動改回 git 的值。cluster 的狀態永遠由 git 決定。

GKE vs k3s

	k3s（本機）	GKE
imagePullSecret	需要手動建	不需要, node 有 Workload Identity
Load Balancer	無, 需要 NodePort	原生支援 L4/L7 LB
Workload Identity	不支援	原生支援
費用	免費	e2-small ~$38/80 天

k3s 適合本機學習環境, GKE 更貼近 production。下一個 Phase 會在 GKE 上做 Prometheus + Grafana, 順便移除 ar-secret 的限制。

References

GitHub Actions 進階：Path Filter、Concurrency、Cache 與 GitOps 自動更新

louChang.tw@gmail.com (Lou Chang) — Mon, 20 Apr 2026 21:00:00 -0400

這篇記錄把 GitHub Actions pipeline 從基礎補到可用: trigger 設計、path filter、concurrency、cache, 到 CI 自動更新 deployment.yaml 完成 GitOps 閉環。最後對比 Jenkins 和 CircleCI。

Trigger 設計

三種 trigger 各自的用途：

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'dev'
        type: choice
        options: [dev, prod]

Trigger	觸發時機	用途
`push`	merge 到 main	主線 CI, 每次合併後跑
`pull_request`	PR 開啟或更新	review 前驗證, 保護 main
`workflow_dispatch`	手動從 GitHub UI	hotfix 補跑、手動指定環境 deploy

workflow_dispatch 加了 inputs 之後, GitHub UI 會出現下拉選單, 讓你在觸發時選擇環境。inputs 支援 string、boolean、number、choice 四種類型。

Path Filter：只在相關檔案變動時觸發

push README 不應該觸發 CI。paths filter 讓 workflow 只在有意義的檔案變動時才跑：

on:
  push:
    branches: [main]
    paths:
      - '**.go'
      - 'Dockerfile'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'
  pull_request:
    branches: [main]
    paths:
      - '**.go'
      - 'Dockerfile'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'

** 匹配任意深度的子目錄, * 只匹配單層。**.go 能匹配 handlers/health.go、middleware/auth.go, 而 *.go 只匹配根目錄的 .go 檔。

workflow_dispatch 不需要 paths, 手動觸發永遠跑。

`if` 條件：控制 Job 和 Step 執行

PR 的目的是 review, 不是上線。deploy job 不應該在 PR 觸發：

deploy:
  needs: build
  if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'

github.event_name 是 GitHub Actions 內建的 context, 值對應觸發的 trigger 名稱。pull_request 被排除在外, test 和 build 還是會跑, 確認 PR 可以合。

if 可以放在兩個層級：

層級	效果	範例
job 層級	整個 job 跳過或執行	deploy 只在 push 跑
step 層級	單一 step 跳過或執行	prod 環境才跑某個 step

step 層級常見的內建函式：

if: success()    # all previous steps passed (default)
if: failure()    # any previous step failed
if: always()     # runs regardless — cleanup, notifications
if: cancelled()  # workflow was cancelled

Concurrency：防止同時跑多個 Deploy

sequenceDiagram
    participant C1 as Commit A
    participant C2 as Commit B
    participant D as Deploy Job

    C1->>D: trigger deploy (3 min)
    C2->>D: trigger deploy (30s later)
    Note over D: cancel-in-progress: true<br/>cancel A, run B

concurrency 讓同一組的 job 不能同時跑：

deploy:
  concurrency:
    group: deploy-${{ github.ref }}
    cancel-in-progress: true

group 是識別 key, github.ref 是 branch 名稱, 讓 main branch 的 deploy 共用同一個 lock。

	`cancel-in-progress: true`	`cancel-in-progress: false`
行為	新的進來, 取消舊的	新的排隊等
適合	deploy（要最新版本）	database migration（不能中斷）

concurrency 只放在 deploy job, 不放 test 和 build——每個 commit 都需要完整的測試記錄。

Go Module Cache：加速 CI

每次 runner 是全新環境, 所有 dependencies 重新下載。go.sum 沒變, 重新下載完全是浪費。

actions/setup-go v4 之後內建 cache：

- uses: actions/setup-go@v6
  with:
    go-version-file: go.mod
    cache: true

cache: true 自動以 runner.os + go.sum hash 為 key。go.sum 沒變就命中 cache 跳過下載。

key 設計原則：把決定 cache 內容的檔案 hash 進 key。

情境	Key 包含什麼
Go	`runner.os` + `hashFiles('**/go.sum')`
Node.js	`runner.os` + `hashFiles('**/package-lock.json')`
Python	`runner.os` + `hashFiles('**/requirements.txt')`

ENV_TAG：環境感知的 Image Tag

flowchart LR
    A{trigger?} -->|workflow_dispatch| B[inputs.environment]
    A -->|push to main| C[prod]
    A -->|other branch| D[dev]
    B --> E[ENV_TAG]
    C --> E
    D --> E

env:
  ENV_TAG: ${{ inputs.environment || (github.ref == 'refs/heads/main' && 'prod') || 'dev' }}

SHORT_SHA：跨 Step 共用變數

每個 run: block 是獨立的 shell, 變數不能直接跨 step 傳遞。GITHUB_ENV 是 GitHub Actions 的特殊檔案, 寫進去的變數在後續所有 step 都能讀到：

- name: Set SHORT_SHA
  run: echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV

- name: Docker push to AR
  run: |
    docker build -t ${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/go-api/go-api:${ENV_TAG}-${SHORT_SHA} .
    docker push ${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/go-api/go-api:${ENV_TAG}-${SHORT_SHA}

${GITHUB_SHA::7} 是 bash 字串截斷語法, 取前 7 字元。Docker push 和 deployment.yaml 更新都用同一個 SHORT_SHA, 保證 tag 一致。

GitOps 自動更新 deployment.yaml

CI build 完之後, 自動更新 k8s/base/deployment.yaml 的 image tag, push 到 gitops branch, ArgoCD 偵測到變更後 sync：

- name: Update image tag
  run: |
    sed -i "s|image: .*-docker.pkg.dev/.*/go-api/go-api:.*|image: us-east1-docker.pkg.dev/${GCP_PROJECT_ID}/go-api/go-api:${ENV_TAG}-${SHORT_SHA}|" k8s/base/deployment.yaml
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    git config user.name "github-actions[bot]"
    git checkout -b gitops/update-image-${SHORT_SHA}
    git add k8s/base/deployment.yaml
    git commit -m "chore: update image tag to ${ENV_TAG}-${SHORT_SHA}"
    git push origin gitops/update-image-${SHORT_SHA}

sed 用 | 而不是 / 作為分隔符, 是因為 image URL 裡有 /, 避免語法混淆。push 到獨立的 gitops branch 而不是直接 push main, 是因為 main 有 branch protection rule。contents: write permission 讓 runner 有寫入 repo 的權限。

Image Tagging：git SHA vs Semver

	Git SHA	Semver (`v1.2.3`)
唯一性	天生唯一	需要人工維護
可追蹤性	直接對應 commit	需要額外記錄 tag 對應的 commit
語意	無	有, `v1.3.0` vs `v1.2.1` 一眼看出
適合	內部服務、CI/CD 自動化	對外 API、library

pipeline 用 {env}-{sha} 格式（例如 prod-7639a24）, 一眼看出環境和 commit。

Jenkins vs GitHub Actions

pipeline {
    agent any
    environment {
        GCP_REGION = 'us-east1'
    }
    stages {
        stage('Test') {
            steps { sh 'go test ./...' }
        }
        stage('Build') {
            steps { sh 'go build ./...' }
        }
        stage('Deploy') {
            when { branch 'main' }
            steps { sh 'docker build -t go-api .' }
        }
    }
    post {
        failure { echo 'Pipeline failed' }
        always { cleanWs() }
    }
}

	GitHub Actions	Jenkins
設定檔	`.github/workflows/*.yml`	`Jenkinsfile`
語法	YAML	Groovy DSL
Job 依賴	`needs: [test]`	stage 預設循序執行
Branch 限制	`if: github.event_name == 'push'`	`when { branch 'main' }`
Cleanup	step-level `if: always()`	`post { always {} }`
架設	雲端, 不用管 infra	需要自己維護 server
整合	GitHub 深度整合	plugin 生態豐富
適合	雲端原生、開源專案	企業、on-premise、複雜 pipeline

CircleCI 對比

# .circleci/config.yml
version: 2.1

orbs:
  go: circleci/go@1.11

workflows:
  ci:
    jobs:
      - test
      - build:
          requires: [test]
      - deploy:
          requires: [build]
          context: gcp-prod
          filters:
            branches:
              only: main

jobs:
  test:
    docker:
      - image: cimg/go:1.23
    steps:
      - checkout
      - go/load-cache
      - run: go test ./...
      - go/save-cache

概念	GitHub Actions	CircleCI
Job 依賴	`needs: [test]`	`requires: [test]`
Branch 限制	`if:` condition	`filters: branches: only:`
可重用套件	Marketplace actions	Orbs
跨 repo 共用 credentials	每個 repo 各設 secrets	Contexts（org 層級共用）
手動觸發 + 參數	`workflow_dispatch` + UI	API call + `pipeline.parameters`

CircleCI 的核心優勢是 Contexts 跨 repo 共用——多個 repo 指向同一個 Context, credentials 集中管理, 改一次全部生效。這個優勢在中大型企業多 repo 環境才有明顯差異。

References

Terraform Bootstrap 層設計: WIF、Artifact Registry 與 GitHub Actions CI/CD

louChang.tw@gmail.com (Lou Chang) — Thu, 16 Apr 2026 21:00:00 -0400

把 GitHub Actions 接到 GCP 推 Docker image, 最常見的做法是建一個 Service Account, 下載 key JSON, 存進 GitHub Secrets。這個方法能跑, 但 key 是長期憑證, 洩漏就完了。

這篇整理我用 Terraform 建出 bootstrap 層的過程: WIF 設定、Artifact Registry、Service Account 最小權限, 以及 GitHub Actions workflow 怎麼把這些串起來, 完全不需要任何 SA key。我實際使用 OpenTofu (Terraform 的開源分支), 語法與 Terraform 完全相容。

Bootstrap 層 vs Environment 層

Terraform 結構常見的分法是把資源按「建立頻率和共用程度」分層。

terraform/
├── bootstrap/          # one-time setup, shared across environments
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── backend.tf
├── environments/
│   └── dev/            # environment-specific resources
└── modules/
    └── vpc/

bootstrap 放什麼: 只建一次、很少改、整個 project 共用的資源。WIF pool 是 per-project 的, Artifact Registry 各環境共用同一個, Service Account 由 CI 統一使用。這些都適合放在 bootstrap。

environments 放什麼: VPC、Subnet、GKE cluster, 這些會隨 dev/prod 不同而有差異。

bootstrap 的一個特殊性: 它自己的 state 存在哪裡? 如果 GCS bucket 已經存在, 直接用同一個 bucket 不同 prefix 即可。

# bootstrap/backend.tf
terraform {
  backend "gcs" {
    bucket = "<project-id>-tfstate"
    prefix = "bootstrap"
  }
}

WIF 的信任鏈

WIF 解決的問題是: GitHub Actions 怎麼向 GCP 證明「這個請求真的來自我的 repo」?

GitHub Actions executes
  -> GitHub issues a short-lived OIDC token (JWT)
     contains: iss, sub, repository, ref, actor, exp (minutes away)
          |
          v
GCP Workload Identity Pool
  -> validates: is iss from GitHub?
  -> checks attribute_condition: is repository == allowed repo?
          |
          v
impersonate Service Account
  -> SA has only artifactregistry.writer
  -> token expires in minutes, no key ever exists

沒有任何 key 存在任何地方。就算 token 被攔截, 幾分鐘後就過期。

Terraform 設定

需要啟用的 GCP API

這是最容易忘記的部分。GCP 每個服務預設是關閉的, 要明確啟用:

resource "google_project_service" "artifact_registry" {
  service = "artifactregistry.googleapis.com"
}

resource "google_project_service" "iam_credentials" {
  service = "iamcredentials.googleapis.com"
}

iamcredentials.googleapis.com 是 WIF impersonate SA 需要的, 不開就會在 CI 跑到一半時出現 403。depends_on 確保資源建立順序正確:

resource "google_artifact_registry_repository" "go_api" {
  depends_on    = [google_project_service.artifact_registry]
  repository_id = "go-api"
  format        = "DOCKER"
  location      = var.region
}

depends_on 是 Terraform 的顯式依賴宣告。通常 Terraform 能從 resource 之間的引用自動推斷順序, 但這裡 google_artifact_registry_repository 並沒有直接引用 google_project_service, 所以需要手動告訴它「先等 API 啟用再建 repository」。

Service Account 與最小權限

resource "google_service_account" "github_actions" {
  account_id   = "github-actions-ci"
  display_name = "GitHub Actions CI"
}

resource "google_project_iam_member" "go_devops" {
  project = var.project_id
  role    = "roles/artifactregistry.writer"
  member  = "serviceAccount:${google_service_account.github_actions.email}"
}

SA 只給 roles/artifactregistry.writer, 不給 Editor 或 Owner。就算 CI pipeline 被入侵, 最多只能推 image, 不能碰其他 GCP 資源。

WIF Pool 與 Provider

resource "google_iam_workload_identity_pool" "github" {
  workload_identity_pool_id = "github-actions-pool"
  display_name              = "GitHub Actions Pool"
}

resource "google_iam_workload_identity_pool_provider" "github" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.github.workload_identity_pool_id
  workload_identity_pool_provider_id = "github-actions-oidc"
  display_name                       = "GitHub Actions OIDC"

  attribute_mapping = {
    "google.subject"       = "assertion.sub"
    "attribute.repository" = "assertion.repository"
  }

  attribute_condition = "attribute.repository == '${var.github_repository}'"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }
}

attribute_mapping 的兩側意思不同:

左邊是你在 GCP 這側定義的名字 (attribute.repository)
右邊是 GitHub JWT 裡的原始 claim (assertion.repository)

assertion 就是 GitHub 發出的 JWT token 內容。attribute_mapping 把 JWT claims 映射成 GCP 可以在 condition 裡使用的屬性。

attribute_condition 限制只有指定的 repo 才能通過驗證。沒有這個 condition, 任何 GitHub repo 都可以用這個 WIF pool。

SA Impersonation Binding

resource "google_service_account_iam_member" "wif_devops" {
  service_account_id = google_service_account.github_actions.id
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.github.name}/attribute.repository/${var.github_repository}"
}

這個 binding 允許「來自指定 repo 的 WIF principal」去 impersonate 這個 SA。principalSet 代表一組符合條件的 principal, 不是單一個。

Outputs

CI workflow 需要這兩個值:

output "workload_identity_provider" {
  value = google_iam_workload_identity_pool_provider.github.name
}

output "service_account_email" {
  value = google_service_account.github_actions.email
}

name 和 email 是 Attributes Reference 裡的欄位, 是資源建立後 GCP 回傳的值, 不是你傳入的 argument。

GitHub Actions Workflow

bootstrap apply 完, 把兩個 output 值存進 GitHub repo 的 Variables (不是 Secrets, 這兩個不是機密):

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

deploy:
  needs: build
  runs-on: ubuntu-latest
  permissions:
    contents: read
    id-token: write
  env:
    GCP_REGION: us-east1
    GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
  steps:
    - uses: actions/checkout@v4
    - uses: google-github-actions/auth@v2
      with:
        workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
        service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
    - uses: google-github-actions/setup-gcloud@v2
    - name: Build and push to Artifact Registry
      run: |
        gcloud auth configure-docker ${GCP_REGION}-docker.pkg.dev --quiet
        docker build -t ${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/go-api/go-api:${{ github.sha }} .
        docker push ${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/go-api/go-api:${{ github.sha }}

id-token: write 只開在需要 GCP 認證的 job, 不要在 workflow 頂層給。test 和 build job 不需要 GCP 認證, 就不需要這個權限。

env 區塊定義的變數在 run: 步驟裡用 $VAR_NAME 取用, 不是 ${{ }} syntax。${{ }} 是 GitHub Actions 的 expression syntax, 用來讀 vars.、secrets.、github. 這些 context。

Arguments vs Attributes

這個概念在寫 Terraform 時很重要:

Arguments (Argument Reference): 你傳入 resource 的值, 例如 account_id、display_name
Attributes (Attributes Reference): 資源建立後可以引用的值, 包含你傳入的和 GCP 自動產生的

email 不在 google_service_account 的 arguments 裡, 你不需要寫它。但 apply 完之後它就存在, 可以用 google_service_account.github_actions.email 引用。查法: Terraform Registry 每個 resource 頁面底部的 Attributes Reference 段落。

References

System Design 核心：Redis、Rate Limiting、Circuit Breaker 與 Scaling 策略

louChang.tw@gmail.com (Lou Chang) — Wed, 15 Apr 2026 21:00:00 -0400

這篇整理 SRE 面試高頻的 System Design 核心概念: Redis 的資料結構與使用場景、四種 Rate Limiting 演算法、Circuit Breaker 的三個狀態, 以及 Scaling Reads 和 Scaling Writes 的常見設計模式。

Redis

為什麼需要 Redis

資料庫每次讀取都要走磁碟 I/O, 延遲約 1-10ms。Redis 把資料存在記憶體, 延遲約 0.1ms。對於熱資料 (頻繁讀取、不常變動), cache 可以讓資料庫壓力降低幾個數量級。

Redis 是 key-value store, 但不只是 cache — 它的資料結構讓它能勝任多種不同的角色。

五種資料結構

結構	類比	適合場景
String	變數	cache、session、計數器
Hash	物件/dict	使用者資料、設定檔
List	雙向佇列	訊息佇列、最近活動紀錄
Set	無序集合	標籤、好友清單、去重
Sorted Set	有分數的集合	排行榜、優先隊列、時間序列

String:
  SET user:123:name "Alice"
  GET user:123:name  -> "Alice"
  INCR user:123:loginCount  -> atomic increment

Hash:
  HSET user:123 name "Alice" age 30 city "Toronto"
  HGET user:123 name  -> "Alice"
  HGETALL user:123    -> all fields

List:
  RPUSH queue:tasks "job1" "job2"
  LPOP queue:tasks  -> "job1"  (FIFO)

Set:
  SADD user:123:tags "golang" "devops"
  SMEMBERS user:123:tags  -> {"golang", "devops"}

Sorted Set:
  ZADD leaderboard 9500 "user:123"
  ZADD leaderboard 8200 "user:456"
  ZREVRANGE leaderboard 0 9 WITHSCORES  -> top 10 with scores

七個使用場景

Cache: 最常見。讀資料庫後存入 Redis, 下次直接從 Redis 拿。TTL 控制過期。

Distributed Lock: 多個服務搶同一資源時 (例如搶票), 用 SET key value NX EX 300 建 lock。NX = 只有 key 不存在時才設定 (原子操作), 避免兩個 instance 同時拿到 lock。EX 300 = 300 秒後自動釋放, 防止 lock 永遠不釋放。

Leaderboard: Sorted Set 天生支援排行榜。ZADD 加分數, ZREVRANGE 取前 N 名, 時間複雜度 O(log N)。

Rate Limiting: 用 INCR 計數, 每個 key 代表一個時間窗口。跨多個 API Gateway instance 共享同一個 Redis, 做到全域限流。

Proximity Search: GEOADD 加入座標, GEODIST 計算距離, GEOSEARCH 找範圍內的點。適合外送、叫車、地圖搜尋。

Streams: 類似 Kafka 的訊息流, 支援 consumer group、訊息持久化、重播。比 Pub/Sub 更可靠。

Pub/Sub: 發布/訂閱模式, 即時推送通知。特性是 fire-and-forget — 訊息送出後不保證對方收到, 斷線期間的訊息會遺失。適合即時通知, 不適合需要保證送達的場景。

Hot Key 問題

Hot Key 是指被大量請求集中打到同一個 Redis key 的情況。例如明星發文, 幾百萬人同時讀同一個貼文的 cache key, 造成那個 key 所在的 Redis node 過載。

三種解法:

本地快取 (Local Cache): 在每個應用服務 instance 上存一份記憶體內 cache, 減少打到 Redis 的請求數量。缺點是各 instance 的 cache 可能不一致, 且不同 instance 占用的記憶體加總起來會大很多。

副本 (Replica): 把 Hot Key 複製到多個 Redis 節點, 例如 post:viral:123:replica1, post:viral:123:replica2。讀取時隨機選一個副本, 分散壓力。缺點是需要額外的管理邏輯來維護副本的一致性。

Key 分散 (Key Sharding): 在 key 後面加隨機後綴 post:viral:123:{0~9}, 寫入時同時寫到所有後綴, 讀取時隨機選一個。本質上是把 Hot Key 打散到多個物理 key, 利用 Redis Cluster 的不同 slot 分流。這是最根本的解法, 因為它直接把流量分散到不同節點, 而不只是減少請求數量。

三種部署模式

模式	特性	適合
Standalone	單節點, 簡單	開發環境
Sentinel	主從複製 + 自動 failover	中型系統, HA 需求
Cluster	自動分片, 多主節點	大型系統, 水平擴展

Rate Limiting

四種演算法

Fixed Window: 把時間切成固定窗口 (例如每分鐘), 每個窗口有一個計數器。請求進來時計數器加一, 超過上限就拒絕。

Window: 00:00 - 01:00
Counter: 95 requests
Limit: 100

request at 00:59 -> counter = 96 -> allowed
request at 01:00 -> new window, counter = 0 -> allowed

問題: 窗口交界處可以瞬間打兩倍流量 — 00:59 的 100 次 + 01:00 的 100 次 = 2 秒內 200 次。

Sliding Window: 計算的是「過去 N 秒內」的請求數, 而不是「這個窗口內」。解決 Fixed Window 的邊界問題。代價是需要記錄每筆請求的時間戳, 儲存成本較高。

Token Bucket: 令牌桶以固定速率產生令牌 (例如每秒 10 個), 桶有容量上限。每個請求消耗一個令牌, 桶空了就拒絕。允許短暫的流量爆發 (burst) 只要桶裡有令牌。適合允許一定彈性的 API。

Bucket capacity: 100 tokens
Refill rate: 10 tokens/second

Burst scenario:
  - bucket is full (100 tokens)
  - 80 requests arrive at once -> allowed (80 tokens consumed)
  - next second: 10 tokens refilled

Leaky Bucket: 請求進入一個固定容量的佇列 (桶), 以固定速率從桶底流出處理。桶滿了就拒絕新請求。輸出速率絕對平滑, 沒有 burst。適合需要嚴格控制流量的場景 (例如付費 API)。

演算法	Burst 支援	實作複雜度	適合場景
Fixed Window	是 (邊界)	最低	簡單 API
Sliding Window	否	中	精確限流
Token Bucket	是 (可控)	中	一般 API
Leaky Bucket	否	中	嚴格平滑輸出

分散式 Rate Limiting

多個 API Gateway instance 各自計數, 用戶可以把限流繞過去 — 打三個 instance 各打 100 次, 實際是 300 次。

解法: 所有 instance 共用 Redis 做計數器。

Gateway A --\
Gateway B ----> Redis (shared counter) -> enforce global limit
Gateway C --/

INCR rate:user:123:minute:1744840800   # key = user + current minute timestamp
EXPIRE rate:user:123:minute:1744840800 60

INCR 是原子操作 — Redis 保證同一時間只有一個操作能修改這個 key, 不會有兩個 instance 同時讀到相同的數字再各自加一的問題。

Circuit Breaker

為什麼需要 Circuit Breaker

Service A 呼叫 Service B, B 開始回應很慢 (例如資料庫過載)。A 的請求堆積等待 B 的回應, A 的線程全部被卡住, A 也開始無法處理新請求。這就是 Cascading Failure (級聯失敗) — 一個服務的問題蔓延到上游。

Circuit Breaker 的設計: 偵測到下游失敗率超過閾值時, 直接短路 (不再嘗試呼叫 B), 立刻回傳錯誤或 fallback。讓 A 保持可用, 不被 B 拖垮。

三個狀態

Closed -> (error rate > threshold) -> Open
Open   -> (after timeout)          -> Half-Open
Half-Open -> (test request fails)  -> Open
Half-Open -> (test request ok)     -> Closed

Closed (正常): 所有請求正常送出。統計失敗率, 超過閾值就切到 Open。

Open (斷開): 不再嘗試呼叫下游, 直接回傳錯誤或 fallback 結果。讓下游有時間恢復。

Half-Open (試探): 等待一段時間後, 放行少量測試請求。如果成功, 切回 Closed。如果還是失敗, 回到 Open 繼續等待。

Fallback 可以是: 回傳快取的舊資料、回傳預設值、降級功能 (例如電商不顯示個人化推薦, 改顯示熱門商品)。

Scaling Reads

讀流量擴展的標準路徑: Index → Denormalization → Read Replica → Sharding → Caching Layer → CDN。

Cache Invalidation

Cache 的核心問題: 資料更新後, cache 裡的舊資料什麼時候失效?

TTL: 最簡單。設定過期時間, 時間到自動失效。缺點是資料更新到 TTL 過期這段時間, 用戶看到的是舊資料。

Write-through: 每次寫入資料庫時, 同步更新 cache。資料一致性最高, 但增加寫入延遲。

Write-behind (Write-back): 先寫 cache, 非同步批次寫入資料庫。寫入速度快, 但 cache 當機時可能遺失資料。

Tagged Invalidation: 給 cache key 打標籤。更新資料時, 把該分類下的所有 cache key 一起失效。例如「所有 category:electronics 的商品 cache」。

Versioned Keys: key 加版本號, 例如 product:123:v5。更新資料時, 版本號加一, 舊 key 自然失效 (沒人讀就等 TTL 自動清除)。好處是不需要主動刪除 cache, 舊 key 繼續存在但不會被讀到。缺點是需要一個地方儲存「目前最新版本號是多少」。

TTL 和 Write-through 通常一起用 — Write-through 確保資料更新立刻反映, TTL 作為保底機制。

CDN 與 Edge Caching

CDN (Content Delivery Network) 在全球多個節點 (edge) 儲存靜態資源的副本。用戶讀取時打到最近的 edge node, 不需要每次都打到 origin server。

動態內容也可以 cache 在 CDN — 例如 API 回應在 CDN edge 快取 30 秒。要注意 cache invalidation: 資料更新後要主動 purge CDN 的快取。

Cache Stampede

Cache 過期的瞬間, 大量請求同時穿透到資料庫, 造成資料庫瞬間過載, 這叫 Cache Stampede (快取雪崩)。

三種解法:

Request Coalescing (請求合併): 第一個打到 cache miss 的請求去查資料庫, 其他請求等待。資料庫回傳後, 所有等待的請求一起拿到結果。問題是需要一個協調機制判斷「誰是第一個」— 通常用 Distributed Lock 實作, 拿到 lock 的去查 DB, 其他人等 lock 釋放後再讀 cache。

Stale-While-Revalidate: 先回傳過期的舊資料給用戶 (不讓用戶等待), 同時非同步去更新 cache。用戶感受不到延遲, 但有短暫的資料不一致窗口。適合對時效性要求不高的場景。

Probabilistic Early Refresh: 在 cache 到期之前, 用機率決定是否提前刷新。越接近到期時間, 刷新的機率越高。這樣 cache 不會在同一時間大量到期, 流量分散到各個時間點。適合高流量系統, 不需要 Distributed Lock, 實作相對簡單。

實際使用上, Request Coalescing 和 Stale-While-Revalidate 常一起用, Probabilistic Early Refresh 是更進階的解法。

Scaling Writes

寫流量擴展比讀流量複雜, 因為寫入需要保證一致性。

資料庫選型

選資料庫是寫 Scaling 的第一步, 不同 DB 對高寫入的支援能力差異很大。

資料庫	適合場景	寫入特性
PostgreSQL	一般交易型系統	ACID, 強一致
Cassandra	高寫入, 時間序列	Write-optimized, eventual consistency
InfluxDB	IoT, metrics	時序資料, 高壓縮率
Column Store	分析查詢	批次寫入, 不適合即時

Horizontal Sharding

資料量太大時, 把資料水平切分到多個資料庫 instance。

Partition Key 選擇: 決定資料落在哪個 shard 的依據。選不好會造成 hot shard — 大量資料集中在同一個 shard。

user_id % 4 -> shard 0, 1, 2, 3

user:1 -> shard 1
user:2 -> shard 2
user:3 -> shard 3
user:4 -> shard 0

問題: cross-shard query 複雜, JOIN 無法跨 shard。需要在應用層做聚合。

Vertical Partitioning

把不同的 table 或 column 拆到不同的資料庫。

Before: one DB with all tables
After:
  Users DB    -> user_id, name, email
  Orders DB   -> order_id, user_id, amount
  Products DB -> product_id, name, price

和 Foreign Key 的差別: Vertical Partitioning 是物理上把 table 放到不同的 DB instance, 不只是邏輯上的關聯。跨 DB 的 JOIN 變成需要在應用層處理。

Queue 解耦寫入

高峰流量時, 把寫入請求先放進 Queue, 非同步處理。

User request -> API -> Queue -> Consumer -> DB

好處: API 立刻回應 (不等 DB 寫入), 流量峰值被 Queue 吸收。壞處: 資料不是立刻寫入, 用戶可能短暫看不到自己剛才的操作結果。

Load Shedding

系統超載時, 主動拒絕低優先度的請求, 保護核心功能。

Traffic spike:
  - Priority 1 (payment): always process
  - Priority 2 (read profile): process if capacity > 60%
  - Priority 3 (recommendation): drop if capacity < 40%

和 Rate Limiting 的差別: Rate Limiting 是對單一用戶限流, Load Shedding 是系統層級的優先度決策。

Hierarchical Aggregation

高頻寫入的計數類資料 (例如按讚數、播放次數), 如果每個事件都直接寫入中央資料庫, root 會過載。

Without aggregation:
  Event 1: likes++ -> Central DB
  Event 2: likes++ -> Central DB
  ... (1M events/sec -> Central DB explodes)

With Hierarchical Aggregation:
  Level 1 (edge nodes): buffer locally, aggregate every 1s
  Level 2 (regional nodes): aggregate from L1 every 10s
  Level 3 (central): receive pre-aggregated data every 60s

L1 node 每秒彙整一次, 送到 L2 的不是 1000 個事件而是一個「這 1 秒有 1000 個 likes」。L2 再彙整 10 秒的資料送到 central。Central 接收的是已經縮減幾個數量級的流量。

注意: root 收到的是彙整後的數量, 不是每個原始事件。如果業務需求是「知道每個用戶各自按了幾次讚」, 就需要在 edge 層保留更細的資料。Hierarchical Aggregation 適合「總數統計」, 不適合「明細追蹤」。

References

Terraform Module 化、Remote State 與 Ansible 基礎

louChang.tw@gmail.com (Lou Chang) — Tue, 14 Apr 2026 21:00:00 -0400

這篇涵蓋兩個主題: Terraform 的 module 化設計與 GCS remote state, 以及 Ansible 的核心結構與冪等性驗證。兩者在角色上互補 — Terraform 負責建立基礎設施, Ansible 負責設定伺服器內部。

Terraform Module 化

為什麼要 Module

Terraform 沒有 module 時, 同樣的 VPC 邏輯在 dev 和 prod 各寫一份。改一個地方, 另一個忘了改, 就出問題。Module 的作用和函式一樣: 定義一次, 傳入不同參數使用。

目標結構:

terraform/
├── modules/
│   └── vpc/
│       ├── variables.tf    # inputs
│       ├── main.tf         # resource definitions
│       └── outputs.tf      # outputs
└── environments/
    ├── dev/
    │   ├── backend.tf
    │   ├── variables.tf
    │   ├── terraform.tfvars
    │   └── main.tf
    └── prod/
        └── ...

modules/ 定義可重用的 infra 單元, environments/ 負責真正的落地, 傳入不同的變數值。

variables.tf

variable "project_id" {
  type = string
}

variable "region" {
  type    = string
  default = "us-east1"
}

variable "vpc_name" {
  type = string
}

variable "subnet_name" {
  type = string
}

variable "subnet_cidr" {
  type = string
}

main.tf

resource "google_compute_network" "vpc" {
  name                    = var.vpc_name
  auto_create_subnetworks = false
  project                 = var.project_id
}

resource "google_compute_subnetwork" "subnet" {
  name          = var.subnet_name
  network       = google_compute_network.vpc.id
  region        = var.region
  ip_cidr_range = var.subnet_cidr
  project       = var.project_id
}

resource "google_compute_firewall" "allow_internal" {
  name    = "${var.vpc_name}-allow-internal"
  network = google_compute_network.vpc.name
  project = var.project_id

  allow {
    protocol = "tcp"
  }
  allow {
    protocol = "udp"
  }
  allow {
    protocol = "icmp"
  }

  source_ranges = [var.subnet_cidr]
}

resource "google_compute_firewall" "allow_ssh" {
  name    = "${var.vpc_name}-allow-ssh"
  network = google_compute_network.vpc.name
  project = var.project_id

  allow {
    protocol = "tcp"
    ports    = ["22"]
  }

  source_ranges = ["0.0.0.0/0"]
}

outputs.tf

output "vpc_id" {
  value = google_compute_network.vpc.id
}

output "vpc_name" {
  value = google_compute_network.vpc.name
}

output "subnet_id" {
  value = google_compute_subnetwork.subnet.id
}

environments/dev/main.tf

provider "google" {
  project = var.project_id
  region  = var.region
}

module "vpc" {
  source      = "../../modules/vpc"
  project_id  = var.project_id
  region      = var.region
  vpc_name    = "devops-vpc"
  subnet_name = "devops-subnet"
  subnet_cidr = "10.0.1.0/24"
}

terraform.tfvars

project_id = "devops-lab-lou-2026"
region     = "us-east1"

prod 環境呼叫同一個 module, 只是傳入不同的 vpc_name 和 subnet_cidr。module 本身不改動。

Remote State 與 State Locking

為什麼需要 Remote State

Terraform 的 state file 記錄「現在 GCP 上長什麼樣子」。沒有 remote state, state 只存在本機:

本機不見 = infra 資訊全部丟失
多人協作 = 每個人各自有一份 state, 互相衝突

GCS backend 把 state 集中存在 GCS bucket, 所有人共用同一份。

為什麼需要 State Locking

如果兩個人同時跑 terraform apply, 兩個人都讀到相同的 state, 各自計算 diff, 各自套用變更 — 結果不可預期。

State locking 讓第一個 apply 開始後就鎖住, 第二個人必須等待鎖釋放才能繼續。這對應的是 CAP Theorem 的 Consistency: 分散式系統裡, 不能讓兩個操作同時修改同一個東西。

# environments/dev/backend.tf
terraform {
  backend "gcs" {
    bucket = "devops-lab-lou-2026-tfstate"
    prefix = "environments/dev"
  }
}

GCS backend 原生支援 locking, 用 GCS object 的 generation 機制實作。不需要額外設定。

初始化:

terraform init
terraform plan
terraform apply

plan 和 apply 要分開的原因: plan 讓你看到「即將發生什麼」, apply 才真正執行。Production 環境裡, plan 的結果通常要先審核才能 apply。

State 操作指令

# list all resources tracked in state
terraform state list

# show detail of a specific resource
terraform state show module.vpc.google_compute_network.vpc

# move resource to a different address (e.g. refactor module path)
terraform state mv old_address new_address

# remove resource from state without destroying it
terraform state rm module.vpc.google_compute_network.vpc

state rm 不會刪除 GCP 上的資源, 只是讓 Terraform 不再追蹤它。下次 apply 時, Terraform 以為那個資源不存在, 可能嘗試重建。所以 state rm 通常搭配 terraform import 使用, 先移除再重新 import 到新的 address。

Ansible

Terraform vs Ansible

	Terraform	Ansible
用途	建基礎設施	設定伺服器內部
語言	HCL (declarative)	YAML playbook
狀態	state file	無 state, 每次重新檢查
連線方式	API call	SSH (agentless)
冪等性	天生冪等	需要正確寫 playbook

Ansible agentless 的意思是: 目標機器不需要安裝任何 Ansible agent, 只需要有 SSH 和 Python。Ansible 在控制機 (你的 laptop 或 CI runner) 上執行, 透過 SSH 連到目標機器執行操作。

現代 K8s 環境裡 Ansible 的角色變小了, 因為 K8s YAML 取代了很多設定工作。但 VM 環境和 on-premise 環境仍然很常見。

核心結構

Inventory: 你要管理哪些機器, 分組管理。

[local]
localhost ansible_connection=local

[webservers]
web1.example.com
web2.example.com

[databases]
db1.example.com ansible_user=ubuntu

Module: Ansible 內建的操作單元, 例如 file, copy, apt, service。Module 是冪等的基礎 — 每個 module 在執行前先檢查目標狀態, 狀態已符合就不做任何事。

Task: 一個步驟, 呼叫一個 module。

Playbook: 一個或多個 task 的組合, 定義在哪些 host 上執行什麼。

Role: 多個 task 的集合, 可重用, 類似 Terraform 的 module。適合封裝 nginx 安裝、prometheus 設定這類可重複使用的邏輯。

基本 Playbook

---
- name: localhost practice
  hosts: local
  tasks:
    - name: create practice directory
      file:
        path: /tmp/ansible-practice
        state: directory
        mode: "0755"

    - name: write config file
      copy:
        dest: /tmp/ansible-practice/config.txt
        content: |
          env=dev
          version=1.0

    - name: show file content
      command: cat /tmp/ansible-practice/config.txt
      register: file_content

    - name: print result
      debug:
        msg: "{{ file_content.stdout }}"

# check connectivity
ansible local -i inventory.ini -m ping

# run playbook
ansible-playbook -i inventory.ini playbook.yml

冪等性驗證

第一次執行:

TASK [create practice directory] ... changed
TASK [write config file]         ... changed
TASK [show file content]         ... changed
TASK [print result]              ... ok

第二次執行 (不改任何東西):

TASK [create practice directory] ... ok      # already exists, no action
TASK [write config file]         ... ok      # content unchanged, no action
TASK [show file content]         ... changed # command module always runs
TASK [print result]              ... ok

file 和 copy module 是冪等的, 第二次執行顯示 ok 代表沒有做任何變更。command module 不是冪等的, 每次都會執行 — 這是設計上需要注意的地方。需要冪等的指令操作要用 creates 或 when 條件控制。

References

GCP Networking 基礎與 API Gateway 設計

louChang.tw@gmail.com (Lou Chang) — Sat, 11 Apr 2026 21:00:00 -0400

這篇涵蓋兩個主題: 在 GCP 上手動建立 VPC、Subnet、Firewall Rules、Service Account, 以及 API Gateway 的設計概念與面試常見問題。

GCP Networking

VPC: Global vs Regional

GCP VPC 是 global 的, Azure VNet 是 regional 的。

GCP:
  devops-vpc (global)
  ├── subnet: us-east1 (10.0.1.0/24)
  └── subnet: asia-east1 (10.0.2.0/24)   # same VPC, different region
  # VMs in different regions communicate over internal network directly

Azure:
  vnet-eastus (East US)                   # region-scoped
  vnet-westus (West US)                   # separate VNet
  # cross-region requires VNet Peering

GCP 的優勢是同一個 VPC 內, 不同 region 的 VM 可以走內網直通, 不需要 Peering。

Subnet 與 CIDR

Subnet 是 regional 的。建 Subnet 要指定 region 和 IP 範圍 (CIDR)。

10.0.1.0/24

10  .  0  .  1  .  0
00001010.00000000.00000001.00000000
|______fixed 24 bits_______| vary |

/24 後面 8 bits 可變 = 2^8 = 256 個 IP (可用 254 個)。

CIDR	Usable IPs	Use case
/8	16,777,214	Large private network
/16	65,534	Medium VPC
/24	254	Typical subnet
/28	14	Small subnet (GCP minimum)
/32	1	Single IP (firewall rule)

/0 = 所有 IP。0.0.0.0/0 就是「任意來源」。

# create VPC (custom mode: you control subnet creation)
gcloud compute networks create devops-vpc --subnet-mode=custom

# create subnet in us-east1
gcloud compute networks subnets create devops-subnet \
  --network=devops-vpc \
  --region=us-east1 \
  --range=10.0.1.0/24

Firewall Rules

GCP Firewall Rules 掛在 VPC 層, 不是 Subnet 層 (Azure NSG 可以掛在 Subnet 或 NIC)。

Priority 數字越小, 優先度越高。預設 1000, 最高 0, 最低 65535。GCP 有一條隱藏的 implied deny-all (priority 65535), 所有沒有 match 到任何 rule 的流量都會被擋。

Priority 500: deny tcp:22 from 1.2.3.4   # matched first -> blocked
Priority 1000: allow tcp:22 from 0.0.0.0/0
# result: 1.2.3.4 is blocked, all other IPs allowed

# allow SSH from anywhere (dev only -- use your own IP in production)
gcloud compute firewall-rules create allow-ssh \
  --network=devops-vpc \
  --allow=tcp:22 \
  --source-ranges=0.0.0.0/0

# allow all internal traffic within the subnet
gcloud compute firewall-rules create allow-internal \
  --network=devops-vpc \
  --allow=tcp,udp,icmp \
  --source-ranges=10.0.1.0/24

# verify source ranges
gcloud compute firewall-rules describe allow-ssh --format="get(sourceRanges)"

Production 做法是 --source-ranges=YOUR_IP/32, 只允許自己的 IP。

Service Account vs Managed Identity

Service Account 是給程式或服務用的身分, 不是給人用的。

	GCP Service Account	Azure Managed Identity
建立方式	手動建立, 手動指派	System-assigned 隨資源自動建立
Credentials	可下載 JSON key (但不建議)	完全沒有 key, Azure 管 token lifecycle
生命週期	獨立存在, 手動管理	System-assigned 隨資源一起刪除

Azure 設計上就把 key 的路堵死了, 是更安全的預設值。GCP 的 SA key 下載太方便, 是常見的安全漏洞來源。

解法是 Workload Identity Federation (WIF): 讓 GitHub Actions 或 GKE Pod 用 OIDC token 換 GCP 權限, 整個流程不需要 SA key。

GitHub Actions
  -> generate OIDC token
    -> WIF validates token
      -> exchange for SA permissions
        -> access GCP resources (no key involved)

SA + WIF = 跟 Managed Identity 同等安全, 但需要主動設定。

# create service account
gcloud iam service-accounts create devops-cicd-sa \
  --display-name="DevOps CI/CD SA" \
  --project=devops-lab-lou-2026

# verify
gcloud iam service-accounts list --project=devops-lab-lou-2026

API Gateway

定義

API Gateway 是所有請求的統一入口, 負責處理橫切關注點 (cross-cutting concerns), 讓後端服務只需要專注在業務邏輯。

在 Gateway 處理	後端服務就不用管
TLS termination	不用處理 HTTPS
Auth (JWT / API key)	不用每個服務各自驗 token
Rate limiting	不用自己擋暴力請求
Caching	不用每個服務自己做 cache
Routing	統一管理 path → service 對應

SSL Termination

TLS handshake 有 CPU 開銷。讓 Gateway 處理 SSL, 後端和 Gateway 之間走 HTTP 內網通訊。

Client  --HTTPS-->  API Gateway  --HTTP-->  Backend Pod A
                    (decrypt here)          Backend Pod B

好處:

憑證只在 Gateway 管一份, 到期只更新一個地方
後端服務省去加解密的 CPU 消耗

Gateway 和後端在同一個 VPC 內, 內部 HTTP 通常可以接受。需要更嚴格的場景 (金融、醫療) 可以加 mTLS, 後端之間也加密。

Caching

讀多寫少、回應不常變動的 API 適合在 Gateway 層 cache。

Without cache:
  User A -> GET /products -> Gateway -> Backend -> DB
  User B -> GET /products -> Gateway -> Backend -> DB
  # 100,000 requests = 100,000 DB queries

With cache:
  User A -> GET /products -> Gateway -> Backend -> DB  (first request, store result)
  User B -> GET /products -> Gateway -> return cached  (no backend hit)
  # 100,000 requests = 1 DB query

個人化的回應 (GET /cart, GET /orders) 不適合 cache, 因為每個用戶的資料不同。

BFF Pattern

不同客戶端對 API 的需求差異越大, 用同一個 Gateway 服務所有客戶端就會出現各種妥協。BFF (Backend for Frontend) 的解法: 為不同類型的客戶端各自維護一個 Gateway。

Web BFF    ---> User Service
Mobile BFF ---> Order Service   (same backend, different gateway)
Public BFF ---> Product Service

Web BFF 可以做大量資料聚合, Mobile BFF 只回傳精簡欄位, Public BFF 做嚴格版本控制。後端微服務保持不變。

適合: 有多個差異明顯的客戶端, 且每個客戶端團隊有能力維護自己的 BFF。小型團隊或客戶端差異不大時, 一個統一 Gateway 就夠了。

GraphQL 是另一個解法: 客戶端自己決定要哪些欄位, 同一個 endpoint 服務所有客戶端。代價是 schema 設計複雜度和 N+1 query 問題。

架構與高可用

Internet
  |
L7 LB          # distributes traffic across Gateway instances, health checks
  |
API Gateway x N instances (stateless)
  |- Auth (JWT / API key validation)
  |- Rate limiting (counters in Redis, shared across instances)
  |- Routing (/users -> User Service, /orders -> Order Service)
  |- SSL Termination
  |
L4 LB          # distributes traffic to backend pods
  |
Backend microservices

Gateway 是無狀態的, 路由規則存在設定檔或 DB, 任何 instance 都能處理任何請求, 水平擴展自然。

Rate limiting 是有狀態的: 計數器存在 Redis, 所有 instance 共享同一份數據。

API Gateway instance A --|
API Gateway instance B --|---> Redis (rate limit counters)
API Gateway instance C --|

沒有共享 Redis 的話, 用戶可以同時打三個 instance 各打 100 次, 繞過 100 次/分鐘的限制。

常見面試問題

Q: Is the Gateway a SPOF?

No. Deploy multiple instances behind a Load Balancer. Gateway is stateless — any instance can handle any request — so horizontal scaling is straightforward.

Q: How do you share rate limit state across instances?

Store rate limit counters in Redis. All Gateway instances read and write to the same Redis, so the limit is enforced globally regardless of which instance handles the request.

Q: What’s the difference between a Gateway and a Load Balancer?

LB distributes traffic at L4/L7. Gateway handles application-level concerns — auth, rate limiting, routing logic. LB sits in front of the Gateway for HA; Gateway sits in front of your services for business logic.

Consistent Hashing

多個 LB instance 如何在不共享狀態的情況下做路由決策?

Round Robin 需要計數器 (「我上次給哪台」), 多個 instance 各自維護計數器, 分流會不均衡。

Consistent Hashing 用確定性算法: 同一個輸入永遠得到同一個輸出, 不依賴任何外部狀態。

hash(client IP) % number_of_backends = which backend to route to

IP ending in 0-3 -> Backend A
IP ending in 4-6 -> Backend B
IP ending in 7-9 -> Backend C

任何 LB instance 收到同一個 IP, 算出來的結果都一樣。不需要溝通, 不需要共享狀態。

Algorithm	Needs shared state	Reason
Round Robin	Yes	requires counter
Least Connections	Yes	requires connection count per backend
Random	No	stateless by nature
Consistent Hashing	No	deterministic function, same input = same output

References

Networking 基礎: DNS、HTTP/HTTPS、Load Balancer 與 Proxy

louChang.tw@gmail.com (Lou Chang) — Thu, 09 Apr 2026 22:00:00 -0400

網路是系統設計的地基。這篇從實際指令出發, 理解 DNS 解析、HTTP/HTTPS、TLS、Load Balancer、Proxy 的概念和 trade-off。

DNS

dig 指令

dig google.com
dig +short example.com
dig +short example.com CNAME

dig 是 DNS 查詢工具。+short 只顯示結果, 省略雜訊。

輸出解讀:

;; QUESTION SECTION:
;google.com.    IN    A          # query A Record (IP address)

;; ANSWER SECTION:
google.com.  300  IN  A  142.250.x.x   # TTL = 300 seconds
google.com.  300  IN  A  142.250.x.x

Google 回傳多個 IP, 是 Client-side Load Balancing — DNS 回傳多個 IP 讓客戶端自己選一個連。

A Record vs CNAME

A Record: domain → IP (直接給地址)

example.com  →  1.2.3.4

CNAME: domain → 另一個 domain (別名, 再去查那個的 IP)

blog.example.com  →  user.github.io  # alias
user.github.io    →  140.82.x.x      # actual IP

TTL

TTL (Time To Live) = DNS cache 的秒數。

TTL 300 = 電腦 cache 這個結果 5 分鐘, 5 分鐘內不重新查詢
改了 DNS record 後, 要等 TTL 才會全面生效
TTL 越短, 改動越快生效, 但 DNS server 負擔越大

CNAME Flattening

根域名 (apex domain, 如 example.com) 技術上不能有 CNAME (DNS 標準限制)。Cloudflare 等 DNS 服務會自動把它壓平成 A Record 回傳, 稱為 CNAME Flattening。

Proxied 模式下, Cloudflare 不回傳真實的 CNAME 或 origin IP, 只回傳自己的 proxy IP。所以 dig example.com CNAME 可能回傳空的。

DevOps 連結

K8s 內部服務互相呼叫靠 CoreDNS (kube-dns)
Pod 找其他 service: service-name.namespace.svc.cluster.local
部署新服務需要設定 domain 指向 Load Balancer IP

HTTP / HTTPS / TLS

curl -v 看連線過程

curl -v https://example.com 2>&1 | head -40

-v 顯示詳細資訊。2>&1 把 stderr 合併到 stdout, 讓 head 能同時截斷兩者。

實際輸出片段:

* Trying x.x.x.x:443...
* TLSv1.3 (OUT), TLS handshake, Client hello   # client proposes cipher suites
* TLSv1.3 (IN),  TLS handshake, Server hello   # server selects TLSv1.3
* TLSv1.3 (IN),  TLS handshake, Certificate    # server sends certificate
* TLSv1.3 (IN),  TLS handshake, Finished       # encrypted channel established
> GET / HTTP/2                                  # HTTP request (inside encrypted channel)
< HTTP/2 200                                    # response

連線順序

TCP 3-way handshake     (establish connection)
  SYN -> SYN-ACK -> ACK

TLS handshake           (establish encryption, on top of TCP)
  Client Hello -> Server Hello -> Certificate -> Verify -> Finished

HTTP request            (transmitted inside encrypted channel)
  GET / HTTP/2

TCP 握手 和 TLS 握手 是兩件不同的事, TCP 先完成才開始 TLS。

憑證資訊

subject: CN=example.com        # certificate issued for this domain
issuer: Google Trust Services  # certificate authority
expire date: ...               # expiry date (auto-renewed by Cloudflare)

DevOps 連結

憑證到期 → 服務掛掉, 是常見的 incident
curl -v 是排查 TLS 問題的基本工具
Ingress Controller 做 TLS termination, 憑證設定在 Ingress 上, 後端 Pod 接收 plain HTTP

Reverse Proxy vs Forward Proxy

Forward Proxy

Client -> Proxy Server -> Target Website

代理客戶端對外的請求。目標網站看到 Proxy 的 IP, 不是你的 IP。

常見用途: 公司內網管控、VPN、隱藏真實 IP。Windows Network Manager 和瀏覽器設定的就是這個。

Reverse Proxy

Client -> Reverse Proxy -> Your Server

代理伺服器接收請求。用戶看到 Proxy 的 IP, 不是伺服器的真實 IP。

常見用途: Cloudflare、Nginx、K8s Ingress Controller。

記法:

Forward Proxy = 幫客戶端出去
Reverse Proxy = 幫伺服器接進來

Nginx 的雙重角色

Nginx 同時可以是:

Web Server: 直接提供 HTML/CSS/圖片
Reverse Proxy: 把請求轉發給後端應用程式

K8s 的 Nginx Ingress Controller 是第二種用法。

Load Balancer

為什麼需要 Load Balancer

單一伺服器處理不了大量流量時, 需要跑多個 Pod。Load Balancer 站在前面, 把請求分散到後面的 Pod。

L4 vs L7

	L4 Load Balancer	L7 Load Balancer
運作層	Transport (TCP/UDP)	Application (HTTP)
看得到	IP + Port	URL, Headers, Cookies
路由依據	IP/Port	URL path, hostname, cookie
速度	快 (封包檢查少)	較慢 (需解析 HTTP)
適合	WebSocket, 持久連線	HTTP API, path-based routing

K8s 對應:

ClusterIP Service ≈ L4 (TCP 轉發, 不看 HTTP 內容)
Ingress ≈ L7 (根據 URL 路由, 由 Traefik 或 Nginx 實作)

Load Balancing 演算法

Round Robin: 依序輪流

request 1 -> Pod 1
request 2 -> Pod 2
request 3 -> Pod 3
request 4 -> Pod 1  # back to the first

適合: 請求處理時間相近的 REST API。LB 幾乎不需要額外計算, 效能最高。

Least Connections: 發給目前連線數最少的 Pod

Pod 1: 100 connections
Pod 2:  20 connections  # next request goes here
Pod 3:  80 connections

適合: 請求處理時間差異大的服務 (如影片轉檔)。代價是 LB 需要持續追蹤每個 Pod 的連線數, 高流量下 LB 本身有額外負擔。

IP Hash: 同一個 IP 永遠打到同一台 Pod

適合: 需要 sticky session 的舊系統 (session 存在特定 server 記憶體裡)。現代系統通常把 session 存 Redis, 不需要 IP Hash。

K8s Ingress vs Ingress Controller

Ingress 分兩層:

Ingress Resource (YAML) = 路由規格, 本身不執行任何事

rules:
  - path: /api
    backend: go-api-service
  - path: /web
    backend: frontend-service

Ingress Controller = 真正執行路由的程式, 需要另外安裝或由雲端提供

Ingress Controller	說明
Nginx Ingress Controller	最普遍, 自己安裝
Traefik	k3s 預設內建
GKE Ingress	GKE 預設, 用 Google Cloud LB
AGIC	AKS 選項, 用 Azure App Gateway

kubectl get svc -n kube-system  # check installed ingress controller
kubectl get ingress -A          # check routing rules

WebSocket 與 L4 LB 的關係

HTTP vs WebSocket

HTTP 是請求-回應模型, 每個請求獨立, 伺服器無法主動推資料。

WebSocket 建立一次連線後持續保持, 伺服器可以隨時主動推資料給客戶端。

HTTP (polling):
Client -> Server: "any new messages?"
Server -> Client: "no"
Client -> Server: "any new messages?"
Server -> Client: "yes, here it is"

WebSocket:
Client <-> Server: (connection established, kept open)
Server -> Client: "new message!"
Server -> Client: "another message!"

為什麼 WebSocket 需要 L4

L7 LB 可能把同一個用戶的不同封包發到不同 Pod, 導致 WebSocket session 斷裂。

L4 LB 在 TCP 層運作, 建立連線後整個 session 黏在同一台 Pod, WebSocket 正常運作。

適合 WebSocket 的情境

即時客服對話框
線上遊戲
股票即時報價
IoT 設備控制 (如智慧插座, 燈泡)

Linux CLI 補充

stderr, stdout, 重新導向

0 = stdin   (input)
1 = stdout  (normal output)
2 = stderr  (error output)

command > file.log        # redirect stdout to file
command 2>/dev/null       # discard stderr
command 2>&1              # merge stderr into stdout
command > file.log 2>&1   # redirect both stdout and stderr to file

| head -40 只截斷進入 pipe 的 stdout。stderr 不進 pipe, 所以不受 head 限制。加上 2>&1 才能讓 head 同時截斷兩者。

常用網路診斷工具

工具	用途
`dig` / `nslookup`	DNS 查詢, 排查 domain 解析問題
`curl -v`	HTTP/HTTPS 測試, 看 TLS 憑證和 headers
`ping`	測試基本連通性
`traceroute`	看封包走哪條路徑
`netstat` / `ss`	看目前的連線狀態

References

Kubernetes 故障模擬: OOMKilled、Probe、ConfigMap 與 Namespace

louChang.tw@gmail.com (Lou Chang) — Thu, 02 Apr 2026 20:00:00 -0400

DevOps 學習筆記

承接前兩篇 (K8s 核心架構、Service/HPA/Debug), 這篇深入 K8s 故障場景的實際行為, 加上 ConfigMap、Secret、Namespace 的用法目標是能預測和診斷問題, 而不只是會 apply YAML

環境: k3s v1.34 single node cluster + go-api (Go HTTP server, scratch image)

OOMKilled — Container 被 Kernel 殺掉

什麼是 OOMKilled

Container 的記憶體用量超過 limits.memory 設定的上限, Linux kernel 的 OOM killer 直接把 process 殺掉

不是 K8s 殺的, 是 kernel 殺的 K8s 只是觀察到 container 死了, 紀錄原因

實驗

在 go-api 加一個 /oom endpoint, 瘋狂配置記憶體:

func OOM(w http.ResponseWriter, r *http.Request) {
    log.Println("oom endpoint hit, allocating memory until killed")
    var data [][]byte
    for {
        block := make([]byte, 10*1024*1024) // 10MB per iteration
        data = append(data, block)
        log.Printf("allocated %d MB", len(data)*10)
    }
}

Deployment 設定 memory limit 為 64Mi:

resources:
  requests:
    memory: 32Mi
  limits:
    memory: 64Mi

用 curl 打 /oom, 連線直接斷掉 — container 被殺了, 所以 connection 中斷

觀察結果

kubectl describe pod <pod-name>

Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137

欄位	值	意義
Reason	OOMKilled	超過 memory limit, 被 OOM killer 終止
Exit Code	137	128 + 9 = SIGKILL, 不是程式自己退出, 是被外力殺掉的
RESTARTS	增加	K8s 自動重啟了 container

重啟後因為 /oom 沒有再被打, Pod 穩定下來但如果 container 啟動就 OOM (比如 init 時就吃太多記憶體), 就會不斷重啟, 最終進入 CrashLoopBackOff

OOMKilled vs CrashLoopBackOff

這兩個常常搞混, 但它們不是同一個層級:

OOMKilled 是原因 — 記憶體超標被殺
CrashLoopBackOff 是狀態 — container 反覆 crash, K8s 拉長重啟間隔 (指數退避: 10s → 20s → 40s → … 最多 5 分鐘)

一個 container 可以因為 OOMKilled 而進入 CrashLoopBackOff, 也可以因為其他原因 (程式碼 bug、設定錯誤) 進入 CrashLoopBackOff

requests vs limits — 兩個完全不同的東西

resources:
  requests:
    memory: 32Mi    # used by Scheduler
  limits:
    memory: 64Mi    # runtime hard cap

requests — 「我至少需要這麼多」

Scheduler 用 requests 決定 Pod 放到哪個 Node 如果 Node 剩餘可分配資源 < Pod 的 requests, Scheduler 就不會把 Pod 排到那個 Node, Pod 狀態會是 Pending

limits — 「最多只能用這麼多」

Container 實際執行時的硬上限超過就被 OOM kill

關鍵差異

	requests	limits
誰看	Scheduler	Kernel (cgroup)
什麼時候看	排程時	執行時
超過會怎樣	Pod Pending (排不上去)	OOMKilled (被殺掉)

實驗: ResourceQuota 模擬資源不足

因為本機 k3s node 有 39GB 記憶體, 用小小的 requests 根本排不滿改用 ResourceQuota 在 namespace 層級限制:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: small-quota
  namespace: resource-test
spec:
  hard:
    requests.memory: 100Mi
    limits.memory: 200Mi

Deploy 4 個 Pod, 各 requests 32Mi (4 × 32Mi = 128Mi > quota 100Mi):

Warning  FailedCreate  replicaset/go-api-hungry-xxx
  Error creating: pods "..." is forbidden:
  exceeded quota: small-quota,
  requested: requests.memory=32Mi,
  used: requests.memory=96Mi,
  limited: requests.memory=100Mi

3 個 Pod 成功, 第 4 個被擋注意這裡和真正的 Node 資源不足不同:

情境	錯誤來源	Pod 狀態	Event
ResourceQuota 超過	API server 直接拒絕	Pod 不存在	FailedCreate on ReplicaSet
Node 資源不足	Scheduler 找不到合適 Node	Pending	FailedScheduling on Pod

Probe — K8s 怎麼知道你的 App 是不是正常的

Container 在跑不代表 app 正常 — 可能 deadlock 了, 可能 database 斷了 K8s 需要一個方法去確認

Probe 就是 K8s 定期打你指定的 endpoint, 看 HTTP status code:

200 → 正常
非 200 → 有問題

兩種 Probe 的差別

	Readiness Probe	Liveness Probe
問的問題	「你準備好接流量了嗎?」	「你還活著嗎?」
失敗後果	從 Service 移除, 不送流量	砍掉 container, 重啟
Pod 還在嗎	在, 只是不接客	container 被殺, 重新啟動
用途	啟動中、暫時忙碌、依賴斷了	真的卡死了, 需要重啟才能救

用餐廳比喻:

Readiness = 「廚房準備好了嗎?」→ 沒好就先不帶客人進來, 但廚房還在
Liveness = 「廚師還有呼吸嗎?」→ 沒有就換一個廚師 (重啟)

設定方式

在 container spec 裡用不同的 key 名稱:

containers:
  - name: go-api
    image: go-api:0.0.5
    readinessProbe:         # ← this key makes it a readiness probe
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 2
      periodSeconds: 5
    livenessProbe:          # ← this key makes it a liveness probe
      httpGet:
        path: /alive
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 3
      failureThreshold: 3   # 3 consecutive failures = dead

可以同時設兩個, 也可以指向同一個 endpoint Production 裡通常分開: readiness 檢查比較多 (database、cache), liveness 只檢查 app 本身有沒有卡死

Readiness Probe 實驗

設定 readiness probe 指向不存在的 /ready endpoint, probe 每 5 秒打一次都拿到 404:

kubectl get pods -l app=go-api-probe-test

NAME                                 READY   STATUS    RESTARTS   AGE
go-api-probe-test-86cd4c5787-7lmrj   0/1     Running   0          39s
go-api-probe-test-86cd4c5787-mtxl2   0/1     Running   0          39s

READY 是 0/1 — container 在跑, 但 K8s 認定沒準備好

kubectl describe pod <pod-name>

Conditions:
  Ready       False

檢查 EndpointSlice:

kubectl get endpointslice -l kubernetes.io/service-name=go-api-probe-test

EndpointSlice 會列出所有 address, 但每個 address 標記 ready: false Service 不會送流量到 ready: false 的 Pod

注意: K8s v1.33+ 開始 kubectl get endpoints 會出 deprecation warning, 改用 kubectl get endpointslice -l kubernetes.io/service-name=<svc> 查

Liveness Probe 實驗

設定 liveness probe 指向不存在的 /alive endpoint, 每 3 秒失敗一次, 連續 3 次後 K8s 殺掉 container:

kubectl get pods -l app=go-api-liveness-test -w

NAME                                   READY   STATUS             RESTARTS     AGE
go-api-liveness-test-95bb8f89c-7qn85   1/1     Running            3 (8s ago)   45s
go-api-liveness-test-95bb8f89c-7qn85   0/1     CrashLoopBackOff   3 (0s ago)   49s
go-api-liveness-test-95bb8f89c-7qn85   1/1     Running            4 (29s ago)  78s
go-api-liveness-test-95bb8f89c-7qn85   0/1     CrashLoopBackOff   4 (0s ago)   88s

和 readiness 完全不同 — RESTARTS 不斷增加, container 被殺了又重啟, 最終進入 CrashLoopBackOff

什麼時候用哪個 — 常見錯誤

一個常見的錯誤: 用 liveness probe 檢查 database 連線 如果 database 掛了, liveness 失敗 → K8s 重啟你的 app → app 起來後 database 還是掛著 → 又 liveness 失敗 → 無限重啟

正確做法: database 連線放 readiness probe database 掛了, readiness 失敗, Pod 只是暫時不接流量, 等 database 恢復就自動回來, 不需要重啟

ConfigMap 與 Secret

解決什麼問題

App 需要設定值 (環境、log level、DB 密碼) 如果寫死在 code 裡, 改設定就要重新 build image, 不同環境 (dev/staging/prod) 要不同 image

ConfigMap 和 Secret 把設定從 image 抽出來, 同一個 image 在不同環境只換設定

ConfigMap — 非敏感設定

一個 key-value 的設定檔, 存在 K8s 裡:

apiVersion: v1
kind: ConfigMap
metadata:
  name: go-api-config
data:
  APP_ENV: "staging"
  LOG_LEVEL: "debug"

Secret — 敏感資料

和 ConfigMap 幾乎一樣, 但用來放密碼、API key:

apiVersion: v1
kind: Secret
metadata:
  name: go-api-secret
type: Opaque
stringData:
  DB_PASSWORD: "my-secret-password-123"

type: Opaque 是 Secret 的類型, 表示「一般用途的 secret」 90% 的情況用 Opaque

其他內建類型:

type	用途
Opaque	通用, 自己定義 key/value (最常用)
kubernetes.io/tls	TLS 憑證 (必須有 tls.crt 和 tls.key)
kubernetes.io/dockerconfigjson	Docker registry 登入帳密

注入 — 把值傳進 Container

Container 本身只認兩種東西: 環境變數和檔案需要把 ConfigMap / Secret 的值變成 container 讀得到的格式

方式一 — 環境變數:

containers:
  - name: go-api
    envFrom:
      - configMapRef:
          name: go-api-config    # all keys become env vars
    env:
      - name: DB_PASSWORD
        valueFrom:
          secretKeyRef:
            name: go-api-secret
            key: DB_PASSWORD     # pick a specific key from Secret

envFrom 把整個 ConfigMap 攤開, valueFrom 從 Secret 挑單一個 key

方式二 — 掛成檔案 (volume mount):

volumes:
  - name: config
    configMap:
      name: go-api-config
volumeMounts:
  - name: config
    mountPath: /etc/config

Container 裡會有 /etc/config/APP_ENV 這個檔案, 內容是 staging 適合設定檔比較大的情況 (例如 nginx.conf)

實驗結果

Go code 用 os.Getenv 讀取:

kubectl logs -l app=go-api-config-test

2026/04/02 23:17:11 env=staging log_level=debug db_configured=true

三個值都成功注入

K8s Secret 安全嗎

K8s Secret 預設只是 base64 編碼, 不是加密 任何有 kubectl 權限的人都能:

kubectl get secret go-api-secret -o yaml
# base64 encoded, decode = plaintext

Production 裡不會直接把密碼寫在 Secret YAML 然後 commit 到 git 實際做法:

External Secret Manager (GCP Secret Manager / Vault / AWS Secrets Manager)
         ↓ (synced by tooling, not manual)
    K8s Secret object
         ↓ (envFrom / valueFrom)
    Container env vars

中間同步的「工具」通常是:

External Secrets Operator — 裝在 K8s 裡, 定期從外部 secret manager 同步到 K8s Secret
CI/CD pipeline — deploy 時用 kubectl create secret 建出來
Terraform — 用 kubernetes_secret resource 建出來

K8s Secret 是外部 secret manager 和 container 之間的橋樑 — container 不會直接呼叫 GCP Secret Manager API, 它只從 K8s Secret 讀環境變數

如果用 GCP Cloud Run (不是 K8s), 則不需要這層橋樑 — Cloud Run 可以直接從 GCP Secret Manager 注入環境變數

Namespace — Cluster 裡的隔離區域

什麼是 Namespace

想像一個 cluster 是一棟辦公大樓:

Namespace = 樓層 — 每個樓層有自己的房間 (Pod)、服務 (Service)、設定 (ConfigMap)
不同樓層可以有一樣名字的房間, 互不衝突
但大樓的電梯 (Node)、停車場 (Storage) 是共用的
預設樓層之間的走廊是通的 (網路互通)

不是 .NET 那種 code 組織用的 namespace, 也不是 Linux kernel 的 namespace (process 隔離) K8s Namespace 是資源的邏輯分群

用途

cluster
├── namespace: dev        ← development
├── namespace: staging    ← testing
├── namespace: prod       ← production
└── namespace: default    ← default, used when no namespace specified

什麼隔離, 什麼不隔離

Namespace 各自獨立的:

Pod、Deployment、Service、ConfigMap、Secret — 名字可以重複, 互不干擾
ResourceQuota — 可以對不同 namespace 設不同資源配額
RBAC 權限 — 可以限制某人只能操作某個 namespace (RBAC = Role-Based Access Control, 用角色控制誰能做什麼)

整個 Cluster 共用的:

Node — 所有 namespace 的 Pod 都跑在同一批機器上
Storage (PersistentVolume)
網路 — 預設跨 namespace 可以互通, 要擋要另外設 NetworkPolicy

跨 Namespace 網路互通實驗

建立 dev 和 staging namespace, 各自部署 go-api 和 Service (名字都叫 go-api, 不衝突)

從 dev 的 Pod 打 staging 的 Service:

# run a Pod with curl in dev namespace
kubectl run test-curl -n dev --image=curlimages/curl -- sleep 3600

# from dev, call staging service
kubectl exec -n dev test-curl -- curl -s http://go-api.staging.svc.cluster.local/healthz

{"status":"ok","version":"0.0.4"}

成功拿到回應, 證明跨 namespace 網路預設是通的

K8s 內部的 DNS 規則: <service-name>.<namespace>.svc.cluster.local 同 namespace 內可以省略, 直接用 service name

注意: scratch image 裡面沒有任何工具 (連 wget、curl、sh 都沒有), 所以不能 kubectl exec 進去 debug 需要另外跑一個有工具的 Pod 來測

必須記住的東西

故障診斷對照表

現象	原因	怎麼查
OOMKilled (exit code 137)	超過 memory limit	`kubectl describe pod` 看 Last State
CrashLoopBackOff	Container 反覆 crash	`kubectl logs --previous` 看上次的 log
Pending	Node 資源不足或 Scheduler 排不上	`kubectl describe pod` 看 Events
FailedCreate	ResourceQuota 超標	`kubectl get events` 看 ReplicaSet event
READY 0/1 但 Running	Readiness probe 失敗	`kubectl describe pod` 看 Conditions
RESTARTS 不斷增加	Liveness probe 失敗或 app crash	`kubectl describe pod` 看 probe 設定

Probe 選擇原則

檢查 app 本身卡死 → liveness (重啟能救)
檢查外部依賴 (DB、cache) → readiness (重啟沒用, 等依賴恢復就好)
不確定的時候 → 先用 readiness, 比 liveness 安全

requests vs limits 一句話

requests = Scheduler 排程用, 「我至少需要這麼多才能被排到 Node 上」
limits = Runtime 上限, 「超過這麼多就被殺」

References

Kubernetes Documentation — Container Resources — requests 與 limits 的完整說明
Kubernetes Documentation — Pod Lifecycle — Pod 狀態與 restart policy
Kubernetes Documentation — Liveness, Readiness and Startup Probes — 三種 probe 的設定與差異
Kubernetes Documentation — ConfigMaps — ConfigMap 的建立與使用方式
Kubernetes Documentation — Secrets — Secret 類型、建立、注入方式
Kubernetes Documentation — Namespaces — Namespace 的用途與隔離邊界
Kubernetes Documentation — Resource Quotas — 用 ResourceQuota 限制 namespace 資源用量
Kubernetes Documentation — DNS for Services and Pods — 跨 namespace 的 DNS 規則
Kubernetes Documentation — EndpointSlice — EndpointSlice 取代舊版 Endpoints

Lou Stack Base

把同一個工具同時做成 CLI 和 MCP 之後, 我學到的事

什麼是 CLI

CLI 怎麼運作

CLI layer 要怎麼設計

什麼是 MCP

MCP 怎麼運作

MCP layer 要怎麼設計

為什麼 CLI 和 MCP 要共用同一個 core workflow

content-i18n 的 core boundary

MCP tool surface 要怎麼設計

Queue state 怎麼運作

Failure modes 和最後規則

CLI / MCP drift

Wrapper logic leak

Low-level tool bypass

Fuzzy completion

Duplicated state logic

References

從即時翻譯到真正的英文內容, 為什麼做 content-i18n

問題不是翻得更快

Fidelity-first 的意思

即時翻譯不夠的地方

Workflow 設計

prepare

write target

review

sync-status

Queue state

Completion rule

為什麼做成 standalone tool

最後整理

References

ArgoCD GitOps 實作：從安裝到完整 CD 流程

Push-based vs Pull-based CD

ArgoCD 架構

安裝 ArgoCD

k8s 目錄結構設計

Application Manifest as Code

imagePullSecret：讓 k3s pull Artifact Registry

完整 GitOps 流程

GKE vs k3s

References

GitHub Actions 進階：Path Filter、Concurrency、Cache 與 GitOps 自動更新

Trigger 設計

Path Filter：只在相關檔案變動時觸發

if 條件：控制 Job 和 Step 執行

Concurrency：防止同時跑多個 Deploy

Go Module Cache：加速 CI

ENV_TAG：環境感知的 Image Tag

SHORT_SHA：跨 Step 共用變數

GitOps 自動更新 deployment.yaml

Image Tagging：git SHA vs Semver

Jenkins vs GitHub Actions

CircleCI 對比

References

Terraform Bootstrap 層設計: WIF、Artifact Registry 與 GitHub Actions CI/CD

Bootstrap 層 vs Environment 層

WIF 的信任鏈

Terraform 設定

需要啟用的 GCP API

Service Account 與最小權限

WIF Pool 與 Provider

SA Impersonation Binding

Outputs

GitHub Actions Workflow

Arguments vs Attributes

References

System Design 核心：Redis、Rate Limiting、Circuit Breaker 與 Scaling 策略

Redis

為什麼需要 Redis

五種資料結構

七個使用場景

Hot Key 問題

三種部署模式

Rate Limiting

四種演算法

分散式 Rate Limiting

Circuit Breaker

為什麼需要 Circuit Breaker

`content-i18n` 的 core boundary

`if` 條件：控制 Job 和 Step 執行