版本：3.10.x

生产部署检查清单

选择受支持的 API7 网关版本后、将生产流量发送到数据面前，请使用此检查清单。本文重点检查处理 API 流量的网关实例。控制面及其数据库同样必须按部署高可用环境所述实现高可用。

需要编排、自动重调度、滚动更新和自动扩缩容时，建议使用 Kubernetes 和 Helm。如果在 Docker 主机上运行 API7 网关，请使用 Docker Compose 管理每个实例，不要分别运行 docker run 命令。Docker Compose 本身不提供跨主机高可用，因此生产 Docker 部署需要多台主机和一个外部负载均衡器。

部署前检查

固定受支持的版本。 将 Helm Chart 和容器镜像固定到与控制面兼容的版本，不要使用 latest。参见支持的版本和互操作性。
为每个网关实例选择 CPU 配额。 以生产环境系统要求为起点，再使用具有代表性的路由、插件、负载、TLS 流量和日志设置进行负载测试。
使 worker 数与 CPU 核数匹配。 为分配给网关的每个 CPU 核配置一个 NGINX worker 进程。例如，分配 4 个 CPU 核时设置 4 个 worker。当容器的 CPU 配额小于宿主机时，不要依赖宿主机级别的自动探测来决定 worker 数。测试方法参见性能基准。
按故障场景规划容量。 一个实例、主机、节点或可用区不可用时，其余网关实例必须能够处理峰值流量。
部署至少两个网关实例。 如需在滚动更新期间或单实例在峰值负载下发生故障时仍保留冗余，请部署 3 个或更多实例。
准备负载均衡器。 只向健康的网关实例发送流量，并在上线前测试移除和重新加入实例。
保护控制面连接。 使用为网关组生成的 mTLS 凭证，将 DP Manager 端点限制在可信网络内，并监控证书到期时间。
明确运维责任。 为容量、升级、证书、数据库备份、告警和事件响应分别指定负责人。

Kubernetes 和 Helm 检查清单

维护生产 values 文件

在版本控制中保存专用的生产 values.yaml 文件。
不要把密钥放入 values 文件，应引用 Kubernetes Secret 或外部密钥管理器。
添加生产覆盖项时，保留控制台生成的网关组、DP Manager 和 mTLS 设置。
应用清单前先使用 helm template 检查渲染结果。
所有变更都通过 helm upgrade --install -f values.yaml 应用。不要编辑生成的 ConfigMap、Deployment 或运行中 Pod 内的文件，因为 Helm 会覆盖这些变更。
将 Chart 版本与 values 文件一并记录，确保升级可以复现。

以下示例为名为 api7-ee-3-gateway 的网关 release 提供生产基线。请根据负载测试和集群拓扑调整 CPU、内存、副本数、镜像标签和调度规则。

values.yaml
apisix:
  kind: Deployment
  replicaCount: 3

  image:
    repository: api7/api7-ee-3-gateway
    tag: "<gateway-version>"

  resources:
    requests:
      cpu: "4"
      memory: 8Gi
    limits:
      cpu: "4"
      memory: 8Gi

  terminationGracePeriodSeconds: 300

  podDisruptionBudget:
    enabled: true
    minAvailable: 2

  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: ScheduleAnyway
      labelSelector:
        matchLabels:
          app.kubernetes.io/name: gateway
          app.kubernetes.io/instance: api7-ee-3-gateway
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app.kubernetes.io/name: gateway
          app.kubernetes.io/instance: api7-ee-3-gateway

nginx:
  workerProcesses: "4"
  workerShutdownTimeout: 240s

api7ee:
  status_endpoint:
    enabled: true
    ip: 0.0.0.0
    port: 7085

gateway:
  readinessProbe:
    httpGet:
      path: /status/ready
      port: 7085
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3
  livenessProbe:
    httpGet:
      path: /status
      port: 7085
    initialDelaySeconds: 10
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3

updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0
    maxSurge: 1

如果使用不同的 Helm release 名称，请更新两个拓扑分布约束中的 app.kubernetes.io/instance。确认节点具有约束所使用的拓扑标签。如果集群未跨可用区部署，请省略可用区约束。

