雲端原生運算生態系教學手冊

雲端原生運算生態系教學手冊 版本:1.0 最後更新:2026 年 1 月 適用對象:資深工程師、系統架構師、SRE / DevOps 工程師、技術主管 定位:企業內部標準教材 文件維護:內部技術團隊 使用情境:大型企業 / 銀行內部系統 最後更新: 2026年1月30日 適用於: 雲端原生運算生態系 Created by: Eric Cheng 目錄 1. 雲端原生運算概論 1.1 什麼是 Cloud Native 1.2 與傳統架構的差異 1.3 CNCF 的角色與定位 1.4 CNCF Landscape 全景圖說明 1.5 雲端原生帶來的價值與挑戰 2. 雲端原生系統整體架構 2.1 典型雲端原生參考架構 2.2 核心分層說明 2.2.1 基礎設施層(Infrastructure Layer) 2.2.2 容器層(Container Runtime Layer) 2.2.3 編排層(Orchestration Layer) 2.2.4 平台層(Platform Layer) 2.2.5 可觀測性(Observability Layer) 2.2.6 安全層(Security Layer) 2.3 微服務與事件驅動架構 3. CNCF 核心專案分類與說明 3.1 Container & Runtime 3.2 Orchestration & Management 3.3 Networking 3.4 Service Mesh 3.5 API Gateway & Ingress 3.6 Observability 3.7 Logging 3.8 Security 3.9 CI/CD 3.10 Storage 3.11 Messaging & Streaming 4. 系統安裝與基礎環境建置 4.1 雲端原生平台建置方式比較 4.2 Managed Kubernetes 比較 4.3 Self-Managed Kubernetes 安裝(kubeadm) 4.4 必要 Add-ons 安裝建議 4.5 開發、測試、正式環境差異設計 5. 系統設定與組態管理 5.1 Kubernetes Namespace 與 RBAC 設計 5.2 ConfigMap / Secret 使用方式 5.3 Helm 與 Kustomize 的角色 5.4 GitOps 架構(以 Argo CD 為例) 5.5 環境參數與設定管理策略 6. 雲端原生系統使用方式 6.1 應用程式容器化流程 6.2 Deployment / StatefulSet 使用情境 6.3 Service / Ingress / Gateway 設計 6.4 自動擴縮(HPA / VPA) 6.5 Rolling Update 與 Zero Downtime Deployment 7. 系統維運與可觀測性 7.1 Metrics、Logs、Traces 的角色 7.2 Prometheus + Grafana 架構 7.3 OpenTelemetry 導入方式 7.4 告警(Alerting)設計原則 7.5 SRE 常用監控指標(SLI / SLO / SLA) 8. 系統安全與治理 8.1 雲端原生安全風險概覽 8.2 Kubernetes Security Best Practices 8.3 Image Security 與 Supply Chain Security 8.4 Policy as Code(OPA / Kyverno) 8.5 零信任(Zero Trust)在雲端原生的應用 9. 系統升級與版本管理 9.1 Kubernetes 升級策略 9.2 CNCF 元件相容性考量 9.3 滾動升級與回滾機制 9.4 升級風險與因應方式 10. 應用系統如何串接雲端原生平台 10.1 傳統系統(Legacy System)上雲策略 10.2 API-based 系統整合 10.3 Event-driven 架構串接方式 10.4 Database、MQ、外部系統整合模式 10.5 金融/企業系統常見整合案例 11. 企業實務建議與最佳實踐 11.1 雲端原生導入常見地雷 11.2 組織與流程調整建議 11.3 開發、維運、資安協作模式 11.4 技術選型建議 11.5 成熟度模型(Cloud Native Maturity Model) 12. 檢查清單(Checklist) 12.1 叢集建置檢查清單 12.2 應用部署檢查清單 12.3 可觀測性檢查清單 12.4 安全檢查清單 12.5 維運檢查清單 附錄 附錄 A:常用 kubectl 指令速查 附錄 B:參考資源 1. 雲端原生運算概論 1.1 什麼是 Cloud Native Cloud Native(雲端原生) 是一種建構和運行應用程式的方法,充分利用雲端運算模型的優勢。根據 CNCF(Cloud Native Computing Foundation)的定義: ...

January 30, 2026 · 30 min · 6212 words · Eric Cheng

Kubernetes教學手冊

Kubernetes教學手冊 項目 內容 文件版本 2.0(企業標準技術白皮書版) 最後更新 2026-10-01 版本基準 Kubernetes v1.37.1(主線,所有範例的基準);1.34/1.35 的差異以 📌 1.34/1.35 差異 標示 周邊元件基準 containerd 2.4.1、etcd 3.7(kubeadm 預設)、Gateway API v1.6.2、Helm 4.3.0、Cilium 1.20.2/Calico 3.32.2、Prometheus 3.15、Argo CD 3.5 適用對象 後端工程師、DevOps/SRE、平台工程師、系統架構師、資安人員 定位 企業內部 Kubernetes 標準教材與導入參考 文件維護 內部技術團隊(Created by Eric Cheng) 🆕 v2.0 改版重點 版本基準從 1.29 改為 1.37.1:1.29 已於 2025-02-28 EOL。本版依 Kubernetes 1.37.1 原始碼與官方文件逐章查證,並註記 1.34/1.35 的差異。 重大生態系變化:Ingress NGINX 已於 2026-03-24 退役(第 4 章並列 Ingress 與 Gateway API,並提供遷移指南);cgroup v1 自 1.35 起預設拒絕啟動、1.36 起必須 containerd 2.x(第 2、11 章);Bitnami 免費映像下架、Helm 4 發布(第 12 章)。 修正 v1.0 的錯誤與過時內容:共 41 項,完整清單見附錄 D.2。 新增章節:第 8 章「安全強化」、第 15 章「疑難排解手冊」、第 16 章「1.29 → 1.37 版本演進」,以及附錄 B–F。 每章結尾新增「💡 本章實務建議」;新增段落標示 🆕,更正段落標示 ⚠️。 閱讀指引 讀者角色 建議閱讀順序 重點章節 初次接觸 Kubernetes 的工程師 1 → 3 → 4 → 5 → 7 1.3 核心物件概念、3.3 Deployment 與 ReplicaSet 後端/應用開發者 3 → 5 → 6 → 13 → 14 6.2 Health Check、13.5 優雅關機 平台/SRE 工程師 2 → 9 → 10 → 11 → 15 10.2 etcd 備份與還原、11.4 破壞性變更檢查 系統架構師 1 → 4 → 10.1 → 14 → 16 4.7 Gateway API、14.3 企業環境實務建議 資安人員 8 → 4.9 → 12.3 → 14.3 8.5 Admission 控制、8.10 供應鏈安全 從舊版升級的團隊 16 → 11 → 4.8 16.3 建議升級路徑、4.8 Ingress NGINX 遷移 📌 標示說明:🆕 v2.0 新增;⚠️ v2.0 更正或重要警示;📌 補充說明與版本差異;✅ 建議做法。功能成熟度標示為「x.y GA/Beta/Alpha」,以 Kubernetes 官方 feature gate 文件為準。 ...

