← 返回

`edge2yaml` 发布：OpenResty Edge 配置的导入、导出与 GitOps 集成

章亦春发布于 Apr 22, 2026 更新于 Apr 21, 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 多个开源软件库。