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

首頁關於我

DevOps

Mark Ku

December 14, 2025

2 min

在這過去的半年裡，我深度參與了「地理資訊平台」的建置案，主要負責第一期的 API Gateway 架構評估及驗證。

這項任務不僅僅是部署一個服務，更具挑戰的是要為海量的地理空間資訊打造一個兼具安全性、可觀測性與高可用性的流量入口。以下將整理這段時間的架構規劃與實作細節，分享我們如何從零打造這套系統。

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

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

根據我們的架構規劃：

流量入口：所有的外部請求（Request）都由 Kong 統一接管。
狀態管理：使用 Redis 處理 Kong 的 Cache 與 Rate Limiting 狀態。
配置儲存：使用 PostgreSQL 儲存路由與插件配置，確保資料持久化。
GitOps 流程：透過 GitLab CI/CD 與 ArgoCD 將設定檔同步至 K8s 環境。

基礎設施環境 (Infrastructure)

這次的架構驗證環境我們選擇部署於 Google Cloud Platform (GCP) 的虛擬機器 (VM) 上，自行架設 Kubernetes Cluster 進行測試。這讓我們能更彈性地模擬地端機房的網路限制與資源調度情境。

自動化部署策略 (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 的誤操作導致資料遺失或金鑰外洩。

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

進行 API Gateway 架構驗證的首要目標，是將既有的地理空間資訊服務 API 納入統一管理。

路由與服務配置

我們利用 Kong Manager 進行了標準化的配置工作，重點如下：

Gateway Services：統一定義後端服務的轉發目標，涵蓋 WFS、WMS、3D Tiles 等多種 GIS 服務協定。
突破插件限制 (Plugin Limitation)：由於 Kong 的機制限制單一路由無法重複掛載相同類型的插件（例如無法對同一 Route 同時設定兩組不同的 Rate Limiting 規則），我們採用 拆分路由 (Route Splitting) 的策略來解決。針對同一個 Backend Service，依據 URL 特徵拆分出多個 Route，以便分別掛載針對性的流量控制插件，實現更細粒度的管理。
Routes 與 Rewrite：設定精確的路徑轉發規則。針對舊版 API，我們靈活運用 Request Transformer 插件搭配正規表達式 (Regex) 進行 URI Rewrite（例如將 ~/(wms|wmts)/(?<path>api/item/1)$ 轉發），確保新舊系統能無縫接軌。

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

分級流量控制 (Tiered Rate Limiting)

為了合理分配運算資源，我們不採用單一限制，而是依據服務資源消耗（如輕量 API vs 重量級 3D Tiles）與用戶等級設計了分級策略。

我們的流量分流策略如下：

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

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

客製化頻寬限制 (Custom Bandwidth Limiting)

除了基礎的請求次數限制 (Rate Limiting)，針對 GIS 領域特有的高頻寬需求（如 3D Tiles 大檔傳輸），我們開發了客製化的 Kong Lua 插件：

多維度頻寬控制：支援從「秒」到「年」的六種時間維度，並自動將 MB 轉換為 Bytes 進行精確運算。
高可靠性架構：實作了 Redis 緩存優化與故障轉移 (Fault Tolerance) 機制。當 Redis 發生故障時，插件會自動降級為本地計數策略，防止單點故障影響 API 可用性。
智慧回滾機制：在流量超限被攔截時，會自動執行 Rollback 扣除該次請求的計數，確保配額計算精確無誤。

精細的權限管控 (ACL & Consumer Groups)

針對付費與敏感資料，我們利用 ACL (Access Control Lists) 插件建立了嚴格的權限模型：

建立了 backend_service, mobile_app 等 Consumers。
將 Consumer 加入特定群組 (如 business-tier-gold, map-data-premium)。
在 Route 層級啟用 ACL，例如 allow: ["advanced"]，確保只有授權用戶能訪問高價值的 GIS 資料。

安全防護

除了基本的 Key Auth，我們還啟用了 Correlation ID 插件，為每個請求注入唯一識別碼 (X-Correlation-ID)，這在跨系統除錯時不僅能追蹤軌跡，也是資安稽核的重要依據。

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

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

Log 分析 (ELK Stack & Custom Lua)

為了確保日誌中能紀錄使用者的真實 IP（而非 Load Balancer IP），我們在 UDP Log 插件中注入了客製化 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')"
}

這段配置讓我們能精準分析地理圖資的熱點分佈，對業務決策提供了關鍵數據。同時，我們採用 Sidecar 模式 部署 Filebeat，直接讀取 /var/log/kong 下的 access/error log 並轉發至 Elasticsearch，建立 kong-logs-YYYY.MM.DD 索引。

指標監控 (Prometheus & Grafana)

利用 Kong 的 Prometheus 插件，我們收集了詳細的流量指標，並在 Grafana 建立了專屬儀表板：

Kong API Gateway Dashboard：即時顯示 Request Rate、Latency（延遲）、Bandwidth（頻寬）等關鍵指標。
Kubernetes Node 硬體監控：透過 Node Exporter 整合，可直接在 Grafana 檢視各 K8s 節點的硬體狀態（CPU、記憶體、Disk I/O、Network Traffic），便於掌握基礎設施的健康度。

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

為了克服原生 Uptime Kuma 在大量監控下的效能瓶頸（約 800 支 API），我們將架構進行了改造：

自動化擴充 (RESTful API Extension)：由於原生的 Uptime Kuma 缺乏對外的 API 介面，為了實現「服務一上線即監控」的自動化目標，我們自行擴充了 RESTful API 功能，讓 CI/CD Pipeline 能在部署時自動註冊監控項目，無須人工介入。
Database 抽離：將預設的 SQLite 替換為 MariaDB，並獨立部署為 kuma-mariadb 服務，支援更高的併發讀寫。
Clustering：透過多個 Uptime Kuma 實例連接同一資料庫，實現負載分擔。

關於這部分的實作細節，我另外整理了一篇文章：使用 Vibe Coding 打造 Uptime Kuma 集群系統：從單機到高可用監控平台。

4. 告警機制的建立 (Alerting)

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

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

1. 服務完全不可用 (KongServiceDown)

當 Kong Namespace 下沒有任何 Up 的 Pod 時觸發：

sum(up{job="kong-metrics", namespace="kong"}) == 0

2. 高錯誤率 (KongHighErrorRate)

當 5xx 錯誤率超過 5% 時觸發，這通常代表後端服務異常：

(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 等級)：

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 不僅能有效攔截未授權的惡意請求，其精細的流量控制機制也能在系統高負載下維持服務穩定，成功達成契約所訂定的各項效能指標。