January 30, 2026 · 98 min · 20736 words · Eric Cheng

Kong API Gateway教學手冊

Kong API Gateway教學手冊 項目 內容 文件版本 2.0(企業標準技術白皮書版) 最後更新 2026-09-30 版本基準(雙軌) Kong Gateway OSS 3.9.3(開源最終發行版,所有實作範例的基準)/Kong Gateway Enterprise 3.16.0.0(最新版)與 3.14 LTS 周邊工具基準 decK 1.67.0、Kong Operator 2.3.x、Kong Ingress Controller 3.5 LTS、Helm chart kong/kong 3.4.x 適用對象 後端工程師、系統架構師、平台/DevOps/SRE 工程師、資安人員 定位 企業內部 API Gateway 標準教材與導入參考 文件維護 內部技術團隊(Created by Eric Cheng) 🆕 v2.0 改版重點 版本基準改為雙軌:Kong 自 3.10 起不再發布 OSS 的 Docker image 與安裝套件,OSS 最後一版是 3.9.3。Enterprise 已經推進到 3.16,並在 3.15 起改成「沒有授權時 Admin API 唯讀」。本版把所有可以免授權執行的範例統一在 OSS 3.9.3 上,Enterprise 的差異集中在第 1.4、10、11、13 章說明。 修正 v1.0 的錯誤設定:已淘汰的 redis_host、KongIngress、config.endpoint(OpenTelemetry)、flush_timeout(HTTP Log)、decK 舊命令、Plugin 優先序規則等,完整清單請見附錄 D.2。 新增章節:第 11 章「安全強化」、第 13 章「AI Gateway 與 MCP」、附錄 C「常見問答」、附錄 D「版本紀錄」、附錄 E「查證紀錄」。 每章結尾新增「💡 本章實務建議」;新增的段落標示為 🆕,更正的段落標示為 ⚠️。 閱讀指引 讀者角色 建議閱讀順序 重點章節 初次接觸 Kong 的工程師 1 → 3 → 4 → 5 → 6 3.2 常見部署方式、5.1 建立第一個 API 系統架構師 1 → 2 → 10 → 11 → 12 1.4 產品矩陣與授權變化、2.2 部署拓樸 平台/SRE 工程師 3 → 8 → 9 → 10 → 15 9.1 decK 與 APIOps、10.4 升級策略 資安人員 6 → 11 → 15.4 11.1 Admin API 保護 AI 平台團隊 1.5 → 13 13.2 以 OSS AI Proxy 串接 LLM 📌 標示說明:OSS 表示 Kong Gateway 開源版(3.9.3)即可使用;EE 表示需要 Kong Gateway Enterprise 授權或 Konnect;DB-less ✅/❌ 表示該 Plugin 是否支援 DB-less 模式。 ...

January 30, 2026 · 70 min · 14808 words · Eric Cheng

Keycloak教學手冊

