跳到主要内容
版本：3.9.x

备份与恢复

每次升级前，都要创建数据库原生备份，并使用 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 工具，以声明式配置文件的形式备份 ADC 支持的网关配置，包括服务、路由、插件和消费者。

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

    源 CP 版本通用字段其他字段
    3.9.19–3.9.20name、description、type 和 labelsenforce_service_publishing

    还应根据每个网关组的 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。ADC 0.30.4 也不会导出消费者组，因此恢复消费者组必须依赖数据库备份。不要假设某个 CP 版本的网关组字段也能被其他版本的 API 接受。

  2. 创建控制台令牌，并确保它能够列出网关组和读取其配置，然后将令牌提供给 ADC：

    export ADC_TOKEN="{DASHBOARD_TOKEN}"

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

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

  4. 每次执行 dump 前，在控制台或 API 中列出网关组，并核对目标网关组的精确名称。将该名称传递给 --gateway-group。

  5. 使用带有 --with-id 的 ADC dump，将每个网关组的数据存储到不同的本地文件。保留后端分配的资源 ID 可以维持资源身份，并避免在恢复到非空网关组时根据名称创建替代资源。请对每个网关组重复执行此命令。务必指定 --gateway-group；如果既未设置此选项，也未设置 ADC_GATEWAY_GROUP，ADC 会请求名为 default 的网关组。复用同一输出文件名可能覆盖先前的导出：

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

有关更多 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 状态。

ADC 0.30.4 不会恢复消费者组。如果网关授权依赖消费者组，请使用数据库恢复，而不是声明式配置恢复。

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

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

    • 使用保存的 name、description、labels 和 enforce_service_publishing 更新已有的 default 网关组。
    • 使用保存的 name、description、type、labels 和 enforce_service_publishing 重新创建所有需要的非默认网关组。
    • 不要发送源版本不接受的字段。type 只能在创建时设置。如果自动创建的 default 网关组中，保存的 type 与全新 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. 在恢复后的 CP 中创建控制台令牌，并确保它能够列出网关组，以及读取、创建、更新和删除所有待恢复的 ADC 支持资源类型。将令牌提供给 ADC 并验证连通性：

    export ADC_TOKEN="{DASHBOARD_TOKEN}"
    adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

  4. 恢复每个文件前，在控制台或 API 中列出网关组，并核对目标网关组的精确名称。导出文件是该网关组中 ADC 支持资源的权威期望状态，因此同步可能删除文件中缺失的远程资源。先针对对应网关组预览变更：

    adc diff -f "api7ee-{GATEWAY_GROUP}-dump.yaml" \
      --backend api7ee \
      --server "https://{DASHBOARD_ADDR}" \
      --gateway-group "{GATEWAY_GROUP}" \
      --no-managed-by-label

    审查生成的 diff.yaml，如果其中存在意外删除或替换，请停止恢复。--no-managed-by-label 会阻止 ADC 在恢复时添加所有权标签，从而保留导出文件中的标签。

  5. 审查差异后，将导出文件同步到对应的网关组。请对每个网关组重复执行预览和同步。务必指定 --gateway-group；如果既未设置此选项，也未设置 ADC_GATEWAY_GROUP，ADC 会请求名为 default 的网关组：

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

  6. 启动或重新连接恢复后的源版本 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 命令部署时，保存完整命令和其中的连接参数、证书及私钥环境变量。
    • 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。前者挂载到后端容器的 /usr/local/api7/conf/conf.yaml，后者挂载到前端容器的 /app/apps/site/config.yaml。恢复清单应分别记录后端连接的控制面数据库与各前端连接的数据库，并确认两者均有可恢复的原生备份。前端数据库中的开发者会话、身份认证和组织信息不能由 ADC 导出替代。不要假定控制面数据库的备份已经覆盖了单独部署的前端数据库。

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

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