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

這件事不只是把服務架起來而已，真正的挑戰在於，要怎麼幫一堆不同性質的服務，設計一個同時兼顧安全性、可觀測性跟高可用性的對外入口。

專案背景與目標

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

導入前的痛點

導入後的價值

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

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

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) 上，使用 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 的誤操作導致資料遺失或金鑰外洩。

效能

依據官方的測試報告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 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 注入客製化欄位：

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 索引。

指標監控 (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 是一款開源的自架式監控工具，類似於 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 集群系統：從單機到高可用監控平台。

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

6. 心得

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