示例将 CPU 和内存的 requests 与 limits 设为相同值，以提供可预测的起点。当 Pod 中所有容器都满足相同要求时，网关容器符合 Kubernetes Guaranteed 服务质量等级。如果组织有意采用 Burstable 策略，请使 CPU request 不低于规划的 worker 数，设置明确的 limit，并验证 CPU 竞争时的延迟。不要在没有代表性负载测试的情况下直接照搬示例规格。

验证可用性和调度

将 apisix.replicaCount 设为至少 2；有更严格可用性要求时使用 3 或更多。
启用 HPA 时，将 autoscaling.minReplicas 设为所需的高可用下限。启用 HPA 后，Chart 会忽略 apisix.replicaCount。
将副本分布到不同节点，并在条件允许时跨可用区分布。使用 kubectl get pods -o wide 确认实际调度位置。
启用 PodDisruptionBudget，使维护期间不会移除过多副本，并确认该预算仍允许计划内节点排空。
使用滚动更新策略，确保升级全程保留足够容量。
为网关 requests 和发布期间临时创建的 maxSurge Pod 预留集群容量。
对延迟敏感的工作负载使用专用或适当隔离的节点；持续高吞吐场景应避免使用突发性能型节点。

验证资源和网关 worker

初始网关配额使用整数个 CPU 核，并将 nginx.workerProcesses 设为相同数值。
根据实测的稳定和峰值用量设置内存 requests 与 limits，并计入启用的插件和共享字典。
监控 CPU throttling、内存工作集、OOM 终止、Pod 重启和请求延迟。
HPA 按 CPU 利用率扩缩容时，请记住利用率以 CPU request 为基准；应对目标值和缩容行为进行负载测试。
联动审视 worker、CPU、内存和副本设置。只改其中一项可能造成资源争用或闲置容量。

验证生命周期和网络

使用 /status 进行存活检查，使用 /status/ready 进行就绪检查。参见配置就绪和存活探针。
只允许集群、监控系统和负载均衡器访问状态端口 7085 和指标端口 9091。
terminationGracePeriodSeconds 应长于 pre-stop 延迟与 nginx.workerShutdownTimeout 之和，对长连接或流式请求尤其如此。
在持续发送流量时测试删除 Pod 和排空节点，确认 readiness 会在连接关闭前将终止中的 Pod 从流量中移除。
根据环境明确选择网关 Service 类型、负载均衡器注解、源 IP 策略和允许的源地址范围。
应用 NetworkPolicy 或同等控制，只允许必要的客户端、上游、监控系统、DNS 和 DP Manager 端点互通。

部署并验证

渲染并检查清单：

helm template api7-ee-3-gateway api7/gateway \
  --version "~3.10.0" \
  -n api7 \
  -f values.yaml > rendered.yaml

应用 release 并等待其健康：

helm upgrade --install api7-ee-3-gateway api7/gateway \
  --version "~3.10.0" \
  -n api7 \
  --create-namespace \
  --atomic \
  --wait \
  -f values.yaml

验证资源和调度位置：

kubectl get deployment,pods,pdb,service -n api7 -o wide
kubectl top pods -n api7
kubectl rollout status deployment/api7-ee-3-gateway -n api7

如果 rendered.yaml 包含渲染后的凭证或其他敏感值，请勿提交该文件。

Docker Compose 检查清单

Docker Compose 可以在单台主机上以一致方式管理一组容器。主机故障时，它不会把容器重新调度到另一台主机，也不会执行跨主机滚动更新。

外置配置

创建专用部署目录，其中包含 Compose 文件、gateway_conf/config.yaml 覆盖文件和用于持久化网关数据的宿主机目录。
将 config.yaml 以只读方式挂载到 /usr/local/apisix/conf/config.yaml。启动 Compose 前确认源路径是文件。
将控制台生成的连接和 mTLS 值保存在受宿主机保护的环境文件或密钥管理器中。不要在构建日志中提交或打印渲染后的密钥。
将 apisix.uid 持久化到容器之外，避免重新创建容器时将其注册为新网关实例。
在 Compose .env 文件或 Compose 文件中固定镜像版本。
按照备份与恢复中的恢复范围，备份 Compose 文件、.env、网关配置和 UID 文件；加密备份 gateway.env，或保存能够从密钥管理器恢复同等控制面连接、网关组及 mTLS 凭据的材料。重新创建容器前审查所有变更。

