备份与恢复

每次升级前，都要创建数据库原生备份，并使用 ADC 导出每个网关组的声明式配置。数据库备份是权威恢复来源，因为其中包含 ADC 不会导出的控制面（CP）状态，例如用户、角色、API 产品和审计数据。

在生产变更前，先在隔离环境中对数据库备份进行恢复测试。在回滚期限结束前，请一直保留该备份和 ADC 导出文件。

警告

只要有效备份可用，就应使用数据库恢复。ADC 只能恢复网关配置，不能替代完整的 CP 恢复。

创建备份

先创建数据库原生备份，再导出每个网关组的声明式配置。

创建数据库原生备份

API7 网关默认使用 PostgreSQL。以下示例使用 pg_dump 创建目录格式的备份：

pg_dump -U api7ee -d api7ee -F d -f api7ee_backup_20250523

• pg_dump：PostgreSQL 的逻辑备份工具，用于导出数据库内容。
• -U api7ee：指定数据库连接用户名为 api7ee。
• -d api7ee：指定要备份的数据库名称为 api7ee。
• -F d：指定备份格式为目录格式，适用于大型数据库和并行恢复。
• -f api7ee_backup_20250523：指定备份的输出目录名称为 api7ee_backup_20250523。备份结果将存储在此目录中。

导出声明式配置

使用 ADC 工具，以声明式配置文件的形式备份 API7 网关配置（服务、路由、插件、消费者等）。

1. 导出资源前，为每个网关组保存恢复清单。记录源版本 Admin API 返回的字段，包括以下创建时字段：

   源 CP 版本	通用字段	其他字段
   3.8.23、3.9.19–3.9.20 或 3.10.0–3.10.2	name、description、type 和 labels	enforce_service_publishing
   3.10.3–3.10.4	name、description、type 和 labels	无
   3.10.5–3.10.7	name、description、type 和 labels	environment

   还应根据每个网关组的 type 保存源版本的连接和部署信息：

   • 对于 api7_gateway，保存 DP 部署配置、CP-DP 连接设置，以及需要安装替换用 mTLS 材料的 Secret 或文件位置。
   • 对于 api7_ingress_controller，保存 Ingress Controller 部署配置，以及提供网关组 admin key 的 Secret 或 values 位置。旧密钥无法向在全新数据库中重新创建的网关组进行身份认证。

   将每份清单与对应的 ADC 导出文件存放在一起。ADC dump 不包含网关组记录、上述两种部署配置、CP-DP 连接材料或 Ingress Controller admin key。不要假设某个 CP 版本的网关组字段也能被其他版本的 API 接受。

2. 验证 ADC 能否连接到 API7 网关：

   adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

3. 每次执行 dump 前，在控制台或 API 中列出网关组，并验证请求的名称只能标识目标网关组。ADC 使用 --gateway-group 按名称查询，部分版本可能选择第一个匹配的搜索结果。如果相似名称导致结果不明确，请勿继续。

4. 使用 ADC dump 将每个网关组的数据存储到不同的本地文件。请对每个网关组重复执行此命令。务必指定 --gateway-group；否则 ADC 会操作 default 网关组，并且复用同一输出文件名可能覆盖先前的导出：

   adc dump -o "api7ee-{GATEWAY_GROUP}-dump.yaml" \
     --backend api7ee \
     --server "https://{DASHBOARD_ADDR}" \
     --gateway-group "{GATEWAY_GROUP}"

有关更多 ADC 命令，请参阅 ADC 文档。

数据恢复与回滚

只要条件允许，就从数据库备份恢复。仅在无法完整恢复数据库时，才使用声明式配置进行恢复。

从数据库恢复

要从数据库备份恢复 API7 网关数据，请创建一个新数据库，并确保所有 CP 组件保持停止状态，直至恢复和验证完成。以下 PostgreSQL 示例会恢复上文创建的目录格式备份。

1. 创建一个正在运行的 CP 无法访问的空目标数据库：

   createdb -U api7ee api7ee_restored

2. 将备份恢复到空目标数据库：

   pg_restore -U api7ee -d api7ee_restored api7ee_backup_20250523/

3. 在允许任何 CP 组件连接之前，验证恢复后的源版本、数据库结构和代表性资源。

4. 更新控制台、DP Manager 以及其他所有 CP 数据库客户端，使其使用恢复后的数据库：

   database:
     dsn: "postgres://api7ee:changeme@192.168.31.10:5432/api7ee_restored"

5. 使用源版本镜像启动一个控制台副本并完成验证，然后再恢复其余 CP 副本和 DP Manager。

6. 使用保存的部署脚本、配置项、证书和配置文件恢复源版本 DP。验证代表性流量后，再让它们重新承载生产流量。

从声明式配置恢复

警告

仅在无法完整恢复数据库时，才使用声明式配置恢复。此方法不会恢复用户、角色、API 产品、审计数据或其他 CP 状态。

使用原配置和镜像标签恢复源版本 CP，并将其连接到新数据库。ADC 导出文件不包含网关组记录、DP 部署配置或 CP-DP mTLS 连接材料。使用 ADC 恢复导出的网关配置前，请先完成以下准备工作：