Keycloak教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-09-30 版本基準 Keycloak 26.7.4(2026-09-16 發佈)、keycloak-js 26.2.x(獨立發版)、Spring Boot 4.1 / Spring Security 7.1 文件定位 企業標準技術白皮書/內部標準教材 適用對象 後端工程師、前端工程師、系統架構師、DevOps/SRE、資安人員、稽核人員 使用情境 大型企業、金融業(銀行/證券/保險)內部與對外系統之身分與存取管理 前一版本 1.0(2026-01-29,適用 Keycloak 24.x/25.x) 文件維護 內部技術團隊 Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Keycloak 26.7;修正 v1.0 中已被移除或棄用的設定(KEYCLOAK_ADMIN、KC_PROXY、hostname v1、KC_CACHE_STACK=kubernetes 等);新增 Grant Type 選擇、BFF、Organizations、Passkeys、DPoP、FAPI 2.0、Token Exchange V2、可觀測性、Rolling Update、設定即程式碼、MCP/AI Agent 授權等章節。完整差異見 附錄 D 版本紀錄,查證依據見 附錄 E 查證紀錄。 閱讀指引 讀者角色 建議閱讀章節 初次接觸 Keycloak 第一章 → 第二章 → 第三章 3.1 → 第四章 前端/後端開發人員 第二章 2.3–2.6 → 第五章 → 第六章 架構師 第一章 1.6–1.7 → 第二章 → 第八章 → 第十章 → 第十二章 DevOps/SRE 第三章 → 第七章 → 第八章 8.1 → 第九章 → 第十一章 資安/稽核人員 第一章 1.7 → 第八章 → 第七章 7.2 → 附錄 A 本文慣例 標記 意義 > 🆕 **v2.0 新增** 本版新增的章節或內容 > ⚠️ **v2.0 更正** 修正 v1.0 錯誤或已過時的內容 > ⚠️ **實務注意** 容易出錯、需特別留意之處 > 💡 **建議** 企業實務建議做法 Supported/Preview/Experimental 依 Keycloak 官方功能成熟度分類;Preview 與 Experimental 功能不建議直接用於正式環境 目錄 文件資訊 閱讀指引 本文慣例 第一章:Keycloak 簡介與核心概念 1.1 Keycloak 是什麼? 1.1.1 核心功能 1.1.2 適用場景 1.1.3 與其他 IAM 方案比較 1.2 IAM、SSO、OAuth 2.0、OIDC 關係說明 1.2.1 名詞解釋 1.2.2 OAuth 2.0 vs OIDC 差異 1.3 Token 類型說明 1.3.1 詳細說明 1.3.2 Access Token 結構範例(JWT) 1.4 核心概念:Realm、Client、User、Role、Group 1.4.1 概念說明 1.4.2 Realm 設計原則 1.5 Authentication vs Authorization 1.5.1 實務流程 1.6 版本發佈節奏與支援策略 1.6.1 版本編號與發佈節奏 1.6.2 執行環境需求 1.6.3 功能成熟度分類 1.7 標準協定地圖 1.8 💡 本章實務建議 第二章:系統架構設計 2.1 Keycloak 在企業系統中的角色 2.1.1 責任分工 2.2 整合架構說明 2.2.1 與 Web 前端(SPA)整合 2.2.2 與 Backend API 整合 2.2.3 與 API Gateway 整合 2.2.4 與 AD / LDAP 整合 2.2.5 與外部身分提供者(Identity Brokering)整合 2.2.6 與行動 App/原生應用整合 2.3 Token Flow(Authorization Code Flow + PKCE) 2.4 Grant Type 選擇矩陣 2.5 PKCE(Proof Key for Code Exchange)深入 2.5.1 運作原理 2.5.2 產生範例 2.5.3 Keycloak 設定 2.6 BFF 模式(Backend for Frontend) 2.7 Organizations 多租戶(B2B) 2.8 💡 本章實務建議 第三章:Keycloak 安裝與部署 3.1 單機部署(Docker) 3.1.1 開發/測試環境快速啟動 3.1.2 使用 Docker Compose 建立開發環境(含 PostgreSQL) 3.2 生產環境部署建議 3.2.1 資料庫選擇 3.2.2 建置最佳化映像(Optimized Image) 3.2.3 生產環境 Docker Compose 3.2.4 Nginx Reverse Proxy 設定 3.2.5 對外公開路徑建議 3.2.6 TLS 部署模式 3.3 基本啟動參數與環境變數 3.3.1 設定來源與優先順序 3.3.2 常用選項 3.3.3 Hostname v2 設定情境 3.3.4 啟動模式與常用指令 3.4 Admin Console 存取方式 3.4.1 存取 URL 3.4.2 首次登入與管理員治理 3.4.3 重要端點 3.5 管理介面(Port 9000)與健康檢查 3.6 Kubernetes Operator 部署 3.6.1 安裝 Operator 3.6.2 Keycloak CR 範例 3.7 💡 本章實務建議 第四章:Keycloak 基本設定 4.1 Realm 建立與規劃原則 4.1.1 建立 Realm 步驟 4.1.2 Realm 設計原則 4.1.3 企業 Realm 規劃範例 4.1.4 新 Realm 上線前必設項目 4.2 Client 類型說明 4.2.1 Client 類型比較 4.2.2 Client 驗證方式(Client Authenticator) 4.2.3 建立 Client 步驟 4.2.4 Confidential Client 設定範例(BFF/伺服器端 Web) 4.2.5 Service Account Client 設定範例(批次/服務對服務) 4.2.6 Public Client 設定範例(SPA/行動 App) 4.3 Redirect URI 與 Web Origin 設定 4.3.1 Redirect URI 設定原則 4.3.2 Web Origin 設定(CORS) 4.3.3 Post Logout Redirect URI 4.4 User、Role、Group 設定策略 4.4.1 User 管理 4.4.2 建立使用者 4.4.3 Group 階層設計 4.5 Realm Role vs Client Role 使用時機 4.5.1 使用時機比較 4.5.2 Composite Role 與預設角色 4.5.3 最佳實務 4.6 Client Scopes 與 Protocol Mapper 4.6.1 Default 與 Optional Scope 4.6.2 常用 Protocol Mapper 4.6.3 Audience 設計(重要) 4.6.4 Full Scope Allowed 與 Token 瘦身 4.7 宣告式 User Profile 4.8 Authentication Flow 與 Required Actions 4.8.1 內建 Flow 4.8.2 自訂 Browser Flow 範例(帳密 + 強制 OTP/Passkey) 4.8.3 Required Actions 4.9 Fine-Grained Admin Permissions V2 4.10 💡 本章實務建議 第五章:應用系統如何串接 Keycloak 5.1 Web 前端串接(OIDC) 5.1.1 使用 keycloak-js 官方套件 5.1.2 初始化設定 5.1.3 Vue 3 整合範例 5.1.4 React 整合範例 5.1.5 API 呼叫時帶入 Token 5.2 Backend API 驗證 Token 機制 5.2.1 Token 驗證流程 5.2.2 驗證方式比較 5.2.3 JWKS 快取與金鑰輪替 5.3 Spring Boot 整合 5.3.1 依賴設定(Maven) 5.3.2 應用程式設定 5.3.3 Security 設定類別 5.3.4 Keycloak 角色轉換器 5.3.5 Controller 範例 5.3.6 呼叫下游服務(Client Credentials) 5.4 Node.js 整合 5.5 常見錯誤與除錯方式 5.5.1 常見錯誤對照表 5.5.2 除錯技巧 5.6 細粒度授權(Authorization Services) 5.7 Admin REST API 與 kcadm.sh 5.7.1 以 Service Account 呼叫 Admin REST API 5.7.2 kcadm.sh(Admin CLI) 5.7.3 Java Admin Client 5.8 💡 本章實務建議 第六章:系統使用情境說明 6.1 SSO 登入流程實例 6.1.1 SSO 實務注意事項 6.2 使用者角色異動後的影響 6.2.1 角色變更生效時機 6.2.2 企業實務建議 6.3 Token 生命週期與 Refresh 機制 6.3.1 時效設定與預設值 6.3.2 Offline Token 6.3.3 前端 Token Refresh 實作 6.4 Logout 流程(Single Logout) 6.4.1 Logout 類型 6.4.2 RP-Initiated Logout 6.4.3 Back-Channel Logout(建議) 6.5 Step-up 認證與認證強度(ACR/LoA) 6.6 服務間呼叫與 Token Exchange 6.6.1 選擇方式 6.6.2 Standard Token Exchange 設定 6.7 💡 本章實務建議 第七章:系統維運與管理 7.1 使用者與權限管理最佳實務 7.1.1 使用者管理原則 7.1.2 JML 流程與 Keycloak 對應 7.1.3 權限審核 Checklist 7.2 Audit Log 與事件追蹤 7.2.1 啟用事件記錄 7.2.2 重要事件類型 7.2.3 事件查詢 API 7.2.4 將事件送往 SIEM 7.3 Keycloak Log 說明 7.3.1 Log 等級與輸出設定 7.3.2 常見 Log 訊息解讀 7.3.3 Log 整合建議 7.4 可觀測性:Metrics 與 Tracing 7.4.1 Metrics 7.4.2 Tracing(OpenTelemetry) 7.5 Workflows 與 SCIM 7.5.1 Workflows(26.6 起正式支援) 7.5.2 SCIM API(26.7 Preview) 7.6 常見營運問題 7.6.1 問題 1:使用者無法登入 7.6.2 問題 2:Token 驗證失敗 7.6.3 問題 3:效能問題 7.6.4 問題 4:Hostname 或 Proxy 設定錯誤 7.6.5 問題 5:升級後管理 API 或整合失效 7.7 💡 本章實務建議 第八章:高可用與資安建議 8.1 Keycloak HA 架構概念 8.1.1 部署架構選擇 8.1.2 快取與 Session 8.1.3 容量規劃(官方 Sizing 指南) 8.1.4 HA 部署要點 8.2 Session 與 Token 設計考量 8.2.1 Session 設計原則 8.2.2 Refresh Token Rotation 8.3 HTTPS 與憑證管理 8.3.1 HTTPS 部署方式 8.3.2 憑證與信任庫設定 8.3.3 憑證管理建議 8.4 防止 Token 洩漏的設計原則 8.4.1 Token 儲存原則 8.4.2 安全設計 Checklist 8.5 與企業資安政策的搭配方式 8.5.1 密碼政策(依 NIST SP 800-63B-4) 8.5.2 密碼雜湊 8.5.3 暴力破解防護 8.5.4 Security Headers 8.5.5 MFA:OTP、Passkeys 與備援碼 8.6 進階 Token 安全:DPoP、PAR 與 FAPI 2.0 8.6.1 DPoP(RFC 9449,26.4 起支援) 8.6.2 PAR(RFC 9126) 8.6.3 Client Policies 與 FAPI 2.0 8.7 機密管理與 FIPS 8.7.1 Vault 整合 8.7.2 FIPS 140 模式 8.8 資安公告與漏洞管理 8.9 💡 本章實務建議 第九章:系統升級與版本管理 9.1 升級前檢查事項 9.1.1 升級前 Checklist 9.1.2 版本資訊查詢 9.2 升級策略:Rolling Update 與 Recreate 9.2.1 使用 update-compatibility 判斷 9.3 資料庫相容性注意事項 9.3.1 資料庫升級流程 9.3.2 Schema 遷移方式 9.3.3 26.7 資料庫相關變更 9.4 版本變更與設定風險 9.4.1 重大架構變更歷史 9.4.2 26.6 → 26.7.4 破壞性與行為變更 9.4.3 已棄用、將移除的功能 9.4.4 設定遷移建議 9.5 Rollback 建議策略 9.5.1 Rollback 計畫 9.5.2 時間評估 9.6 💡 本章實務建議 第十章:最佳實務與設計建議 10.1 Realm / Client 命名規範 10.1.1 命名規範建議 10.2 多系統共用 Keycloak 的設計原則 10.2.1 架構設計 10.2.2 Token 內容標準 10.3 銀行或大型企業常見踩雷點 10.3.1 踩雷案例 1:Token 過大 10.3.2 踩雷案例 2:AD 整合效能差 10.3.3 踩雷案例 3:Refresh Token 被盜用 10.3.4 踩雷案例 4:升級後前端登入失敗 10.3.5 踩雷案例 5:Hostname 設定錯誤導致 iss 不一致 10.3.6 踩雷案例 6:透過 Mapper 帶入的管理角色失效 10.3.7 踩雷案例 7:第三方 Cookie 限制導致 SSO 狀態偵測失效 10.3.8 踩雷案例 8:Service Account 權限過大 10.4 開發、測試、正式環境隔離建議 10.4.1 環境隔離架構 10.4.2 環境設定管理 10.4.3 設定同步建議 10.5 💡 本章實務建議 第十一章:設定即程式碼與自動化 11.1 為何需要設定即程式碼 11.2 Realm Export/Import 11.2.1 CLI 匯出/匯入 11.2.2 Admin Console/REST API 部分匯入 11.3 keycloak-config-cli 11.4 Operator KeycloakRealmImport 11.5 Terraform Provider 11.6 工具選擇比較 11.7 CI/CD 與環境升遷 11.8 💡 本章實務建議 第十二章:新興標準與 AI Agent 授權 12.1 功能成熟度總覽 12.2 Keycloak 作為 MCP 授權伺服器 12.2.1 規範支援狀態 12.2.2 設定步驟(MCP 2025-06-18 以後) 12.3 Client ID Metadata Document(CIMD) 12.4 Identity Assertion JWT Grant(ID-JAG) 12.5 Shared Signals Framework(SSF) 12.6 AuthZEN 12.7 OID4VCI(可驗證憑證發行) 12.8 評估與導入建議 12.9 💡 本章實務建議 附錄 A:檢查清單(Checklist) A.1 初次部署檢查清單 A.2 日常維運檢查清單 A.3 系統整合檢查清單 A.4 升級前檢查清單 附錄 B:常見 Q&A B.1 Q1:忘記 Admin 密碼怎麼辦? B.2 Q2:如何批次匯入使用者? B.3 Q3:Token 過期時間如何調整? B.4 Q4:如何查看目前線上使用者? B.5 Q5:Client Secret 外洩怎麼辦? B.6 Q6:如何實作 API 的細粒度授權? B.7 Q7:使用者被暴力破解防護鎖定,如何解鎖? B.8 Q8:如何在不停機的情況下輪替 Client Secret? B.9 Q9:升級後登入或 API 大量失敗,如何處理? B.10 Q10:登入後被導向內部網址或出現「HTTPS required」? 附錄 C:版本功能對照表 附錄 D:版本紀錄 D.1 版本歷程 D.2 v1.0 → v2.0 更正表 D.3 v2.0 新增章節 附錄 E:查證紀錄 E.1 待確認事項 附錄 F:參考資料 第一章:Keycloak 簡介與核心概念 1.1 Keycloak 是什麼? Keycloak 是開源的 身分與存取管理(Identity and Access Management, IAM) 解決方案,提供單一登入(SSO)、身分聯合、使用者管理與細緻授權等能力,並以 OAuth 2.0、OpenID Connect(OIDC)與 SAML 2.0 等標準協定對外提供服務。 ...

