作者 I 楊澤淼，騰訊天美工作室群后臺開發(fā)工程師
本文整理自 2025 年 4 月 12 日楊澤淼在 APISIX 深圳 Meetup 的演講。
關于騰訊天美
天美工作室群 Timi Studio Group 是騰訊游戲旗下精品游戲研發(fā)工作室，也是多款熱門手游的研發(fā)商，包括《使命召喚手游》、《寶可夢大集結》、《Honor Of Kings》（《王者榮耀》國際版）和《王者榮耀》。
其代表作《王者榮耀》是全球最受歡迎的 MOBA 手游之一，截止到 2023 年 12 月，王者榮耀單日活躍人數(shù)最高破 1 億 6 千萬，最高同時在線人數(shù)破 300 萬，總下載次數(shù)逾 38 億次，注冊用戶數(shù)亦突破 3 億。2017 年 5 月取得全球手游綜合收入榜冠軍。（數(shù)據(jù)來源：維基百科）
TAPISX 業(yè)務網(wǎng)關
我們所在的團隊在業(yè)務開發(fā)中主要采用 Golang 語言，同時負責部分運維職責。鑒于團隊在運維領域的經(jīng)驗相對有限，且希望控制成本，我們期望借助業(yè)務網(wǎng)關統(tǒng)一處理多項事務，如鑒權、流量錄制等。此外，由于我們在海外業(yè)務中需要頻繁遷移基礎設施，因此無法依賴云上方案，并要求所有數(shù)據(jù)和組件具備遷移能力。
TAPISIX 簡介
雖然 APISIX 完全開源且擁有豐富的插件生態(tài)，但在公司內部使用時，仍需考慮和公司現(xiàn)有基礎設施的集成，例如對接公司內部的服務發(fā)現(xiàn)、日志規(guī)范及 trace 上報等。這些功能是公司內特定的，無法直接合并到開源 upstream 中。因此我們基于 APISIX，添加了一系列專門為公司內部環(huán)境設計的插件，開發(fā)了定制化版本 TAPISIX。
我們的服務運行在 Kubernetes(k8s）集群上，以 APISIX 作為流量入口，與內部業(yè)務服務對接。服務發(fā)現(xiàn)采用公司內部的北極星系統(tǒng)，指標監(jiān)控借助 APISIX 社區(qū)版的 Prometheus 實現(xiàn)，日志和 trace 采集都是通過 OpenTelemetry 進入 ClickHouse。在 CI 工具方面，我們采用 OCI（類似 GitHub Actions），支持通過 YAML 定義流水線；CD 工具則選用 Argo CD，基于開源方案實現(xiàn)持續(xù)部署。
由于我們的業(yè)務主要面向海外市場，對合規(guī)性要求極為嚴苛，這導致許多公司內部組件無法直接落地使用。
本次分享將涵蓋以下四個方面：
網(wǎng)關拓展：如何根據(jù)業(yè)務需求擴展網(wǎng)關功能。
部署運維：網(wǎng)關的部署與日常運維實踐。
Runtime 運維：Runtime 環(huán)境的維護與優(yōu)化。
其他經(jīng)驗：團隊在網(wǎng)關運營中積累的實用經(jīng)驗。
一、網(wǎng)關拓展
目標與挑戰(zhàn)
我們的目標是構建一個業(yè)務網(wǎng)關，依托于 APISIX 的插件能力滿足定制化需求。作為業(yè)務團隊，我們面臨以下挑戰(zhàn)：
開發(fā)門檻高：一線開發(fā)人員熟悉 Golang，但對 Lua 語言和 APISIX 插件開發(fā)不熟悉，導致上手成本高。
插件可靠性：如何確保開發(fā)的插件能夠安全、穩(wěn)定地上線。
核心問題
如何降低開發(fā)門檻？
如何快速驗證插件功能？
如何確保插件的可靠性？
解決方案
為解決上述問題，我們從以下四個方面入手：
開發(fā)規(guī)范（可維護性）
本地快速運行與測試
流水線建設（構建流程）
可靠性保證
1. 開發(fā)規(guī)范
開發(fā)規(guī)范易于理解，我們需定義一個庫，明確插件的存儲路徑，并要求插件采用單文件形式，與 APISIX 的單文件插件機制保持一致，便于管理和維護。
為降低開發(fā)門檻，我們支持本地快速運行與測試。借助 APISIX 的 Docker 鏡像，可將本地插件通過卷映射至容器中，實現(xiàn)便捷部署。同時，利用下游的 echo-service（基于開源 Node.js 開發(fā)的服務），可模擬上游行為。該服務能夠返回請求的所有內容，如請求頭等。通過在請求中添加特定參數(shù)（如 HTTP 狀態(tài)碼 500），可模擬上游的異常行為，從而全面驗證插件功能。
2. 本地快速運行與測試
為降低開發(fā)門檻并加速驗證，我們提供了便捷的本地開發(fā)環(huán)境支持：
文件映射：通過將本地插件文件映射到 Docker 容器中，開發(fā)人員可以實時測試插件的變更。
Makefile 構建：構建 Makefile 文件，支持通過 make run-dev 命令快速啟動插件測試環(huán)境，確保本地文件與容器無縫連接。
瀏覽器直接訪問：開發(fā)人員只需在瀏覽器中訪問相關接口，即可直接驗證插件功能，無需額外部署或配置。
通過定義開發(fā)規(guī)范和提供本地快速開發(fā)支持，我們有效降低了開發(fā)門檻，加速了插件的驗證過程。開發(fā)人員可以專注于功能實現(xiàn)，而無需擔心復雜的部署和測試流程，從而提高了整體開發(fā)效率。
3. 流水線建設（構建流程）
在流水線建設過程中，需要保證可靠性和開發(fā)插件的穩(wěn)定性。開發(fā)流程如下：
分支管理與 PR 流程：
a. 開發(fā)人員從 master 分支拉取一個新分支進行開發(fā)。
b. 完成開發(fā)后，提交 Pull Request（PR）至 master 分支。
Webhook 觸發(fā)：提交 PR 后，系統(tǒng)會自動觸發(fā) Webhook，啟動流水線。
流水線檢測：
a.Lint 檢查：主要檢查代碼格式規(guī)范。
b.單元測試：運行單元測試，驗證插件的功能是否符合預期。
c.Try Build：使用源代碼構建鏡像，驗證代碼的可構建性。
4. 可靠性保障（CR、lint、單側、黑盒測試）
我們使用了 Grafana 旗下的 k6 測試框架進行核心用例的驗證。k6 框架支持聲明式編寫測試用例，可以覆蓋多種場景。我們定期回放這些用例，檢查接口是否通過。例如，即使只是修改了插件，我們也會進行全面的回放測試，包括解析能力和服務發(fā)現(xiàn)能力等。
核心用例與 k6 測試框架
k6 測試用例：包含幾百個測試用例，覆蓋了核心流程，確保插件的可靠性。
通過本地開發(fā)、快速驗證、MR 提交、流水線檢測、可靠性保障以及打包部署的完整流程，我們確保了插件從開發(fā)到上線的每個環(huán)節(jié)都經(jīng)過嚴格的質量控制。
二、部署運維
接下來簡要介紹 APISIX 的部署模式，分為數(shù)據(jù)面和控制面。數(shù)據(jù)面負責實際的代理工作；控制面負責管理配置，包括管理端和其他功能，將配置寫入 etcd，數(shù)據(jù)面從 etcd 讀取配置并加載到內存中，完成路由功能。
APISIX 提供了三種部署方式，以適應不同的生產(chǎn)環(huán)境需求：
傳統(tǒng)模式：數(shù)據(jù)面和控制面同時部署在一個實例中。
分離模式：數(shù)據(jù)面和控制面獨立部署，數(shù)據(jù)面宕機時，控制面仍可操作和修改。
獨立模式：僅部署數(shù)據(jù)面，配置從本地 YAML 文件加載，不依賴 etcd。
只保留數(shù)據(jù)面的獨立模式也是我們使用的方式，所有的配置都存儲在本地，避免了對 etcd 的依賴。這種模式更適用于海外場景。由于 etcd 屬于數(shù)據(jù)庫選型，部分云廠商不提供 etcd 服務，且海外對數(shù)據(jù)合規(guī)性要求嚴格，并且我們的部署環(huán)境在 k8s，因此也采用了對 k8s 友好的配置管理方式。
YAML 配置：所有配置直接存儲在 YAML 文件中，便于管理和自動化部署。
ConfigMap 存儲：將 yaml 文件直接放置在 k8s 的 ConfigMap 中，確保配置的版本化和可追溯性。
我們定義網(wǎng)關為不可變基礎設施，日常運營中不會進行頻繁的變更。即使是路由變更，也被視為一次完整的變更操作。
Kubernetes 配置管理與部署實踐
問題描述：在管理 config.yaml 時，我們發(fā)現(xiàn) k8s 的部署實際上依賴于一系列復雜的配置文件，例如 Service.yaml、ConfigMap.yaml 和 Workload 等。這些配置文件數(shù)量龐大且細節(jié)繁多，容易導致管理上的復雜性和錯誤。
解決方案：K8s 社區(qū)提出 Helm Chart 作為解決方案。Helm Chart 是一種將 k8s 配置文件模板化的工具，能夠顯著簡化配置管理。APISIX 官方提供了 Helm Chart，助力我們高效管理核心配置（如節(jié)點數(shù)等），無需手動填寫大量 YAML 文件。目前，Helm Chart 已有效解決配置復雜性問題。
衍生問題：然而，衍生出來的另一個關鍵問題是：如何將 Helm Chart 或 YAML 文件部署到 k8s集群上。
解決方案：為此，我們采用了 GitOps 模式，通過流水線將 YAML 文件部署到 K8s 集群。在 GitOps 模式下，所有配置以代碼形式存儲在 Git 中。借助 Git 觸發(fā) CI/CD 流程，實現(xiàn)自動化部署。config.yaml 和其他配置文件均存儲在 Git 中，確保了配置的版本化管理和可追溯性。通過這種方式，我們不僅簡化了配置管理，還實現(xiàn)了部署流程的自動化和標準化，提升了整體效率和可靠性。
部署流程示例
在上圖展示的部署流程中，SRE（Site Reliability Engineer）代表用戶進行配置管理。任何修改，如路由變更或鏡像更新，都需要通過修改 Helm Chart 倉庫來實現(xiàn)。修改后，Argo CD 會自動檢測到變更并觸發(fā)流水線，拉取最新的配置完成部署。另外，Git 和 K8s 之間建立了強同步關系，確保配置的一致性和可靠性。
例如，部署完成后，我擁有 k8s 集群的完全訪問權限，對 service.yaml 文件進行了修改。Argo CD 會持續(xù)監(jiān)控集群狀態(tài)，若發(fā)現(xiàn)實際資源與 Git 倉庫中的配置不匹配，將自動觸發(fā)同步，使用 Git 倉庫中的內容覆蓋集群配置。
GitOps 的優(yōu)勢
這種模式帶來諸多益處：
配置一致性：所有配置變更均通過 Git 進行，確保系統(tǒng)配置的一致性。
安全性：減少手動修改帶來的潛在風險，所有變更均有跡可循。
自動化部署：基于 Argo CD 或 Git 的版本變更，實現(xiàn)自動化部署與灰度發(fā)布。
在實際部署中，我們僅需維護兩個倉庫：代碼庫（存放應用代碼）、部署庫（如下圖，存放所有部署相關的配置文件）。
這種簡化模式使得許多傳統(tǒng)的管理平臺變得不再必要，整個流程更加高效簡潔。需要將應用部署到其他集群時，只需從部署庫拉取相應分支，并應用到目標集群即可，整個過程簡單高效。
在以上部署實踐中，APISIX 的關鍵配置文件（如路由配置和 config.yaml 啟動配置）被整合到一個 Helm Chart 庫中，便于統(tǒng)一管理和部署。然而，這種部署方式也可能帶來一個問題：它本質上將 APISIX 當作了一個普通服務來部署。
為什么不用 APISIX Ingress Controller？
APISIX Ingress Controller 作為社區(qū)為 k8s 提供的官方解決方案，其核心流程如下：通過定義 APISIXRoute 等自定義資源，以 YAML 文件的形式在 k8s 中描述路由等配置。
將這些 CRD 部署到 k8s 集群后，Ingress Controller 會持續(xù)監(jiān)聽相關的 CRD 資源。解析 CRD 中的配置信息，并通過調用 APISIX 的 Admin API 將配置同步到 APISIX 中。Ingress Controller 主要為了進行 CRD 和 APISIX 之間的部署，最終還是將數(shù)據(jù)寫入 etcd。
經(jīng)過審慎評估，我們發(fā)現(xiàn) APISIX Ingress Controller 的部署和運維模式并不完全適配我們的團隊需求，主要有以下原因：
業(yè)務網(wǎng)關定位：作為業(yè)務網(wǎng)關，我們更側重于降低開發(fā)和運維門檻，提高易用性和開發(fā)效率。
運維成本考量：Ingress Controller 的引入會增加一層額外的運維復雜度。它需要與 k8s 進行深度集成，涉及額外的 Golang 編寫的代碼和 k8s API 調用，這無疑提高了運維的難度和成本。
環(huán)境一致性問題：由于需要依賴 k8s 環(huán)境，本地開發(fā)環(huán)境與線上部署環(huán)境存在差異，可能導致諸如“本地可以正常運行而線上出現(xiàn)問題”等不一致的情況，增加排查和解決故障的難度。
版本耦合：APISIX 版本與 Ingress Controller 版本之間存在強耦合關系。由于我們的 APISIX 基于開源版本進行了定制化修改，只維護特定版本的兼容性。這可能導致某些 API 不被支持或出現(xiàn)兼容性問題，進而影響系統(tǒng)的穩(wěn)定性和可靠性。
配置不透明性：通過 Ingress Controller 的方式，最終配置還需寫入 etcd，這可能導致配置狀態(tài)不一致的問題。例如，Ingress Controller 監(jiān)聽失敗或 etcd 狀態(tài)不佳時，可能會引發(fā)連接過多等問題，使得整個架構鏈路變得更加不透明和復雜。與之相比，Helm Chart 的優(yōu)勢在于其提供了一個完整且可審計的 YAML 文件，其中包含了所有的路由配置，使得路由狀態(tài)清晰可見。
因此，我們沒有選擇 APISIX Ingress Controller。
如何實現(xiàn)配置熱更新？
在 k8s 環(huán)境中部署 APISIX 時，實現(xiàn)配置熱更新是確保系統(tǒng)穩(wěn)定性和可用性的關鍵。APISIX 的配置主要分為兩種：
APISIX 路由配置（apisix.yaml）：采用傳統(tǒng)的加載方式，用于定義路由配置，包括路由的 upstream 以及相應的轉發(fā)規(guī)則等內容。
啟動配置（config.yaml）：主要作為啟動項配置文件，用于指定諸如 APISIX 運行端口等關鍵參數(shù)。某些配置項的變更需要重啟服務才能生效。
k8s 資源部署流程
修改 Git 配置：對上述提及的 Git 配置進行修改。
交付 Argo CD：將修改后的配置交付給 Argo CD。
生成資源文件：Argo CD 依據(jù)修改后的配置，通過 Helm Chart 生成相應的 ConfigMap、Service YAML 等資源文件。
在 k8s 環(huán)境中，apisix.yaml 和 config.yaml 這些資源文件均以 ConfigMap 的形式存在。
APISIX 配置變更處理機制
問題描述： 當 APISIX 相關配置發(fā)生變更時，對應的 ConfigMap 會相應地進行更新，但此時 Deployment（即 APISIX 部署實例）本身尚未改變。
解決方案：為解決這一問題，k8s 社區(qū)提出了相應的解決方案，即通過合理地拆分配置，并巧妙地利用哈希與注解方式，將需要變更的 ConfigMap 內容以注解的形式注入到 Deployment 中，從而實現(xiàn)配置的動態(tài)更新。
apisix-configmap.yaml：主要用于存放 APISIX 的核心業(yè)務邏輯配置，如路由規(guī)則等。更改此類 ConfigMap 時，由于 APISIX 內置的定時器機制，其會定期從本地文件讀取并更新內存中的配置信息，因此無需重啟 APISIX 服務，即可實現(xiàn)配置的更新與生效。
config-configmap.yaml：主要包含 APISIX 運行環(huán)境等基礎配置。當此類 ConfigMap 發(fā)生變更時，由于其涉及 APISIX 服務的基礎運行環(huán)境設置，為了確保新配置能夠正確地被加載與應用，需要重啟 APISIX 部署實例。
更新觸發(fā)機制：為實現(xiàn)配置變更的自動檢測與更新流程觸發(fā)，我們采用注解方式對 ConfigMap 內容進行哈希處理，并將哈希值寫入 deployment.yaml 文件。當配置變更導致哈希值更新時，deployment.yaml 文件會相應發(fā)生變化，k8s 系統(tǒng)檢測到這一變化后，會自動觸發(fā)更新流程，從而確保 APISIX 部署實例能夠及時應用新的配置。
三、Runtime 運維
Runtime 運維主要分為三個部分：metrics 采集、trace 上報、日志收集。
1. Metrics 采集
k8s 集群提供了官方的 metrics 采集解決方案，名為 Kubernetes Prometheus Operator。通過定時抓取服務暴露的 metrics 端口和信息，定期將數(shù)據(jù)上報至外部系統(tǒng)，如 Prometheus。由于該部分未進行深度定制，此處不再贅述。相關的 k8s 配置在 APISIX 的 Helm Chart 中已有完整描述。
2. Trace 上報
Trace 上報基于 APISIX 提供的 OpenTelemetry 插件實現(xiàn)。該插件通過 OpenTelemetry 協(xié)議將數(shù)據(jù)上報至 OpenTelemetry Collector，最終將數(shù)據(jù)寫入 ClickHouse，完成 Trace 數(shù)據(jù)的采集與存儲。
3. 日志收集
日志收集同樣采用 OpenTelemetry 協(xié)議。然而，APISIX 社區(qū)版的 OpenTelemetry 插件僅支持 Trace 上報，而不包括日志上報功能。因此，我們建議采用本地日志存儲方式，通過 sidecar 模式將 APISIX 日志寫入一個共享文件夾。在 Deployment 中掛載另一個 Pod，該 Pod 與 APISIX Pod 共享同一個日志文件夾，從而實現(xiàn)日志的采集，并通過 OpenTelemetry 協(xié)議進行上報。
另外，社區(qū)提供的監(jiān)控面板功能較為通用，針對性不足。因此，我們基于采集到的指標數(shù)據(jù)定制開發(fā)了專用的監(jiān)控面板，以滿足特定的監(jiān)控需求。告警系統(tǒng)則基于 Grafana 的開源方案構建，利用其強大的可視化和告警功能，實現(xiàn)對 APISIX 運行狀態(tài)的實時監(jiān)控和告警。
四、其他經(jīng)驗
Standalone 路由管理
我們首先對路由管理策略進行了優(yōu)化。在早期的路由管理實踐中，我們將所有路由配置集中放置在一個單一的 config 文件中。然而，這種做法很快暴露出問題，隨著業(yè)務的發(fā)展和路由數(shù)量的增加，YAML 文件的規(guī)模急劇膨脹，給維護帶來了巨大挑戰(zhàn)。
正如業(yè)內調侃的那樣，“k8s 運維工程師是‘YAML 工程師’”之說，恰是因為面對海量的 YAML 配置文件而產(chǎn)生的無奈與自嘲。為應對這一難題，我們從兩個關鍵維度出發(fā)，對路由進行了合理拆分。
模塊化拆分：依據(jù) APISIX 的路由規(guī)范，將配置劃分為 collector 配置與 consumer 配置的模塊，實現(xiàn)了功能層面的解耦與分類管理。
域名維度拆分：針對 route 文件，按照域名這一核心維度進行拆分，使路由配置更加精細化、條理化，便于后續(xù)的維護與擴展。
重復路由配置
在 k8s 的 upstream 配置中，存在多種類型，這些不同類型配置間的差異往往僅體現(xiàn)在 service name 這一關鍵要素上。在引入新版本并更新 Lua 包后，我們充分利用其支持的錨點功能，對重復配置問題進行了有效治理。通過錨點機制，實現(xiàn)了對共性配置部分的抽象與復用，在實際應用中成功減少了約 70% 的重復配置內容，極大地提升了配置管理的效率與簡潔性，降低了因重復配置而引入錯誤的風險。
APISIX 替換 Ingress 遷移實踐
初始架構與背景
最初，我們的鏈路架構為：Edge one 作為一個 CDN，然后流量經(jīng) CLB 轉發(fā)至 Ingress（Istio），最后到達內部的 APISIX。
Ingress 的存在主要源于歷史原因，當時在云上選擇了 Istio 作為服務網(wǎng)格解決方案。然而，隨著業(yè)務的發(fā)展和技術的演進，我們計劃直接替換掉 Ingress，采用 APISIX 作為 K8s Ingress，以實現(xiàn)更高效、更靈活的流量管理。
遷移方案評估
在遷移過程中，我們評估了兩種主要的遷移方案：
●方案一 CDN 灰度與雙域名：即在現(xiàn)有架構旁側部署一個新的 APISIX 實例，引導新的流量至該實例。然而，此方案的缺點在于前端需要修改域名，可能會對用戶訪問和業(yè)務連續(xù)性產(chǎn)生一定影響，因此我們謹慎考慮后暫時擱置了這一方案。
●方案二 CDN 流量調配：選擇這種方式，它可以配置多個 CLB 路由，并且能夠實現(xiàn)基于百分比的流量推送。這種方式的優(yōu)勢在于能夠在不改變用戶訪問入口的前提下，逐步將流量切換至新的 APISIX 實例，并且可以根據(jù)實際情況靈活調整流量比例，便于觀察和評估遷移效果。
最終方案實施與優(yōu)勢
我們最終選擇了方案二，成功形成了一條新的流量鏈路：新流量通過灰度方式直接到達 APISIX。這一新的鏈路架構帶來了以下顯著優(yōu)勢：
端側無變更：前端用戶訪問的域名和入口保持不變，確保了用戶體驗的連續(xù)性，避免了因域名變更可能引發(fā)的用戶困惑或訪問中斷問題。
后端全自助：后端具備自主控制和管理流量切換的能力，可根據(jù)業(yè)務需求和系統(tǒng)狀態(tài)靈活調整流量分配，無需依賴外部協(xié)調整合。
快速回退能力：由于具備灰度發(fā)布的能力，如果在遷移過程中發(fā)現(xiàn)任何問題，可以迅速將流量回退至原有的鏈路，最大程度降低遷移風險，保障業(yè)務的穩(wěn)定運行。
用戶無感知遷移：整個遷移過程對用戶而言是透明的，用戶在訪問業(yè)務時不會察覺到后端架構的變化，確保了業(yè)務遷移的平滑性和無縫性。
以下展示的是遷移的整體流程。
總 結
我們團隊基于 APISIX 二次開發(fā)了 TAPISX 業(yè)務網(wǎng)關。APISIX 作為我們業(yè)務網(wǎng)關的核心組件，在滿足海外業(yè)務的高合規(guī)性要求、降低開發(fā)和運維門檻、提高系統(tǒng)靈活性和可靠性等方面發(fā)揮了關鍵作用。它為我們打造了一個高效、穩(wěn)定、靈活的業(yè)務網(wǎng)關平臺，為業(yè)務的持續(xù)發(fā)展提供了有力支持。未來，我們期待與 APISIX 一起，探索更多創(chuàng)新的應用場景，為業(yè)務創(chuàng)造更大的價值。
熱門跟貼