在宿主机管理的文件中配置 worker 数和状态端点：

gateway_conf/config.yaml
apisix:
  status:
    ip: 0.0.0.0
    port: 7085

nginx_config:
  worker_processes: 4
  worker_shutdown_timeout: 240s

此示例中的 worker 数与下方 Compose 服务分配的 4 个 CPU 核相匹配。

在 compose.yaml 旁的 .env 中设置用于 Compose 插值的值：

.env
GATEWAY_VERSION=<gateway-version>
GATEWAY_STATUS_BIND_IP=127.0.0.1

127.0.0.1 仅适用于本机健康检查。为多主机部署配置外部负载均衡器前，请把 GATEWAY_STATUS_BIND_IP 改为负载均衡器能够访问的宿主机私有地址，并通过防火墙或安全组只允许受信任的负载均衡器和监控来源访问端口 7085。

将控制台生成的 Docker 命令中的网关组和 mTLS 值复制到 gateway.env。以下文件展示所需格式：

gateway.env
API7_CONTROL_PLANE_ENDPOINTS='["https://<dp-manager-host>:7943"]'
API7_GATEWAY_GROUP_SHORT_ID=<gateway-group-short-id>
API7_CONTROL_PLANE_CERT='-----BEGIN CERTIFICATE-----
<gateway-client-certificate>
-----END CERTIFICATE-----'
API7_CONTROL_PLANE_KEY='-----BEGIN PRIVATE KEY-----
<gateway-client-private-key>
-----END PRIVATE KEY-----'
API7_CONTROL_PLANE_CA='-----BEGIN CERTIFICATE-----
<control-plane-ca-certificate>
-----END CERTIFICATE-----'

请保持 PEM 值使用单引号，使 Docker Compose 保留换行。将每个占位符替换为生成命令中的完整值。

启动网关前创建持久化 UID 文件和宿主机日志目录。UID bind mount 的源必须已是文件，否则 Docker 可能在该路径创建目录。确保网关容器内运行的用户可以写入 gateway_logs。

mkdir -p gateway_data gateway_logs
test -s gateway_data/apisix.uid || uuidgen > gateway_data/apisix.uid
chmod 600 gateway.env
chmod 644 gateway_data/apisix.uid

在每台网关主机上生成不同的 UID。只有重新创建同一个网关实例时才复用 UID；不要把它复制到另一台同时运行的实例。

使用 Compose 管理网关

以控制台生成的 Docker 命令作为网关组和 mTLS 环境变量的来源，再将这些值迁移到 Compose 部署中。生产导向的网关服务可以采用以下模式：

compose.yaml
services:
  gateway:
    image: api7/api7-ee-3-gateway:${GATEWAY_VERSION}
    restart: unless-stopped
    cpus: "4.0"
    mem_limit: 8g
    env_file:
      - ./gateway.env
    volumes:
      - ./gateway_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
      - ./gateway_data/apisix.uid:/usr/local/apisix/conf/apisix.uid:ro
      - ./gateway_logs/:/usr/local/apisix/logs/:rw
    ports:
      - "9080:9080"
      - "9443:9443"
      - "${GATEWAY_STATUS_BIND_IP:-127.0.0.1}:7085:7085"
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1:7085/status/ready >/dev/null 2>&1 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s
    stop_grace_period: 5m
    logging:
      driver: json-file
      options:
        max-size: 100m
        max-file: "5"

使用控制台生成的准确网关组、DP Manager、证书和密钥值。只允许负责 API7 网关运维的账户访问 gateway.env。运行 docker compose config 时需特别小心，其输出可能包含解析后的环境变量密钥值。

以上日志限制可防止默认本地 JSON 日志无限增长。如果使用集中式日志驱动或 Agent，请将该部分替换为相应系统所需的设置。

将网关日志保存到宿主机

Compose 的 logging 部分只轮转从标准输出和标准错误捕获的容器输出。API7 网关默认将 access log 和 error log 写入 /usr/local/apisix/logs/。上面的 gateway_logs bind mount 会把这些文件保存到宿主机部署目录，无需在 gateway_conf/config.yaml 中额外配置日志路径。

