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

API7 网关故障排查

本指南帮助你诊断和解决 API7 网关在安装、配置和运行过程中遇到的常见问题。对于每个问题，本指南都提供了症状、可能原因和解决步骤。

前置条件​

诊断工具​

在排查具体问题前，请先熟悉以下诊断工具。

检查组件状态​

Kubernetes​

# 检查所有 API7 Pod
kubectl get pods -n api7 -o wide

# 检查 Pod 事件中的错误
kubectl describe pod {pod_name} -n api7

# 检查 Pod 日志
kubectl logs {pod_name} -n api7 --tail=100

Docker​

# 检查容器状态
docker ps -a --filter "name=api7"

# 检查容器日志
docker logs {container_name} --tail=100

检查数据面错误日志​

官方网关镜像将默认错误日志发送到容器标准错误，因此请使用容器运行时提供的日志命令：

# Kubernetes
kubectl logs -n api7 {gateway_pod} -f

# Docker
docker logs {gateway_container} -f

如果部署将宿主机目录绑定挂载到 /usr/local/apisix/logs，请改为检查该宿主机目录中的 error.log。例如，生产环境的 Compose 布局将其保存到 gateway_logs/error.log。如果配置了其他日志路径或日志驱动，请检查对应的目标位置。

检查控制面日志​

# Kubernetes
kubectl logs -n api7 {cp_pod} --tail=100

# Docker
docker logs {cp_container} --tail=100

测试连通性​

# 测试网关 HTTP 端口
curl -v "http://{GATEWAY_HOST}:9080/"

# 测试网关 HTTPS 端口
curl -v "https://{GATEWAY_HOST}:9443/" --insecure

# 测试控制台访问
curl -v "https://{DASHBOARD_HOST}:7443/" --insecure

控制面问题​

无法访问控制台​

症状：无法访问 https://{host}:7443 上的控制台 Web 界面。

可能原因和解决方法：

  1. Pod 或容器未运行：

    # Kubernetes
    kubectl get pods -n api7 -l app.kubernetes.io/component=dashboard

    # Docker
    docker ps -a --filter "name=dashboard"

    如果 Pod 处于 CrashLoopBackOff 状态，或容器已经退出，请检查日志中的启动错误。

  2. 端口未暴露或被防火墙阻止：

    • 确认服务正在监听：kubectl get svc -n api7 | grep dashboard。
    • 确认端口 7443 未被防火墙或安全组规则阻止。
    • 若要本地访问，请执行 kubectl port-forward svc/api7ee3-dashboard 7443:7443 -n api7。

  3. TLS 证书问题：如果使用自定义 TLS 证书，请确认其有效且已正确挂载。

PostgreSQL 连接失败​

症状：控制面 Pod 因数据库连接错误无法启动。

可能原因和解决方法：

  1. PostgreSQL 未运行：

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

  2. 数据库凭证不正确：确认 Helm values 或环境变量中的数据库密码与 PostgreSQL 配置一致。

  3. 持久卷问题：如果 PostgreSQL 存储已满或 PVC 未绑定，请执行：

    kubectl get pvc -n api7

配置变更未生效​

症状：在控制台中进行的变更没有出现在数据面。

可能原因和解决方法：

  1. DP Manager 连接问题：确认 DP Manager 服务正在运行且数据面可以访问：

    kubectl get svc -n api7 | grep dp-manager

  2. 检查控制面与数据面之间使用的 mTLS 证书是否已过期；如已过期，请续期并重新部署。

  3. 确保 NetworkPolicy 或防火墙规则没有阻止控制面与数据面之间的 7900/7943 端口通信。

数据面问题​

HTTP 502 Bad Gateway​

症状：客户端收到 502 Bad Gateway 响应。

可能原因和解决方法：

  1. 上游服务无法访问：从网关 Pod 中确认上游服务正在运行且可以访问。网关镜像不包含 curl，因此请在与 Pod 共享网络的临时调试容器中执行：

    kubectl debug -n api7 -it {gateway_pod} \
      --image=curlimages/curl:8.10.1 \
      -- curl -v "http://{upstream_host}:{upstream_port}/"

  2. DNS 解析失败：如果使用服务名称，请从网关 Pod 内的临时容器确认 DNS 解析：

    kubectl debug -n api7 -it {gateway_pod} \
      --image=registry.k8s.io/e2e-test-images/jessie-dnsutils:1.3 \
      -- nslookup {upstream_service_name}

  3. 上游超时：检查错误日志中的超时消息。如果后端响应缓慢，请提高上游超时时间。API7 网关的上游配置位于 Service 中；timeout 对象的 connect、send 和 read 值均以秒为单位：

    curl -k "https://localhost:7443/apisix/admin/services/{service_name}?gateway_group_id={gateway_group_id}" -X PUT \
      -H "X-API-KEY: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "{service_name}",
        "upstream": {
          "type": "roundrobin",
          "nodes": [
            {"host": "{upstream_host}", "port": {upstream_port}, "weight": 1}
          ],
          "timeout": {
            "connect": 30,
            "send": 30,
            "read": 30
          }
        }
      }'

    必须发送完整的 Service 请求体（名称和上游配置），因为 PUT 会替换整个资源。发送前先使用 GET /apisix/admin/services/{service_name}?gateway_group_id={gateway_group_id} 获取当前 Service，并将新的 timeout 配置合并到完整请求体中。

