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

数据面弹性

API7 网关数据面节点会将配置缓存在内存中，因此在控制面（CP）短暂中断时仍可继续处理流量。但是，如果中断持续时间较长，例如发生数据库故障、控制面升级或灾难恢复，无法连接 CP 的节点在重启后将无法加载配置。

在规划好流量服务节点的扩缩容和高可用性后，使用本指南：

备用控制面（Fallback CP） 将网关配置存储到 AWS S3、S3 兼容存储或 Azure Blob 存储。发生中断时，以备用读取模式重启或重新部署流量节点，使其使用已存储的快照作为配置来源。

当控制面连接失败时，备用控制面不会自动切换正在运行的节点。持续运行的节点会继续使用内存中的配置。当节点必须在控制面不可用期间启动时，使用备用读取模式；控制面恢复后，再恢复节点原来的部署配置。

工作原理​

备用控制面快照可以由备份网关节点或定时运行的控制面推送器生成。备份网关与处理流量的节点同时运行，但不处理 API 流量。它只负责从控制面接收配置，并定期将配置导出到外部存储。下图展示了这一方案。

正常运行​

正常运行时，每个数据面节点（包括备份节点）都会通过 mTLS 端口 7943 监听控制面的 etcd 兼容 API，以接收配置。有关详情，请参见架构中的拉取/监听模型。备份节点还会定期将收到的配置写入外部存储。

备用模式​

控制面不可用时，运维人员需要以备用读取模式重新部署或重启流量节点。节点启动时，会根据网关组短 ID 从外部存储加载资源对象和数据面配置对象。

导出内容​

备份节点或控制面推送器按网关组导出两类数据：

类别内容
资源数据路由、服务、上游、消费者、凭证、SSL 证书、全局规则、插件元数据、插件配置、四层路由、密钥、自定义插件和 Protobuf 定义
配置数据数据面配置，包括密钥环和服务发现设置

每个网关组的数据会存储为独立对象，并以网关组的短 ID 作为键。恢复节点必须使用与所加载快照相同的 API7_GATEWAY_GROUP_SHORT_ID。

信息

Chart 仍会为备份 Release 创建网关 Service，并发布配置的端口。但是，网关会在启动时识别写入模式，不生成 HTTP/HTTPS 和四层流量的 server 块。不要将备份 Service 加入负载均衡器、Ingress 路由、DNS 记录或客户端配置。备份节点不计入许可证配额。

前置条件​

  • 正在运行的 API7 网关部署，至少有一个网关组。
  • 外部存储后端：
    • AWS S3 或 S3 兼容存储：两个具有适当访问权限的存储桶，一个用于资源数据，一个用于配置数据。使用其他 S3 兼容服务时，准备自定义端点 URL。
    • Azure Blob 存储：两个具有适当访问凭证的 Blob 容器，一个用于资源数据，一个用于配置数据。

AWS S3 权限​

备份节点或控制台推送器的 IAM 策略必须包括：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": [
        "arn:aws:s3:::fallback-cp-data/*",
        "arn:aws:s3:::fallback-cp-config/*"
      ]
    }
  ]
}

以备用模式运行的流量节点需要对相同存储桶拥有 s3:GetObject 权限。

对于 S3 兼容存储，请在存储服务商中授予等效的对象读写权限。

Azure Blob 存储权限​

对使用 Workload Identity 的备份网关，授予其在两个容器上的 Storage Blob Data Contributor 角色。恢复身份只需要 Storage Blob Data Reader 角色。控制面推送器需要存储账户访问密钥；账户访问密钥直接授权访问，不通过 Azure RBAC 角色授权。

静态凭证​

Kubernetes 静态密钥示例要求：在每个包含备份网关、恢复网关或使用该凭证的控制台推送器的命名空间中，预先创建名为 fallback-storage-credentials 的 Secret。

提供商必需的 Secret 键
AWS S3aws-access-key-id, aws-secret-access-key
Azure Blob Storageazure-storage-account-key

