API7 网关故障排查
本指南帮助你诊断和解决 API7 网关在安装、配置和运行过程中遇到的常见问题。对于每个问题，本指南都提供了 症状、可能原因和解决步骤。
前置条件
- 令牌管理。
诊断工具
检查组件状态
Kubernetes
kubectl get pods -n api7 -o wide
kubectl describe pod {pod_name} -n api7
kubectl logs {pod_name} -n api7 --tail=100
Docker
docker ps -a --filter "name=api7"
docker logs {container_name} --tail=100
检查日志
# Kubernetes
kubectl exec -n api7 {gateway_pod} -- tail -f /usr/local/apisix/logs/error.log
kubectl logs -n api7 {cp_pod} --tail=100
# Docker
docker exec {gateway_container} tail -f /usr/local/apisix/logs/error.log
docker logs {cp_container} --tail=100
测试连通性
curl -v "http://{GATEWAY_HOST}:9080/"
curl -v "https://{GATEWAY_HOST}:9443/" --insecure
curl -v "https://{DASHBOARD_HOST}:7443/" --insecure
控制面问题
无法访问控制台
症状：无法访问 https://{host}:7443 上的控制台 Web 界面。
可能原因和解决方法：
-
Pod 或容器未运行：
kubectl get pods -n api7 -l app.kubernetes.io/component=dashboard
docker ps -a --filter "name=dashboard"如果 Pod 处于
CrashLoopBackOff状 态，或容器已经退出，请检查日志中的启动错误。 -
端口未暴露或被防火墙阻止：确认端口 7443 未被防火墙或安全组规则阻止。若要本地访问，可以执行
kubectl port-forward svc/api7ee3-dashboard 7443:7443 -n api7。 -
TLS 证书问题：如果使用自定义 TLS 证书，请确认其有效且已正确挂载。
PostgreSQL 连接失败
症状：控制面 Pod 因数据库连接错误无法启动。
- 确认 PostgreSQL 正在运行：
kubectl get pods -n api7 -l app.kubernetes.io/name=postgresql。 - 确认 Helm values 或环境变量中的数据库密码与 PostgreSQL 配置一致。
- 如果存储已满或 PVC 未绑定，请执行
kubectl get pvc -n api7检查持久卷状态。
配置变更未生效
症状：在控制台中进行的变更没有出现在数据面。
- 确认 DP Manager 服务正在运行且数据面可以访问：
kubectl get svc -n api7 | grep dp-manager。 - 检查控制面与数据面之间使用的 mTLS 证书是否已过期；如已过期，请续期并重新部署。
- 确保 NetworkPolicy 或防火墙规则没有阻止控制面与数据面之间的 7900/7943 端口通信。
数据面问题
HTTP 502 Bad Gateway
症状：客户端收到 502 Bad Gateway 响应。
-
从网关 Pod 中确认上游服务正在运行且可以访问：
kubectl exec -n api7 {gateway_pod} -- curl -v "http://{upstream_host}:{upstream_port}/" -
如果使用服务名称，请在网关 Pod 内确认 DNS 解析：
kubectl exec -n api7 {gateway_pod} -- nslookup {upstream_service_name}。 -
检查错误日志中的超时消息。API7 网关的上游配置位于 Service 中；提高
timeout对象的connect、send和read值（单位为秒）。PUT 会替换整个资源，因此发送前必须先获取当前 Service，并合并完整的timeout配置：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
}
}
}'发送前先使用
GET /apisix/admin/services/{service_name}?gateway_group_id={gateway_group_id}获取当前 Service，并将现有字段合并到完整请求体中。
HTTP 503 Service Temporarily Unavailable
症状：特定路由返回 503。
- 如果启用了主动健康检查且所有节点都失败，网关会返回 503。请在控制台中检查上游健康状态。
- 如果启用了
api-breaker插件，连续失败可能已触发熔断器并打开熔断。
HTTP 404 Route Not Found
症状：请求返回 {"error_msg":"404 Route Not Found"}。
- 确认目标网关组中的 Service 已配置该路由。
- 如果路由设置了
host条件，请确认请求中的Host标头完全匹配。 - 确认请求路径与路由的 URI 模式匹配，并检查尾部斜杠。
高延迟
症状：API 响应时间明显高于预期。
-
确认
worker_processes与 CPU 核数匹配 ：config.yamlnginx_config:
worker_processes: auto -
暂时禁用非必要插件，逐个重新启用以定位性能瓶颈。
-
高流量部署可能因访问日志产生 I/O 瓶颈。必要时降低日志详细程度，或设置
nginx_config.http.enable_access_log: false。 -
检查网关 Pod 的 CPU 和内存使用情况；如果资源受到限制，请提高资源上限。
证书和 TLS 问题
控制面与数据面之间的 mTLS 握手失败
症状：数据面无法连接控制面，日志显示 TLS 握手错误。
- 确认数据面证书由控制面信任的同一 CA 签发；请从控制台重新下载连接脚本。
- 使用
openssl x509 -in /path/to/tls.crt -noout -dates检查证书有效期。 - 确认数据面中的 etcd 主机配置指向正确的 DP Manager 服务地址和端口（mTLS 使用 7943）。
客户端流量的 SSL 证书不生效
症状：客户端向网关发送 HTTPS 请求时出现证书错误。
- 通过控制台或 Admin API 上传 SSL 证书。
- 确保证书的 Common Name 或 Subject Alternative Names 与请求域名匹配。
- 确保证书链完整，包含中间证书。
安装问题
Helm 安装失败
- 执行
helm repo update。 - 确认集群有足够的 CPU、内存和存储来调度所有 Pod。
- 如果 PostgreSQL 或 Prometheus 需要持久化存储，请确认存在默认 StorageClass：
kubectl get storageclass。
镜像拉取错误
症状：Pod 卡在 ImagePullBackOff 或 ErrImagePull 状态。
-
对私有镜像仓库创建 image pull secret：
kubectl create secret docker-registry api7-registry \
--docker-server={REGISTRY_URL} \
--docker-username={USERNAME} \
--docker-password={PASSWORD} \
-n api7 -
在离线环境中，将所需镜像复制到私有仓库。请参阅安装包。
-
确认镜像标签存在于仓库中。
性能问题
网关未达到预期 QPS
- 参阅性能基准测试了解优化建议。
- 检查系统限制；基准测试的打开文件数通常应至少为 1024000：
ulimit -n。 - 将 worker 进程数设置为
auto，或显式设置为 CPU 核数。 - 基准测试期间禁用访问日志，以减少日志 I/O 对吞吐量的影响。
- 避免使用突发型云实例，优先使用专用型或计算优化型实例以获得稳定性能。
获取更多帮助
如果无法通过本指南解决问题：