January 30, 2026 · 80 min · 16866 words · Eric Cheng

OpenTelemetry教學手冊

OpenTelemetry教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 前一版本 1.0(2026-01-27) 版本基準 OpenTelemetry Collector / Contrib v0.162.0(2026-09-29)、Helm Chart opentelemetry-collector 0.174.0、Operator v0.160.0、Java Agent 2.31.1、Java SDK 1.66.0、JS SDK 2.11.0、Semantic Conventions 1.44.0、Specification 1.61.0、OTLP 1.11.1;完整矩陣見 附錄 D.1 適用對象 後端工程師、DevOps / SRE、平台工程團隊、系統架構師、資安與稽核人員 文件定位 企業標準技術白皮書:概念 → 架構 → 安裝 → 設定 → 應用串接 → 維運 → 升級 → 治理 驗證方式 文中 Collector 設定以 otelcol-contrib 0.162.0 validate 驗證;PromQL 與告警規則以 promtool 3.15.0 check rules 驗證;查證紀錄見 附錄 E 作者 Eric Cheng 📌 v2.0 改版重點 ...

January 30, 2026 · 72 min · 15283 words · Eric Cheng

Apache Kafka 教學手冊

Apache Kafka 教學手冊 項目 內容 文件版本 2.0 最後更新 2026 年 9 月 29 日 適用版本 Apache Kafka 4.3.x(KRaft 模式;ZooKeeper 模式已於 4.0 移除) 適用對象 後端工程師、系統架構師、SRE、DevOps、資安與稽核人員 文件定位 企業標準技術白皮書/內部標準教材 使用情境 大型企業、金融業(銀行、證券、保險)內部系統 文件維護 內部技術團隊 Created by Eric Cheng ⚠️ v2.0 重大改版說明:本版以 Apache Kafka 4.3(最新修補版 4.3.1)為基準全面改寫。v1.0 以 Kafka 3.x/ZooKeeper 並存時代為基準,其中 inter.broker.protocol.version 升級流程、zookeeper.connect ACL 指令、config/kraft/ 設定路徑等內容在 4.x 已不適用。完整更正清單請見附錄 E:版本更新紀錄,查證來源請見附錄 F:查證紀錄。 目錄 執行摘要 1. Apache Kafka 簡介 1.1 Kafka 是什麼?解決什麼問題? 1.2 與傳統 Message Queue 的差異 1.3 適合與不適合的使用情境 1.4 核心概念與五大 API 1.4.1 事件(Event)結構 1.4.2 核心術語 1.4.3 五大 API 1.5 版本演進與 4.x 重點 1.5.1 近期版本時間軸 1.5.2 4.x 對企業的關鍵影響 1.6 💡 本章實務建議 2. Kafka 系統架構總覽 2.1 Kafka 核心元件說明 2.1.1 Broker 2.1.2 Topic 與 Partition 2.1.3 Producer 2.1.4 Consumer 與 Consumer Group 2.1.5 Controller 與 KRaft Metadata Quorum 2.1.6 Share Group(Queues for Kafka) 2.2 高可用(HA)與水平擴充設計原則 2.2.1 副本機制(Replication) 2.2.2 高可用設計原則 2.2.3 機架感知(Rack Awareness) 2.2.4 水平擴充原則 2.3 儲存層架構 2.3.1 Log Segment 結構 2.3.2 高效能設計 2.4 Tiered Storage(分層儲存) 2.5 💡 本章實務建議 3. Kafka 安裝與部署 3.1 環境需求 3.1.1 硬體需求 3.1.2 軟體需求 3.1.3 網路需求 3.2 單機環境安裝(KRaft 模式) 3.3 多節點叢集安裝(正式環境) 3.3.1 叢集規劃 3.3.2 Controller 節點設定 3.3.3 Broker 節點設定 3.3.4 叢集初始化與啟動 3.3.5 Controller 動態擴縮 3.4 ZooKeeper 移除與遷移路徑 3.5 常見安裝錯誤與排除方式 3.6 Docker 容器部署 3.6.1 快速啟動 3.6.2 以環境變數設定 3.6.3 Docker Compose 範例(單節點開發環境) 3.7 Kubernetes 部署 3.8 系統服務與作業系統調校 3.8.1 Systemd Service 3.8.2 JVM 調校 3.8.3 作業系統調校 3.9 💡 本章實務建議 4. Kafka 基本設定說明 4.1 Broker 重要設定參數 4.1.1 核心設定 4.1.2 效能相關設定 4.1.3 日誌與可靠性設定 4.1.4 Kafka 4.0 預設值變更 4.2 Topic 設計原則 4.2.1 Partition 數量設計 4.2.2 Replication Factor 設計 4.2.3 Topic 層級設定 4.3 Producer 重要設定 4.4 Consumer 重要設定 4.5 資料保留策略(Retention Policy) 4.6 Share Group 設定 4.7 動態設定管理 4.8 💡 本章實務建議 5. Kafka 系統使用教學 5.1 Topic 管理 5.1.1 建立 Topic 5.1.2 查詢 Topic 5.1.3 修改 Topic 5.1.4 刪除 Topic 5.2 Producer 發送訊息 5.2.1 使用 Console Producer 5.2.2 Java Producer 範例 5.3 Consumer 消費訊息 5.3.1 使用 Console Consumer 5.3.2 Java Consumer 範例 5.4 Offset 管理 5.4.1 查看 Consumer Group Offset 5.4.2 重置 Offset 5.4.3 群組管理工具(KIP-1043) 5.5 訊息順序性與重複消費 5.5.1 訊息順序保證 5.5.2 避免重複消費 5.6 Share Group 操作 5.6.1 Console Share Consumer 5.6.2 管理 Share Group 5.6.3 Java Share Consumer 範例 5.7 交易與 Exactly-Once 語意 5.7.1 傳遞語意比較 5.7.2 交易 Producer(Consume-Transform-Produce) 5.8 💡 本章實務建議 6. Kafka 與應用系統串接方式 6.1 與 Spring Boot 整合 6.1.1 Maven 依賴 6.1.2 設定檔(application.yml) 6.1.3 Producer 實作 6.1.4 Consumer 實作 6.1.5 Kafka 設定類別與錯誤處理 6.1.6 非阻塞重試(@RetryableTopic) 6.1.7 Share Consumer 整合 6.2 系統解耦架構設計 6.3 同步系統 vs 事件驅動架構 6.4 常見整合架構模式 6.4.1 Event Sourcing 6.4.2 CDC(Change Data Capture) 6.4.3 Saga 模式 6.4.4 Transactional Outbox 模式 6.5 Schema Registry 與 Schema 演進 6.6 Kafka Connect 與 CDC 6.7 Kafka Streams 串流處理 6.8 💡 本章實務建議 7. Kafka 系統維運與監控 7.1 常見監控指標 7.1.1 Broker 層級指標 7.1.2 Controller 與 KRaft 指標 7.1.3 Topic/Partition 層級指標 7.1.4 Client 層級指標 7.2 Consumer Lag 監控與處理 7.2.1 查看 Consumer Lag 7.2.2 Lag 過高的原因與解決方案 7.3 系統監控設定 7.3.1 JMX 監控設定 7.3.2 Prometheus 整合 7.3.3 Grafana Dashboard 7.4 常見營運問題與排查 7.4.1 問題排查流程 7.4.2 常見問題與解決方案 7.4.3 日誌檢查 7.5 容量規劃與效能調校 7.5.1 儲存容量估算 7.5.2 網路頻寬估算 7.5.3 效能調校對照表 7.5.4 壓力測試 7.6 叢集維護作業 7.6.1 Partition 重新分配 7.6.2 Preferred Leader 選舉 7.6.3 Cordon(隔離)Broker 與磁碟(KIP-1066) 7.6.4 Broker 下線流程 7.7 災難復原與跨機房部署 7.7.1 部署模式比較 7.7.2 MirrorMaker 2 7.7.3 備份策略 7.8 💡 本章實務建議 8. Kafka 系統升級與版本控管 8.1 升級策略(Rolling Upgrade) 8.1.1 版本控管概念 8.1.2 升級前提(升級至 4.3) 8.1.3 升級步驟 8.2 升級前檢查清單 8.3 升級風險與回復機制 8.3.1 常見風險 8.3.2 回滾步驟 8.4 Client 相容性 8.4.1 官方相容性摘要(Kafka 4.x) 8.4.2 Java 版本需求 8.4.3 升級順序建議 8.5 3.x 升級至 4.x 破壞性變更 8.6 版本支援與發布週期 8.7 💡 本章實務建議 9. 安全性與權限控管 9.1 SSL/TLS 加密 9.1.1 建立 SSL 憑證 9.1.2 Broker SSL 設定 9.2 SASL 認證 9.2.1 認證機制比較 9.2.2 SASL/SCRAM 設定 9.2.3 Client 端設定 9.2.4 SASL/OAUTHBEARER(OIDC) 9.2.5 Controller Listener 安全 9.3 ACL 權限控管 9.3.1 啟用 Authorizer 9.3.2 設定 ACL 9.3.3 常見 ACL 權限 9.4 企業安全設計建議 9.5 機密管理與身分對應 9.5.1 Config Provider 9.5.2 mTLS 身分對應 9.6 稽核、配額與合規 9.6.1 Authorizer 稽核日誌 9.6.2 Client Quota 9.6.3 金融業合規考量 9.7 💡 本章實務建議 10. 最佳實務與常見地雷 10.1 Topic 命名建議 10.1.1 命名規範 10.2 Partition 設計地雷 10.2.1 常見錯誤 10.2.2 Partition 數量計算 10.3 Consumer Group 錯誤案例 10.3.1 案例 1:Consumer 數量超過 Partition 10.3.2 案例 2:誤用 Consumer Group 10.3.3 案例 3:Rebalance 風暴 10.3.4 案例 4:Kubernetes 滾動部署造成反覆 Rebalance 10.4 真實專案常見誤用情境 10.4.1 將 Kafka 當作資料庫使用 10.4.2 忽略冪等性設計 10.4.3 同步呼叫與非同步混用(雙寫問題) 10.4.4 大訊息傳輸 10.4.5 其他常見地雷 10.5 最佳實務總結 10.6 Consumer Group 與 Share Group 選型 10.7 事件設計規範 10.7.1 事件信封(Envelope)標準 10.7.2 事件設計原則 11. 檢查清單(Checklist) 11.1 新專案導入 Checklist 11.1.1 規劃階段 11.1.2 部署階段 11.1.3 開發階段 11.1.4 上線前 11.2 日常維運 Checklist 11.2.1 每日檢查 11.2.2 每週檢查 11.2.3 每月檢查 11.3 故障排除 Checklist 11.3.1 Controller 問題 11.3.2 Broker 問題 11.3.3 Producer 問題 11.3.4 Consumer 問題 11.4 升級 Checklist 11.4.1 升級前 11.4.2 升級中 11.4.3 升級後 附錄 附錄 A:常用指令速查 A.1 叢集與 Metadata A.2 Topic 管理 A.3 設定管理 A.4 Group 管理 A.5 Console Producer/Consumer A.6 維運作業 附錄 B:設定參數速查 B.1 Broker/Controller 重要參數 B.2 Producer 重要參數 B.3 Consumer 重要參數 B.4 Group 層級參數(Broker 端控制) 附錄 C:參考資源 C.1 官方文件(Apache Kafka 4.3) C.2 版本發布與 KIP C.3 社群資源 C.4 生態系與延伸閱讀 附錄 D:名詞對照表 附錄 E:版本更新紀錄 E.1 版本歷程 E.2 v2.0 主要更正 E.3 v2.0 新增章節 附錄 F:查證紀錄 F.1 待後續確認事項 執行摘要 Apache Kafka 是目前企業界事實上的**事件串流平台(Event Streaming Platform)**標準。它同時具備「發布/訂閱」、「持久化儲存」與「串流處理」三種能力,使企業能以單一平台串接交易系統、資料平台、監控系統與 AI/分析應用。 ...

