如果本地的 vLLM 服务已经启动,但注册到 Consul 后健康检查一直返回 503,通常不是推理服务彻底挂了,而是服务发现和探活之间没有对齐。这类问题多半集中在两个地方:一是 vLLM 的 /health 端点还没有真正就绪,二是 Consul 的探活请求没有命中正确的地址或路径。下面按排查顺序说明。
先判断是 vLLM 自身问题还是 Consul 配置问题
当本地推理服务器注册到 Consul 后,探活接口返回 503,首先需要区分是 vLLM 服务本身未就绪,还是 Consul 探活配置有误。可以直接在服务器上执行 curl 命令访问 vLLM 的健康检查端点,例如 curl -i http://127.0.0.1:8000/health。如果返回 200 OK,说明服务正常,问题出在 Consul 的探活路径或端口上;如果同样返回 503,则可能是模型尚未加载完成,或服务内部出现错误。此时查看 vLLM 日志,确认是否还在加载模型或是否因显存不足而启动失败。
如果 vLLM 是通过 systemd 管理的,可以用 journalctl -u vllm -n 100 查看最近日志;如果是手动启动的,则看终端输出或重定向的日志文件。重点看有没有 “Loading model”、“CUDA out of memory” 之类的关键信息。如果日志显示模型还在加载,那就等加载完毕后再观察。
# 查看 vLLM 服务最近日志(假设由 systemd 启动)
journalctl -u vllm -n 100
Consul 健康检查的配置要点
配置 Consul 健康检查时,需要仔细填 `http` 字段,确保路径指向 vLLM 的 /health,而不是其他端点。同时根据模型加载时间设置合理的 `interval` 和 `timeout`,比如间隔十几秒,超时两三秒。如果模型加载需要较长时间,可以使用 `initial_status: warning`,并配合 `deregister_critical_service_after` 设置一个足够长的容忍时间,例如数十分钟,以避免正常加载过程中被误判为不健康而移除。
下面是一个 Consul 服务注册 JSON 示例,健康检查指向 vLLM 的 /health:
{
"id": "vllm-0",
"name": "vllm-inference",
"address": "10.0.0.2",
"port": 8000,
"check": {
"http": "http://10.0.0.2:8000/health",
"interval": "15s",
"timeout": "3s",
"initial_status": "warning",
"deregister_critical_service_after": "30m"
}
}
这里的 address 要填 Consul agent 能访问到的地址,通常用内网 IP 而不是 localhost。http 字段必须指向 vLLM 的 /health,不能写成 /metrics 或其他路径。interval 是探活间隔,timeout 是单次请求超时,这两个值要大于 vLLM 响应健康检查的实际耗时。对于模型加载时间较长的服务,initial_status 可以让注册开始时先标记为 warning,等健康检查通过后再转绿。
模型加载导致的 503 怎么处理
vLLM 服务启动后,会在后台加载权重文件,这个过程可能持续几十秒甚至几分钟。在模型未完全就绪前,虽然 HTTP 端口已经打开,但 /health 端点会返回 503。Consul 在服务注册后立即启动探活,如果还没来得及等加载完成就探活,自然就会标记为不健康。对这种情况,可以在注册脚本中先循环调用 /health,直到返回 200 后再注册到 Consul,也可以依赖 Consul 的 `initial_status` 功能,先把健康状态设为 warning。
下面是一个简单的等待脚本,在注册前先确认 /health 返回 200:
#!/bin/bash
# 等待 vLLM 健康检查返回 200,再注册到 Consul
for i in {1..30}; do
if curl -sf http://127.0.0.1:8000/health; then
break
fi
sleep 5
done
# 提交注册信息(根据 Consul 版本调整命令)
consul services register /etc/consul.d/vllm.json
这个脚本会在 30 次循环内检查 /health,每次间隔 5 秒,最长等约 150 秒。如果模型加载时间比这还长,需要把循环次数调大。脚本执行完后才注册服务,这样 Consul 第一次探活时 vLLM 已经就绪。如果不想写脚本,也可以使用 `initial_status: warning`,但要注意,如果 Consul 探活一直失败,最终还是会变成 critical。
建议把循环等待脚本和 `initial_status` 分开看待:脚本更适合服务启动流程可控的场景;`initial_status` 更适合临时注册、不想改启动脚本的场景。两者也可以同时用,但要注意 `initial_status` 是 Consul 注册时的起始状态,不是健康检查的替代品。
地址与端口不匹配的检查
另一个容易忽略的问题是 Consul agent 和 vLLM 不在同一个网络命名空间。比如 vLLM 默认绑定 0.0.0.0,但注册时填了 localhost;Consul 如果运行在另一台机器或容器里,请求就会打到 Consul agent 自己的 8000 端口,自然返回 503。注册前应当在 Consul agent 所在环境里执行 curl http://实际IP:8000/health,确认该地址可达。同时检查防火墙和云安全组,别只放行 127.0.0.1。
关于 deregister_critical_service_after 的边界
deregister_critical_service_after 的值会直接影响故障恢复的代价。如果设置过短,比如 5 分钟,vLLM 因为临时显存不足或重启而短暂失去响应时,Consul 会直接把它从服务列表里移除,客户端就找不到这个推理服务了。设置过长,比如一天,则失效服务会长时间留在列表里,调用方会一直尝试连接不可用的地址。对于 vLLM 这种启动耗时的服务,建议先给到 30 分钟以上,配合告警观察实际恢复时间,再逐步调短。这里需要结合你的模型大小和机器性能确认,没有固定值。
排查时始终记住:本地通不代表 Consul 通,Consul 通不代表服务健康。每次调整健康检查参数后,最好在 Consul UI 里观察几次探活周期,确认状态稳定后再继续调其他项。