---
title: "半年回顧：中大型系統 API Gateway (Kong) 架構評估及驗證"
description: "這半年我負責協助某中大型系統的專案第一期的 API Gateway 架構評估及驗證。本文紀錄了如何利用 Kong 實現圖資服務的路由管理、金鑰驗證，並整合 Prometheus、Grafana 與 ELK Stack 建立完整的監控體系。"
canonical_url: "https://blog.markkulab.net/post/kong-api-gateway-architecture-verification"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2025-12-14 10:00:00 +0800"
category: "DevOps"
tags: ["kong", "api gateway", "kubernetes", "prometheus", "grafana", "elk", "devops", "architecture"]
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---

# 半年回顧：中大型系統 API Gateway (Kong) 架構評估及驗證

在過去半年，我實際參與了一個中大型系統專案第一期的建置，主要負責 API Gateway 的架構評估與 PoC 驗證。

這件事不只是把服務架起來而已，真正的挑戰在於，要怎麼幫一堆不同性質的服務，設計一個同時兼顧安全性、可觀測性跟高可用性的對外入口。
![架構圖](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/./architecture.png)

## 專案背景與目標

客戶擁有大量內部 API 服務，希望透過數位轉型將其**對外開放並商業化**。核心目標是建立一個**自助式 API 租賃平台**，讓開發者能快速申請、按量付費使用，第一期的部份，就是評估方案和架構在正式開發系統前，驗證是否能夠達成需求。

## 導入前的痛點

| 面向 | 問題 |
|------|------|
| **流程效率** | 紙本申請、多層簽核、綁定 IP，金鑰核發曠日廢時 |
| **用量追蹤** | 無統一監控，不知誰在用、用多少，無法追蹤 |
| **安全穩定** | 缺乏統一認證、無流量控制，難以定位問題 |
| **系統整合** | 子系統各自為政，開發者對接成本高 |

## 導入後的價值

透過 API Gateway，我們可以帶來的價值：

- **效率提升**：API Key 申請從好幾天縮短至幾分鐘
- **透明計費**：即時用量統計，支援分級方案設計
- **統一入口**：單一 Gateway 存取所有 API，降低學習成本
- **自動化維運**：Rate Limiting、ACL 自動運作，集中監控異常

## 1. 核心架構：為什麼選擇 Kong？

在評估階段，我們需要一個能夠處理高並發請求、支援豐富插件且能與 Kubernetes 原生整合的解決方案，最終我們選用了 **Kong API Gateway** 搭配 **Redis** 與 **PostgreSQL** 作為核心架構。


根據我們的架構規劃：
* **流量入口**：所有的外部請求（Request）都由 Kong 統一接管。
![kong](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/kong.png)
* **狀態管理**：使用 **Redis** 處理 Kong 的 Cache 與 Rate Limiting 狀態。
* **配置儲存**：使用 PostgreSQL 儲存路由與插件配置，確保資料持久化。
* **GitOps 流程**：透過 GitLab CI/CD 與 ArgoCD 將設定檔同步至 K8s 環境。
![argocd](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/argocd.png)


### 基礎設施環境 (Infrastructure)
這次的架構驗證環境我們選擇部署於 **Google Cloud Platform (GCP)** 的虛擬機器 (VM) 上，使用 **RKE（Rancher Kubernetes Engine）** 自行架設 **Kubernetes Cluster** 進行測試。RKE 是 Rancher 推出的 Kubernetes 安裝與管理工具，主打快速、標準化地在現有主機上部署 Kubernetes 叢集，這讓我們能更彈性地模擬地端機房的網路限制與資源調度情境。

### 自動化部署策略 (Helm & Helmfile)
我們採用 **Helmfile** 來管理多個 Helm Releases（包含 Kong, Redis, Postgres 等）。為了讓架構更穩健並符合資安要求，我們採取了**狀態分離**的部署策略：

*   **Stateless 服務自動化**：Application 層級的元件（如 Kong Gateway, Kuma）完全交由 GitOps 自動同步。
*   **Stateful 與機敏資料手動化**：考量到資料安全性與持久化需求，**Secret (敏感資訊)** 與 **PersistentVolume (PV/PVC)** 均從 Helm Chart 中抽離。這些資源由維運人員**手動部署** (Manual Apply)，確保不會因為 CI/CD pipeline 的誤操作導致資料遺失或金鑰外洩。

