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

部署高可用环境

以高可用（HA）方式部署 API7 网关，可以消除控制面（CP）和数据面（DP）中的单点故障。本指南介绍部署生产级高可用环境所需的前置条件、架构和具体步骤。

如需了解相关概念，请参阅高可用性。

本页介绍如何部署高可用拓扑。部署完成后，可使用以下配置和管理指南进行日常运维：

部署前，请规划能够在故障期间维持集群可用性的外围基础设施：

  • 自带高可用或托管故障转移机制的外部 PostgreSQL 部署。
  • 分别位于控制面和数据面前端的负载均衡器。
  • 控制台和 DP Manager 端点所需的 TLS 证书，以及数据面节点所需的 mTLS 证书。
  • 每次只重启一个节点，并在继续操作前验证流量的维护流程。

架构概览​

高可用部署包括：

  • 共享一个 PostgreSQL 数据库、并由负载均衡器提供前端入口的多个控制面节点（控制台 + DP Manager）。
  • 位于一个或多个网关组中、并由负载均衡器提供前端入口的多个数据面节点。
  • （可选）备用网关节点：定期将配置导出到外部存储（AWS S3 或 Azure Blob Storage），使数据面在控制面中断时仍具备弹性。

前置条件​

部署检查清单​

安装或扩容任何高可用节点前，请完成以下准备工作：

  1. 准备外部 PostgreSQL 实例或集群，并确认自动故障转移由 API7 网关之外的系统负责。
  2. 为控制面和数据面负载均衡器预留稳定的 DNS 名称或虚拟 IP。
  3. 准备控制台和 DP Manager 端点所需的 TLS 证书。如果数据面节点通过 mTLS 连接，还需准备部署流程所需的 CA 和节点证书。
  4. 确认每个控制面节点使用相同的 PostgreSQL DSN，并且每个数据面节点都通过同一个 DP Manager 端点连接到同一个网关组。
备注

API7 网关依赖 PostgreSQL 的可用性，但不会替你配置 PostgreSQL 复制、主库提升或备份。请将数据库高可用视为控制面高可用的前置条件。

最少节点数​

组件最少节点数说明
控制面2每个节点运行控制台和 DP Manager
数据面2每个节点运行 API7 网关
PostgreSQL托管实例或高可用集群高可用配置不在本指南范围内；请参阅 PostgreSQL 高可用

硬件要求​

组件CPU内存磁盘
控制面4 核8 GB40 GB
数据面4 核8 GB20 GB

详细要求请参阅系统要求。

网络端口​

确保组件之间可以访问以下端口：

服务端口协议说明
控制台7080 / 7443HTTP / HTTPS控制台 UI 和 Admin API
DP Manager7900 / 7943HTTP / HTTPS数据面管理
网关（HTTP）9080HTTPAPI 流量
网关（HTTPS）9443HTTPSAPI 流量
网关状态7085HTTP健康检查端点
PostgreSQL5432TCP数据库
Prometheus9090HTTP指标（可选）

负载均衡器和 TLS​

在生产高可用环境中，应为每条流量路径配置稳定的前端入口：

端点常见前端用途
控制台Ingress、内部负载均衡器或反向代理运维人员访问控制台和 Admin API
DP Manager集群内部 Service 或内部负载均衡器为数据面节点提供稳定的 mTLS 地址
数据面外部负载均衡器或 Ingress Controller客户端 API 流量

在 Kubernetes 中，控制面 Chart 已经为控制台和 DP Manager 分别创建 Service。常见做法是保持 dashboard_service.type: ClusterIP，通过 Ingress 或内部代理暴露控制台，同时将 dp_manager_service 保持为稳定的内部端点。如果数据面节点从集群外部连接，请通过内部负载均衡器或其他稳定的私有前端暴露 DP Manager。

控制面高可用​

API7 控制台和 DP Manager 都是无状态应用程序，所有配置均存储在 PostgreSQL 中。要实现高可用，请在负载均衡器后部署多个实例。

所有控制面副本必须共享：

  • 同一个 PostgreSQL 数据库。
  • 相同的许可证状态和控制台配置。
  • 面向运维人员和数据面节点的稳定端点。

在 Helm 配置中设置副本数并保持 Service 前端稳定，以扩展控制面：

values.yaml
dashboard:
  # ❶
  replicaCount: 2
dp_manager:
  # ❷
  replicaCount: 2

postgresql:
  # ❸
  builtin: false

dashboard_service:
  # ❹
  type: ClusterIP

dp_manager_service:
  # ❺
  type: ClusterIP

dashboard_configuration:
  database:
    dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

dp_manager_configuration:
  database:
    dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

❶ 至少部署 2 个控制台副本以实现冗余。

❷ 至少部署 2 个 DP Manager 副本。

❸ 禁用内置 PostgreSQL，并让控制面连接外部高可用数据库。

❹ 将控制台放在稳定的前端之后，例如 Ingress、内部代理或 LoadBalancer Service。

❺ 为同一网关组中的所有数据面节点提供一个稳定的 DP Manager 地址。

如果同一个 Helm Release 中仍启用了开发者门户，还需将 developer_portal_configuration.database.dsn 设置为同一个 PostgreSQL 端点，或者在该 Release 中禁用开发者门户。

安装或升级 Helm Release：

helm upgrade --install api7ee3 api7/api7ee3 -f values.yaml -n api7 --create-namespace

如果在控制台自身终止 TLS，请使用 dashboard.keyCertSecret 配置控制台证书。如果改为在 Ingress 或负载均衡器上终止 TLS，请确保后端端口只能从可信网络访问。