在安装或升级 Release 前，通过批准的密钥管理流程创建并填充此 Secret。Kubernetes Secret 属于特定命名空间，因此网关与控制面 Release 使用不同命名空间时，需要分别创建 Secret。Docker 示例要求在容器启动前，通过宿主机环境或密钥注入系统，为对应的 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 或 AZURE_STORAGE_ACCOUNT_KEY 变量设置非空值。

配置备份节点​

备份节点是一种在 fallback_cp 下配置了 mode: write 的网关实例。它与普通数据面节点一样连接控制面，但将配置写入外部存储，不处理流量。

为每个网关组部署一个备份节点，使用独立的 Helm Release。从控制台为该网关组生成的 values 开始配置，以保留 DP Manager 端点、mTLS Secret、网关组环境变量、镜像和其他连接设置。将下面的备用配置加入完整的 values 文件。

Chart 从顶层 deployment.fallback_cp 读取备用配置。在 write 模式下，它保留 DP Manager 连接，并渲染 node_listen、容器端口和网关 Service 端口，同时禁用就绪与存活探针，以及 HTTP 和四层访问日志。网关在启动时将自身报告为备份节点，并且不生成 NGINX 流量 server 块。不要将已发布的网关 Service 接入流量路径，确保该 Release 保持明确隔离。

使用服务账户 IAM 角色（IRSA）：

backup-node-values.yaml
apisix:
  kind: Deployment
  replicaCount: 1

deployment:
  fallback_cp:
    interval: 60
    mode: write
    aws_s3:
      region: "us-east-1"
      resource_bucket: "fallback-cp-data"
      config_bucket: "fallback-cp-config"

serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/fallback-cp-role"

❶ 配置导出之间的时间间隔，单位为秒。
❷ write 模式启用存储导出。Chart 保留端口声明，而网关不生成流量 server 块。
❸ S3 存储桶所在的 AWS 区域。
❹ ❺ 分别用于资源数据和配置数据的存储桶。

使用 IAM 访问密钥：

保留控制台生成的 apisix.extraEnvVars 条目，并将存储凭证追加到该列表中。完整列表必须保留 API7_GATEWAY_GROUP_SHORT_ID 及其他所有生成的条目：

backup-node-values.yaml
apisix:
  kind: Deployment
  replicaCount: 1
  extraEnvVars:
    - name: API7_GATEWAY_GROUP_SHORT_ID
      value: "YOUR_GATEWAY_GROUP_SHORT_ID"
    - name: AWS_ACCESS_KEY_ID
      valueFrom:
        secretKeyRef:
          name: fallback-storage-credentials
          key: aws-access-key-id
    - name: AWS_SECRET_ACCESS_KEY
      valueFrom:
        secretKeyRef:
          name: fallback-storage-credentials
          key: aws-secret-access-key

deployment:
  fallback_cp:
    interval: 60
    mode: write
    aws_s3:
      access_key: '${{AWS_ACCESS_KEY_ID}}'
      secret_key: '${{AWS_SECRET_ACCESS_KEY}}'
      region: "us-east-1"
      resource_bucket: "fallback-cp-data"
      config_bucket: "fallback-cp-config"

对于 S3 兼容存储，使用存储服务商提供的访问密钥和秘密密钥，并在 aws_s3 块中添加 endpoint：

deployment:
  fallback_cp:
    aws_s3:
      endpoint: "https://s3-compatible.example.com"
      use_path_style: true

仅当存储服务商要求路径风格的存储桶 URL 时，才启用 use_path_style。

配置控制面推送器​

除了使用备份网关，还可以由控制台进程定期导出每个网关组的配置。此方案不要求为每个网关组部署备份节点，但每次创建快照时都依赖正在运行的控制台和数据库。

Helm​

在 dashboard_configuration.fallback_cp 下配置推送器。将凭证条目合并到现有的完整 dashboard.extraEnvVars 列表中。Helm 会替换列表，因此只含凭证的覆盖文件可能删除其他必需条目，例如通过 Secret 提供的数据库 DSN。

对于 AWS S3：

