健康检查

AISIX 为进程、流量、配置和模型状态分别提供健康与状态端点。这些端点同时适用于开源 AISIX 网关和连接 AISIX Cloud 的 AISIX 网关。请使用与所监控条件对应的端点。要验证从调用方到模型服务提供方的完整路径，请通过网关发送测试请求。

问题	端点	监听器
这个实例是否应该被重启？	GET /livez	代理
此实例是否应接收代理流量？	GET /readyz	代理
此实例是否已应用任何有效配置？	GET /status/ready	指标/状态
此实例当前使用什么配置提供服务？	GET /status/config	指标/状态
模型是否可用于路由？	GET /status/models	指标/状态

这些端点不需要身份认证。启用 Prometheus 指标时会提供指标/状态端点；默认情况下已启用。请确保该监听器仅对监控和运维系统开放。

代理存活检查

使用 /livez 检查进程存活状态：

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

健康进程返回 200 OK，响应体为 ok。

正在排空的实例同样返回 200。存活检查决定的是要不要重启实例，而排空是有意为之的工作：一个已被告知关闭的实例正在处理完它已经接收的请求，重启它恰好会杀掉这些请求。报告排空状态的是 /readyz，这样流量会被撤走，而实例不会在自己仍有进行中请求时被替换掉。

手动排查时可以追加 ?verbose=1。自动化探针不要依赖 verbose 响应体。

存活检查刻意保持较窄范围。它不能证明模型可用，也不能证明模型服务提供方请求能够成功。

它确实意味着网关已经加载了配置，但这只是承载该端点的监听器何时存在所带来的副作用。从 etcd 或 AISIX Cloud 读取资源的网关，在应用第一个配置之前不会绑定代理监听器，因此在那之前 /livez 不是返回 503，而是根本不会有响应。参见启动与第一个配置。

流量就绪

使用 /readyz 判断实例是否应接收流量：

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

实例正在排空时，该端点返回 503 Service Unavailable。有效配置可用后，只要网关仍能使用该配置提供服务，实例就会保持就绪。

在应用第一个配置之前，/readyz 的表现取决于资源来源；对于使用 etcd 或 AISIX Cloud 的网关，得到的并不是 503：承载该端点的代理监听器尚未绑定，探针只会得到被拒绝的连接。要观察这一阶段，请使用指标/状态监听器上的 GET /status/ready，参见启动与第一个配置。

控制面或配置存储中断不会仅仅因为最近没有更新就让运行中的网关变为未就绪。来源停滞通常会影响所有实例，将它们全部移出流量会中断流量路径，而不是把流量转移到健康实例。请单独监控配置新鲜度。

排查实例未就绪的原因时可以追加 ?verbose=1。自动化探针不要依赖 verbose 响应体。

在 Kubernetes 中，请将存活和就绪探针分别指向代理监听器上的 /livez 和 /readyz，并在同一个监听器上再配置一个 startupProbe，使网关仍在连接配置来源期间另外两个探针都不会动作。该探针需要多大的预算，参见启动与第一个配置。请为网关留出足够的终止时间，以排空进行中的请求和流式请求。

启动与第一个配置

从 etcd 或 AISIX Cloud 读取资源的网关，在应用第一个配置之前不会绑定代理监听器。这样可以避免流量到达没有任何资源可提供服务的实例。完成任意一次初始 etcd 连接后，各监听器的表现如下：

监听器	可观察状态
代理	未绑定。/livez、/readyz 以及所有面向调用方的端点都会拒绝连接。
指标/状态	启用 Prometheus 指标时绑定。GET /status/ready 返回 503 Service Unavailable，响应体为 no configuration available；GET /status/config 报告状态 never_loaded。
Admin	开源网关启用该监听器时，在等待期间绑定。它自己的 /livez 返回 200，/readyz 始终返回 503。

带凭据的初始 etcd 连接发生在 AISIX 创建任何监听器之前。如果该连接停滞，上述所有端点都不可用。该窗口是有上限的：启动时会先后连接两个提供方，因此最长为 etcd.dial_timeout_ms × 端点数 × 2。只有配置了 etcd.user 的部署会走到这一步，因为没有凭据时该连接不产生任何 I/O。

网关连不上 ratelimit.redis 或 cache.redis 不会延迟任何监听器。这两个后端都会照常绑定并以降级方式提供服务，并在后台接入。

使用资源文件的网关会在加载文件后立即绑定监听器。从可用的磁盘快照恢复的 etcd 或 AISIX Cloud 网关也会立即绑定。

因此，指标/状态监听器是冷启动的主要信号。如果该监听器不可用，请参见网关正在运行，但代理端口拒绝连接，查看症状、日志和修复方法。etcd 超时的准确作用范围和默认值记录在 etcd 配置存储中。

