版本：3.10.x

在 Kubernetes 上部署

本指南介绍如何使用 Helm Chart 在 Kubernetes 上部署 API7 网关。部署包含两个主要组件：

控制面（CP）：控制台、DP Manager 和 PostgreSQL 数据库。
数据面（DP）：处理 API 流量的 API7 网关实例。

架构概览

前置条件

开始前，请确保具备：

运行 1.25 或更高版本的 Kubernetes 集群，例如 EKS、GKE、AKS 或自建集群。
已配置集群访问权限的 kubectl 1.25 或更高版本。
Helm 3.10 或更高版本。请参阅安装 Helm。
PostgreSQL 12 或更高版本。生产环境建议使用外部数据库。
API7 网关许可证。请参阅获取试用许可证。

StorageClass

PostgreSQL 和 Prometheus 默认启用持久化存储。如果集群未配置 StorageClass，将出现 PVC 绑定错误。请配置 StorageClass，或禁用持久化（生产环境不建议）。

第 1 步：添加 API7 Helm 仓库

helm repo add api7 https://charts.api7.ai
helm repo update

验证仓库是否添加成功：

helm search repo api7/

预期输出包含 api7/api7ee3（控制面）和 api7/gateway（数据面）。

第 2 步：创建命名空间

为所有 API7 组件创建专用命名空间：

kubectl create namespace api7

第 3 步：准备 PostgreSQL 数据库

生产部署应使用外部 PostgreSQL 数据库（例如 Amazon RDS、Cloud SQL、Azure Database for PostgreSQL），以获得持久性和高可用。

如果正在评估 API7 或运行非生产环境，Helm Chart 可以部署内置 PostgreSQL 实例。此时跳过本步骤，并在第 4 步的控制面配置文件中设置 postgresql.builtin: true。

对于外部 PostgreSQL，请创建数据库和用户：

CREATE DATABASE api7ee;
CREATE USER api7ee WITH ENCRYPTED PASSWORD 'YOUR_DB_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE api7ee TO api7ee;

第 4 步：配置控制面

创建 cp-values.yaml 文件：

cp-values.yaml
# -- 禁用内置 PostgreSQL Chart，并将控制台指向外部数据库。
postgresql:
  # 1
  builtin: false

dashboard_configuration:
  database:
    # 2
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_PG_HOST:5432/api7ee"

dp_manager_configuration:
  database:
    # 2
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_PG_HOST:5432/api7ee"

dashboard_service:
  # 3
  type: ClusterIP

使用外部数据库时禁用内置 PostgreSQL Chart。
将控制台和 DP Manager 中的 YOUR_PG_HOST、YOUR_DB_PASSWORD 替换为 PostgreSQL 连接信息。使用 AWS RDS 时，请填写实例端点，例如 api7ee.xxxx.us-east-1.rds.amazonaws.com。
初始安装建议使用 ClusterIP，通过 kubectl port-forward 访问控制台。需要长期访问时，改用 LoadBalancer 或 Ingress Controller。

快速评估配置

要使用内置 PostgreSQL 快速评估（不适用于生产环境）：

cp-values-eval.yaml
postgresql:
  # 1
  builtin: true
  primary:
    persistence:
      enabled: true
      size: 10Gi

dashboard_service:
  # 2
  type: ClusterIP

在评估环境中启用内置 PostgreSQL Chart。
将控制台 Service 保持为 ClusterIP，并使用 kubectl port-forward 访问。

第 5 步：安装控制面

helm install api7ee3 api7/api7ee3 \
  -f cp-values.yaml \
  -n api7

此处 Helm Release 名称和 Chart 名称均为 api7ee3，与 Chart 自身的 Chart.yaml 一致。可以选择其他 Release 名称，但修改后也要相应调整下方验证命令中的 Helm 选择器。

第 6 步：验证控制面 Pod

等待所有控制面 Pod 进入 Ready 状态：

kubectl -n api7 wait \
  --for=condition=Ready pod \
  -l app.kubernetes.io/name=api7ee3 \
  --timeout=900s

镜像拉取期间也可以持续观察 Pod 状态：

kubectl get pods -n api7 -w

预期输出：

