故障排除

修改资源前，请先将 AISIX 故障范围缩小到启动、配置、调用方策略、模型服务提供方路径或 AISIX Cloud 投射。请按顺序执行检查，直到明确失败层级，再根据对应章节决定下一步操作。

快速排查

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

先检查监听器健康状态：

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

这里连接被拒绝本身就是一个信号，而不是命令执行失败。使用 etcd 或 AISIX Cloud 作为资源来源时，网关在应用第一个配置之前不会绑定代理监听器，因此从未连上该来源的实例根本没有代理端口可以响应。参见进程在运行但代理端口拒绝连接。

启用 Prometheus 指标时，请在私有指标/状态监听器上检查最新观察到和已应用的配置；该监听器在进程启动时即绑定，因此在上述情况下同样会响应：

curl -sSi "http://127.0.0.1:9090/status/ready"
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."
      }
    ]
  }'

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

信号	下一步检查
监听器健康检查被拒绝而不是返回响应。	网关是否应用过任何配置：先看指标/状态监听器上的 /status/ready，再看配置来源。
监听器健康检查失败。	进程、监听器绑定、启动配置和 TLS。
配置状态为 degraded 或 out_of_sync。	被拒绝的资源、最近一次加载失败和配置来源。
配置状态没有反映预期的直接 etcd 变更。	etcd 可达性、监听的前缀和配置来源状态。
模型发现没有显示预期别名。	调用方 API Key 访问权限、模型类型和配置可见性。
真实代理请求在分发到上游前失败。	调用方身份认证、模型访问、安全护栏、限流或预算。
真实代理请求到达模型服务提供方后失败。	模型服务提供方密钥、base URL、上游模型 ID、配额、服务故障或出站网络路径。

请求关联请使用 x-aisix-request-id，AISIX 会将其添加到各端点类型的代理响应中。成功的 Chat Completions 响应还包含 x-aisix-call-id。精确响应头范围请参阅响应头与错误码。

验证配置可见性

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

信号	检查项	处理方式
进程在启动期间失败。	动态资源来源、网络可达性、TLS 证书路径、文件权限和启动配置语法。	修复启动配置或资源来源后重启网关。
进程在运行，但代理端口拒绝连接。	指标/状态监听器上的 /status/ready 和 /status/config，然后确认网关能否连上其配置来源。	恢复配置来源。网关会持续重试，并在某次读取成功后立即绑定监听器；参见进程在运行但代理端口拒绝连接。
配置状态为 never_loaded、degraded 或 out_of_sync。	/status/config 的 source、applied、rejected 和 last_failure 字段。	恢复来源或修正被拒绝的配置，再确认下一次加载状态为 synced。
直接 etcd 变更没有反映在代理流量中。	已应用的网关配置快照、存储连接和监听的前缀。	快照更新后验证最终代理路径；参见配置传播。
模型发现缺少新别名。	调用方 API Key 允许列表、模型类型和快照新鲜度。	修正模型或调用方 API Key，然后再次查询模型发现。
错误提到缺少模型服务提供方密钥或未知资源。	模型服务提供方密钥、模型和调用方 API Key 引用。	按顺序创建或修正依赖资源，然后发送真实代理请求。

对于使用存储的网关，etcd 提供动态资源来源。如果加载快照后 etcd 不可用，网关可以继续使用该快照，但在配置连接恢复前无法接收新增或更新的动态资源。

进程在运行但代理端口拒绝连接

当进程处于运行状态——既没有退出，也没有报出错误——但发往代理端口的所有请求（包括 /livez）都被拒绝时，请执行这一步。

从 etcd 或 AISIX Cloud 读取资源的网关，只有在应用第一个配置之后才会绑定代理监听器。在那之前端口并不存在，因此现象看起来像进程从未启动，而不像它正在等待。它确实是在等待：它不会退出，不会绑定一个降级的监听器，也不会退化成什么都不提供。它会在某次读取成功的那一刻绑定监听器；读取失败时按指数退避重试，退避从 1 秒增长到 60 秒上限。完整契约参见启动与第一个配置。

请在全程保持绑定的指标/状态监听器上确认这一判断：

curl -sSi "http://127.0.0.1:9090/status/ready"
curl -sS "http://127.0.0.1:9090/status/config"

返回 503 且响应体为 no configuration available，同时 /status/config 中 state 为 never_loaded，就是这种情况。网关日志中同样有记录：等待开始时写出一条 waiting for the first configuration before binding the proxy listener，随后每 10 秒写出一条 proxy listener still not bound: no configuration has been applied yet，直到等待结束。

信号	检查项	处理方式
/status/config 报告 source.connected: false 且 state 为 never_loaded。	etcd 端点或 AISIX Cloud 端点、DNS 解析、mTLS 证书材料，以及网关与该来源之间的网络策略。	恢复可达性。某次读取成功后，网关无需重启即会绑定监听器。
/status/config 报告 state 为 empty，且监听器已绑定。	所配置的 etcd.prefix 和 env_id。	来源可以连上，但其中没有属于该网关的资源；应修正前缀而不是排查连接。
网关日志出现每 10 秒一条的告警，但 /status/config 没有记录任何连接失败。	所配置的端点是否只接受连接却不返回响应——死掉的配置存储前面挂着负载均衡器时就是这种表现。	修复到来源的链路。除非设置了 etcd.request_timeout_ms，配置读取不受任何超时限制，因此默认情况下被接受的读取会一直处于在途状态，只产生告警而没有可供重试的显式失败。设置该项会给读取加上上限，把这种挂起变成退避会重试的失败；取值请依据那里的说明，而不是依据你愿意等多久。它覆盖的是配置读取，以及建立配置 watch 的握手。卡在建立连接时的认证交互上，则仍然不在任何超时设置的覆盖范围内。
指标/状态监听器同样拒绝连接。	进程是否在运行，以及 observability.metrics.prometheus.enabled。	这不是上述等待——请按进程或启动配置失败来排查。
在 Kubernetes 中，Pod 反复重启并报告 CrashLoopBackOff。	同样的可达性检查；启动探针的预算正在按设计发挥作用。	恢复配置来源。不要用调大预算来掩盖来源不可达，也不要把探针改指向其他监听器。

从磁盘缓存恢复了可用快照的网关，以及使用资源文件的网关，会立即绑定监听器，不会进入这种状态。参见离线韧性。

验证调用方访问与策略

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

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

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

当不同网关实例的限流结果不一致时，请先确定计数器后端，再修改策略。内存计数器为各进程本地所有。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 所配置上游端点的访问日志对照。

验证 AISIX Cloud 投射

当控制面状态与实时网关行为不一致，或 AISIX 网关无法接收投射配置时，请执行此步骤。

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

识别失败层级后，请使用相关功能指南或参考页面。每次修正后重新运行面向调用方的请求，以验证完整路径，而不仅是刚刚失败的组件。