January 30, 2026 · 69 min · 14532 words · Eric Cheng

Redis教學手冊

Redis教學手冊 項目 內容 文件版本 2.0 最後更新 2026 年 9 月 29 日 初版日期 2026 年 1 月 27 日(v1.0) 適用版本 Redis Open Source 8.10.x(最新修補版 8.10.2,2026-09-17);向下相容說明涵蓋 7.2 / 7.4 / 8.0~8.8 適用對象 資深/中階後端工程師、系統架構師、SRE、DevOps、DBA、資安與稽核人員、新進同仁 文件定位 企業標準技術白皮書/內部標準教材 審閱週期 每季檢視一次;Redis 發布新 minor 版本或重大 CVE 時即時更新 Created by Eric Cheng ⚠️ v2.0 重大改版說明:v1.0 以 Redis 7.2 為基準撰寫。自 2025 年 5 月起 Redis 進入 8.x 世代:Redis Stack 模組(JSON、Query Engine、Time Series、機率型資料結構)併入 Redis Open Source、授權新增 AGPLv3 選項、新增 Vector Set 與 Array 資料型態,並連續修補多個可導致遠端程式碼執行(RCE)的 CVE。本版以 Redis 8.10.2 為基準全面檢視每一章,修正 v1.0 約 40 處過時或錯誤內容,並新增第 14、15 章與附錄 B~E。完整更正清單請見附錄 C:版本更新紀錄,逐項查證來源請見附錄 D:查證紀錄。 ...