要轮转该目录中的文件，请启用内置 log-rotate 插件，并把以下设置合并到 gateway_conf/config.yaml 的现有 plugin_attr 部分：

gateway_conf/config.yaml
plugin_attr:
  log-rotate:
    enable: true
    timeout: 10000
    interval: 3600
    max_kept: 168
    max_size: 104857600
    enable_compression: false

同时在配置参考所示的现有 plugins 列表中启用 log-rotate。请保留所有已有插件名：如果把 plugins 设为只包含 log-rotate，其他插件会被禁用。

该插件会轮转挂载目录内的 access.log 和 error.log。请根据保留要求调整间隔、保留文件数、最大文件大小和压缩设置，并持续监控宿主机磁盘用量。

验证宿主机和容器

为宿主机操作系统、Docker daemon、监控 Agent 和负载均衡 Agent 预留 CPU 和内存；不要把宿主机所有 CPU 核都分配给网关容器。
设置 cpus 和 mem_limit；Docker 容器默认没有资源限制。
使 nginx_config.worker_processes 与 Compose CPU 配额一致，并通过负载测试验证。
将容器 nofile 限制设为高于已配置 NGINX worker 连接数的要求，并确认宿主机内核限制足够。
配置 restart policy，并确认宿主机重启后 Docker 会自动启动。
将日志发送到有容量上限的本地驱动或集中式日志系统，并监控磁盘用量。
只允许可信运维人员访问 Docker socket 和部署文件。
只公开代理端口；状态、指标、DP Manager、控制台和数据库端口应限制在可信网络内。

验证并启动部署：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 gateway
docker stats --no-stream "$(docker compose ps -q gateway)"

确认容器健康且网关可以接收流量。先加载 .env 中的实际绑定地址；仅本机部署使用默认的 127.0.0.1，多主机部署使用为负载均衡器配置的私网地址：

set -a
. ./.env
set +a
curl -i "http://${GATEWAY_STATUS_BIND_IP:-127.0.0.1}:7085/status"
curl -i "http://${GATEWAY_STATUS_BIND_IP:-127.0.0.1}:7085/status/ready"
curl -i "http://127.0.0.1:9080/"

配置匹配路由前，端口 9080 返回 404 属于预期行为。

提供跨主机高可用

在至少两台独立 Docker 主机上运行相同的固定版本 Compose 部署。
基础设施支持时，将主机置于不同故障域。
在网关主机前部署外部负载均衡器。确认 GATEWAY_STATUS_BIND_IP 是负载均衡器可达的宿主机私有地址，并限制来源后，再对端口 7085 的 /status 或 /status/ready 配置 HTTP 健康检查。
确保一台主机不可用时，其余主机能够处理峰值流量。
升级前先从负载均衡器排空一台网关主机，等待连接结束，更新并验证后将其恢复服务，再继续下一台。
测试整台主机故障。容器 restart policy 只处理同一主机上的进程或 daemon 恢复。

不要把单台 Docker 主机上的多个副本作为唯一高可用措施。主机、Docker daemon、网络接口和存储仍是共享故障点。

安全和运维检查清单

最终上线检查

所有网关实例在 API7 控制台中均显示为健康。
负载均衡器只向就绪实例发送流量。
每个网关实例配置的 worker 数都与 CPU 配额一致。
Kubernetes 副本分布在预期的节点或可用区中，或者 Docker 副本运行在不同主机上。
资源监控面板和告警已经启用并完成测试。
证书到期告警、数据库备份、升级步骤、回滚步骤和事件联系人均已记录。
生产冒烟测试已验证关键路由、身份认证、限流、TLS、上游连接、日志和指标。

部署前检查​

Kubernetes 和 Helm 检查清单​

维护生产 values 文件​

验证可用性和调度​

验证资源和网关 worker​

验证生命周期和网络​

部署并验证​

Docker Compose 检查清单​

外置配置​

使用 Compose 管理网关​

将网关日志保存到宿主机​

验证宿主机和容器​

提供跨主机高可用​

安全和运维检查清单​

最终上线检查​

后续步骤​