cp-values.yaml (AWS S3)
dashboard:
  extraEnvVars:
    # 在这些条目上方或下方保留全部现有控制台环境变量。
    - name: AWS_ACCESS_KEY_ID
      valueFrom:
        secretKeyRef:
          name: fallback-storage-credentials
          key: aws-access-key-id
    - name: AWS_SECRET_ACCESS_KEY
      valueFrom:
        secretKeyRef:
          name: fallback-storage-credentials
          key: aws-secret-access-key

dashboard_configuration:
  fallback_cp:
    cron_spec: "@every 1m"
    aws_s3:
      access_key: '${AWS_ACCESS_KEY_ID}'
      secret_key: '${AWS_SECRET_ACCESS_KEY}'
      region: "us-east-1"
      resource_bucket: "fallback-cp-data"
      config_bucket: "fallback-cp-config"
      use_path_style: false

对于 S3 兼容存储，在同一配置块中添加 custom_endpoint。仅当存储服务商要求路径风格的存储桶 URL 时，才将 use_path_style 改为 true：

dashboard_configuration:
  fallback_cp:
    aws_s3:
      custom_endpoint: "https://s3-compatible.example.com"
      use_path_style: true

对于 Azure Blob 存储：

cp-values.yaml (Azure Blob Storage)
dashboard:
  extraEnvVars:
    # 在此条目上方或下方保留全部现有控制台环境变量。
    - name: AZURE_STORAGE_ACCOUNT_KEY
      valueFrom:
        secretKeyRef:
          name: fallback-storage-credentials
          key: azure-storage-account-key

dashboard_configuration:
  fallback_cp:
    cron_spec: "@every 1m"
    azure_blob:
      account_name: "youraccount"
      account_key: '${AZURE_STORAGE_ACCOUNT_KEY}'
      resource_container: "fallback-cp-data"
      config_container: "fallback-cp-config"

控制面推送器要求显式提供访问密钥，不使用网关镜像的 IAM 或 Workload Identity 凭证链。

Docker 或安装包​

在控制台配置文件中配置相同的推送器。启动每个控制台副本前，通过进程管理器或批准的密钥注入机制填充所引用的环境变量：

dashboard-config.yaml
fallback_cp:
  cron_spec: "@every 1m"
  aws_s3:
    access_key: "${AWS_ACCESS_KEY_ID}"
    secret_key: "${AWS_SECRET_ACCESS_KEY}"
    region: "us-east-1"
    resource_bucket: "fallback-cp-data"
    config_bucket: "fallback-cp-config"
    use_path_style: false
  azure_blob:
    account_name: "youraccount"
    account_key: "${AZURE_STORAGE_ACCOUNT_KEY}"
    resource_container: "fallback-cp-data"
    config_container: "fallback-cp-config"

❶ 控制控制台推送配置频率的调度表达式，常用值包括 @every 1m 和 @every 5m。 ❷ ❸ 可以配置一个或两个存储后端，控制台会推送到每个已配置的后端。

对于 S3 兼容存储，在控制台侧的 aws_s3 块中添加 custom_endpoint。仅当存储服务商要求路径风格的存储桶 URL 时，才将 use_path_style 改为 true：

fallback_cp:
  aws_s3:
    custom_endpoint: "https://s3-compatible.example.com"
    use_path_style: true
信息

多个控制台实例运行时，分布式锁确保任一时刻只有一个实例执行推送。

从备用存储恢复流量节点​

发生中断前，为每个网关组保存完整的正常部署 values 或生成的 Docker 命令。确认所选备份方法已在资源存储位置和配置存储位置中，各写入一个以网关组短 ID 命名的对象。

控制面不可用且流量节点必须重启时，以备用读取模式启动该节点。网关会在启动时加载已存储的快照，并将其作为配置来源。

将保存的 normal-values.yaml 复制为 recovery-base-values.yaml。在副本中保留控制台生成的 API7_GATEWAY_GROUP_SHORT_ID 环境变量，以及所有存储身份或凭证配置。