NAME                                    READY   STATUS    RESTARTS   AGE
api7ee3-dashboard-xxxxx-yyyyy           1/1     Running   0          2m
api7ee3-dp-manager-xxxxx-yyyyy          1/1     Running   0          2m
api7ee3-developer-portal-xxxxx-yyyyy    1/1     Running   0          2m

如果使用内置 PostgreSQL，还应看到：

api7-postgresql-0                       1/1     Running   0          2m

备注

冷启动时，内置 PostgreSQL 镜像仍在拉取或初始化，api7ee3-dp-manager 或 api7ee3-developer-portal 可能短暂重启。如果 Pod 日志显示数据库拒绝连接且 api7-postgresql-0 尚未就绪，请等待 PostgreSQL 就绪后重新检查控制面 Pod。数据库可用后，此暂时状态应自动恢复，无需手动操作。

第 7 步：验证控制面 Service

kubectl get svc -n api7 -l app.kubernetes.io/name=api7ee3 -o wide

预期输出：

NAME                       TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
api7ee3-dashboard          ClusterIP   10.100.25.236   <none>        7080/TCP,7443/TCP            3m
api7ee3-developer-portal   ClusterIP   10.100.88.101   <none>        4321/TCP                     3m
api7ee3-dp-manager         ClusterIP   10.100.239.32   <none>        7900/TCP,7943/TCP           3m

关键 Service：

Service	端口	用途
`api7ee3-dashboard`	7443	控制台 UI 和 Admin API
`api7ee3-dashboard`	7080	控制台 HTTP 端点
`api7ee3-developer-portal`	4321	开发者门户 Service
`api7ee3-dp-manager`	7900	DP Manager HTTP 端点
`api7ee3-dp-manager`	7943	DP Manager mTLS 端点（网关连接）

第 8 步：访问控制台

将控制台端口转发到本地计算机：

kubectl -n api7 port-forward svc/api7ee3-dashboard 7443:7443

在浏览器中打开 https://localhost:7443，使用默认凭证（admin / admin）登录。首次登录时，控制台会提示重置密码，随后打开 Activate License 页面，可在此上传并激活许可证。

第 9 步：配置 DP Manager 地址

在 API7 控制台中进入 Gateway Settings，将 DP Manager Address 设置为 Kubernetes 内部 Service DNS：

https://api7ee3-dp-manager:7943

数据面实例将使用此地址连接控制面。

第 10 步：添加网关实例（生成数据面证书）

在 API7 控制台中选择网关组（例如 default），进入 Gateway Instances 并点击 Add Gateway Instance。选择 Kubernetes，填写目标命名空间并生成部署脚本。控制台将生成：

数据面的 TLS 证书（tls.crt）。
TLS 私钥（tls.key）。
用于验证控制面的 CA 证书（ca.crt）。
为生成证书创建 Secret 的 kubectl create secret 命令。
包含所有必需参数的完整 Helm 安装命令。

复制生成的脚本，其中包含证书、Secret 创建命令，以及安装数据面的准确 Helm 命令。

第 11 步：创建 mTLS Secret

从生成的脚本提取证书并创建 Kubernetes Secret：

# 将生成脚本中的证书保存到文件，然后创建 Secret：
kubectl create secret generic api7-ee-3-gateway-tls \
  --from-file=tls.crt=/tmp/tls.crt \
  --from-file=tls.key=/tmp/tls.key \
  --from-file=ca.crt=/tmp/ca.crt \
  -n api7

警告

每个网关组的证书都是唯一的。如果有多个网关组，每组都需要自己的证书和独立 Kubernetes Secret。

第 12 步：安装数据面

使用控制台生成的 Helm 命令，或将生成的配置写入 dp-values.yaml，再使用 Helm 安装数据面。

dp-values.yaml
etcd:
  auth:
    tls:
      enabled: true
      existingSecret: api7-ee-3-gateway-tls
      certFilename: tls.crt
      certKeyFilename: tls.key
      verify: true
  host:
    # ❶
    - https://api7ee3-dp-manager:7943

gateway:
  tls:
    existingCASecret: api7-ee-3-gateway-tls
    certCAFilename: ca.crt

apisix:
  extraEnvVars:
    - name: API7_GATEWAY_GROUP_SHORT_ID
      # ❷
      value: default
  # ❸
  replicaCount: 2
  image:
    repository: api7/api7-ee-3-gateway
    tag: ${GATEWAY_VERSION}

