Ops Notes：實戰踩坑筆記
這個目錄的軸是**「實戰踩坑」**。每篇文章格式：
症狀（見到什麼錯）
↓
診斷（排除什麼、怎麼找到問題）
↓
原因（真正的根因）
↓
修法（commit 連結）
↓
可推廣教訓
跟教學類文章不同軸：
infra/ = 系統原理教學（網路/TLS/container/CI/CD 怎麼運作）ops-notes/（本目錄）= 實戰踩過什麼坑、怎麼修的process/04-incident-management = 事件處理流程方法論（不是具體案例）case-studies/ = 拆解別人家系統（不是自己踩的坑）
資料來源
主要取自 proto/infra 專案真實 commit 歷史：
C:/Users/home/work/proto/infra/micro-service/ （微服務壓測平台）C:/Users/home/work/proto/infra/gitlab/C:/Users/home/work/proto/infra/monitor/
未來其他專案（quartz-blog GitHub Actions、K8s 壓測平台、本機 Docker 環境）的坑也可進來。
Stage：🌱 seed（還沒寫） / 🌿 growing / 🌳 mature
子目錄規劃（5+ 案例的主題群預先開）
每個 O 主題群有 3~8 案例。案例數 ≥ 5 的群，按 skill「預先開子目錄」規則，寫第一篇就建子目錄：
| 主題群 | 案例數 | 子目錄路徑 |
|---|
| O01 K8s 部署阻斷 | 5 | ops-notes/k8s-deploy/ |
| O02 Kong Gateway | 8 | ops-notes/kong/ |
| O03 Ingress 路由 | 5 | ops-notes/ingress/ |
| O04 Docker / Registry | 5 | ops-notes/docker/ |
| O05 Probe 健康檢查 | 4 | 先扁平（未達 5） |
| O06 Env / Secret | 5 | ops-notes/env-secret/ |
| O07 CI/CD | 5 | ops-notes/cicd/ |
| O08 資源限制可靠性 | 4 | 先扁平 |
| O09 可觀測性 | 5 | ops-notes/observability/ |
| O10 前端部署坑 | 3 | 先扁平 |
| O11 Submodule | 4 | 先扁平 |
| O12 壓測調校 | 3 | 先扁平 |
案例數 < 5 的群先扁平，累積到 5 再搬進子目錄。
O01 K8s 部署阻斷排除
部署上不去、Pod 起不來、Service 連不通的系列。
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | PVC 名稱與 NetworkPolicy 缺漏 | P0 部署阻斷 | 3a99526 | 🌱 |
| 02 | SecurityContext、Migration Job、Loki config | 部署驗證失敗 | 3bc972c | 🌱 |
| 03 | Init Container resources 不足 | Migration 跑不起來 | ef48204 | 🌱 |
| 04 | emptyDir 沒設 sizeLimit + hostPath 沒驗證 type | 安全性問題 | 8f5b610 | 🌱 |
| 05 | RabbitMQ SecurityContext 過嚴 | 寫入權限錯誤 | 72145bc | 🌱 |
O02 Kong Gateway 實戰坑
→ 子目錄：kong
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Kong ConfigMap YAML 縮進錯誤 | kustomize build 失敗 | 1367e7b | yaml-indent 🌿 |
| 02 | Kong RSA Key 縮排 + YAML block scalar | JWT plugin 載入失敗 | f422f66 | 🌱 |
| 03 | Kong ConfigMap 被 kustomize 覆蓋為 placeholder | 路由失效 | a3ec1e9 | 🌱 |
| 04 | Kong Sandbox 不允許 cjson | post-function 失敗 | 50fdb56 | 🌱 |
| 05 | Kong ConfigMap Big5/ISO-8859 編碼 | 載入失敗 | c4b5083 | 🌱 |
| 06 | Kong 健康路由 + CORS origin 設定 | NodePort 連不通 | deb0ec7 | 🌱 |
| 07 | Kong public key injection | JWT 驗證失敗 | b9469f7 | 🌱 |
| 08 | Kong Metrics Port 與 Prometheus scrape | 指標收不到 | 4ce0436 | 🌱 |
O03 Ingress 與路由
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Ingress 綁 host 導致 OrbStack / IP 直連失敗 | 無法直接 IP 連 | ab1eb5f | 🌱 |
| 02 | Ingress SSL redirect 先關閉（TLS 未備） | 連線迴圈 | a1dece6 | 🌱 |
| 03 | Host-based routing + proxy-redirect | backstage 路由錯 | 1e312da | 🌱 |
| 04 | backstage SPA base path 修正 | 靜態資源 404 | aa656e8 | 🌱 |
| 05 | frontstage SSR healthcheck 調整 | liveness probe 失敗 | 7000cab | 🌱 |
O04 Docker / Registry 問題
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | 地端 Registry imagePullPolicy IfNotPresent | 拉不到 image | 10f6682 | 🌱 |
| 02 | Migration Job image source 改地端 | CI 失敗 | d0b538c | 🌱 |
| 03 | DinD insecure registry + TLS 關閉 | Docker login 失敗 | c252a03 | 🌱 |
| 04 | Frontend Docker build：.dockerignore + env schema | build 時爆 | 2d22aa6 | 🌱 |
| 05 | Wait for DinD daemon before docker login | 時序 race | 175a612 | 🌱 |
O05 Probe 與健康檢查
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Fluent-bit HTTP server 沒啟用 | liveness probe 失敗 | 760d9c4 | 🌱 |
| 02 | Smoke test 改用 busybox pod | kubectl exec 失敗 | 7ff47cf | 🌱 |
| 03 | Health check 路由修正 | /api/health 錯路徑 | 0cb095f | 🌱 |
| 04 | FE startupProbe + Ingress TLS 預備 | 啟動時探測過早 | af0b7b4 | 🌱 |
O06 Env / Secret 管理
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Redis 密碼 $$ 跳脫（Docker Compose 提前展開） | 密碼變空 | 419ed88 | 🌱 |
| 02 | env 檔案 .env 與 .example 對齊 | 欄位漏掉 | 08e41fd | 🌱 |
| 03 | env_file 管理（移除 environment） | secret 洩漏風險 | dd9db1f | 🌱 |
| 04 | SecretGenerator + Staging Overlay | 環境隔離 | df802e1 | 🌱 |
| 05 | CI variables 注入 secrets | 不走 file | 4ec506b | 🌱 |
O07 CI/CD Pipeline
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Typo bse64 → base64 in rollback stage | rollback 失敗 | d0d93a6 | 🌱 |
| 02 | 地端 CI/CD 適配：lint + deploy | GitLab runner 設定 | 4ec506b | 🌱 |
| 03 | Blue-green deploy + —no-switch 選項 | 切換控制 | 66ed6dc | 🌱 |
| 04 | 藍綠部署腳本自動化 | 人工切換風險 | 642573e | 🌱 |
| 05 | Discord 部署通知 | 無法得知部署狀態 | 98a5281 | 🌱 |
O08 資源限制與可靠性
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | HPA / PDB 設計（auth-service stress test） | 擴容不及 | 3fc8ba8 | 🌱 |
| 02 | Resource requests + DB pool 壓測調校 | OOM / 連線 timeout | cf96a90 | 🌱 |
| 03 | Migration TTL 設定 | Job 殘留 | ef48204 | 🌱 |
| 04 | FE HPA/PDB + Kong HPA | 流量波動應對 | e307265 | 🌱 |
O09 可觀測性修補
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | Prometheus scrape + NP port 限制 | 指標丟失 | 4ce0436 | 🌱 |
| 02 | Grafana 穩定性 + PVC 註解 | 重啟資料丟失 | 2ba4871 | 🌱 |
| 03 | Kong Prometheus plugin + Grafana dashboards | 缺 Kong 儀表板 | 5dd4456 | 🌱 |
| 04 | OTEL env vars 注入 backend | trace 不完整 | ec61ede | 🌱 |
| 05 | fluent-bit RBAC 加固 | 日誌收集缺權限 | eb59114 | 🌱 |
O10 前端部署坑
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | SPA base path 修正 | 資源 404 | aa656e8 | 🌱 |
| 02 | SSR healthcheck 調整 | probe 失敗 | 7000cab | 🌱 |
| 03 | .dockerignore + env schema 對齊 | build 時 env 缺 | 2d22aa6 | 🌱 |
O11 Submodule 與多 repo 協作
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | auth-service 從 tracked files 改 submodule | 單 repo 太大 | 5f80b21 | 🌱 |
| 02 | switch-gitlab.sh 切換 remote | 本機 / 雲端 GitLab 切換 | 5f80b21 | 🌱 |
| 03 | Submodule 同步時機 | 主 repo / sub repo 版本錯 | dbde1b9 | 🌱 |
| 04 | b2e/f2e 前綴命名統一 | submodule 命名衝突 | 5f5c2e1 | 🌱 |
O12 壓測驅動的調校
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | HPA/PDB 調整（壓測 MS.2/MS.5/MS.8） | 負載下 scale 不夠 | 3fc8ba8 | 🌱 |
| 02 | Resource requests / DB pool tune | 壓測發現瓶頸 | cf96a90 | 🌱 |
| 03 | Rate limit 調高（k6 壓測） | 壓測自己 rate limit 被擋 | e97c980 | 🌱 |
寫作流程
每篇 ops-note 的標準模板：
---
title: "..."
tags: [ops-notes, k8s, kong, ...]
description: "..."
date: YYYY-MM-DD
severity: P0 / P1 / P2
time-to-fix: X hours / days
commits: [sha1, sha2]
---
# 症狀
（錯誤訊息、觀察到的現象）
# 診斷
（我試過什麼、排除了什麼）
# 原因
（真正的根因）
# 修法
（commit 連結 + diff 摘要）
# 可推廣教訓
（這類問題以後怎麼避免）
進度統計
- 主題群：12（O01~O12）
- 案例總數：約 55
- 全部 🌱（等待從 commit 萃取內容）
- 🌳 mature：0
下一步
- 先從 O01（K8s 部署阻斷）、O02（Kong 坑）開始，這兩類最多人會踩
- 每篇以「症狀驅動」寫，讓 Google 搜尋症狀時能找到
- 抽離真實 commit 內容，去敏感化（密碼、internal URL 等）