设置 Kubernetes 启动探针的预算

代理监听器上的 startupProbe 会在第一个配置可用前阻止存活和就绪检查动作。它的预算 periodSeconds x failureThreshold 必须同时覆盖连接配置来源和应用其中资源的时间。api7/aisix Helm Chart 使用 300 秒预算，即 periodSeconds: 2 和 failureThreshold: 150。

该预算为大规模配置留出余量，不是对启动时间的实测上限。

网关会在大约 0、1、3、7、15、31 和 63 秒时重试失败的读取，之后每分钟重试一次。请避免让探针预算恰好在下一次重试前结束。如果来源持续不可用并超过预算，Kubernetes 会重启容器，并可能报告 CrashLoopBackOff。请修复来源，而不是把探针改指向其它监听器。

关闭与排空

AISIX 会把变为未就绪与关闭监听器分开处理，让负载均衡器有时间撤下该实例。收到 SIGTERM 或 SIGINT 时，网关会：

1. 立即让 /readyz 返回 503 Service Unavailable，使下一次健康检查将其移出流量。/livez 保持 200：进程是健康的，排空期间不应被重启。
2. 继续接受新连接，至少持续 shutdown.min_drain_secs，默认为 30 秒。
3. 为 HTTP/1.1 响应添加 Connection: close，并向 HTTP/2 客户端发送 GOAWAY 帧，使客户端停止复用连接，而不会中断进行中的工作。
4. 最小窗口结束后，不设自身期限地等待进行中请求数降为零，然后停止接受新连接。
5. 在保留快照缓存的 etcd 或 AISIX Cloud 网关上，再最多等待 5 秒，让仍在途中的快照缓存写入落盘，然后退出。

请把 min_drain_secs 设置为大于 /readyz 状态变化后负载均衡器停止路由所需的时间。对于 Kubernetes，该时间为 periodSeconds x failureThreshold；对于外部负载均衡器，请使用检查间隔乘以重试次数。

config.yaml

shutdown:
  min_drain_secs: 30

这个窗口是最小值，而不是关闭期限。窗口结束后，网关仍会等待进行中的请求数降为零。设为 0 会取消最小窗口，仅当没有任何系统通过健康检查将流量路由到该实例时才适用。

由于等待进行中工作数降为零的过程没有上限，整个流程的实际上限由部署平台决定——Kubernetes 中是 terminationGracePeriodSeconds，systemd 下是 TimeoutStopSec。请把它设置为大于 shutdown.min_drain_secs、最长请求或流式传输时长，以及启用持久化时的 5 秒快照缓存排空这三者之和，并留出运维余量。还应加上任何 preStop 钩子的持续时间，因为它会消耗同一个 Kubernetes 终止预算。

启用快照持久化时，最后这一项不是可有可无的余量，而且它是额外的时间，不会被在途请求的排空吸收：快照缓存排空要等到进行中请求数降为零之后才开始。网关在应用配置之后会在后台写快照缓存，因此一个刚应用完配置就被停止的实例，可能仍有一次写入没有完成。如果它在写入中途被杀掉，重启时用的就是缓存中此前保存的内容，而不是它刚刚应用的那份配置——如果那次写入本身就是第一次，则根本没有缓存可用。由于代理监听器要等到第一个配置被应用才绑定，没有缓存的网关在重新连上配置来源之前不会再打开端口。这 5 秒是对一次本地文件写入的固定兜底，而不是可调的旋钮，也没有对应的配置项。5 秒过后写入仍在途中时，网关会写出一条 WARN 并不再等待；这次写入是被放弃等待而不是被取消，而缓存文件的替换是原子的，因此落到磁盘上的一定是最近某一次应用的结果，绝不会是写了一半的内容。

备注

请把外部负载均衡器的健康检查指向 /readyz，而不是单纯的 TCP 连接探测。TCP 探测无法观察到就绪状态，它唯一能得到的信号就是监听器关闭——而这正是排空窗口要避免的那个事件。

在日志中观察排空过程

排空过程会记录自身的进展，因为一次请求通常留下的记录是在它结束时才写出的——而在平台的宽限期到期时仍在运行的请求根本走不到那一步。这些日志正是你把网关已经接手的工作，与信号之后仍被路由过来的流量区分开的依据：

日志内容	字段	写出时机
draining — /readyz now reports 503, still accepting new connections	min_drain_secs、in_flight、open_connections	收到信号时写出一次。
still draining in-flight requests	in_flight、open_connections	排空期间周期性写出。
request arrived while draining	method、path，以及该请求自身的 request_id、peer 和 downstream_request_id	信号之后每到达一个请求写一条。
accepted a new downstream connection while draining	peer、open_connections	信号之后每接受一条连接写一条。