❶ 将数据面指向集群内部的 DP Manager mTLS Service。

❷ 如果不使用默认组，请将 default 替换为网关组短 ID。

❸ 根据可用性要求和与控制面兼容的网关镜像版本设置副本数及 ${GATEWAY_VERSION}。生产环境必须固定明确版本，不要使用 latest。

helm upgrade --install api7-ee-3-gateway api7/gateway \
  -f dp-values.yaml \
  -n api7

第 13 步：验证数据面 Pod

kubectl get pods -n api7 -l app.kubernetes.io/name=gateway -w

预期输出：

NAME                                       READY   STATUS    RESTARTS   AGE
api7-ee-3-gateway-xxxxx-yyyyy              1/1     Running   0          1m
api7-ee-3-gateway-xxxxx-zzzzz              1/1     Running   0          1m

第 14 步：验证数据面 Service

kubectl get svc -n api7 -l app.kubernetes.io/name=gateway

预期输出：

NAME                          TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
api7-ee-3-gateway-gateway     NodePort   10.100.50.100   <none>        80:31080/TCP,443:31443/TCP   1m

第 15 步：在控制台中验证连接

如果实例未出现：

检查数据面 Pod 日志：kubectl logs -n api7 -l app.kubernetes.io/name=gateway --tail=50。
确认 mTLS Secret 存在：kubectl get secret api7-ee-3-gateway-tls -n api7。
确认 Secret 包含全部必需文件：kubectl get secret api7-ee-3-gateway-tls -n api7 -o json | jq '.data | keys'。
确认数据面 Pod 可以访问控制面地址。出现 TLS 握手错误属于预期现象，此检查仅验证 DNS 和网络连通性：kubectl exec -n api7 <gateway-pod> -- curl -sk --connect-timeout 5 "https://api7ee3-dp-manager:7943/" -o /dev/null -w "%{http_code}"。

第 16 步：暴露网关

选择以下一种方式，为外部流量暴露网关：

方式 A：NodePort Service（默认）

网关 Helm Chart 默认创建 NodePort Service。可以通过节点 IP 访问，也可以端口转发该 Service 进行本地验证。

# 使用端口转发访问默认 Service
kubectl port-forward -n api7 svc/api7-ee-3-gateway-gateway 9080:80

方式 B：LoadBalancer Service

在云提供商环境中，将 Service 改为 LoadBalancer 以分配外部地址：

helm upgrade api7-ee-3-gateway api7/gateway \
  --set "gateway.type=LoadBalancer" \
  -n api7 --reuse-values

更新 Service 后，检查外部地址：

kubectl get svc -n api7 api7-ee-3-gateway-gateway \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

方式 C：Ingress Controller

如果已有 Ingress Controller（例如 NGINX Ingress、AWS ALB Controller），请创建指向网关 Service 的 Ingress 资源。

第 17 步：测试部署

向网关发送测试请求：

curl -i "http://127.0.0.1:9080/"

如果尚未配置路由，应收到 API7 网关返回的 404 响应，表明网关正在运行并接收流量。

可以在自动冒烟测试中使用以下最小断言：

kubectl -n api7 wait \
  --for=condition=Ready pod \
  -l app.kubernetes.io/name=gateway \
  --timeout=600s

kubectl -n api7 get secret api7-ee-3-gateway-tls \
  -o json | jq '.data | keys'

curl -i "http://127.0.0.1:9080/"

预期结果包括：网关 Pod 已就绪；Secret 包含 ca.crt、tls.crt 和 tls.key；配置路由前返回 HTTP 404。

云平台专用指南

AWS EKS

负载均衡器配置

使用 AWS Load Balancer Controller 支持网络负载均衡器（NLB）：

Additional values for EKS
apisix:
  service:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: "external"
      service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"
      service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"

节点组建议

对于性能敏感的部署，请使用专用节点组：

节点组	实例类型	用途
`api7-cp`	`m5.xlarge`（4 vCPU、16 GB）	控制面组件
`api7-dp`	`c5.2xlarge`（8 vCPU、16 GB）	网关数据面

使用节点选择器或节点亲和性将组件调度到适当节点：