January 30, 2026 · 82 min · 17267 words · Eric Cheng

ELK Stack教學手冊

Logstash / Elasticsearch / Kibana(ELK Stack)教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Elastic Stack 9.5.4(2026-09-15 發佈):Elasticsearch/Logstash/Kibana/Filebeat 同版;相容說明涵蓋 8.19.x(支援至 2027-07-15) 文件定位 企業標準技術白皮書/內部標準教材 適用對象 資深軟體工程師、系統架構師、SRE/DevOps 工程師、資安與稽核人員 前置知識 Linux 基礎、Java/Spring Boot 應用程式、基本網路與 TLS 概念 使用情境 企業級 Logs Visualization 平台(與 Prometheus/Grafana 並存的 Observability 架構) 前一版本 1.0(2026-01-29,以 Elastic Stack 8.12 為基準) Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Elastic Stack 9.5;修正 v1.0 中已移除、已失效或錯誤的設定(_flush/synced、yum downgrade、Filebeat type: log、Logstash ssl => false、elasticsearch.yml 內的 index 層級設定、Kibana i18n.locale: "zh-TW"、ILM freeze 等);改以 Data Stream、ECS、API Key 與 TLS 為預設做法;新增授權層級、容量規劃、Data Tiers、ES|QL、Alerting、Streams、Snapshot/SLM、OpenTelemetry(EDOT)、Kubernetes(ECK)、故障排除手冊與 9.x 版本演進等章節。完整差異見 附錄 D 版本紀錄,查證依據見 附錄 E 查證紀錄。 ...

