semantic-router 容器连通性排障完全指南:Docker Compose / Kubernetes 下的后端寻址、防火墙、端口发布与 Grafana 指标链验证
semantic-router 容器连通性排障完全指南:Docker Compose / Kubernetes 下的后端寻址、防火墙、端口发布与 Grafana 指标链验证
本文档基于仓库 container-connectivity.md 展开,总结在 Docker Compose 与 Kubernetes 环境中部署 semantic-router 时最常见的一批连通性问题——后端地址不可达、主机防火墙拦截、容器端口未发布、Grafana 面板“No data”——并给出可直接复制的修复命令、配置片段与验证步骤。读完本文,你将掌握:如何让 vLLM 等后端在容器网络内被正确寻址、如何判定并放行防火墙、如何把 Router 的 /metrics 与 API 端口正确发布到宿主机,以及如何用 PromQL 逐段验证“Router → Prometheus → Grafana”的完整可观测链路。
1. 问题全景:四类高频故障速查
运行 semantic-router 时,连通性问题通常集中在这四个层面:
| 故障层 | 典型症状 | 核心修复方向 |
|---|---|---|
| 后端寻址 | Envoy/Router 超时、5xx、Prometheus 中“up/down”抖动,容器内 curl 后端失败 | 后端监听 0.0.0.0;Router 配置中使用可达 IPv4 或 K8s Service DNS |
| 主机防火墙 | 宿主机能 curl 通后端,容器/Pod 内却超时 | 放行 UFW / firewalld / 云安全组对应端口 |
| 端口发布 | 宿主机访问不到 /metrics 或 API,docker ps 看不到发布端口 |
用 ports: 而非仅 expose: |
| 可观测链路 | Grafana 面板显示 “No data” | 确认指标被触发、Prometheus 抓取目标 UP、面板查询模式正确 |
下文按这四类故障逐一展开,并在最后给出可整段执行的快速检查清单。
2. 后端端点必须使用 IPv4 地址
2.1 症状与根因
- Router/Envoy 持续超时、返回 5xx,或在 Prometheus 中表现为目标“up/down”抖动(探活失败导致被踢出负载均衡池)。
- 在容器/Pod 内部用
curl访问后端失败,但在宿主机上却正常。
常见的三个根因:
- 后端只绑定了 127.0.0.1:vLLM、uvicorn 等服务默认只监听回环地址,容器网络命名空间与宿主机不共享,自然无法从容器/Pod 内访问。
- 使用了 IPv6 地址或解析到 IPv6 的主机名:在 IPv6 被禁用或被网络策略拦截的环境中,这类地址不可达。
- Router 配置里写了
localhost/127.0.0.1:在容器中这两个地址指的是容器自身,而非宿主机。对 standalone 模式的 semantic-router 而言,这同样意味着它访问的是自己,而不是宿主机上运行的模型服务。
2.2 修复:让后端监听所有接口
启动 vLLM(或任意 OpenAI 兼容服务)时,显式指定监听地址为 0.0.0.0:
# 让 vLLM 监听所有网卡(宿主机直接运行场景)
python -m vllm.entrypoints.openai.api_server \
--host 0.0.0.0 --port 11434 \
--served-model-name phi4
--host 0.0.0.0 是关键:它使服务在所有接口上监听,容器网络才能通过宿主机的网桥或网关 IP 到达它。--served-model-name 用于声明服务对外暴露的模型名,Router 配置中的模型名需要与之对齐。
2.3 Router 侧:用可达的 IPv4 或 Service DNS
在 Docker Compose 场景下,Router 配置中的后端地址必须指向“从容器内可路由到宿主机”的 IPv4:
- macOS:通常
host.docker.internal可用(Docker Desktop 自动注入);如果不可用,改用宿主机的局域网 IPv4 地址。 - Linux 或自定义网络:使用 Docker 主机网关 IPv4(默认网络通常是
172.17.0.1,自定义 bridge 网络则按docker network inspect的结果为准)。
配置片段(示例中 llm_backends 为 v0.3 时代文档使用的字段名;当前仓库 config/config.yaml 中同一语义由 providers.models[].backend_refs[].endpoint 表达,字段含义一致——endpoint 即后端地址):
# config/config.yaml(片段)
llm_backends:
- name: phi4
# 使用可达的 IPv4;替换为你宿主机的实际 IP
address: http://172.28.0.1:11434
注意:
172.28.0.1是示例网络中的 Docker 主机网关地址,不同 Docker 网络各不相同。不要在未核对docker network inspect结果的情况下照抄。
2.4 在容器内发现主机网关(Linux)
在容器或 Pod 内执行:
# 在容器/Pod 内部
ip route | awk '/default/ {print $3}'
输出的第三条字段即默认路由的网关 IP——在 bridge 网络下通常就是宿主机在容器网络内的地址,可直接用作 address。
2.5 Kubernetes:优先使用 Service,而不是写死 IP
Kubernetes 下不要试图填 Pod IP(Pod 重建即失效),应通过 Service 提供稳定的 DNS 名:
apiVersion: v1
kind: Service
metadata:
name: my-vllm
spec:
selector:
app: my-vllm
ports:
- name: http
port: 8000
targetPort: 8000
Router 配置随后使用:
http://my-vllm.default.svc.cluster.local:8000
Service 的 cluster DNS 解析为集群内部 IPv4 地址,天然满足“IPv4 可达”的要求,且自带负载均衡与 Pod 漂移透明性。注意确认 selector 与后端 Deployment 的 Pod 标签一致,否则 Endpoints 为空、DNS 能解析但连接失败。
3. 主机防火墙拦截容器/Pod 流量
3.1 症状
宿主机可以 curl 通后端,但容器/Pod 内请求超时——直到防火墙规则放行后才恢复。这类问题最容易被误判为“后端没起来”。
3.2 修复:按平台放行端口
- macOS:
系统设置 → 网络 → 防火墙,为后端进程(如 Python/uvicorn)允许“传入连接”;临时测试也可以直接关闭防火墙,排查后恢复。 - Linux(UFW,Ubuntu/Debian):
sudo ufw allow 11434/tcp
sudo ufw allow 11435/tcp
- Linux(firewalld,RHEL/CentOS/Fedora):
sudo firewall-cmd --add-port=11434/tcp --permanent
sudo firewall-cmd --add-port=11435/tcp --permanent
sudo firewall-cmd --reload
- 云主机:除操作系统防火墙外,还需在云控制台的安全组 / ACL 中放行对应入方向端口。
3.3 从容器内验证
放行后,从容器/Pod 内部实际验证一次:
docker compose exec semantic-router curl -sS http://<IPv4>:11434/v1/models
/v1/models 是 OpenAI 兼容服务的标准端点,返回 200 且列出模型列表即代表容器到后端的链路已打通。这条命令同时验证了第 2 节的寻址结论。
4. Docker Compose:端口必须 ports: 发布,而不是只 expose
4.1 症状与根因
宿主机访问不到 /metrics 或 API;docker ps 的 PORTS 列没有任何映射。根因是只使用了 expose——它仅声明容器内部端口对 Compose 网络可见,并不会把端口发布到宿主机。
4.2 修复:显式映射 ports:
services:
semantic-router:
# ...
ports:
- "9190:9190" # Prometheus /metrics
- "50051:50051" # gRPC/HTTP API(按你的实际服务端口调整)
这两个端口号与仓库实现一致:Prometheus 指标端口的默认值 9190 定义在 runtime_bootstrap.go(metrics-port 标志,默认 9190);gRPC ExtProc 监听端口的默认值 50051 定义在同一文件(port 标志,默认 50051)。若你通过 --metrics-port 或 --port 修改过,则 ports: 左侧(宿主机端口)要同步修改。
4.3 从宿主机验证
curl -sS http://localhost:9190/metrics | head -n 5
返回 Prometheus 文本格式的指标即代表发布成功。若此命令超时但容器内正常,请回到第 3 节检查防火墙对 9190 的放行情况。
5. Grafana 面板显示 “No data” 的定位与修复
5.1 常见原因一:指标尚未被触发
不少面板并非启动即有数据,而是只有代码路径被真实执行后才增长。文档与源码给出两个典型例子(指标名可在 metrics.go 中找到对应定义):
- 成本:
llm_model_cost_total{currency="USD"}——只有当RecordModelCost被调用、成本被记录时才增长(metrics.go,记录函数会在金额为负时直接返回、默认币种为 USD)。 - 拒绝:
llm_request_errors_total{reason="pii_policy_denied"|"jailbreak_block"}——只有当 PII 策略或越狱检测真的拦截请求时才增长。该指标的reason标签在 RecordRequestError 中做了归一化(如deadline_exceeded → timeout、upstream_5xx等),便于按原因聚合。
对策:向 Router 发送能触发这些路径的流量(例如启用 PII/Jailbreak 规则后构造敏感或注入类请求),而不是盯着空面板怀疑部署失败。
5.2 常见原因二:面板查询模式问题
- 分类柱状图通常需要瞬时查询(instant query),用范围查询会看到聚合形状失真。
- 分位数面板(如 p95 延迟)依赖 histogram 桶数据,若采集端没有启用或配置直方图桶,
histogram_quantile会返回空。源码中延迟直方图的桶定义可见 metrics.go:llm_model_completion_latency_seconds的桶覆盖 0.005s 到 1800s,包含维护 30 秒 P95 告警所需的范围。
5.3 可直接用于 Explore 的 PromQL 示例
以下查询覆盖分类、成本、拒绝与延迟四类常见面板(reason 正则 pii_policy_denied|jailbreak_block 与文档一致):
# 分类计数(瞬时)
sum by (category) (llm_category_classifications_count)
# 成本速率(USD/秒)
sum by (model) (rate(llm_model_cost_total{currency="USD"}[5m]))
# 按模型统计的拒绝数
sum by (model) (rate(llm_request_errors_total{reason=~"pii_policy_denied|jailbreak_block"}[5m]))
# 拒绝率百分比
100 * sum by (model) (rate(llm_request_errors_total{reason=~"pii_policy_denied|jailbreak_block"}[5m]))
/ sum by (model) (rate(llm_model_requests_total[5m]))
# 延迟 p95
histogram_quantile(0.95, sum by (le) (rate(llm_model_completion_latency_seconds_bucket[5m])))
其中 llm_model_requests_total、llm_model_cost_total、llm_request_errors_total、llm_model_completion_latency_seconds 均由 metrics.go 中的 promauto.NewCounterVec / NewHistogramVec 注册,标签维度(model、currency、reason、le)与上述查询完全对应。
5.4 Prometheus 抓取配置:先确认目标 UP
在 Prometheus 配置中分别抓取 Router 与 Envoy:
scrape_configs:
- job_name: semantic-router
static_configs:
- targets: ["semantic-router:9190"]
- job_name: envoy
metrics_path: /stats/prometheus
static_configs:
- targets: ["envoy-proxy:19000"]
抓取路径 /stats/prometheus 是 Envoy 的标准 Prometheus 暴露端点,19000 是 Envoy admin 端口约定。在 Prometheus 的 Status → Targets 页面确认这两个目标均为 UP;若 DOWN,按第 4 节的端口发布与第 3 节的防火墙顺序排查。
5.5 时间范围与刷新
选择包含近期流量的时间窗口(建议 Last 5–15 minutes),发送测试请求后手动刷新面板。Grafana 面板默认的时间范围若早于数据产生时间,同样会显示 “No data”。
6. 快速检查清单(按序执行)
- 后端监听:确认后端进程监听
0.0.0.0;Router 配置中的address/endpoint使用可达 IPv4(或解析到 IPv4 的 K8s Service DNS),不要写localhost。 - 防火墙:宿主防火墙放行后端端口(UFW / firewalld / 云安全组)。
- 端口发布:Docker Compose 中用
ports:映射 9190(/metrics)与服务端口(默认 50051)。 - 抓取目标:Prometheus
semantic-router:9190与envoy-proxy:19000均为 UP。 - 指标触发:发送能触发成本/拒绝等路径的流量;按需调整面板的瞬时/范围查询模式与时间范围。
7. 附:排障链路中的源码依据
- 指标注册与记录函数:pkg/observability/metrics/metrics.go —— 全部
llm_*指标的标签定义、桶配置与归一化逻辑。 - 默认端口(9190 / 50051):cmd/runtime_bootstrap.go ——
--metrics-port、--port标志的默认值。 - 路由配置结构(后端端点、网关模式):config/config.yaml ——
providers.models[].backend_refs[].endpoint、listeners与gateway相关字段。 - Envoy 本地配置示例:deploy/local/envoy.yaml —— ext_proc 过滤器与 Envoy 监听结构,可对照排查 x-envoy-* 头与上游超时行为。