作者 I 楊澤淼，騰訊天美工作室群后臺開發工程師

本文整理自 2025 年 4 月 12 日楊澤淼在 APISIX 深圳 Meetup 的演講。

關于騰訊天美

天美工作室群 Timi Studio Group 是騰訊游戲旗下精品游戲研發工作室，也是多款熱門手游的研發商，包括《使命召喚手游》、《寶可夢大集結》、《Honor Of Kings》（《王者榮耀》國際版）和《王者榮耀》。

其代表作《王者榮耀》是全球最受歡迎的 MOBA 手游之一，截止到 2023 年 12 月，王者榮耀單日活躍人數最高破 1 億 6 千萬，最高同時在線人數破 300 萬，總下載次數逾 38 億次，注冊用戶數亦突破 3 億。2017 年 5 月取得全球手游綜合收入榜冠軍。（數據來源：維基百科）

TAPISX 業務網關

我們所在的團隊在業務開發中主要采用 Golang 語言，同時負責部分運維職責。鑒于團隊在運維領域的經驗相對有限，且希望控制成本，我們期望借助業務網關統一處理多項事務，如鑒權、流量錄制等。此外，由于我們在海外業務中需要頻繁遷移基礎設施，因此無法依賴云上方案，并要求所有數據和組件具備遷移能力。

TAPISIX 簡介

雖然 APISIX 完全開源且擁有豐富的插件生態，但在公司內部使用時，仍需考慮和公司現有基礎設施的集成，例如對接公司內部的服務發現、日志規范及 trace 上報等。這些功能是公司內特定的，無法直接合并到開源 upstream 中。因此我們基于 APISIX，添加了一系列專門為公司內部環境設計的插件，開發了定制化版本 TAPISIX。

