Gateway 模式
gateway 模式决定客户端流量从哪里进入,目标决定整套服务在哪里运行。它们与 --engine 是不同的选择:--engine 提供原生判断请求,不启用 Chat 路由;省略时启动 Router 模式。共用的前端与模型运行时见组件架构。
| 模式 | 客户端流量进入 | 适用场景 |
|---|---|---|
standalone(默认) | Router 本身,它在配置的 listeners 上提供 OpenAI 兼容接口 | 单机、开发、边缘、大多数自托管 |
extproc | Router 前面的基于 Envoy 的网关,Router 提供 ext_proc | 需要限流、mTLS、高级路由匹配等 Envoy 能力,或接入你已有的网关 |
| 目标 | standalone | extproc |
|---|---|---|
docker(默认) | Router 容器服务 listener,没有 Envoy 容器 | CLI 启动的 Envoy 容器位于 Router 之前,与以前的版本一致 |
kubernetes | Router Pod 服务 listener,由 Service 暴露 | Router 为你的 Envoy Gateway、Envoy AI Gateway、Istio 或 KServe 提供 ext_proc |
vllm-sr serve # standalone,docker
vllm-sr serve --gateway extproc # Envoy 在前,docker
vllm-sr serve --target kubernetes --config config.yaml
除 非你需要上面列出的 Envoy 功能,否则先用 standalone。在 docker 目标上,切换模式就是用当前生效的配置重启:运行 vllm-sr serve --gateway extproc,再运行普通的 vllm-sr serve 即可切回。standalone 模式下没有 Envoy 容器,所以 vllm-sr logs envoy 和 x-envoy-* 响应头只属于 extproc。
两种模式运行同一个路由核心,因此同一个请求在两种模式下得到相同的决策、相同的上游请求和相同的响应变换。
设计文档列出了少数有意为之的差异,例如只有 Envoy 才会添加的
x-envoy-* header。
以前的版本总是在 Router 前面放 Envoy。现在默认是 standalone;vllm-sr serve --gateway extproc 会恢复 Envoy 入口。
参见发布说明。
standalone 模式下 Router 做什么
-
listener:
listeners中的每一项都以 HTTP/1.1 和 HTTP/2(明文下为 h2c)提供服务。timeout限制读取请求的时间(客户端停止发送请求体时返回 408)和空闲连接保持的时间, 不限制后端仍在流式返回的响应。请求体上限 500 MiB,每个 listener 最多 50,000 个连接,与 Envoy 模板的限制一致。 -
API key: 设置
api_keys后,客户端需以Authorization: Bearer <key>或api-key: <key>发送其中之一; 其他请求得到 OpenAI 风格的 401。key 在请求到达 provider 之前被移除。 -
模型白名单: 设置
models后,该 listener 只接受这些请求模型(见模型白名单)。 -
TLS:
tls让该 listener 以 TLS 1.2 及以上提供服务,通过 ALPN 协商 HTTP/2 或 HTTP/1.1。相对路径相对于配置 文件所在目录。证书文件变化时 Router 会重新加载密钥对,因此续期后的证书(轮换的 Kubernetes Secret、cert-manager) 无需重启即可用于新连接;加载失败时继续使用之前的密钥对。--gateway extproc不提供该能力。listeners:- name: https-8443address: 0.0.0.0port: 8443tls:cert_file: certs/tls.crtkey_file: certs/tls.key -
边缘的信任边界: 客户端发送的两类 header 永远不会进入路由或到达后端:
- 身份 header(
x-authz-*,以及global.services.authz.identity指定的名称),除非 listener 信任它们(见身份 header); - 只有可信代理才能设置的代理控制 header:
x-envoy-internal以及 Envoy 的重试、超时和追踪控制,例如x-envoy-max-retries、x-envoy-retry-on和x-envoy-upstream-rq-timeout-ms。这份清单就是 Envoy 从外部请求中剥离的那一份。
Router 之后的基于 Envoy 的组件(例如 sidecar 或模型服务前的网关)会听从 Router 发来的这些控制。剥离它们能让 Router 的可靠性策略始终是唯一的重试和超时权威。
- 身份 header(
-
探针: 进程运行时
GET /health就会应答;路由核心可以接收流量后GET /ready才应答。Prometheus 指标仍在 Router 的指标端口(9190)。 -
重新加载: Router 原地重新加载配置。修改 listener 的地址、端口、超时或
tls路径,或者新增、删除 listener, 都会以restart_required被拒绝,直到 Router 重启;API key、apis及其模型白名单和身份信任可原地重新加载。 -
关闭: 收到 SIGTERM 后,
GET /ready返回 503,listener 停止接受连接,每个 HTTP/2 连接(包括 h2c)都会收到 GOAWAY。正在处理的请求有global.router.drain_timeout_seconds秒(默认 25)完成;见关闭时的排空。
模型白名单
listener apis 中某个 API 的 models 列出该 API 接受的全部请求 model 值。可以用它让公开 key 只能访问 Router 的自动模型,而内部
listener 仍可使用所有模型:
listeners:
- name: dashboard-internal # 第一个 listener:Dashboard Playground 使用它
address: 127.0.0.1
port: 8898
- name: public
address: 0.0.0.0
port: 8899
api_keys: ["${WORKSHOP_KEY}"]
apis:
chat_completions: {models: [vllm-sr/auto]}
responses: {models: [vllm-sr/auto]}
- 名称精确匹配(区分大小写,请求值去除首尾空白后比较),不展开别名:请列出客户端可能发送的每个名称。为空或不设置时, listener 接受所有模型。
- 检查在 API key 检查之后、任何 signal、缓存或 decision 之前进行,使用的是 Router 为路由解析出的同一个模型。其他模型
(包括原本会直通的 provider 模型)得到
403,错误码model_not_allowed,并以客户端协议返回。没有模型的请求得到400 model_required。 - 该 listener 上的
GET /v1/models只列出目录中存在的允许名称。 - decision 在进程内发起的模型调用(Looper 和 request-graph hop)不是客户端请求,不受限制,因此
vllm-sr/auto仍可到达其 decision 指定的所有 provider 模型。 - 即使开启了
global.router.skip_processing.enabled,该 listener 也会忽略x-vsr-skip-processing,因为跳过的请求 会绕过检查。 --gateway extproc会以 unsupported 拒绝带models的 listener:CLI 生成的 Envoy listener 目前还不执行它。
身份 header
默认情况下,listener 会丢弃客户端发送的身份 header,因为 Router 前面没有任何组件认证过它:任何人都可以冒充任何
用户。standalone 模式下由 Router 自己丢弃;使用 --gateway extproc 时,CLI 生成的 Envoy listener 会在任何过滤器或 Router
读取它们之前删除它们。在认证代理之后,或者对自行设置用户的可信应用服务器,可以让 listener 保留这些 header:
listeners:
- name: http-8899
address: 0.0.0.0
port: 8899
identity:
trust_headers: true
# 可选:只在来自代理所在网络的连接上保留它们。
trusted_peers: ["10.0.0.0/8"]
trust_headers保留x-authz-*header(x-authz-user-id、x-authz-user-groups、x-authz-team-id、x-authz-tenant-id)以及global.services.authz.identity指定的名称。standalone Router 还会保留global.services.authz.delegated_credential的 header,Chat 和 System One 请求都一样;无论如何,--gateway extproclistener 都会删除客户端发送的副本。trusted_peers(CIDR)只在连接的对端地址属于其中某个网络时才保留它们;Router 不会为此读取X-Forwarded-For。 为空时,信任 header 的 listener 信任所有对端。只有 standalone 模式检查对端:--gateway extproc拒绝trusted_peers,这时请只保留trust_headers,并放在会删除客户端身份 header 的代理之后。- 每个 listener 只为自己的请求做决定,重新加载会应用修改。在不信任身份的 listener 上,请求是匿名的。
- 两种模式下,身份 header 都不会到达模型提供方:Router 和生成的 Envoy listener 会从每个上游请求中删除它们。
Memory 和 router replay 会记录每个请求的用户。没有信任身份的 listener 时,它们仍会加载,并把每个请求视为匿名请求;Router 会在启动时记录一条点名这些功能的警告。