← 返回

`edge2yaml` 釋出：OpenResty Edge 配置的匯入、匯出與 GitOps 整合

章亦春釋出於 Apr 22, 2026 更新於 Apr 22, 2026

預計閱讀 6 分鐘

閱讀次數

OpenResty Edge 本身已具備完善的配置管理能力。透過 Admin 控制檯 UI 或 API 進行的每一次變更，都有完整的變更記錄可查，並內建了審查釋出流程。對於絕大多數團隊和場景，這套原生機制在可靠性和易用性上已經足夠。

但在與客戶的溝通中，我們注意到一類特定需求——尤其集中在深度使用 Kubernetes 生態、或已建立 GitOps 體系的團隊：

他們習慣將所有基礎設施配置以文字檔案形式存入 Git 倉庫，透過 PR/MR 流程驅動變更；
他們的 CI/CD 流水線已經成熟，希望閘道器配置的變更也能接入這套自動化體系，而不是單獨走一套 UI 操作；
他們需要在開發、測試、生產等多套環境之間頻繁複制配置，希望有一種可指令碼化的方式來完成；
面對大量結構相似的配置項時，他們更傾向於直接編輯文字檔案，而不是在 UI 上逐條點選。

這類需求的本質，是希望將 OpenResty Edge 配置納入團隊已有的配置即程式碼工作流，而不是在 OpenResty Edge Admin 之外再維護一套獨立的管理流程。

如果你的團隊目前主要透過 Admin UI 管理配置，本文介紹的工具並非必需品，繼續使用原生機制即可；當出現 GitOps、多環境同步或批次編輯等需求時，再考慮引入 edge2yaml。

`edge2yaml` 是甚麼

edge2yaml 是 OpenResty Edge 官方提供的命令列工具，實現本地 YAML 檔案與 OpenResty Edge 平臺之間的雙向轉換。其核心操作只有三類：

匯入（import）：將本地 YAML 配置檔案推送到 Edge Admin，建立或更新對應配置；
匯出（export）：將 Edge Admin 中的現有配置拉取到本地，生成結構化的 YAML 檔案；敏感資訊（如 SSL 私鑰、使用者密碼）在匯出時會以佔位符替代；
清理（cleanup）：按指定範圍移除 Edge Admin 中的配置項，支援從"清理整個應用"到"僅清理某個應用下的某一類配置"等多種粒度。需要注意，當 Edge 中啟用了"自動同步到其他分割槽"時，為相容多本地配置場景，相關全域性配置在清理操作下不會被實際重置或刪除；未啟用時，本地不存在的多餘配置會被重置或清理。

工具透過 Edge Admin 的 API 與平臺通訊，需要提供 API Token 進行認證。配置檔案按分割槽和應用組織，目錄結構清晰，便於版本控制系統追蹤。從能力覆蓋上看，它支援管理全域性配置、全域性/應用級上游、頁面規則等功能，覆蓋了 OpenResty Edge 上大部分功能，基本滿足日常運維中可配置的主要物件。

注意：edge2yaml 目前僅支援企業版 OpenResty Edge。

典型使用場景

1. GitOps 工作流

將匯出的 YAML 檔案存入 Git 倉庫，配置變更透過 PR/MR 提交，經過 Code Review 後由 CI/CD 流水線呼叫 edge2yaml 自動匯入。這種方式讓閘道器配置的變更流程與應用程式碼的釋出流程保持一致，適合已建立 GitOps 規範的團隊。

2. 多環境配置同步

從生產環境匯出配置，修改其中環境相關的引數（如上游地址、域名），再匯入到測試或預釋出環境。相比手動在多套 UI 上重複操作，這種方式更可控，也更容易排查差異。

3. 外部版本化備份

定時執行匯出命令，將生成的 YAML 檔案提交到 Git 倉庫。結合 Git 的歷史記錄，可以檢視任意時間點的配置快照，並在需要時將其重新匯入。

4. 批次編輯

當需要對大量配置項進行結構相似的修改時（例如批次調整上游超時引數、批次新增某條規則），直接編輯 YAML 檔案或透過指令碼生成，再一次性匯入，效率高於逐條 UI 操作。匯入過程中若 YAML 存在欄位非法等問題，工具會給出定位到具體檔案和行號的錯誤提示，便於快速修復。