1. 使用保存的恢复清单和源版本 Admin API，在同步前恢复网关组记录：

   • 使用保存的 name、description 和 labels 更新已有的 default 网关组。对于 3.10.5–3.10.7，还应恢复保存的 environment，这些版本允许在更新时设置该字段。
   • 使用保存的通用字段重新创建所有需要的非默认网关组。对于 3.8.23、3.9.19–3.9.20 或 3.10.0–3.10.2，还需发送 enforce_service_publishing；对于 3.10.3–3.10.4，不发送其他字段；对于 3.10.5–3.10.7，则发送 environment。
   • 不要发送源版本不接受的字段。type 和 enforce_service_publishing 只能在创建时设置。如果自动创建的 default 网关组中，这两个字段的任一保存值与全新 CP 中的值不同，请停止同步，因为 Admin API 无法使两个网关组完全一致。

   ADC 不会创建网关组记录。请参阅管理网关组。

2. 根据每个已保存网关组的 type 恢复连接材料：

   • 对于 api7_gateway，恢复源版本 DP 部署配置，替换其 CP-DP 连接设置，并安装由恢复后的 CP 生成的新 mTLS 证书，不要复用旧 CA 签发的证书。
   • 对于 api7_ingress_controller，恢复源版本 Ingress Controller 部署配置。使用 GET /api/gateway_groups/{gateway_group_id}/admin_key 获取为重新创建的网关组生成的新密钥，或者使用同一路径的 PUT 方法轮换密钥，然后替换控制器使用的 Secret 或 values 中的旧密钥。请将明文密钥作为敏感信息安全存储。

   ADC 恢复和验证完成前，请让 DP 和 Ingress Controller 保持停止状态，或将它们与生产流量隔离。

3. 使用 ADC 验证服务连通性，并确认它可以连接到 API7 网关：

   adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

4. 每次同步前，在控制台或 API 中列出网关组，并验证请求的名称只能标识目标网关组。如果相似名称导致结果不明确，请勿继续。然后将每个导出文件同步到对应的网关组。请对每个网关组重复执行此命令。务必指定 --gateway-group；否则 ADC 会操作 default 网关组：

   adc sync -f "api7ee-{GATEWAY_GROUP}-dump.yaml" \
     --backend api7ee \
     --server "https://{DASHBOARD_ADDR}" \
     --gateway-group "{GATEWAY_GROUP}"

5. 启动或重新连接恢复后的源版本 DP 和 Ingress Controller。确认每个 DP 或控制器都使用替换后的凭据连接到目标网关组，并验证代表性流量，然后再让它们重新承载生产流量。

其他文件

除了在 API7 网关中创建的资源配置外，还需要手动备份一些重要文件：

1. 各组件实际使用的配置文件与部署配置项。文件名取决于部署方式，不能把控制面和数据面的配置文件相互替换：

   • Docker Compose：备份控制台的 dashboard_conf/conf.yaml，以及 DP Manager 的 dp_manager_conf/conf.yaml。控制面这两个宿主机文件分别挂载到各自容器的 /usr/local/api7/conf/conf.yaml，由对应组件的启动参数加载。同时保存 docker-compose.yaml 和实际使用的环境变量。数据面使用文件配置时，备份数据面的 config.yaml 及宿主机挂载源文件；使用控制台生成的 Docker 命令部署时，保存完整命令和其中的连接参数、证书及私钥环境变量。
   • RPM：备份控制台的 /usr/local/api7/dashboard/conf/dashboard.yaml，DP Manager 的 /usr/local/api7/dp-manager/conf/dp-manager.yaml，控制台前端的 /usr/local/api7/dashboard/conf/console.env，以及每个数据面实例的 /usr/local/apisix/conf/config.yaml。同时保存这些配置引用的证书、私钥和连接参数文件。
   • Kubernetes / OpenShift（Helm）：保存每个控制面和数据面 release 实际使用的 values、命令行覆盖参数及渲染后的资源清单，包括已启用的开发者门户配置。单独保存所引用的 ConfigMap 和 Secret，或外部密钥管理系统中的恢复材料；例如，数据库连接 Secret 的值并不包含在仅使用占位符的 values 或 ConfigMap 中。记录各网关组 mTLS Secret 的命名空间、名称及证书和私钥对应的键。

   对于自定义容器或高可用部署，按实际挂载和启动参数核对每个组件的宿主机源文件与容器内路径，保存全部副本共用或独有的配置，而不是仅按上述示例文件名查找。

2. 自定义插件的源代码。

3. 部署 API7 网关实例时使用的部署脚本和其他文件。

如果启用了开发者门户，还应保存其后端和每个前端实例实际加载的配置、Portal 令牌、身份认证密钥，以及前端数据库的原生备份。Docker Compose 手工部署中，备份开发者门户后端的 backend_conf/conf.yaml，以及开发者门户前端的 frontend_conf/config.yaml；打包的本地评估部署中，开发者门户前端配置生成在 developer_portal_fe_conf/config.yaml。恢复清单应分别记录后端连接的控制面数据库与各前端连接的数据库，并确认两者均有可恢复的原生备份。前端数据库中的开发者会话、身份认证和组织信息不能由 ADC 导出替代。不要假定控制面数据库的备份已经覆盖了单独部署的前端数据库。

证书、私钥和其他凭据也属于受保护的恢复材料。备份旧凭据不意味着它们可以用于新建的网关组；使用声明式配置恢复时，仍须按上文要求替换 mTLS 材料或 Ingress Controller 管理密钥。

这些文件因部署而异，恢复时可能需要使用。请将其加密存储在访问受控的备份系统中，不要将包含凭据或 Secret 数据的备份提交到源码仓库，并在回滚演练期间确认运维人员可以取回并使用这些恢复材料。