这两个计数回答的是不同的问题，且无法互相推导。in_flight 统计正在处理的请求，流式响应只要还可能有字节流出就一直占着自己的名额；open_connections 统计代理监听器上处于打开状态的下游连接，包含连接池中没有承载请求、正处于空闲的那些。因此，in_flight 一直不降导致排空迟迟不结束，说明网关在处理自己已经接手的工作；in_flight 已降为零而 open_connections 仍不降，说明客户端握着用不到的连接不放；open_connections 还在上升，则说明仍有组件在往这里路由新连接。

那两条逐事件的日志合起来解释了滚动更新期间失败的请求。一条到达日志若能匹配到 peer 相同的接受日志，说明连接本身是在网关已经请求被摘除之后才被路由过来的——负载均衡器还没跟上，而这正是 min_drain_secs 要吸收的情况。一条到达日志若匹配不到接受日志，说明该连接早于信号存在，是客户端从自己的连接池中复用的，而这正是 Connection: close 响应头负责退役的对象。

不过接受日志本身无法区分你的调用方和你的平台。/livez 和 /readyz 同样由代理监听器提供服务，探针在整个排空期间会持续以各自独立的连接到达，因此它们会抬高 open_connections，也会像其他连接一样产生接受日志。作出这项判断的是到达日志：它知道请求路径，并有意排除这两个探针端点，以免为数不多的真实请求被每隔几秒一次的探针淹没。接受日志则用来看到达日志看不到的情况——一条建立了却从未被使用的连接。

peer 和 downstream_request_id 提供访问日志与请求关联中描述的请求到达上下文。将 peer 与前置代理的连接记录匹配，并将 downstream_request_id 与其请求记录匹配。

配置状态

指标/状态监听器提供两个配置检查。

GET /status/ready 是仅检查配置的启动门禁：

• 应用第一个有效配置之前返回 503 Service Unavailable；
• 有效配置可用后返回 200 OK；后续更新失败而 AISIX 使用最后已知的有效快照时也会返回 200 OK。

对于使用 etcd 或 AISIX Cloud 的网关，应用第一个配置之前应当观察的就是这个端点，因为在那之前代理监听器尚未绑定。参见启动与第一个配置。

GET /status/config 用于说明 AISIX 观察到和应用的内容：

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

当资源更新没有反映到代理行为中时，请使用该端点。比较来源状态与已应用状态，然后检查被拒绝的资源和最近一次加载失败。有关完整响应字段、状态含义、Prometheus 指标和告警示例，请参阅配置状态。

配置状态不能替代调用方路径验证。预期快照应用后，请查询 GET /v1/models，并发送行为发生变更的请求。请参阅配置传播。

按模型检查运行时健康状态

当网关已就绪，但路由避开某个模型或报告没有符合条件的目标时，请使用 GET /status/models：

curl -sS "http://127.0.0.1:9090/status/models"

每个已配置模型会报告以下高层状态之一：

• healthy：可用于路由；
• cooldown：在最近的上游失败后暂时移出路由；只有开启了冷却的模型才会进入该状态；
• unhealthy：后台模型检查失败后被排除；
• not_applicable：可用性由其目标决定的虚拟模型。

状态视图有助于识别冷却和后台检查失败，但不会验证调用方访问权限或模型服务提供方凭证。即使模型报告为健康，调用方 API Key、模型服务提供方密钥或上游响应仍可能导致请求失败。

有关完整响应字段，请参阅配置状态。

组合健康信号

请从最早失败的层级开始排查：

信号	下一项检查
/livez 或 /readyz 拒绝连接。	代理监听器是否已经绑定。对于使用 etcd 或 AISIX Cloud 的网关，在应用第一个配置之前它不会绑定；请检查 /status/ready 和配置来源。
/livez 失败。	进程状态、监听器绑定和监听器 TLS
/readyz 失败。	排空状态
/status/ready 失败。	初始配置来源和加载错误
/status/config 为 degraded 或 out_of_sync。	被拒绝的资源、来源连接和 last_failure
/status/models 报告 cooldown 或 unhealthy。	模型服务提供方凭证、提供方可用性、模型检查和出站网络
所有健康端点均成功，但请求失败。	调用方访问权限、模型服务提供方路径、策略执行和上游响应

最后，请使用与应用相同的路径进行检查：

AISIX_API_KEY="YOUR_CALLER_API_KEY"

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

然后通过所需的端点和模型发送真实请求。最后这项探测会验证运行时健康端点刻意不检查的条件。

下一步

使用故障排除，将失败的健康检查或请求路径检查进一步定位到配置、调用方策略、AISIX Cloud 投射或上游模型服务提供方。