`edge2yaml` 與 OpenResty Edge Admin 原生能力的關係

在決定是否引入 edge2yaml 之前，有必要先了解 OpenResty Edge Admin 內建的配置管理能力，以及 edge2yaml 相比之下的定位和侷限。

OpenResty Edge Admin 內建能力

OpenResty Edge Admin 的配置管理基於資料庫實現，具備以下特性：

變更記錄完整：每次操作的操作人、時間、變更內容均有記錄，上下文清晰；
內建審查釋出流程：支援變更審查和受控釋出，操作狀態實時可見；
平臺級可靠性與資料備份機制：資料一致性由平臺保證，並具備相應的備份與恢復能力；
併發安全：多人同時操作時，資料庫事務機制保障不會出現配置覆蓋或丟失。

對於絕大多數配置管理需求，Edge Admin 原生方式是更可靠、更完整的選擇。

edge2yaml 適合將 OpenResty Edge 配置納入 Git 和 CI/CD 體系，但有幾點固有侷限需要了解：匯出的 YAML 檔案是時間點快照，版本歷史的粒度和完整性依賴團隊的提交習慣，不如平臺自動維護的變更記錄精細；部分執行時狀態和平臺內部關聯關係也無法透過靜態 YAML 完整表達。

此外需要注意，SSL 私鑰、使用者密碼等敏感資訊出於安全原因在匯出時會以佔位符替代，跨環境遷移時需單獨處理這部分配置。

建議的使用方式

將 OpenResty Edge Admin 作為日常配置管理的主要入口，充分利用其內建的版本控制、審查釋出和備份能力。在以下特定場景中，可以將 edge2yaml 作為補充工具：

團隊已有成熟的 GitOps 體系，希望將 Edge 配置納入統一管理；
需要在多套環境之間遷移配置；
需要將配置變更接入現有 CI/CD 流水線；
需要在外部系統中保留一份配置的文字備份。

兩者並不衝突，合理分工可以兼顧工作流偏好與平臺可靠性。

小結

edge2yaml 為偏好 GitOps 工作方式的團隊提供了一條官方通道，使 OpenResty Edge 的配置管理可以融入 Git 和 CI/CD 體系。如果你的團隊習慣用 Git 管理基礎設施配置，或者需要在多環境之間批次同步配置，edge2yaml 值得嘗試。

更完整的安裝說明、命令引數與配置目錄結構，請參閱官方文件中的基於 YAML 檔案的 OpenResty Edge 配置映象，以及對應的使用示例。

申請試用 OpenResty Edge

關於 OpenResty Edge

OpenResty Edge 是一款專為微服務和分散式流量架構設計的全能型閘道器軟體，由我們自主研發。它集流量管理、私有 CDN 構建、API 閘道器、安全防護等功能於一體，幫助您輕鬆構建、管理和保護現代應用程式。OpenResty Edge 擁有業界領先的效能和可擴充套件性，能夠滿足高併發、高負載場景下的苛刻需求。它支援排程 K8s 等容器應用流量，並可管理海量域名，輕鬆滿足大型網站和複雜應用的需求。

關於作者

章亦春是開源 OpenResty^® 專案創始人兼 OpenResty Inc. 公司 CEO 和創始人。

章亦春（Github ID: agentzh），生於中國江蘇，現定居美國灣區。他是中國早期開源技術和文化的倡導者和領軍人物，曾供職於多家國際知名的高科技企業，如 Cloudflare、雅虎、阿里巴巴，是“邊緣計算“、”動態追蹤“和“機器程式設計“的先驅，擁有超過 22 年的程式設計及 16 年的開源經驗。作為擁有超過 4000 萬全球域名使用者的開源專案的領導者。他基於其 OpenResty^® 開源專案打造的高科技企業 OpenResty Inc. 位於美國矽谷中心。其主打的兩個產品 OpenResty XRay（利用動態追蹤技術的非侵入式的故障剖析和排除工具）和 OpenResty Edge（最適合微服務和分散式流量的全能型閘道器軟體），廣受全球眾多上市及大型企業青睞。在 OpenResty 以外，章亦春為多個開源專案貢獻了累計超過百萬行程式碼，其中包括，Linux 核心、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl 等，並編寫過 60 多個開源軟體庫。