January 29, 2026 · 86 min · 18213 words · Eric Cheng

Prometheus與Grafana教學手冊

Prometheus與Grafana教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Prometheus 3.15.0(2026-09-24)、Prometheus LTS 3.13.x(支援至 2027-07-31)、Alertmanager 0.34.1、Grafana 13.2.3(2026-09-29)、node_exporter 1.12.1;完整矩陣見 1.5 版本基準與相容性矩陣 文件定位 企業標準技術白皮書/內部標準教材:Prometheus+Alertmanager+Grafana 的規劃、安裝、設定、使用、告警、安全、高可用、維運與升級 適用對象 資深工程師、DevOps/SRE、系統管理員、系統架構師、資安與稽核人員 前置知識 Linux 系統管理(systemd、防火牆、檔案權限)、容器與 Kubernetes 基本概念、HTTP 與 TLS、YAML 姊妹文件 《Metrics Visualization 教學手冊》:指標設計、PromQL 分析、儀表板設計、SLO 與架構決策的深入探討;《OpenTelemetry教學手冊》:OTel SDK 與 Collector;《Logs Visualization 教學手冊》:日誌視覺化 前一版本 1.0(2026-01-27,以 Prometheus 2.48、Grafana 10.2 為基準) Created by Eric Cheng 📌 v2.0 改版重點:章節重新編排為 15 章與 7 個附錄,全面對齊 Prometheus 3.x、Alertmanager 0.34 與 Grafana 13。 修正錯誤:修正 v1.0 中已不適用或會造成故障的內容。例如 3.x 發行包已不含 consoles、apt-key 已棄用、Alertmanager /api/v1 已移除(回傳 410)、match/source_match 已棄用、Teams Office 365 connector 已停用、快照還原步驟會刪除快照本身、儲存估算重複折算壓縮率、Grafana 稽核設定鍵錯誤且為 Enterprise 限定、Istio istio-telemetry 已不存在等。 新增內容:容量規劃、Alertmanager 安裝、Compose 與 Kubernetes 部署、離線安裝、Service Discovery 與 relabel、抓取保護、Remote Write/Agent mode、OTLP、Grafana 資料庫與認證整合、原生直方圖、Dynamic dashboards、Grafana Alerting 決策、規則單元測試、安全強化、高可用、自我監控、Prometheus 2.x → 3.x 遷移、Grafana 13 升級、AI 輔助維運與臺灣法規對應。 追溯依據:所有差異見 E.2 v1.0 → v2.0 更正對照表,查證依據見 附錄 F:查證紀錄。 閱讀指引 讀者角色 建議閱讀章節 初次接觸 Prometheus/Grafana 第 1 章 → 第 2 章 → 4.5 → 第 7 章 → 第 8 章 系統管理員(VM/實體機) 第 3 章 → 4.1–4.4 → 第 5、6 章 → 第 12 章 → 第 13 章 Kubernetes 平台工程師 2.6 → 4.6 → 5.2–5.4 → 11.1–11.2 → 12.4 SRE/值班人員 第 7 章 → 第 9 章 → 12.1 → 12.6 → 第 15 章 應用程式開發人員 2.2–2.3 → 7.4 → 14.1–14.2 → 14.5 架構師 2.6–2.7 → 3.2 → 第 11 章 → 14.3–14.4 資安/稽核人員 第 10 章 → 14.6 → 15.3 技術主管/決策者 1.1–1.5 → 2.7 → 13.1 → 14.6 → 14.7 本文慣例 標記 意義 ✅/❌ 建議做法/不建議做法 ⚠️ 容易出錯或有風險的地方 💡 實務技巧 🧪 實驗性功能:需 --enable-feature 或 feature toggle,行為可能在後續版本變更,不納入 LTS 支援範圍 📌 版本差異或改版說明 🏢 只在 Grafana Enterprise 或 Grafana Cloud 提供的功能 $變數 Grafana 範本變數 <尖括號> 需依環境替換的值 example.internal 範例內部網域,請替換為實際網域 ⚠️ 本手冊的指令以 RHEL 9/10 與 Ubuntu 24.04 LTS 為例,設定檔與 PromQL 皆以 Prometheus 3.15、Alertmanager 0.34.1、Grafana 13.2.3 撰寫,並以官方二進位檔的 promtool/amtool 驗證(見 附錄 F:查證紀錄)。若仍在 Prometheus 2.x,請先閱讀 13.2 Prometheus 2.x → 3.x 遷移。 ...

