版本：最新版（未发布）

受限网络环境

Semantic Router 可能因三种不同原因需要网络访问：

在更改镜像或代理设置之前，先确认失败的是哪一层。仓库超时、Hugging Face 超时和不可达的提供方端点需要不同的修复。

诊断失败层

启动协议栈，并检查其状态和组件日志：

vllm-sr serve --config config.yaml
vllm-sr status
vllm-sr logs router
vllm-sr logs envoy  # --gateway extproc only

现象	可能的层
镜像拉取或仓库身份验证错误	容器仓库
Router 已启动，但在加载模型产物时等待	Hugging Face 或本地模型路径
服务栈已就绪，但 completions 返回连接错误	提供方端点或防火墙
Kubernetes Pod 停留在 `ImagePullBackOff`	集群节点访问仓库

从能到达其仓库的网络预先拉取镜像，或把它们镜像到部署环境可用的仓库。本地开发时，在使用不拉取策略之前确认每个所需镜像都已存在：

vllm-sr serve --config config.yaml --image-pull-policy never

never 不会下载缺失镜像；镜像不存在时启动失败。当本地镜像应被复用、但缺失的仍可拉取时，使用 ifnotpresent。

对于 make vllm-sr-dev 构建的镜像，需要显式选择本地 tag，因为稳定包版本的可编辑 CLI 默认仍会选择发布镜像：

VLLM_SR_IMAGE=ghcr.io/vllm-project/semantic-router/vllm-sr:latest \
  vllm-sr serve --config config.yaml --image-pull-policy never

对于 AMD 或 NVIDIA 构建，选择对应的 vllm-sr-rocm 或 vllm-sr-cuda 镜像，并传入 --platform rocm 或 --platform cuda。如果自定义了构建 tag 或仓库，请使用实际值；完整本地流程见开发指南。

从源码构建项目时，通过组织已批准的代理或镜像配置包管理器和容器运行时。避免把区域端点、凭据或本地代理地址提交到仓库。

本地 CLI 会把 HF_ENDPOINT、HF_TOKEN、HF_HOME 和 HF_HUB_CACHE 转发到 Router 容器。只设置环境需要的值：

export HF_ENDPOINT=https://your-approved-hugging-face-mirror.example
export HF_TOKEN=your_token_if_required
vllm-sr serve --config config.yaml

把令牌放在环境或外部密钥管理器中。CLI 会在日志中遮蔽敏感的透传值。

离线部署时，预先下载所需产物并放到工作区模型目录：

在 Router 配置中使用 /app/models/...，然后确认文件存在于运行时内，且格式与所选信号或嵌入实现匹配。

提供方 URL 必须从 Router/Envoy 网络可达，而不仅是从宿主机 shell。不要把运行在另一容器或宿主机上的后端写成 localhost；在容器内，localhost 指向该容器自身。

使用以下模式之一：

逐步的端点和防火墙检查清单见容器连通性。

Kubernetes 节点使用自己的容器运行时，不会继承运行 kubectl 的机器上的镜像缓存或代理设置。

对于受限集群：

kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp