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

Metrics Visualization 教學手冊

Metrics Visualization 教學手冊(Prometheus + Grafana) 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Prometheus 3.15.0(2026-09-24)、Prometheus LTS 3.13.x(支援至 2027-07-31)、Grafana 13.2.3(2026-09-29)、Alertmanager 0.34.1;完整矩陣見 1.3 版本基準與相容性矩陣 文件定位 企業標準技術白皮書/內部標準教材:指標設計、PromQL 分析、儀表板、告警與 SLO、架構決策與治理 適用對象 資深後端工程師、系統架構師、SRE/DevOps 工程師、技術主管、資安與稽核人員 前置知識 Linux 與容器、Kubernetes 基本概念、RESTful API、微服務架構、基本監控概念 姊妹文件 《Prometheus與Grafana教學手冊》:安裝、設定檔、維護、升級操作步驟;《OpenTelemetry教學手冊》:OTel SDK 與 Collector 前一版本 1.0(2026-01-26,以 Prometheus 2.x/Grafana 11 時期做法為主) Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Prometheus 3.x 與 Grafana 13。修正 v1.0 中無法執行或結果錯誤的範例,例如 relabel 位址改寫、predict_linear 子查詢語法、錯誤率告警百分比顯示、不存在的指標名稱 redis_keys_total、Pushgateway「TTL」說法、以「P99 達標時間比例」定義延遲 SLO 等。新增原生直方圖、OTLP 與 UTF-8、Kubernetes Operator、Alertmanager 設計、規則單元測試、Dynamic dashboards、Dashboard as Code(Git Sync)、Grafana Alerting、多視窗多燃燒率告警、SLO 工具鏈、Grafana Assistant 與 MCP、AI 治理,以及第 9 章「企業級部署、容量與治理」。完整差異見 D.2 v1.0 → v2.0 更正對照表,查證依據見 附錄 E:查證紀錄。 ...

January 26, 2026 · 64 min · 13522 words · Eric Cheng

微前端教學手冊

微前端教學手冊 版本:1.0 最後更新:2026 年 1 月 適用對象:資深工程師 / Tech Lead / Architect 最後更新: 2026年1月23日 適用於: 微前端 Created by: Eric Cheng 微前端(Micro-Frontend)教學手冊 版本:1.0 適用對象:資深前端/全端工程師、Tech Lead、架構師 最後更新:2026 年 1 月 目錄 微前端的核心價值與真正要解決的問題 1.1 什麼是微前端? 1.2 微前端真正要解決的問題 1.3 什麼情況「不該用微前端」 1.4 微前端 vs 單體前端 vs Monorepo 1.5 本章實務案例 微前端主流架構模式比較 2.1 基座(Shell / Container)模式 2.2 Runtime Integration vs Build-time Integration 2.3 iframe / Web Components / Module Federation 比較 2.4 主流框架方案比較 2.5 本章實務案例 Module Federation 深度解析 ...

January 23, 2026 · 34 min · 7103 words · Eric Cheng

Claude Agent Skills教學手冊

Claude Agent Skills 使用教學手冊 版本:1.0 最後更新:2026 年 1 月 適用對象:新進軟體工程師、系統分析師、AI 導入成員 最後更新: 2026年1月8日 適用於: Claude Code Created by: Eric Cheng 目錄 前言 文件目的 適用對象 如何使用本手冊 第一章:Claude Agent 與 Agent Skills 基礎概念 1.1 什麼是 Claude Agent 1.2 什麼是 Agent Skills 1.3 Agent / Tool / Skill 的差異與關係 1.4 為什麼要使用 Agent Skills 第二章:Agent Skills 的設計理念 2.1 Skill 的責任邊界(Single Responsibility) 2.2 Skill 與 Prompt 的差異 2.3 Skill 是可重用、可組合的能力單元 2.4 官方 Skills Repo 的設計原則 第三章:官方 Skills Repository 結構說明 3.1 Skills GitHub 專案的目錄結構 3.2 Skill 的命名慣例 3.3 Skill 定義中的關鍵元素 第四章:Agent Skills 的使用方式 4.1 如何在 Agent 中呼叫 Skill 4.2 Skill 在任務流程中的角色 4.3 單一 Skill vs 多 Skill 組合 第五章:實務範例 5.1 需求文件產生 Skill 5.2 程式碼 Review / 重構 Skill 5.3 測試案例產生 Skill 第六章:新手常見錯誤與最佳實務 6.1 Skill 設計過大或過小的問題 6.2 把 Skill 當成一次性 Prompt 的錯誤用法 6.3 如何讓 Skill 更容易被重用 6.4 如何讓 Agent 行為更穩定 第七章:團隊導入建議 7.1 適合先從哪些類型的 Skill 開始 7.2 如何建立內部 Skill Library 7.3 與既有開發流程整合 7.4 導入成熟度階段建議 附錄:檢查清單(Checklist) Skill 建立前檢查 SKILL.md 撰寫檢查 Skill 發布前檢查 團隊導入檢查 參考資源 官方資源 延伸閱讀 前言 文件目的 本手冊旨在協助團隊成員快速理解並導入 Claude Agent Skills,透過系統化的教學內容,讓新進同仁能夠: ...

January 12, 2026 · 14 min · 2880 words · Eric Cheng