HAProxy、APISIX 與 LiteLLM：分層 API / LLM Gateway

我的實際用途

這三套軟體都有 proxy、routing 或 traffic policy 能力，但在我的 Home Gateway 架構裡不是三選一，也不是把所有請求依序通過三個功能相同的 gateway。

我的分層方式是：

Internet / API Client
          │
          ▼
Home Gateway
HAProxy：公開入口、TLS、hostname 分流
          │
          │ api.yihua.app
          ▼
APISIX：API route、consumer auth、rate limit、observability
          │
          ├── 一般 API ─────────────► Application services
          │
          └── LLM API
                   │
                   ▼
              LiteLLM：model alias、provider routing、usage / cost
                   │
                   ├──► LM Studio：本機模型
                   └──► OpenRouter / 其他 AI model API

HAProxy 擋在最外面，api.yihua.app 才轉給 APISIX；APISIX 判斷 route 是否屬於 LLM API，只有這部分再交給 LiteLLM。一般 application API 不需要多經過 LiteLLM。

三者比較

面向	HAProxy	Apache APISIX	LiteLLM
核心定位	Reverse proxy / load balancer	通用 API Gateway	LLM Gateway / provider abstraction
在架構中的位置	Home Gateway 最外層	`api.yihua.app` API policy layer	LLM API 專用內層
主要理解的對象	連線、TLS、Host、path、backend	Route、consumer、plugin、upstream	Model、provider、token、cost
TLS termination	主要負責	可支援，但此架構不是公網第一層	不作為主要 edge TLS 層
一般 API auth	可做基礎限制，但不是主要選擇	主要負責	僅處理 LLM 內層需要的 key / team context
HTTP rate limit	適合 edge 粗粒度保護	適合 consumer / route quota	適合 LLM project / model policy
Token / cost	不理解	可透過 AI plugin 處理	核心使用情境
Provider 轉換	不負責	AI plugin 可處理	核心使用情境
LM Studio	只能當一般 HTTP upstream	可當 AI upstream	當作 OpenAI-compatible model backend
OpenRouter	只能當一般 HTTP upstream	可由 AI plugin 串接	原生支援的 provider 路線
適合取代誰	可涵蓋很小型環境的部分 APISIX 工作	簡單需求下可涵蓋 HAProxy 或 LiteLLM 部分工作	不取代 Home Gateway 或通用 API Gateway

為什麼要分三層

HAProxy：讓 Home Gateway 保持穩定

Home Gateway 需要面對所有公開服務，不應為了某個 model provider 或 API consumer 的變動頻繁改動。HAProxy 只要穩定處理 TLS、hostname 與內部 upstream，api.yihua.app 的 lifecycle 就可以交給 APISIX。

APISIX：讓公開 API 有一致治理

不論後端是一般 application service 還是 LiteLLM，外部 client 都先經過相同的 authentication、route、rate limit、logging 與 tracing。這讓 LLM API 不會成為繞過公共 API policy 的特殊入口。

LiteLLM：隔離快速變動的模型供應商

LM Studio 與 OpenRouter 的 endpoint、credential、model name、能力與 fallback 條件都可能不同。LiteLLM 把這些差異封裝在內層，client 與 APISIX 只需要認得穩定的 model alias 和 LLM route。

重疊功能怎麼處理

這個架構最容易出問題的地方，不是少一個功能，而是同一個功能在三層各做一次。

我會採用以下原則：

HAProxy 只做 edge connection protection 與粗粒度分流。
APISIX 是公開 API authentication 與 request quota 的 source of truth。
LiteLLM 是 model routing、provider credential、token usage 與 cost policy 的 source of truth。
APISIX 若加 token limit，只作為公開平台的硬上限；LiteLLM 再處理 model 或 project 細項。
每一層都產生或傳遞同一個 request ID，才能跨 HAProxy、APISIX、LiteLLM 與 backend 追查問題。

何時可以少一層

分層不是越多越好。如果需求改變，可以縮減：

只有少量固定 API、沒有 consumer 或 plugin 治理時：HAProxy 可直接送 backend，不一定需要 APISIX。
只有 LLM API，而且 APISIX AI plugin 已涵蓋所有 provider 與成本需求時：可評估由 APISIX 直接連 LM Studio / OpenRouter。
LiteLLM 已是唯一公開服務，且 Home Gateway 不需承接其他網域時：可重新評估 APISIX，但仍需保留可靠的 edge TLS 與存取控制。

以目前用途而言，三層的價值是責任清楚，而不是單純增加 proxy 數量。

驗證清單

建置完成後不能只確認每個 process 有啟動，至少要驗證：

從外部透過 https://api.yihua.app 完成 TLS 與 DNS 路徑
HAProxy 傳遞正確的 Host、client IP 與 request ID
APISIX authentication、route 與 rate limit 實際生效
一般 API 不會誤送 LiteLLM
LLM chat completion 與 streaming 能從 APISIX 穿過 LiteLLM 到 LM Studio
LM Studio 不可用時，符合條件的請求能正確 fallback 到 OpenRouter
tool calling、structured output、embeddings 與 Responses API 依實際 client 逐項測試
APISIX 與 LiteLLM 的 log 可以用同一個 request ID 對照

只有完成一個真正的 model response round-trip，才能說這條 LLM Gateway 路徑已經可用。