DP values with node selector
apisix:
  nodeSelector:
    nodeName: api7-dp

EKS 专用前置条件

使用 NLB 时安装 AWS Load Balancer Controller。
为 PostgreSQL 持久化存储创建 EBS CSI 驱动插件。
配置 kubectl 访问 EKS 集群：

aws eks update-kubeconfig --region <region-code> --name <cluster-name>

GCP GKE

负载均衡器配置

GKE 会自动为 LoadBalancer Service 创建 TCP 负载均衡器。要使用带 Google Cloud Armor 的 HTTP(S) 负载均衡：

Additional values for GKE
apisix:
  service:
    annotations:
      cloud.google.com/l4-rls: "enabled"
      networking.gke.io/load-balancer-type: "Internal"  # 仅允许内部访问

防火墙规则

确保以下防火墙规则允许流量进入 GKE 节点：

端口	协议	来源	用途
9080	TCP	客户端 CIDR	网关 HTTP 流量
9443	TCP	客户端 CIDR	网关 HTTPS 流量
7443	TCP	管理员 CIDR	控制台访问
7943	TCP	集群内部	控制面与数据面 mTLS 通信

GKE 专用前置条件

PostgreSQL 使用 Cloud SQL 时启用 GKE Workload Identity。
创建 Cloud SQL PostgreSQL 实例，并为 VPC 配置私有 IP。

Azure AKS

负载均衡器配置

AKS 默认使用 Standard SKU 负载均衡器。要配置内部访问：

Additional values for AKS
apisix:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "true"

AKS 专用前置条件

使用 Azure Disk CSI 驱动（AKS 1.21+ 默认启用）提供 PostgreSQL 持久化存储。
使用外部 PostgreSQL 时，创建 Azure Database for PostgreSQL Flexible Server。
生产环境使用 Azure CNI，以获得可预测的 Pod IP 分配。

生产环境加固

资源请求和限制

生产工作负载必须设置资源请求和限制。以下是起始示例值，并非 Chart 默认值；请根据流量特征、已启用插件和性能基准结果进行调整。

DP values with resource limits
apisix:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

Worker 进程

配置 NGINX Worker 进程数，使其与分配给网关 Pod 的 CPU 核数一致：

--set "nginx.workerProcesses=auto"

也可以设置明确数量：

--set "nginx.workerProcesses=4"

PodDisruptionBudget

创建 PodDisruptionBudget（PDB），确保节点维护期间网关保持可用：

pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api7-gateway-pdb
  namespace: api7
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: gateway

kubectl apply -f pdb.yaml

HorizontalPodAutoscaler

启用基于 CPU 利用率的自动扩缩容：

hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api7-gateway-hpa
  namespace: api7
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api7-ee-3-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

kubectl apply -f hpa.yaml

反亲和性规则

将网关 Pod 分散到多个节点，以提高容错能力：

DP values with anti-affinity
apisix:
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - gateway
            topologyKey: kubernetes.io/hostname

故障排查

控制面 Pod 在初次启动期间重启

现象：api7ee3-dp-manager 或 api7ee3-developer-portal 短暂进入 CrashLoopBackOff，日志显示数据库拒绝连接。

原因：使用内置 PostgreSQL Chart 时，控制面组件可能在 PostgreSQL 完成镜像拉取并开始接受连接前启动。

解决方法：

kubectl get pods -n api7 -w
kubectl logs -n api7 statefulset/api7-postgresql --tail=100
kubectl logs -n api7 deploy/api7ee3-dp-manager --tail=100

等待 api7-postgresql-0 变为 1/1 Running，然后验证所有控制面 Pod 均已就绪：

kubectl -n api7 wait \
  --for=condition=Ready pod \
  -l app.kubernetes.io/name=api7ee3 \
  --timeout=900s

如果 PostgreSQL 就绪后控制面 Pod 仍持续重启，请检查 Pod 事件和数据库 DSN 配置。

Pod 停留在 Pending 状态

现象：控制面或数据面 Pod 一直处于 Pending 状态。

原因：集群资源不足，或 PVC 缺少 StorageClass。

解决方法：

# 检查 Pod 事件
kubectl describe pod <pod-name> -n api7

# 按时间顺序检查命名空间事件
kubectl get events -n api7 --sort-by=.lastTimestamp