为了在 Kubernetes 上获得更可靠的调度分布，还可配置 dashboard.topologySpreadConstraints 和 dp_manager.topologySpreadConstraints，让副本落在不同的工作节点或可用区。

提示

所有控制台和 DP Manager 实例都必须连接到同一个 PostgreSQL 数据库。PostgreSQL 高可用（主从复制、Patroni，或 Amazon RDS、Azure Database、Google Cloud SQL 等托管服务）属于独立事项，应根据数据库提供商的文档进行配置。

数据面高可用​

数据面节点是无状态的：它们从控制面接收配置并独立处理流量。请在负载均衡器后部署多个节点。

为实现可预测的故障转移行为，请确保：

  • 每个节点都属于同一个网关组。
  • 负载均衡器仅向健康节点转发流量。
  • 尽可能将节点分散到不同故障域，例如不同主机、可用区或 Kubernetes 工作节点。

健康检查配置​

每个网关节点都提供用于健康监控的状态端点：

端点方法说明
/statusGET网关正在运行时返回 200
/status/readyGET网关已准备好接收流量时返回 200

状态端点默认监听 7085 端口。请配置负载均衡器定期检查该端点，例如每 10–30 秒检查一次。

如果只需确认网关进程仍在运行，请使用 /status。如果希望负载均衡器只向仍可连接 DP Manager 的节点路由流量，请使用 /status/ready。

备注

如果你的运维模式允许数据面节点在控制面短暂中断期间继续使用缓存配置提供服务，检查 /status 可让这些节点继续接收流量。如果希望在 DP Manager 连接丢失时让负载均衡器停止路由流量，请使用 /status/ready。有关详细权衡，请参阅配置就绪和存活探针。

部署多个数据面节点​

将以下面向高可用的配置添加到 api7/gateway Chart 所使用的 values.yaml 文件中：

gateway-values.yaml
api7ee:
  status_endpoint:
    # ❶
    enabled: true
    ip: 0.0.0.0
    port: 7085

apisix:
  # ❷
  replicaCount: 3

  podDisruptionBudget:
    # ❸
    enabled: true
    minAvailable: 1

  affinity:
    # ❹
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - gateway
            topologyKey: kubernetes.io/hostname

gateway:
  # ❺
  readinessProbe:
    httpGet:
      path: /status/ready
      port: 7085
  livenessProbe:
    httpGet:
      path: /status
      port: 7085

❶ 在 7085 端口暴露状态端点，以便 Kubernetes 和外部健康检查程序验证节点状态。

❷ 至少运行 2 个数据面副本以实现高可用；如果希望在维护期间保留更多容量，可从 3 个副本起步。

❸ 使用 PodDisruptionBudget，避免自愿中断一次驱逐所有网关 Pod。

❹ 将 Pod 分散到不同工作节点，以降低单节点故障的影响。

❺ 分别使用就绪和存活检查，让调度器和负载均衡器停止向未就绪节点发送流量。

请选择符合环境要求的 Service 暴露方式。在托管 Kubernetes 中，设置 gateway.type: LoadBalancer 是创建数据面前端的常见方式。如果已有 Ingress Controller 或外部 L4/L7 负载均衡器，请保留符合该设计的 Service 类型，并让前端指向网关 Service。

有关健康检查和弹性行为的详细信息，请参阅数据面高可用性。

数据面弹性（备用控制面）​

对于要求数据面能够承受控制面长时间中断的环境，请配置备用控制面。此功能会定期将全部网关配置导出到外部存储（AWS S3 或 Azure Blob Storage）；控制面不可用时，数据面节点可以从存储中获取配置。

详细配置步骤请参阅数据面弹性。

验证​

部署高可用环境后，请验证每个组件：

  1. 控制面：通过负载均衡器 URL 访问控制台。检查各节点的访问日志，确认两个实例都在处理请求。

  2. 数据面：通过数据面负载均衡器发送测试请求：

    curl -i "http://<dp-load-balancer>:9080/"

  3. 健康检查：验证每个数据面节点上的状态端点：

    curl -i "http://<dp-node>:7085/status"
    # Expected: HTTP/1.1 200 OK

  4. 故障转移测试：停止一个控制面节点，确认仍可通过负载均衡器访问控制台。停止一个数据面节点，确认 API 流量仍通过其他节点正常转发。

运维手册​

在验收测试和日常维护期间执行以下检查。

控制面故障转移测试​

  1. 通过控制面负载均衡器登录控制台。
  2. 停止或隔离一个控制面节点。
  3. 刷新控制台，确认当前会话仍可使用。
  4. 应用一项小型配置变更，例如更新路由描述，并确认变更成功。
  5. 恢复故障节点，确认它重新加入负载均衡器后端池。

数据面故障转移测试​

  1. 通过数据面负载均衡器持续发送请求。
  2. 停止或排空一个网关节点。
  3. 确认负载均衡器健康检查将该节点标记为不健康。
  4. 验证客户端流量仍通过其他网关节点转发，且未发生完全中断。
  5. 恢复节点，并确认它只有在通过健康检查后才重新提供服务。

滚动重启流程​

每次只维护一个节点：

  1. 重启任何节点前，确认至少还有一个控制面节点和一个数据面节点处于健康状态。
  2. 从负载均衡器后端池中移除一个节点，或优雅地排空该节点。
  3. 重启节点，等待它恢复健康状态。
  4. 在继续处理下一个节点前，验证控制台访问或网关流量。
  5. 对其余节点重复上述步骤。

除非已经安排停机维护，否则切勿同时重启所有控制面节点或所有数据面节点。

后续步骤​