使用在 DP Manager 不可用时仍能工作的探针。在备用读取模式下，/status/ready 仍会检查 DP Manager。如果就绪探针使用该端点，或以其他方式依赖 DP Manager，请在恢复副本中替换整个 gateway.readinessProbe 块。对已启用的流量容器端口使用 TCP 探针。以下示例使用 Chart 默认的时间设置和默认 HTTP 端口 9080：

recovery-base-values.yaml （探针节选）
gateway:
  readinessProbe:
    failureThreshold: 6
    initialDelaySeconds: 10
    periodSeconds: 10
    successThreshold: 1
    tcpSocket:
      port: 9080
    timeoutSeconds: 1

仅在 HTTP 监听已启用时使用此端口。如果网关只处理 HTTPS，将 tcpSocket.port 设置为其配置的 HTTPS 容器端口，默认值为 9443。如果网关只处理四层流量，使用其配置的某个 TCP 四层容器端口。

如果存活探针也使用 /status/ready，请在恢复副本中将其改为配置的状态监听端口上的 /status。TCP 探针只能确认代理监听端口接受连接；还需测试快照中的一条路由，以验证网关能够处理请求。

为所用存储服务商创建单独的备用 values 文件。

fallback-read-values.yaml
serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/fallback-cp-reader-role"

deployment:
  fallback_cp:
    mode: read
    aws_s3:
      region: "us-east-1"
      resource_bucket: "fallback-cp-data"
      config_bucket: "fallback-cp-config"

对于 S3 兼容存储，在 aws_s3 块中添加 endpoint。仅当存储服务商要求路径风格的存储桶 URL 时，才将 use_path_style 设为 true：

deployment:
  fallback_cp:
    aws_s3:
      endpoint: "https://s3-compatible.example.com"
      use_path_style: true

上述示例为恢复操作创建对应存储服务商的服务账户。授予 AWS 角色对两个存储桶的 s3:GetObject 权限，或授予 Azure 身份对两个容器的 Storage Blob Data Reader 角色。如果正常 values 已指定服务账户，将所需注解和 Azure Pod 标签合并到该现有身份，不要将其替换。

如果流量节点使用访问密钥，将存储凭证条目追加到 recovery-base-values.yaml 中现有的 apisix.extraEnvVars 列表，并将对应的 ${{...}} 字段加入 fallback-read-values.yaml。在恢复副本中保留完整环境变量列表，确保 Helm 保留 API7_GATEWAY_GROUP_SHORT_ID 等生成条目。

使用与正常 Release 相同的 Chart 版本，在恢复副本上叠加备用文件：

helm upgrade YOUR_GATEWAY_RELEASE api7/gateway \
  --version YOUR_GATEWAY_CHART_VERSION \
  -n YOUR_NAMESPACE \
  -f recovery-base-values.yaml \
  -f fallback-read-values.yaml \
  --wait

此次升级作用于所选的整个 Release，需要规划其网关 Pod 的滚动更新。Chart 将 role_data_plane.config_provider 设为 json，每个替换后的 Pod 在启动时使用网关组短 ID 获取资源对象和数据面配置对象。Pod 就绪后，通过网关 Service 请求快照中的一条路由。

警告

备用模式使用已存储的快照处理流量，不会接收后续控制面变更。

  • 对于 Helm，重新运行升级命令，用 --reset-values -f normal-values.yaml 替换两个恢复 values 文件，以恢复正常配置和探针。等待控制台中替换后的 Pod 报告为健康，再通过 Service 验证当前配置和流量。
  • 对于 Docker，让其他高可用节点继续处理流量，从负载均衡器摘除备用节点，并移除备用容器以释放端口 9080 和 9443。启动原先固定版本的控制台生成命令，等待新实例报告为健康，并验证当前配置和流量。让节点重新接收流量前，恢复其正常的负载均衡器检查。

验证备份与恢复​

