故障排查
修改资源前，请先将 AISIX 故障范围缩小到启动、配置、调用方策略、服务提供方路径或托管投射。请按顺序执行检查，直到明确失败层级，再根据对应章节决定下一步操作。
快速排查
修改配置前，请先从运行时路径开始检查。
先检查监听器健康状态：
curl -i "http://127.0.0.1:3000/livez"
在自托管模式下，使用 Admin Key 检查 Admin 监听器和配置健康状态：
AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
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}"
启用 Prometheus 指标时，请在私有指标/状态监听器上检查最新观察到和已应用的配置：
curl -sS "http://127.0.0.1:9090/status/config"
使用应用实际使用的同一个调用方 API Key 验证模型发现：
AISIX_API_KEY="YOUR_CALLER_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。 |
配置状态为 degraded 或 out_of_sync。 | 被拒绝的资源、最近一次加载失败和配置来源。 |
| 自托管模式下 Admin 健康状态没有反映预期写入，或不可用。 | etcd 可达性、快照修订版本和配置 watch 健康状态。 |
| 模型发现没有显示预期别名。 | 调用方 API Key 访问权限、模型类型和配置可见性。 |
| 真实代理请求在上游调度前失败。 | 调用方认证、模型访问、安全护栏、限流或预算。 |
| 真实代理请求到达服务提供方后失败。 | 服务提供方密钥、base URL、上游模型 ID、配额、故障或出站网络路径。 |
请求关联请使用 x-aisix-request-id，AISIX 会将其添加到各端点类型的代理响应中。成功的 Chat Completions 响应还包含 x-aisix-call-id。精确响应头范围请参见响应头与错误码。
验证配置可见性
当资源最近刚创建或更新，或代理表现得像仍在使用旧配置时，请执行这一步。
| 信号 | 检查项 | 处理方式 |
|---|---|---|
| 进程启动失败。 | etcd 端点、网络可达性、TLS 证书路径、文件权限和启动配置语法。 | 修复启动配置或 etcd 连接后重启网关。 |
配置状态为 never_loaded、degraded 或 out_of_sync。 | /status/config 中的 source、applied、rejected 和 last_failure 字段。 | 恢复来源或修正被拒绝的配置，再确认下一次加载状态为 synced。 |
| Admin 写入成功，但代理流量仍使用旧资源。 | 自托管模式下 Admin 健康检查中的快照新鲜度。 | 快照更新后验证最终代理路径；参见配置传播。 |
| 模型发现缺少新别名。 | 调用方 API Key 允许列表、模型类型和快照新鲜度。 | 修正模型或调用方 API Key，然后再次查询模型发现。 |
| 错误提到缺少服务提供方密钥或未知资源。 | 服务提供方密钥、模型和调用方 API Key 引用。 | 按顺序创建或修正依赖资源，然后发送真实代理请求。 |
在自托管部署中，etcd 是网关控制面的一部分。如果加载快照后 etcd 不可用，网关可以继续使用该快照，但在配置连接恢复前无法接收新增或更新的动态资源。
验证调用方访问与策略
当 AISIX 在调用服务提供方前拒绝请求，或不同调用方 API Key 的模型发现结果不一致时，请执行这一步。
| 信号 | 检查项 | 处理方式 |
|---|---|---|
| 认证错误。 | 应用发送的是明文调用方 API Key，而不是存储哈希或上游服务提供方密钥。 | 更新应用密钥或认证请求头。 |
| 权限或模型访问错误。 | 请 求的模型别名是否被调用方 API Key 允许。 | 将别名加入调用方 API Key，或请求已允许的模型。 |
| 内容策略错误。 | 已启用安全护栏、各护栏运行阶段，以及触发的提示词或响应内容。 | 视情况调整提示词、安全护栏规则或失败开放行为。 |
| 限流或预算错误。 | 重试提示、API Key 限制、模型限制、共享策略、托管预算状态和副本本地计数器。 | 等待重试窗口、提高限制或调整匹配策略。 |
精确代理错误信封、状态码和重试响应头请参见代理错误与重试。
当不同网关实例的限流结果不一致时，请先确定计数器后端，再修改策略。内存计数器为各进程本地所有。Redis 会共享计数器，但运行时 Redis 故障会回退到进程本地执行。恢复后，故障期间的计数不会合并回 Redis；请先恢复 Redis，并等待活动窗口滚动结束，再判断计数器是否重新对齐。
验证服务提供方链路
当 AISIX 已认证调用方、解析模型别名并开始向已配置服务提供方调度后，请执行这一步。
| 信号 | 检查项 | 处理方式 |
|---|---|---|
502 或 upstream_error。 | 服务提供方密钥 Secret、base URL、上游模型 ID、服务提供方配额、服务故障和出站网络路径。 | 修复上游访问问题后再次发送同一代理请求。 |
503 且服务提供方不可用。 | 服务提供方适配器可用性，以及解析出 的适配器是否支持请求路由。 | 使用受支持的服务提供方、适配器、端点或模型。 |
503 且所有候选不可用。 | 多目标模型健康状态、冷却状态和路由过滤条件。 | 恢复健康目标或调整路由行为。 |
| 模型健康状态降级或不可用。 | 最近连续上游失败、服务提供方故障、配额、出站网络路径和凭证有效性。 | 恢复服务提供方可达性，或将流量路由到健康目标。 |
当问题与服务提供方有关时，请对照对应服务提供方上游指南检查失败路由。
解读传输错误
传输错误表示请求未在 HTTP 层完成，因此没有可供解读的上游状态码。网关日志会在消息旁记录原因链，可据此区分故障：
| 日志行中的原因 | 含义 | 检查位置 |
|---|---|---|
dns error: failed to lookup address information | 无法解析模型服务提供方主机名。 | DNS 配置、api_base 主机名和出站 DNS 策略。 |
tcp connect error: Connection refused | 该主机和端口上没有程序接受连接。 | api_base 端口，以及中间代理是否正在监听。 |
tcp connect error: Connection timed out | 连接尝试被网络路径丢弃。 | 路径上的防火墙、安全组和出站规则。 |
connection closed before message completed 或发送期间发生连接重置 | 对端在请求完成前关闭了池化连接。 | upstream.pool_idle_timeout_secs；参见调整上游连接层。 |
| TLS 或证书错误 | 与模型服务提供方或拦截代理的握手失败。 | 信任根，以及终止 TLS 的代理是否重新签发流量证书。 |
如果仅在服务提供方整体健康时偶发错误，通常是连接复用问题，而非模型服务提供方故障。将 pool_idle_timeout_secs 降到路径上最短空闲超时以下，然后重新检查。
入站侧也可能发生对称故障。如果 AISIX 前方的网关或负载均衡器在 AISIX 健康时偶发报告连接重置或 502，请检查 downstream.idle_timeout_secs 是否低于该节点自身的连接池空闲超时；此时 AISIX 会关闭前方节点仍视为可用的连接。保持默认值 0 可排除此问题。参见调整下游连接层。
将上游错误归因到正确的网络跳点
当记录的消息为 upstream returned HTTP <status>: <body> 时，状态和正文来自响应 api_base 的组件；只有当其前方没有任何中间组件时，该组件才是模型服务提供方。如果响应正文使用某个代理自身的术语，则错误由中间跳点而非模型服务提供方生成：
- 包含
reset reason的upstream connect error or disconnect/reset before headers，或exceeded request buffer limit while retrying upstream，由基于 Envoy 的代理、服务网格和 API 网关生成。 - 通用 HTML 错误页由反向代理或负载均衡器生成，不是模型服务提供方的 JSON API。
网关会记录这些正文用于排查，但不会返回调用方：上游 5xx 响应会以通用 502 错误封装到达应用。请使用日志中的每次尝试记录识别失败的 provider_key_id 和目标模型，再与 api_base 所属跳点的访问日志对照。
验证托管网关投射
当控制面状态与实时网关行为不一致，或托管网关无法接收投射配置时，请执行这一步。
| 信号 | 检查项 | 处理方式 |
|---|---|---|
| 托管心跳失败。 | 证书身份、信任根、运行时状态、控制面 URL 和出站网络路径。 | 先恢复托管连接，再排查资源投射；参见托管网关设置。 |
| 控制面显示资源，但实时流量没有使用它。 | 处理流量的网关对应的环境作用域和投射状态。 | 将资源移到正确环境，或等待投射完成。 |
| 托管预算检查失败或看起来不可用。 | 托管连接、预算策略目标和预算检查响应详情。 | 恢复预算检查连接，或修正托管策略。 |
| Playground 成功但实时流量不同。 | 实时网关、环境、模型别名、调用方 API Key 和服务提供方目标。 | 通过预期托管网关和环境发送实时请求。 |
下一步
你已经了解如何按层级缩小故障范围。需要重新检查生产基线时，请返回生产部署；也可以根据失败层级阅读对应功能指南。