Ops Notes 系列 Roadmap
計畫文件，不會被 Quartz 渲染（無 frontmatter）。案例計畫 + 子目錄規劃 + 寫作流程都在這。
公開頁 → ops-notes/index.md
系列定位
實戰踩坑筆記——不是教學，是「我踩過這個坑，症狀 / 診斷 / 根因 / 修法」的原始紀錄。主要資料來源是 proto/infra 專案真實 commit 歷史，未來吸收其他專案（quartz-blog、AI 工具、K8s 壓測平台）的踩坑。
跟 backend / infra / management 的分工：
| 系列 | 軸 |
|---|
| ops-notes/（本系列） | 事件：真實踩坑案例（症狀驅動） |
| infra/ | 設施：平台建立與運維設計 |
| management/engineering-process/ | 流程：事件處理方法論 / 事故管理 |
| case-studies/ | 案例：拆別人家的系統（不是自己踩的） |
三層切法：
- 方法論（how to think）→
management/engineering-process/04-incident-management/
- 平台設計（how the platform works）→
infra/
- 具體事件（what happened to me）→ 本系列
每篇 ops-note 的標準模板
症狀（見到什麼錯）
↓
診斷（排除什麼、怎麼找到問題）
↓
原因（真正的根因）
↓
修法（commit 連結）
↓
可推廣教訓
Frontmatter：
---
title: "..."
tags: [ops-notes, k8s, kong, ...]
description: "..."
date: YYYY-MM-DD
severity: P0 / P1 / P2
time-to-fix: X hours / days
commits: [sha1, sha2]
---
資料來源
C:/Users/home/work/proto/infra/micro-service/ （微服務壓測平台）C:/Users/home/work/proto/infra/gitlab/C:/Users/home/work/proto/infra/monitor/C:/Users/home/work/prd/quartz-blog/ （本部落格的踩坑）C:/Users/home/work/tools/openclaw/ （AI Agent 平台）- 未來的新專案
主題群規劃（15 群）
Stage：🌱 seed（還沒寫）/ 🌿 growing / 🌳 mature
案例數 ≥ 5 的群 → 預先開子目錄（寫第一篇就建，避免後面搬）。
| 主題群 | 案例數 | 子目錄路徑 | 狀態 |
|---|
| O01 K8s 部署阻斷 | 5 | ops-notes/k8s-deploy/ | ✅ 已預開 |
| O02 Kong Gateway | 8 | infra/gateway-mesh/kong/ | ✅ 已在 I02 章 |
| O03 Ingress 路由 | 5 | ops-notes/ingress/ | ✅ 已預開 |
| O04 Docker / Registry | 5 | ops-notes/docker/ | ✅ 已預開 |
| O05 Probe 健康檢查 | 4 | 先扁平 | — |
| O06 Env / Secret | 5 | ops-notes/env-secret/ | ✅ 已預開 |
| O07 CI/CD Pipeline | 5 | ops-notes/cicd/ | ✅ 已預開 |
| O08 資源限制可靠性 | 4 | 先扁平 | — |
| O09 可觀測性 | 5 | ops-notes/observability/ | ✅ 已預開 |
| O10 前端部署坑 | 3 | 先扁平 | — |
| O11 Submodule | 4 | 先扁平 | — |
| O12 壓測調校 | 3 | 先扁平 | — |
| O13 Meta / 方法論 | 4 | 先扁平 | 吸收自 I10 |
| O14 AI 工具踩坑 | 估 6 | ops-notes/ai-tools/ | ✅ 已預開（新增） |
| O15 Blog / 部落格部署 | 估 5 | ops-notes/blog-deploy/ | ✅ 已預開（新增） |
案例總數：約 71（56 既有 + 15 新增 O14/O15 + 4 方法論）
主題群詳細清單
O01 K8s 部署阻斷排除（5 案例）
部署上不去、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 實戰坑（8 案例）
注意：Kong 案例歸到 infra/gateway-mesh/kong/ 子目錄（Kong 身份是 Gateway，不是純 ops 分類）。
| # | 案例 | 症狀 | 來源 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 與路由（5 案例）
| # | 案例 | 症狀 | 來源 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 問題（5 案例）
| # | 案例 | 症狀 | 來源 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 與健康檢查（4 案例，先扁平）
| # | 案例 | 症狀 | 來源 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 管理（5 案例）
| # | 案例 | 症狀 | 來源 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（5 案例）
| # | 案例 | 症狀 | 來源 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 資源限制與可靠性（4 案例，先扁平）
| # | 案例 | 症狀 | 來源 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 可觀測性修補（5 案例）
| # | 案例 | 症狀 | 來源 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 前端部署坑（3 案例，先扁平）
| # | 案例 | 症狀 | 來源 commit | stage |
|---|
| 01 | SPA base path 修正 | 資源 404 | aa656e8 | 🌱 |
| 02 | SSR healthcheck 調整 | probe 失敗 | 7000cab | 🌱 |
| 03 | .dockerignore + env schema 對齊 | build 時 env 缺 | 2d22aa6 | 🌱 |
O11 Submodule 與多 repo 協作（4 案例，先扁平）
| # | 案例 | 症狀 | 來源 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 壓測驅動的調校（3 案例，先扁平）
| # | 案例 | 症狀 | 來源 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 | 🌱 |
跟 O01-O12 案例軸不同：O01-O12 是「踩過什麼」，O13 是「怎麼系統化處理這類問題」。
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 01 | 為什麼需要 Runbook 系統 | o13-why-runbook-system | 🌱 | Tribal knowledge 散落在人腦；on-call 半夜 page 沒 context；Runbook 是機構記憶 |
| 02 | Runbook 系統設計 | o13-runbook-system-design | 🌱 | 跟 alert 綁定；template 設計；git-based vs wiki vs Backstage TechDocs；怎麼避免 Runbook 過時 |
| 03 | K8s Troubleshooting 方法論 | o13-k8s-troubleshooting-methodology | 🌱 | Pod stuck Pending / CrashLoopBackOff / OOMKilled / ImagePullBackOff 的系統化診斷流程；具體案例見 O01 |
| 04 | K8s / Helm Upgrade 策略 | o13-upgrade-strategy | 🌱 | 跨 version 升級計畫；破壞性變更對策；rollback 流程；跟 infra/k8s/07-k8s-troubleshooting 連動 |
O14 AI 工具踩坑（新增，估 6 案例）
資料來源：tools/openclaw/ + prd/quartz-blog/ + 日常用 AI 工具踩的坑。
| # | 案例（預期主題） | 子類 | Stage |
|---|
| 01 | Claude Code Context 爆超耗 token | Claude Code | 🌱 |
| 02 | Cursor rules 跟 Claude Code .claude/ 衝突 | Multi-tool | 🌱 |
| 03 | Ollama 本地模型 GPU / RAM 超限 | Local model | 🌱 |
| 04 | OpenAI / Anthropic API Rate Limit + Retry 策略 | API | 🌱 |
| 05 | MCP Server 連線不通 / tool schema 亂填 | MCP | 🌱 |
| 06 | AI Agent 無限 loop / Memory 爆 | Agent | 🌱 |
O15 Blog / 部落格部署坑（新增，估 5 案例）
資料來源：prd/quartz-blog/ 本部落格的踩坑。
| # | 案例（預期主題） | 子類 | Stage |
|---|
| 01 | Quartz wikilink resolver 抓不到（文件重命名 / 搬家後） | Wikilink | 🌱 |
| 02 | GitHub Actions build fail（frontmatter 格式 / plugin 錯） | CI | 🌱 |
| 03 | Image 路徑問題（images/ 相對 vs 絕對 / 大小寫） | Asset | 🌱 |
| 04 | Quartz plugin 設定導致 FolderPage 失效 | Plugin | 🌱 |
| 05 | 部署到 GitHub Pages 失敗（build size / 路徑 / CNAME） | Deploy | 🌱 |
跟 I09 Disaster Recovery 的 workflow 整合
I09 #26「DR event 完整 workflow」設計了閉環：
告警（I05 #26 chain）
↓
open ticket（PM07 Issue Tracker）
↓
runbook 執行（ops-notes O13 methodology）
↓
具體案例 commit（ops-notes O01-O12, O14-O15）
↓
postmortem（management/engineering-process/04）
↓
update runbook（ops-notes O13 #02）
↓
update Chaos test（infra/disaster-recovery/#23）
Convention：每個 ops-note 結尾加「相關 Runbook / Postmortem / Chaos test」區塊，做成閉環 traceability。
## 相關 Runbook / Postmortem / Chaos test
- Runbook：`ops-notes/O13/<runbook-slug>`
- Postmortem：`management/engineering-process/04-incident-management/<incident-slug>`
- Chaos test：`infra/disaster-recovery/25-first-chaos-experiment`（如有）
- Alert rule：`infra/observability/22-alert-design`（如有）
進度追蹤
Milestone：
- M1：O01 K8s 部署阻斷（5 篇，最多人踩）+ O02 Kong 第一案例（已 🌿）
- M2：O06 Env/Secret + O07 CI/CD（5+5）
- M3：O13 方法論 4 篇（建立 runbook 系統）
- M4：O14 AI 工具 + O15 Blog 部署（新增）
- M5：O09 可觀測性 + 剩餘
下一步
- 先從 O01（K8s 部署阻斷）、O02（Kong 坑）開始，這兩類最多人會踩
- 每篇以「症狀驅動」寫，讓 Google 搜尋症狀時能找到
- 抽離真實 commit 內容，去敏感化（密碼、internal URL 等）
- 每篇結尾加「相關 Runbook / Postmortem / Chaos test」閉環區塊
跨系列連結