跳到主要内容

故障排查

本页按故障类型提供排查思路，帮助定位启动失败、权限错误、策略拦截、上游错误和托管连接问题。

本指南帮助你诊断运行中的 AISIX 网关为什么没有按预期工作。请按顺序执行检查，直到明确失败层级，再根据对应章节决定下一步操作。

快速排障​

修改配置前，请先从运行时路径开始检查。

先检查监听器健康状态：

curl -i "http://127.0.0.1:3000/livez"

在自托管模式下，使用 Admin Key 检查 Admin 监听器和配置健康状态：

curl -i "http://127.0.0.1:3001/livez"

curl -sS "http://127.0.0.1:3001/admin/v1/health" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

使用应用实际使用的同一个调用方 API Key 验证模型发现：

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

然后向失败端点发送一次真实请求。例如，使用调用方 API Key 检查 OpenAI 兼容聊天路径：

curl -sS "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Say hello."
      }
    ]
  }'

根据响应状态、错误类型和关联响应头选择下一步检查。

信号下一步检查
监听器健康检查失败。进程、监听器绑定、启动配置和 TLS。
自托管模式下 Admin 健康状态过期或不可用。etcd 可达性、快照新鲜度和配置 watch 健康状态。
模型发现没有显示预期别名。调用方 API Key 访问权限、模型类型和配置可见性。
真实代理请求在上游调度前失败。调用方认证、模型访问、安全护栏、限流或预算。
真实代理请求到达服务提供方后失败。服务提供方密钥、base URL、上游模型 ID、配额、故障或出站网络路径。

请求关联方面，chat completions 响应使用 x-aisix-call-id。许多直接代理端点，包括 Messages、Responses、rerank、audio 和 passthrough，使用 x-aisix-request-id。精确响应头范围请参见响应头与错误码。

验证配置可见性​

当资源最近刚创建或更新，或代理表现得像仍在使用旧配置时，请执行这一步。

信号检查项处理方式
进程启动失败。etcd 端点、网络可达性、TLS 证书路径、文件权限和启动配置语法。修复启动配置或 etcd 连接后重启网关。
Admin 写入成功，但代理流量仍使用旧资源。自托管模式下 Admin 健康检查中的快照新鲜度。快照更新后验证最终代理路径；参见配置传播。
模型发现缺少新别名。调用方 API Key 允许列表、模型类型和快照新鲜度。修正模型或调用方 API Key，然后再次查询模型发现。
错误提到缺少服务提供方密钥或未知资源。服务提供方密钥、模型和调用方 API Key 引用。按顺序创建或修正依赖资源，然后发送真实代理请求。

在自托管部署中，etcd 是网关控制面的一部分。如果 etcd 不可用，服务提供方密钥、模型别名、调用方 API Key、策略和导出器等动态资源将无法正确加载。

验证调用方访问与策略​

当 AISIX 在调用服务提供方前拒绝请求，或不同调用方 API Key 的模型发现结果不一致时，请执行这一步。

信号检查项处理方式
认证错误。应用发送的是明文调用方 API Key，而不是存储哈希或上游服务提供方密钥。更新应用密钥或认证请求头。
权限或模型访问错误。请求的模型别名是否被调用方 API Key 允许。将别名加入调用方 API Key，或请求已允许的模型。
内容策略错误。已启用安全护栏、各护栏运行阶段，以及触发的 prompt 或响应内容。视情况调整 prompt、安全护栏规则或失败开放行为。
限流或预算错误。重试提示、API Key 限制、模型限制、共享策略、托管预算状态和副本本地计数器。等待重试窗口、提高限制或调整匹配策略。

精确代理错误信封、状态码和重试响应头请参见代理错误与重试。

验证服务提供方链路​

当 AISIX 已认证调用方、解析模型别名并开始向已配置服务提供方调度后，请执行这一步。

信号检查项处理方式
502 或 upstream_error。服务提供方密钥 secret、base URL、上游模型 ID、服务提供方配额、服务故障和出站网络路径。修复上游访问问题后再次发送同一代理请求。
503 且服务提供方不可用。服务提供方适配器可用性，以及解析出的适配器是否支持请求路由。使用受支持的服务提供方、适配器、端点或模型。
503 且所有候选不可用。多目标模型健康状态、冷却状态和路由过滤条件。恢复健康目标或调整路由行为。
模型健康状态降级或不可用。最近连续上游失败、服务提供方故障、配额、出站网络路径和凭证有效性。恢复服务提供方可达性，或将流量路由到健康目标。

当问题与服务提供方有关时，请对照对应服务提供方上游指南检查失败路由。

验证托管网关投射​

当 AISIX Cloud 状态与实时网关行为不一致，或托管网关无法接收投射配置时，请执行这一步。

信号检查项处理方式
托管心跳失败。证书身份、信任根、运行时状态、控制面 URL 和出站网络路径。先恢复托管连接，再排查资源投射；参见托管网关设置。
Cloud 显示资源，但实时流量没有使用它。处理流量的网关对应的环境作用域和投射状态。将资源移到正确环境，或等待投射完成。
托管预算检查失败或看起来不可用。托管连接、预算策略目标和预算检查响应详情。恢复预算检查连接，或修正托管策略。
Cloud Playground 成功但实时流量不同。实时网关、环境、模型别名、调用方 API Key 和服务提供方目标。通过预期托管网关和环境发送实时请求。

下一步​

你已经了解如何按层级缩小故障范围。需要重新检查生产基线时，请返回生产部署；也可以根据失败层级阅读对应功能指南。