备份与恢复

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

在生产变更前，先在隔离环境中对数据库备份进行恢复测试。在回滚期限结束前，请一直保留所有备份材料。

警告

数据库原生备份包含可由控制面解密的凭据和 CA 私钥。请使用运维人员掌控的密钥对备份进行静态加密和传输加密，严格限制并审计访问，仅在必要期限内保留。

只要有效备份可用，就应使用数据库恢复。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.8.23–3.8.24、3.9.19–3.9.23 或 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.10	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. 创建控制台 Token，并确保它能够列出网关组和读取其配置，然后将 Token 提供给 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 文档。

备份部署文件

请将以下与部署方式有关的文件与数据库备份和 ADC 导出文件一同保存。文件名取决于部署方式和补丁版本：

1. 控制面部署文件、组件镜像标签、数据库配置及所需凭据的引用：

   • Docker Compose（打包的控制面部署）：保存 Compose 文件和环境变量、控制台的 dashboard_conf/conf.yaml、DP Manager 的 dp_manager_conf/conf.yaml、开发者门户后端的 developer_portal_conf/conf.yaml。启用 API Usage 时，保存 API Usage 的 api_usage_conf/conf.yaml。启用 File Server 时，保存 File Server 的 api7-ee-file-server-config.yaml。从 3.10.5 起，如果启用了门户前端的 profile，保存开发者门户前端的 developer_portal_fe_conf/config.yaml。每个数据面网关实例使用的 config.yaml 或部署 values 按下文第 2 项保存。
   • Docker Compose（独立部署开发者门户）：保存开发者门户后端的 backend_conf/conf.yaml、开发者门户前端的 frontend_conf/config.yaml，以及 Portal Token 和身份认证密钥。后端必须使用现有的控制面数据库，而前端使用单独的身份认证与会话数据库；请保留这两个数据库的可恢复备份。
   • RPM（3.10.1）：按照安装包随附的说明和 systemd 单元文件操作。保存所有引用的配置文件、环境变量文件、证书、私钥和连接参数；文件布局以该版本的安装包为准。
   • RPM（3.10.2 至 3.10.6，独立 Console）：保存控制台的 /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。同时保存每个数据面实例的 config.yaml 或部署 values。
   • RPM（3.10.7 及更高版本，内嵌控制台）：保存控制台的 /usr/local/api7/dashboard/conf/dashboard.yaml、DP Manager 的 /usr/local/api7/dp-manager/conf/dp-manager.yaml。同时保存每个数据面实例的 config.yaml 或部署 values。Console 内嵌在 Dashboard 二进制文件中，因此这些版本没有 console.env 文件，也没有独立的 api7ee-console 服务。
   • Kubernetes / OpenShift（Helm）：保存每个控制面 release 的 values、命令行覆盖参数、渲染后的资源清单，以及引用的 ConfigMap 和 Secret。另行保存外部密钥管理系统中的恢复材料。

2. 每个数据面网关实例使用的 config.yaml 文件或部署 values，以及所引用的证书、私钥和连接参数。

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

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

请将这些文件保存在访问受控的备份系统中，并在回滚演练期间确认运维人员能够取回。

数据恢复与回滚

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

从数据库恢复

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

1. 设置用于恢复的 PostgreSQL 管理角色。该角色需要 CREATEDB 权限、将 api7ee 指定为数据库所有者的权限，以及授予目标数据库 public schema 权限的权限：

   export POSTGRES_ADMIN_USER="YOUR_POSTGRES_ADMIN_USER"

2. 使用该角色创建正在运行的 CP 无法访问的空目标数据库，将应用角色指定为所有者，并授予其访问 public schema 的权限：

   createdb -U "${POSTGRES_ADMIN_USER}" \
     --owner=api7ee \
     api7ee_restored
   
   psql -U "${POSTGRES_ADMIN_USER}" \
     -d api7ee_restored \
     -c 'GRANT ALL ON SCHEMA public TO api7ee;'

3. 以应用角色恢复备份。遇到第一个错误时立即停止，避免将部分恢复误认为恢复成功：

   pg_restore --exit-on-error \
     -U api7ee \
     -d api7ee_restored \
     api7ee_backup_20250523/

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

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

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

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

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

从声明式配置恢复

警告

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

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

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

   • 使用保存的 name、description 和 labels 更新已有的 default 网关组。对于 3.8.23–3.8.24、3.9.19–3.9.23 或 3.10.0–3.10.2，还应恢复保存的 enforce_service_publishing；对于 3.10.5–3.10.10，则恢复保存的 environment。
   • 使用保存的通用字段重新创建所有需要的非默认网关组。对于 3.8.23–3.8.24、3.9.19–3.9.23 或 3.10.0–3.10.2，还需发送 enforce_service_publishing；对于 3.10.3–3.10.4，不发送其他字段；对于 3.10.5–3.10.10，则发送 environment。
   • 不要发送源版本不接受的字段。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 中创建控制台 Token，并确保它能够列出网关组，以及读取、创建、更新和删除所有待恢复的 ADC 支持资源类型。将 Token 提供给 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 或控制器都使用替换后的凭据连接到目标网关组，并验证代表性流量，然后再让它们重新承载生产流量。