故障排除
修改资源前，请先将 AISIX 故障范围缩小到启动、配置、调用方策略、模型服务提供方路径或 AISIX Cloud 投射。请按顺序执行检查，直到明确失败层级，再根据对应章节决定下一步操作。
快速排查
修改配置前，请先从运行时路径开始检查。
先检查监听器健康状态：
curl -i "http://127.0.0.1:3000/livez"
这里连接被拒绝本身就是一个信号，而不是命令执行失败。使用 etcd 或 AISIX Cloud 作为资源来源时，网关在应用第一个配置之前不会绑定代理监听器，因此从未连上该来源的实例根本没有代理端口可以响应。只有配置来源能无限期造成这种状态。无法连接 ratelimit.redis 或 cache.redis 时，有界的启动连接尝试期间可能延迟所有监听器；尝试结束后，Redis 不再阻止启动，受影响的子系统进入降级模式，但代理监听器仍须获得有效配置。参见网关正在运行，但代理端口拒绝连接。
启用 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，然后确认网关能否连上其配置来源。 | 恢复配置来源。网关会持续重试，并在某次读取成功后立即绑定监听器；参见网关正在运行，但代理端口拒绝连接。 |
/status/config 报告 state: empty，且代理监听器已绑定。 | 所配置的 etcd.prefix 和 env_id。 | 来源可以连上，但其中没有属于该网关的资源；应修正前缀而不是连接。 |
配置状态为 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 读取资源的网关，在应用第一个配置前会保持该监听器关闭。只有配置来源能无限期造成这种状态。无法连接 ratelimit.redis 或 cache.redis 时，会先产生有界的启动延迟；延迟结束后，Redis 不再阻止监听器初始化。代理监听器可用后，网关按副本统计限流计数，并把 backend: redis 缓存策略当作未命中，同时每 5 分钟重述一次告警。配置读取成功后立即绑定代理监听器；失败的读取按指数退避重试，从 1 秒增长到 60 秒上限。
完成初始 etcd 连接后，请在第一个配置等待期间保持绑定的指标/状态监听器上确认这一判断：
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，即可确认正在等待第一个配置。以下日志消息会显示进展：
| 级别 | 消息 | 含义 |
|---|---|---|
INFO | waiting for the first configuration before binding the proxy listener | 等待开始。 |
WARN | proxy listener still not bound: no configuration has been applied yet | 尚未应用配置；每 10 秒重复一次。 |
INFO | first configuration applied — binding the proxy listener | 读取成功，代理监听器正在打开。 |
WARN | still connecting to etcd — nothing waiting on this connection can proceed until it answers | etcd 连接或重连仍未完成；每 10 秒重复一次，并携带 endpoints 和 waited_secs。带凭据的启动连接期间，该消息可能在任何监听器创建前出现。 |
使用以下信号识别等待为何持续：
| 信号 | 检查项 | 处理方式 |
|---|---|---|
/status/config 报告 source.connected: false 且 state 为 never_loaded。 | etcd 端点或 AISIX Cloud 端点、DNS 解析、mTLS 证书材料，以及网关与该来源之间的网络策略。 | 恢复可达性。某次读取成功后，网关无需重启即会绑定监听器。 |
代理等待告警重复出现，但 /status/config 没有记录连接失败。 | 端点是否只接受连接而不响应，例如不可用存储前方的负载均衡器。 | 恢复来源链路。未设置 etcd.request_timeout_ms 时读取不受限制，因此停滞的读取不会进入重试退避。设置前请阅读超时说明。 |
指标/状态监听器也拒绝连接，且同时配置了 etcd.user 和 etcd.password_env。 | 带凭据的初始连接是否仍未完成。连接持续 10 秒后，AISIX 会以 WARN 级别持续报告。 | 恢复端点。带凭据的初始连接发生在创建任何监听器之前，且最长为 etcd.dial_timeout_ms × 端点数 × 2，因为启动时会先后连接两个提供方。只有写了 dial_timeout_ms: 0 的配置才会无限等待；给该字段一个有限取值即可限制它。 |
因 observability.metrics.prometheus.enabled 为 false 而无法连接指标/状态监听器。 | 网关日志中的进程状态和配置来源消息。 | 如果进程仍在运行，请恢复配置来源。如需状态端点，请在私有监听器上启用指标，再重启网关以应用该启动变更。 |
| 指标/状态监听器已启用但拒绝连接，且不可能仍在进行带凭据的初始连接。 | 进程状态、启动语法、监听地址和 TLS 文件访问。 | 修正启动故障并重启网关。代理地址和 TLS 材料会在等待第一个配置前完成校验。 |
| 进程因 etcd 拒绝启动连接而退出。 | etcd.user 与 etcd.password_env 这一对配置、该环境变量中的密码，以及 etcd 是否启用认证。 | 修正凭据或认证配置。启动连接上被拒绝的凭据属于致命故障，不会重试。 |
etcd 要求认证，但缺少 etcd.user 或 etcd.password_env，配置读取不断报告认证或 Token 错误。 | 是否同时配置了两个凭据字段。缺少其中任一项时，AISIX 不会进行认证。 | 同时配置两个字段，并让指定的环境变量包含正确密码，然后重启网关。 |
进程保持运行，并记录 etcd refused this gateway's credentials — no configuration can be read until they are fixed; still retrying。 | 读取 etcd.prefix 的权限；如果进程在 etcd 不可达时启动，还要验证凭据。 | 修正该前缀的访问权限。配置读取期间的拒绝会被重试，除此之外 /status/config 与来源不可达相似。 |
在 Kubernetes 中，Pod 反复重启并报告 CrashLoopBackOff。 | 同样的可达性检查；启动探针的预算正在按设计发挥作用。 | 恢复配置来源。不要用调大预算来掩盖来源不可达，也不要把探针改指向其他监听器。 |
etcd.dial_timeout_ms 默认为 5000 毫秒，etcd.request_timeout_ms 默认不设置、因而没有上限。request_timeout_ms 覆盖配置读取和创建 watch 的握手，但不覆盖已建立的 watch 流。过短的取值可能阻止冷启动网关绑定，也可能让运行中的网关落后于存储。准确的作用范围和取值风险请参见 etcd 配置存储。
从磁盘缓存恢复了可用快照的网关，以及使用资源文件的网关，会立即绑定监听器，不会进入这种状态。参见离线韧性。
验证调用方访问与策略
当 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 网关和环境发送实时请求。 |
识别失败层级后，请使用相关功能指南或参考页面。每次修正后重新运行面向调用方的请求，以验证完整路径，而不仅是刚刚失败的组件。