我們的服務運行在 Kubernetes(k8s）集群上，以 APISIX 作為流量入口，與內部業務服務對接。服務發現采用公司內部的北極星系統，指標監控借助 APISIX 社區版的 Prometheus 實現，日志和 trace 采集都是通過 OpenTelemetry 進入 ClickHouse。在 CI 工具方面，我們采用 OCI（類似 GitHub Actions），支持通過 YAML 定義流水線；CD 工具則選用 Argo CD，基于開源方案實現持續部署。

由于我們的業務主要面向海外市場，對合規性要求極為嚴苛，這導致許多公司內部組件無法直接落地使用。

本次分享將涵蓋以下四個方面：

1. 網關拓展：如何根據業務需求擴展網關功能。

2. 部署運維：網關的部署與日常運維實踐。

3. Runtime 運維：Runtime 環境的維護與優化。

4. 其他經驗：團隊在網關運營中積累的實用經驗。

一、網關拓展

目標與挑戰

我們的目標是構建一個業務網關，依托于 APISIX 的插件能力滿足定制化需求。作為業務團隊，我們面臨以下挑戰：

1. 開發門檻高：一線開發人員熟悉 Golang，但對 Lua 語言和 APISIX 插件開發不熟悉，導致上手成本高。

2. 插件可靠性：如何確保開發的插件能夠安全、穩定地上線。

核心問題

1. 如何降低開發門檻？

2. 如何快速驗證插件功能？

3. 如何確保插件的可靠性？

解決方案

為解決上述問題，我們從以下四個方面入手：

1. 開發規范（可維護性）

2. 本地快速運行與測試

3. 流水線建設（構建流程）

4. 可靠性保證

1. 開發規范

開發規范易于理解，我們需定義一個庫，明確插件的存儲路徑，并要求插件采用單文件形式，與 APISIX 的單文件插件機制保持一致，便于管理和維護。

為降低開發門檻，我們支持本地快速運行與測試。借助 APISIX 的 Docker 鏡像，可將本地插件通過卷映射至容器中，實現便捷部署。同時，利用下游的 echo-service（基于開源 Node.js 開發的服務），可模擬上游行為。該服務能夠返回請求的所有內容，如請求頭等。通過在請求中添加特定參數（如 HTTP 狀態碼 500），可模擬上游的異常行為，從而全面驗證插件功能。

2. 本地快速運行與測試

為降低開發門檻并加速驗證，我們提供了便捷的本地開發環境支持：

1. 文件映射：通過將本地插件文件映射到 Docker 容器中，開發人員可以實時測試插件的變更。

2. Makefile 構建：構建 Makefile 文件，支持通過 make run-dev 命令快速啟動插件測試環境，確保本地文件與容器無縫連接。

3. 瀏覽器直接訪問：開發人員只需在瀏覽器中訪問相關接口，即可直接驗證插件功能，無需額外部署或配置。

通過定義開發規范和提供本地快速開發支持，我們有效降低了開發門檻，加速了插件的驗證過程。開發人員可以專注于功能實現，而無需擔心復雜的部署和測試流程，從而提高了整體開發效率。

3. 流水線建設（構建流程）

在流水線建設過程中，需要保證可靠性和開發插件的穩定性。開發流程如下：

1. 分支管理與 PR 流程：

a. 開發人員從 master 分支拉取一個新分支進行開發。

b. 完成開發后，提交 Pull Request（PR）至 master 分支。

1. Webhook 觸發：提交 PR 后，系統會自動觸發 Webhook，啟動流水線。

2. 流水線檢測：

a.Lint 檢查：主要檢查代碼格式規范。

b.單元測試：運行單元測試，驗證插件的功能是否符合預期。

c.Try Build：使用源代碼構建鏡像，驗證代碼的可構建性。

4. 可靠性保障（CR、lint、單側、黑盒測試）

我們使用了 Grafana 旗下的 k6 測試框架進行核心用例的驗證。k6 框架支持聲明式編寫測試用例，可以覆蓋多種場景。我們定期回放這些用例，檢查接口是否通過。例如，即使只是修改了插件，我們也會進行全面的回放測試，包括解析能力和服務發現能力等。

核心用例與 k6 測試框架

• k6 測試用例：包含幾百個測試用例，覆蓋了核心流程，確保插件的可靠性。

通過本地開發、快速驗證、MR 提交、流水線檢測、可靠性保障以及打包部署的完整流程，我們確保了插件從開發到上線的每個環節都經過嚴格的質量控制。

二、部署運維

接下來簡要介紹 APISIX 的部署模式，分為數據面和控制面。數據面負責實際的代理工作；控制面負責管理配置，包括管理端和其他功能，將配置寫入 etcd，數據面從 etcd 讀取配置并加載到內存中，完成路由功能。

APISIX 提供了三種部署方式，以適應不同的生產環境需求：

1. 傳統模式：數據面和控制面同時部署在一個實例中。

2. 分離模式：數據面和控制面獨立部署，數據面宕機時，控制面仍可操作和修改。

3. 獨立模式：僅部署數據面，配置從本地 YAML 文件加載，不依賴 etcd。

只保留數據面的獨立模式也是我們使用的方式，所有的配置都存儲在本地，避免了對 etcd 的依賴。這種模式更適用于海外場景。由于 etcd 屬于數據庫選型，部分云廠商不提供 etcd 服務，且海外對數據合規性要求嚴格，并且我們的部署環境在 k8s，因此也采用了對 k8s 友好的配置管理方式。

• YAML 配置：所有配置直接存儲在 YAML 文件中，便于管理和自動化部署。

• ConfigMap 存儲：將 yaml 文件直接放置在 k8s 的 ConfigMap 中，確保配置的版本化和可追溯性。

我們定義網關為不可變基礎設施，日常運營中不會進行頻繁的變更。即使是路由變更，也被視為一次完整的變更操作。

Kubernetes 配置管理與部署實踐

問題描述：在管理 config.yaml 時，我們發現 k8s 的部署實際上依賴于一系列復雜的配置文件，例如 Service.yaml、ConfigMap.yaml 和 Workload 等。這些配置文件數量龐大且細節繁多，容易導致管理上的復雜性和錯誤。

解決方案：K8s 社區提出 Helm Chart 作為解決方案。Helm Chart 是一種將 k8s 配置文件模板化的工具，能夠顯著簡化配置管理。APISIX 官方提供了 Helm Chart，助力我們高效管理核心配置（如節點數等），無需手動填寫大量 YAML 文件。目前，Helm Chart 已有效解決配置復雜性問題。

衍生問題：然而，衍生出來的另一個關鍵問題是：如何將 Helm Chart 或 YAML 文件部署到 k8s集群上。

解決方案：為此，我們采用了 GitOps 模式，通過流水線將 YAML 文件部署到 K8s 集群。在 GitOps 模式下，所有配置以代碼形式存儲在 Git 中。借助 Git 觸發 CI/CD 流程，實現自動化部署。config.yaml 和其他配置文件均存儲在 Git 中，確保了配置的版本化管理和可追溯性。通過這種方式，我們不僅簡化了配置管理，還實現了部署流程的自動化和標準化，提升了整體效率和可靠性。

部署流程示例

在上圖展示的部署流程中，SRE（Site Reliability Engineer）代表用戶進行配置管理。任何修改，如路由變更或鏡像更新，都需要通過修改 Helm Chart 倉庫來實現。修改后，Argo CD 會自動檢測到變更并觸發流水線，拉取最新的配置完成部署。另外，Git 和 K8s 之間建立了強同步關系，確保配置的一致性和可靠性。

例如，部署完成后，我擁有 k8s 集群的完全訪問權限，對 service.yaml 文件進行了修改。Argo CD 會持續監控集群狀態，若發現實際資源與 Git 倉庫中的配置不匹配，將自動觸發同步，使用 Git 倉庫中的內容覆蓋集群配置。

GitOps 的優勢

這種模式帶來諸多益處：

• 配置一致性：所有配置變更均通過 Git 進行，確保系統配置的一致性。

• 安全性：減少手動修改帶來的潛在風險，所有變更均有跡可循。

• 自動化部署：基于 Argo CD 或 Git 的版本變更，實現自動化部署與灰度發布。

在實際部署中，我們僅需維護兩個倉庫：代碼庫（存放應用代碼）、部署庫（如下圖，存放所有部署相關的配置文件）。

這種簡化模式使得許多傳統的管理平臺變得不再必要，整個流程更加高效簡潔。需要將應用部署到其他集群時，只需從部署庫拉取相應分支，并應用到目標集群即可，整個過程簡單高效。

在以上部署實踐中，APISIX 的關鍵配置文件（如路由配置和 config.yaml 啟動配置）被整合到一個 Helm Chart 庫中，便于統一管理和部署。然而，這種部署方式也可能帶來一個問題：它本質上將 APISIX 當作了一個普通服務來部署。

為什么不用 APISIX Ingress Controller？

APISIX Ingress Controller 作為社區為 k8s 提供的官方解決方案，其核心流程如下：通過定義 APISIXRoute 等自定義資源，以 YAML 文件的形式在 k8s 中描述路由等配置。

將這些 CRD 部署到 k8s 集群后，Ingress Controller 會持續監聽相關的 CRD 資源。解析 CRD 中的配置信息，并通過調用 APISIX 的 Admin API 將配置同步到 APISIX 中。Ingress Controller 主要為了進行 CRD 和 APISIX 之間的部署，最終還是將數據寫入 etcd。

經過審慎評估，我們發現 APISIX Ingress Controller 的部署和運維模式并不完全適配我們的團隊需求，主要有以下原因：

1. 業務網關定位：作為業務網關，我們更側重于降低開發和運維門檻，提高易用性和開發效率。

2. 運維成本考量：Ingress Controller 的引入會增加一層額外的運維復雜度。它需要與 k8s 進行深度集成，涉及額外的 Golang 編寫的代碼和 k8s API 調用，這無疑提高了運維的難度和成本。

3. 環境一致性問題：由于需要依賴 k8s 環境，本地開發環境與線上部署環境存在差異，可能導致諸如“本地可以正常運行而線上出現問題”等不一致的情況，增加排查和解決故障的難度。

4. 版本耦合：APISIX 版本與 Ingress Controller 版本之間存在強耦合關系。由于我們的 APISIX 基于開源版本進行了定制化修改，只維護特定版本的兼容性。這可能導致某些 API 不被支持或出現兼容性問題，進而影響系統的穩定性和可靠性。

5. 配置不透明性：通過 Ingress Controller 的方式，最終配置還需寫入 etcd，這可能導致配置狀態不一致的問題。例如，Ingress Controller 監聽失敗或 etcd 狀態不佳時，可能會引發連接過多等問題，使得整個架構鏈路變得更加不透明和復雜。與之相比，Helm Chart 的優勢在于其提供了一個完整且可審計的 YAML 文件，其中包含了所有的路由配置，使得路由狀態清晰可見。

因此，我們沒有選擇 APISIX Ingress Controller。

如何實現配置熱更新？

在 k8s 環境中部署 APISIX 時，實現配置熱更新是確保系統穩定性和可用性的關鍵。APISIX 的配置主要分為兩種：

1. APISIX 路由配置（apisix.yaml）：采用傳統的加載方式，用于定義路由配置，包括路由的 upstream 以及相應的轉發規則等內容。

2. 啟動配置（config.yaml）：主要作為啟動項配置文件，用于指定諸如 APISIX 運行端口等關鍵參數。某些配置項的變更需要重啟服務才能生效。

k8s 資源部署流程

1. 修改 Git 配置：對上述提及的 Git 配置進行修改。

2. 交付 Argo CD：將修改后的配置交付給 Argo CD。

3. 生成資源文件：Argo CD 依據修改后的配置，通過 Helm Chart 生成相應的 ConfigMap、Service YAML 等資源文件。

在 k8s 環境中，apisix.yaml 和 config.yaml 這些資源文件均以 ConfigMap 的形式存在。

APISIX 配置變更處理機制

問題描述： 當 APISIX 相關配置發生變更時，對應的 ConfigMap 會相應地進行更新，但此時 Deployment（即 APISIX 部署實例）本身尚未改變。

解決方案：為解決這一問題，k8s 社區提出了相應的解決方案，即通過合理地拆分配置，并巧妙地利用哈希與注解方式，將需要變更的 ConfigMap 內容以注解的形式注入到 Deployment 中，從而實現配置的動態更新。

• apisix-configmap.yaml：主要用于存放 APISIX 的核心業務邏輯配置，如路由規則等。更改此類 ConfigMap 時，由于 APISIX 內置的定時器機制，其會定期從本地文件讀取并更新內存中的配置信息，因此無需重啟 APISIX 服務，即可實現配置的更新與生效。

• config-configmap.yaml：主要包含 APISIX 運行環境等基礎配置。當此類 ConfigMap 發生變更時，由于其涉及 APISIX 服務的基礎運行環境設置，為了確保新配置能夠正確地被加載與應用，需要重啟 APISIX 部署實例。

更新觸發機制：為實現配置變更的自動檢測與更新流程觸發，我們采用注解方式對 ConfigMap 內容進行哈希處理，并將哈希值寫入 deployment.yaml 文件。當配置變更導致哈希值更新時，deployment.yaml 文件會相應發生變化，k8s 系統檢測到這一變化后，會自動觸發更新流程，從而確保 APISIX 部署實例能夠及時應用新的配置。

三、Runtime 運維

Runtime 運維主要分為三個部分：metrics 采集、trace 上報、日志收集。

1. Metrics 采集

k8s 集群提供了官方的 metrics 采集解決方案，名為 Kubernetes Prometheus Operator。通過定時抓取服務暴露的 metrics 端口和信息，定期將數據上報至外部系統，如 Prometheus。由于該部分未進行深度定制，此處不再贅述。相關的 k8s 配置在 APISIX 的 Helm Chart 中已有完整描述。

2. Trace 上報

Trace 上報基于 APISIX 提供的 OpenTelemetry 插件實現。該插件通過 OpenTelemetry 協議將數據上報至 OpenTelemetry Collector，最終將數據寫入 ClickHouse，完成 Trace 數據的采集與存儲。

3. 日志收集

日志收集同樣采用 OpenTelemetry 協議。然而，APISIX 社區版的 OpenTelemetry 插件僅支持 Trace 上報，而不包括日志上報功能。因此，我們建議采用本地日志存儲方式，通過 sidecar 模式將 APISIX 日志寫入一個共享文件夾。在 Deployment 中掛載另一個 Pod，該 Pod 與 APISIX Pod 共享同一個日志文件夾，從而實現日志的采集，并通過 OpenTelemetry 協議進行上報。

另外，社區提供的監控面板功能較為通用，針對性不足。因此，我們基于采集到的指標數據定制開發了專用的監控面板，以滿足特定的監控需求。告警系統則基于 Grafana 的開源方案構建，利用其強大的可視化和告警功能，實現對 APISIX 運行狀態的實時監控和告警。

四、其他經驗

Standalone 路由管理

我們首先對路由管理策略進行了優化。在早期的路由管理實踐中，我們將所有路由配置集中放置在一個單一的 config 文件中。然而，這種做法很快暴露出問題，隨著業務的發展和路由數量的增加，YAML 文件的規模急劇膨脹，給維護帶來了巨大挑戰。

正如業內調侃的那樣，“k8s 運維工程師是‘YAML 工程師’”之說，恰是因為面對海量的 YAML 配置文件而產生的無奈與自嘲。為應對這一難題，我們從兩個關鍵維度出發，對路由進行了合理拆分。

• 模塊化拆分：依據 APISIX 的路由規范，將配置劃分為 collector 配置與 consumer 配置的模塊，實現了功能層面的解耦與分類管理。

• 域名維度拆分：針對 route 文件，按照域名這一核心維度進行拆分，使路由配置更加精細化、條理化，便于后續的維護與擴展。

重復路由配置

在 k8s 的 upstream 配置中，存在多種類型，這些不同類型配置間的差異往往僅體現在 service name 這一關鍵要素上。在引入新版本并更新 Lua 包后，我們充分利用其支持的錨點功能，對重復配置問題進行了有效治理。通過錨點機制，實現了對共性配置部分的抽象與復用，在實際應用中成功減少了約 70% 的重復配置內容，極大地提升了配置管理的效率與簡潔性，降低了因重復配置而引入錯誤的風險。

APISIX 替換 Ingress 遷移實踐

初始架構與背景

最初，我們的鏈路架構為：Edge one 作為一個 CDN，然后流量經 CLB 轉發至 Ingress（Istio），最后到達內部的 APISIX。

Ingress 的存在主要源于歷史原因，當時在云上選擇了 Istio 作為服務網格解決方案。然而，隨著業務的發展和技術的演進，我們計劃直接替換掉 Ingress，采用 APISIX 作為 K8s Ingress，以實現更高效、更靈活的流量管理。

遷移方案評估

在遷移過程中，我們評估了兩種主要的遷移方案：

●方案一 CDN 灰度與雙域名：即在現有架構旁側部署一個新的 APISIX 實例，引導新的流量至該實例。然而，此方案的缺點在于前端需要修改域名，可能會對用戶訪問和業務連續性產生一定影響，因此我們謹慎考慮后暫時擱置了這一方案。

●方案二 CDN 流量調配：選擇這種方式，它可以配置多個 CLB 路由，并且能夠實現基于百分比的流量推送。這種方式的優勢在于能夠在不改變用戶訪問入口的前提下，逐步將流量切換至新的 APISIX 實例，并且可以根據實際情況靈活調整流量比例，便于觀察和評估遷移效果。

最終方案實施與優勢

我們最終選擇了方案二，成功形成了一條新的流量鏈路：新流量通過灰度方式直接到達 APISIX。這一新的鏈路架構帶來了以下顯著優勢：

• 端側無變更：前端用戶訪問的域名和入口保持不變，確保了用戶體驗的連續性，避免了因域名變更可能引發的用戶困惑或訪問中斷問題。

• 后端全自助：后端具備自主控制和管理流量切換的能力，可根據業務需求和系統狀態靈活調整流量分配，無需依賴外部協調整合。

• 快速回退能力：由于具備灰度發布的能力，如果在遷移過程中發現任何問題，可以迅速將流量回退至原有的鏈路，最大程度降低遷移風險，保障業務的穩定運行。

• 用戶無感知遷移：整個遷移過程對用戶而言是透明的，用戶在訪問業務時不會察覺到后端架構的變化，確保了業務遷移的平滑性和無縫性。

以下展示的是遷移的整體流程。

總 結

我們團隊基于 APISIX 二次開發了 TAPISX 業務網關。APISIX 作為我們業務網關的核心組件，在滿足海外業務的高合規性要求、降低開發和運維門檻、提高系統靈活性和可靠性等方面發揮了關鍵作用。它為我們打造了一個高效、穩定、靈活的業務網關平臺，為業務的持續發展提供了有力支持。未來，我們期待與 APISIX 一起，探索更多創新的應用場景，為業務創造更大的價值。