HTTP 503 Service Temporarily Unavailable​

症状：特定路由返回 503。

可能原因和解决方法：

  1. 所有上游节点均不健康：如果启用了主动健康检查且所有节点都失败，网关会返回 503。请在控制台中检查上游健康状态。
  2. 触发熔断器：如果启用了 api-breaker 插件，连续失败可能已使熔断器进入断开状态。

HTTP 404 Route Not Found​

症状：请求返回 {"error_msg":"404 Route Not Found"}。

可能原因和解决方法：

  1. 路由未发布：确认包含该路由的服务模板版本已发布到正确的网关组。
  2. Host 不匹配：如果路由设置了 host 条件，请确认请求中的 Host 标头完全匹配。
  3. 路径不匹配：确认请求路径与路由的 URI 模式匹配，并检查尾部斜杠。

高延迟​

症状：API 响应时间明显高于预期。

可能原因和解决方法：

  1. 工作进程不足：检查 worker_processes 设置，确保其与可用 CPU 核数一致：

    config.yaml
    nginx_config:
      worker_processes: auto

  2. 插件开销：暂时禁用非必要插件，逐个重新启用以定位性能瓶颈。

  3. 访问日志 I/O：高流量部署可能因访问日志产生 I/O 瓶颈。可以考虑禁用访问日志或降低日志详细程度：

    config.yaml
    nginx_config:
      http:
        enable_access_log: false

  4. 资源争用：检查网关 Pod 的 CPU 和内存使用情况；如果资源受到限制，请提高资源上限。

证书和 TLS 问题​

控制面与数据面之间的 mTLS 握手失败​

症状：数据面无法连接控制面，日志显示 TLS 握手错误。

可能原因和解决方法：

  1. 证书不匹配：确认数据面证书由控制面信任的同一 CA 签发；请从控制台重新下载连接脚本。

  2. 证书已过期：检查证书有效期：

    openssl x509 -in /path/to/tls.crt -noout -dates

  3. 控制面地址错误：确认数据面中的 etcd 主机配置指向正确的 DP Manager 服务地址和端口（mTLS 使用 7943）。

客户端流量的 SSL 证书不生效​

症状：客户端向网关发送 HTTPS 请求时出现证书错误。

可能原因和解决方法：

  1. 未上传证书：通过控制台或 Admin API 上传 SSL 证书。
  2. SNI 不匹配：确保证书的 Common Name 或 Subject Alternative Names 与请求域名匹配。
  3. 证书链不完整：确保证书链完整，包含中间证书。

安装问题​

Helm 安装失败​

症状：helm install 或 helm upgrade 命令执行失败。

可能原因和解决方法：

  1. Helm 仓库未更新：

    helm repo update

  2. 集群资源不足：确认集群有足够的 CPU、内存和存储来调度所有 Pod。

  3. 未配置 StorageClass：如果 PostgreSQL 或 Prometheus 需要持久化存储，请确认存在默认 StorageClass：

    kubectl get storageclass

镜像拉取错误​

症状：Pod 卡在 ImagePullBackOff 或 ErrImagePull 状态。

可能原因和解决方法：

  1. 私有镜像仓库身份认证失败：对私有镜像仓库创建 image pull secret：

    kubectl create secret docker-registry api7-registry \
      --docker-server={REGISTRY_URL} \
      --docker-username={USERNAME} \
      --docker-password={PASSWORD} \
      -n api7

  2. 离线环境：将所需镜像复制到私有仓库。请参阅安装包。

  3. 镜像标签错误：确认镜像标签存在于仓库中。

性能问题​

网关未达到预期 QPS​

症状：基准测试的 QPS 低于文档中的基准值。

可能原因和解决方法：

  1. 参阅性能基准，了解优化建议。

  2. 检查系统限制：

    # 检查打开文件数限制
    ulimit -n

    # 基准测试时应至少为 1024000

  3. 确认工作进程数与 CPU 核数一致：设置 worker_processes: auto，或将其显式设置为 CPU 核数。

  4. 基准测试期间禁用访问日志：访问日志 I/O 会降低吞吐量。

  5. 避免使用突发型云实例：优先使用专用型或计算优化型实例，以获得稳定性能。

获取更多帮助​

如果无法通过本指南解决问题：

  1. 检查错误日志，并在 API7 文档中搜索具体错误消息。
  2. 联系 API7 支持团队，并提供以下信息：
    • API7 网关版本
    • 部署方式（Kubernetes/Docker）
    • 相关错误日志
    • 复现步骤
  3. 访问 API7 社区，了解社区动态并获取相关资源。