January 29, 2026 · 87 min · 18519 words · Eric Cheng

Logs Visualization教學手冊

Logs Visualization 教學手冊(ELK Stack) 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Elastic Stack 9.5.4(2026-09-15 發佈):Elasticsearch/Logstash/Kibana 同版;相容說明涵蓋 8.19.x(支援至 2027-07-15) 文件定位 企業標準技術白皮書/內部標準教材:Logs 視覺化、查詢分析、告警與治理 適用對象 資深軟體工程師、系統架構師、SRE/DevOps 工程師、資安與稽核人員 前置知識 Linux 基礎、Java/Spring Boot 應用程式、JSON 與 HTTP API、基本的 Elasticsearch 概念 姊妹文件 《ELK Stack 教學手冊》v2.0:平台安裝、設定、升級、ECK、叢集維運 前一版本 1.0(2026-01-26,以 Elastic Stack 8.x 早期做法為主) Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Elastic Stack 9.5。索引設計從「每日 index + rollover alias」改為 Data Stream + ECS + LogsDB。Logstash 範例改用 ssl_enabled、API Key 與 data stream 輸出。修正 v1.0 中已失效或錯誤的設定,例如 ILM freeze、node.attr.data、Alerting 規則格式、grok 自訂 pattern 錯誤、萬用字元刪除 index、法規年限等。新增多個章節:ES|QL、Log 分析(Pattern/Rate/Change Point)、Dashboard as Code、Elastic AI(Agent Builder、MCP)、AI 治理、查詢問題排除、導入路線圖、上線審查清單。完整差異見 D.2 v1.0 → v2.0 更正對照表,查證依據見 附錄 E:查證紀錄。 ...

January 26, 2026 · 68 min · 14298 words · Eric Cheng