依赖备用存储前，在非生产网关组中测试完整流程：

  1. 创建一条易于识别的测试路由，等待下一个备份间隔或控制台定时任务。
  2. 检查备份网关或控制台日志，确认资源对象和数据面配置对象都在同一次运行中成功写入。如果任一写入失败，不要使用该次运行的结果恢复。
  3. 确认两个存储位置都存在以网关组短 ID 命名的对象。资源对象应包含测试路由，配置对象应包含同一网关组的数据面配置。对比对象的最后修改时间或版本 ID 与成功运行记录。在存储服务商支持时启用对象版本控制，并保留恢复所需的配对对象。
  4. 保存正常部署 values 或 Docker 命令及探针设置，然后让控制面对测试节点不可用。
  5. 以备用读取模式启动该节点。先直接验证测试路由，再配置恢复探针，通过 Service 或负载均衡器发送相同请求。确认请求到达恢复节点，并且网关组使用的认证、插件、上游和服务发现按预期工作。
  6. 控制面恢复后，恢复正常部署配置。等待实例报告为健康，应用一项小的配置变更，确认节点收到该变更后再恢复生产流量。
警告

备用对象包含网关资源和数据面配置，包括带有凭证的插件字段、私钥，以及网关可直接使用的网关组密钥环。请加密存储后端、限制读写权限、审计访问，并采用适合配置备份的保留策略。

配置参考​

备份节点/流量节点（config.yaml）​

字段类型描述
deployment.fallback_cp.mode字符串备份节点使用 write；从备用存储启动的流量节点使用 read。默认值为 read。
deployment.fallback_cp.interval整数导出间隔，单位为秒，仅用于备份节点。
deployment.fallback_cp.aws_s3.access_key字符串AWS 访问密钥 ID，使用 IRSA 时无需设置。
deployment.fallback_cp.aws_s3.secret_key字符串AWS 秘密访问密钥，使用 IRSA 时无需设置。
deployment.fallback_cp.aws_s3.region字符串S3 存储桶所在的 AWS 区域。
deployment.fallback_cp.aws_s3.resource_bucket字符串用于资源数据的 S3 存储桶。
deployment.fallback_cp.aws_s3.config_bucket字符串用于配置数据的 S3 存储桶。
deployment.fallback_cp.aws_s3.endpoint字符串自定义 S3 端点，用于 S3 兼容存储。
deployment.fallback_cp.aws_s3.use_path_style布尔值是否使用路径风格的 S3 存储桶 URL。默认值为 false。
deployment.fallback_cp.azure_blob.account_name字符串Azure 存储账户名称。
deployment.fallback_cp.azure_blob.account_key字符串Azure 存储账户密钥，使用 Workload Identity 时无需设置。
deployment.fallback_cp.azure_blob.resource_container字符串用于资源数据的 Blob 容器。
deployment.fallback_cp.azure_blob.config_container字符串用于配置数据的 Blob 容器。
deployment.fallback_cp.azure_blob.endpoint字符串自定义 Azure Blob 端点，默认值为 https://<account_name>.blob.core.windows.net。

控制台（dashboard-config.yaml）​

字段类型描述
fallback_cp.cron_spec字符串配置推送的调度表达式，例如 @every 1m。
fallback_cp.aws_s3.access_key字符串AWS 访问密钥 ID。
fallback_cp.aws_s3.secret_key字符串AWS 秘密访问密钥。
fallback_cp.aws_s3.region字符串S3 存储桶所在的 AWS 区域。
fallback_cp.aws_s3.resource_bucket字符串用于资源数据的 S3 存储桶。
fallback_cp.aws_s3.config_bucket字符串用于配置数据的 S3 存储桶。
fallback_cp.aws_s3.custom_endpoint字符串用于 S3 兼容存储的自定义 S3 端点。在 API7 控制面 Helm Chart 中配置为 dashboard_configuration.fallback_cp.aws_s3.custom_endpoint。
fallback_cp.aws_s3.use_path_style布尔值是否使用路径风格的存储桶 URL。默认值为 false，仅当存储服务商要求路径风格 URL 时才启用。在 API7 控制面 Helm Chart 中配置为 dashboard_configuration.fallback_cp.aws_s3.use_path_style。
fallback_cp.azure_blob.*—与网关侧 azure_blob 配置的字段相同。

后续步骤​