### 效能
依據官方的[測試報告](https://developer.konghq.com/gateway/performance/benchmarks/)Kong Gateway 在單機 16 核心的資源下，能夠穩定處理 10 萬級別的 RPS，且即便在 HTTPS 加密與多重插件邏輯處理下，仍能保持 毫秒級 (Single-digit ms) 的極低延遲，適合對效能有嚴苛要求的微服務架構。

## 2. API 管理機制的實作 (API Management)

進行 API Gateway 架構驗證的首要目標，是將既有的子系統 API 納入統一管理。

### 路由與服務配置
我們利用 **Kong Manager** 進行了標準化的配置工作，重點如下：

*   **Gateway Services**：統一定義後端服務的轉發目標，涵蓋多種 API 服務協定。
*   **突破插件限制 (Plugin Limitation)**：由於 Kong 的機制限制單一路由無法重複掛載相同類型的插件（例如無法對同一 Route 同時設定兩組不同的 Rate Limiting 規則），我們採用 **拆分路由 (Route Splitting)** 的策略來解決。針對同一個 Backend Service，依據 URL 特徵拆分出多個 Route，以便分別掛載針對性的流量控制插件，實現更細粒度的管理。

    為實作差異化限流，我們採用 Route Splitting 策略。
    **舉例說明**：假設後端有一個電商服務 `ecommerce-service`，我們可以依據 Route Prefix 拆分成多條路由：

    | Route Name | Path Prefix | Rate Limit | 用途 |
    |------------|-------------|------------|------|
    | `product-list` | `/api/v1/products/*` | 1000 req/min | 商品列表查詢 |
    | `order-create` | `/api/v1/orders/*` | 100 req/min | 訂單建立（高運算） |
    | `payment-process` | `/api/v1/payments/*` | 50 req/min | 金流處理（敏感操作） |

    透過這種方式，不僅能針對不同 API 設定差異化的流量限制，還能**利用 Route Prefix 分別統計各類 API 的用量**，便於後續進行用量分析、計費與資源規劃。

*   **Routes 與 Rewrite**：設定精確的路徑轉發規則。針對舊版 API，我們靈活運用 **Request Transformer** 插件搭配正規表達式 (Regex) 進行 URI Rewrite（例如將 `~/(wms|wmts)/(?<path>api/item/1)$` 轉發），確保新舊系統能無縫接軌。

> 💡 **這過程中的重要體悟**：
> 進行 API Gateway 架構驗證時，強烈建議**優先進行 API 正規化 (Normalization)**。
> 如果後端 API 的 URL 結構混亂、命名不統一，雖然靠 Gateway 的 Regex Rewrite 勉強能轉發，但這會導致路由設定變得極度複雜且難以維護。長痛不如短痛，先梳理好 API 規範，整合起來才會事半功倍。

### 認證機制選擇：為何採用 Key Auth？
考量使用者組成與相容性，我們在 JWT、HMAC 與 API Key 間權衡後，採用「Header 型 Key Auth」。

- 不選 JWT：需處理過期/刷新與客端狀態，整合與維運成本高。
- 不選 HMAC：必須實作簽章/時戳與加解密，跨語言 SDK 維護成本高。
- 選 Key Auth：低門檻（Header 直接帶金鑰）、高相容（常見工具與框架原生支援）、可疊加安全（IP 白名單、ACL、Rate Limiting）。

### 使用者呼叫網路服務流程

以下以使用者呼叫流程，概述 Gateway 的實際運作步驟：

1. 發起請求：使用者攜帶 API Key 呼叫平台。
2. 認證與授權（Kong）：驗證 Key 的有效性及權限。
3. 流量控制（Rate Limit）：檢查是否超過方案額度。
4. 服務代理：轉發請求至後端子系統
5. 記錄與回傳：非同步寫入 Log，並回傳資料。

### 分級流量控制 (Tiered Rate Limiting)
為了合理分配運算資源，我們的流量分流策略如下：

1.  **頻次控制 (Rate Limit)**：針對一般 API 與高負載服務，分別設定「基礎」與「高頻次」通道，以滿足不同應用場景的需求。
2.  **頻寬控制 (Bandwidth Limit)**：針對大檔案傳輸，由於 Kong（即便是付費版）原生並未支援以「流量大小」為基準的精細控制，因此我額外**開發了客製化插件**來實作頻寬限制。

為了支援多節點 (Multi-Node) 的水平擴展，我們將 Rate Limiting 的策略改為 **Redis 模式 (Redis Mode)**。所有的計數與狀態皆統一儲存於 **Redis** 中，確保數據在不同節點間的一致性，避免單機計數導致的誤差。

![custom-plugin](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/custom-plugin-1.png)
![custom-plugin](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/custom-plugin-2.png)

### 客製化頻寬限制 (Custom Bandwidth Limiting)
除了基礎的請求次數限制 (Rate Limiting)，針對大檔案或高頻寬需求的服務，我們開發了客製化的 Kong Lua 插件：
* **多維度頻寬控制**：支援從「秒」到「年」的六種時間維度，並自動將 MB 轉換為 Bytes 進行精確運算。
* **高可靠性架構**：實作了 **Redis 緩存優化**與**故障轉移 (Fault Tolerance)** 機制。當 Redis 發生故障時，插件會自動降級為本地計數策略，防止單點故障影響 API 可用性。

### 精細的權限管控 (ACL & Consumer Groups)
針對付費與敏感資料，我們利用 **ACL (Access Control Lists)** 插件建立了嚴格的權限模型：
* 建立了 `backend_service`, `mobile_app` 等 Consumers。
* 將 Consumer 加入特定群組 (如 `business-tier-gold`)。

### 自動化上架流程（基於 Swagger 的 URL Sync）

在解決了核心的路由與權限配置後，下一個挑戰是如何讓眾多子系統快速且標準化地上架。為了避免人工手讀 Swagger 文件再手動 Key 設定所造成的失誤，我們設計了一套 **URL Sync 模式**。

這套機制的核心在於「規格即時同步」，系統不透過人工上傳檔案，而是直接讀取子系統提供的 **Swagger / OpenAPI Specification (OAS) URL**。

我們的自動化上架流程包含四個關鍵步驟：

- 規範讀取 (Swagger Sync)：管理員只需設定子系統的 Swagger/OAS URL，系統便會自動抓取最新的 API 規格。
- Kong 轉換 (Spec to Config)：系統解析 Swagger 內容後，自動在 Kong 內建立對應的 Route 與 Plugin，確保 Gateway 的路由規則與 Swagger 文件定義完全一致。
- 自動監控：上架的同時，系統會自動觸發 Uptime Kuma 建立健康檢查機制（Health Check），實現「服務一上線即監控」的目標。
- 對外發布：完成上述配置後，服務即正式上線並透過 Gateway 進行代理。

## 3. 打造全方位的監控體系 (Observability)

完善的監控是 Gateway 穩定運行的基石。這半年我們投入了大量心力整合 **ELK Stack** 與 **Prometheus** 生態系，實現從「日誌查詢」到「指標儀表板」的全方位可觀測性。

### Log 分析 (ELK Stack & Custom Lua)

Kong 的日誌插件本身已包含 `client_ip` 欄位，但若需要取得更多進階資訊（如經過多層 Proxy 後的原始 IP、`X-Forwarded-For` Header 等），可以透過 **UDP Log** 插件的 `custom_fields_by_lua` 注入客製化欄位：

```lua
custom_fields_by_lua = {
  remote_addr = "return kong.client.get_forwarded_ip()",
  real_ip = "return ngx.var.realip_remote_addr",
  x_forwarded_for = "return kong.request.get_header('x-forwarded-for')"
}
```

這段配置讓我們能取得更完整的來源 IP 資訊，精準分析流量來源與使用行為，對業務決策提供了關鍵數據。同時，我們採用 **Sidecar 模式** 部署 Filebeat，直接讀取 `/var/log/kong` 下的 access/error log 並轉發至 Elasticsearch，建立 `kong-logs-YYYY.MM.DD` 索引。
![log-sever](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/log-server.png)


### 指標監控 (Prometheus & Grafana)
利用 Kong 的 Prometheus 插件，我們收集了詳細的流量指標，並在 **Grafana** 建立了專屬儀表板：
![prometheus](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/prometheus.png)
* **Kong API Gateway Dashboard**：即時顯示 Request Rate、Latency（延遲）、Bandwidth（頻寬）等關鍵指標。
![grafana-kong-monitor](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/grafana-kong-monitor.png)
* **Kubernetes Node 硬體監控**：透過 Node Exporter 整合，可直接在 Grafana 檢視各 K8s 節點的硬體狀態（CPU、記憶體、Disk I/O、Network Traffic），便於掌握基礎設施的健康度。
![grafana-hardware-monitor](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/grafana-hardware-monitor.png)


### 服務可用性監控 (Uptime Kuma Clustering)

**Uptime Kuma** 是一款開源的自架式監控工具，類似於 Uptime Robot，但可以完全部署在自己的伺服器上。它提供了直覺的 Web UI，支援多種監控類型（HTTP、TCP、Ping、DNS 等），並能透過 Telegram、Slack、Email 等管道發送告警通知。對於需要監控大量內部服務且不想依賴外部 SaaS 的團隊來說，是個很好的選擇。

為了克服原生 Uptime Kuma 在大量監控下的效能瓶頸（約 800 支 API），我們將架構進行了改造：
* **自動化擴充 (RESTful API Extension)**：由於原生的 Uptime Kuma 缺乏對外的 API 介面，為了實現「服務一上線即監控」的自動化目標，我們自行擴充了 RESTful API 功能，讓日後上架API 時，自動監控。
* **Database 抽離**：將預設的 SQLite 替換為 **MariaDB**，並獨立部署為 `kuma-mariadb` 服務，支援更高的併發讀寫。
* **Clustering**：透過多個 Uptime Kuma 實例連接同一資料庫，實現負載分擔。

關於這部分的實作細節，我另外整理了一篇文章+：[使用 Vibe Coding 打造 Uptime Kuma 集群系統：從單機到高可用監控平台](https://blog.markkulab.net/implement-uptime-kuma-cluster-vibe-coding/)。
![Uptime Kuma 監控儀表板顯示 API 服務狀態與事件日誌](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/custom-uptime-kuma.png)


## 4. 告警機制的建立 (Alerting)
![alert-manager](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/alert-manager-2.png)
![alert-manager](https://blog.markkulab.net/content/markku/posts/kong-api-gateway-architecture-verification/images/alert-manager-1.png)

監控的最後一哩路是「告警」。我們在 Prometheus 與 **Alert Manager** 中定義了 **20 條告警規則**，分為 Critical、Warning 與 Info 三個等級。

以下是我們定義的幾個關鍵 Critical 告警規則 (PromQL)：

### 1. 服務完全不可用 (KongServiceDown)
當 Kong Namespace 下沒有任何 Up 的 Pod 時觸發：
```promql
sum(up{job="kong-metrics", namespace="kong"}) == 0
```

### 2. 高錯誤率 (KongHighErrorRate)
當 5xx 錯誤率超過 5% 時觸發，這通常代表後端服務異常：
```promql
(sum(rate(kong_http_requests_total{code=~"5.."}[5m])) by (instance)
 /
 sum(rate(kong_http_requests_total[5m])) by (instance)
) > 0.05
```

### 3. 高延遲 (KongHighLatency)
當 P95 請求延遲超過 2 秒時觸發 (Warning 等級)：
```promql
histogram_quantile(0.95, 
  sum(rate(kong_latency_bucket[5m])) by (le, instance)
) > 2000
```

### 4. 系統資源告警
* **硬碟空間**: `NodeDiskSpaceCritical` (可用空間 < 5%)
* **記憶體**: `NodeMemoryCritical` (使用率 > 95%)

## 5. 驗證與成果

這半年的最終成果，順利協助專案**通過第一期的系統驗收**。

在驗收過程中，我們使用開源 API 測試工具 **Hoppscotch** (前身為 Postwoman) 針對多項關鍵服務進行了密集的功能驗證。測試結果顯示，API Gateway 不僅能有效攔截未授權的惡意請求，其精細的流量控制機制也能在系統高負載下維持服務穩定，成功達成契約所訂定的各項效能指標。

## 6. 心得
Kong OSS 本身不提供群組規則、進階流量控管或僅限 route 層級的控制機制，也沒有 API 訂閱的原生概念，因此，若要使用 Kong 來實作 API 訂閱制或較為複雜的群組權限與流量規則，通常需要進行大量客製化；否則在設計上容易顯得不夠貼合需求，必須遷就既有的架構與邏輯。

---

## 關於本文與作者

本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/kong-api-gateway-architecture-verification)

授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結

### 關於作者

**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider

- 10+ 年資深軟體工程師，現為 AI 應用 Builder
- 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統
- 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎

### 作者開發的免費工具

以下工具皆可免費使用：

- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 <MermaidViewer> 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。
- [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材

### 每日 Podcast

- [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml

### 電子報

[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。