# 如果与 PVC 相关，请检查存储类
kubectl get storageclass

数据面无法连接控制面

现象：数据面 Pod 处于 Running，但日志显示 connection refused 或 certificate verify failed。

解决方法：

验证 mTLS Secret 存在且包含全部三个文件：

kubectl get secret api7-ee-3-gateway-tls -n api7 -o json | jq '.data | keys'
# 预期输出：["ca.crt", "tls.crt", "tls.key"]

验证数据面 Pod 能够解析控制面地址：

kubectl exec -n api7 <gateway-pod> -- nslookup api7ee3-dp-manager

检查数据面 Pod 日志中的具体错误：

kubectl logs -n api7 <gateway-pod> --tail=100

无法访问控制台

现象：配置端口转发或 LoadBalancer 后仍无法访问控制台。

解决方法：

验证控制台 Pod 正在运行：kubectl get pods -n api7 -l app.kubernetes.io/component=dashboard。
检查 Service 端点：kubectl get endpoints -n api7 api7ee3-dashboard。
确保网络策略或安全组未阻止 7443 端口。

后续步骤

API7 网关控制面配置参考：部署后调整控制面设置。
扩缩容数据面：添加更多网关实例以处理增长的流量。
升级 API7 网关：将安装升级到较新版本。
数据面高可用性：配置健康检查和故障转移。
安装常见问题：排查常见安装问题。

架构概览​

前置条件​

第 1 步：添加 API7 Helm 仓库​

第 2 步：创建命名空间​

第 3 步：准备 PostgreSQL 数据库​

第 4 步：配置控制面​

第 5 步：安装控制面​

第 6 步：验证控制面 Pod​

第 7 步：验证控制面 Service​

第 8 步：访问控制台​

第 9 步：配置 DP Manager 地址​

第 10 步：添加网关实例（生成数据面证书）​

第 11 步：创建 mTLS Secret​

第 12 步：安装数据面​

第 13 步：验证数据面 Pod​

第 14 步：验证数据面 Service​

第 15 步：在控制台中验证连接​

第 16 步：暴露网关​

方式 A：NodePort Service（默认）​

方式 B：LoadBalancer Service​

方式 C：Ingress Controller​

第 17 步：测试部署​

云平台专用指南​

AWS EKS​

负载均衡器配置​

节点组建议​

EKS 专用前置条件​

GCP GKE​

负载均衡器配置​

防火墙规则​

GKE 专用前置条件​

Azure AKS​

负载均衡器配置​

AKS 专用前置条件​

生产环境加固​

资源请求和限制​

Worker 进程​

PodDisruptionBudget​

HorizontalPodAutoscaler​

反亲和性规则​

故障排查​

控制面 Pod 在初次启动期间重启​

Pod 停留在 Pending 状态​

数据面无法连接控制面​

无法访问控制台​

后续步骤​

架构概览

前置条件

第 1 步：添加 API7 Helm 仓库

第 2 步：创建命名空间

第 3 步：准备 PostgreSQL 数据库

第 4 步：配置控制面

第 5 步：安装控制面

第 6 步：验证控制面 Pod

第 7 步：验证控制面 Service

第 8 步：访问控制台

第 9 步：配置 DP Manager 地址

第 10 步：添加网关实例（生成数据面证书）

第 11 步：创建 mTLS Secret

第 12 步：安装数据面

第 13 步：验证数据面 Pod

第 14 步：验证数据面 Service

第 15 步：在控制台中验证连接

第 16 步：暴露网关

方式 A：NodePort Service（默认）

方式 B：LoadBalancer Service

方式 C：Ingress Controller

第 17 步：测试部署

云平台专用指南

AWS EKS

负载均衡器配置

节点组建议

EKS 专用前置条件

GCP GKE

负载均衡器配置

防火墙规则

GKE 专用前置条件

Azure AKS

负载均衡器配置

AKS 专用前置条件

生产环境加固

资源请求和限制

Worker 进程

PodDisruptionBudget

HorizontalPodAutoscaler

反亲和性规则

故障排查

控制面 Pod 在初次启动期间重启

Pod 停留在 Pending 状态

数据面无法连接控制面

无法访问控制台

后续步骤