vLLM 网络配置：负载均衡、TLS 与 WebSocket
讲解如何用 Docker 发布 vLLM 在线服务上游，并通过 nginx 配置流式反向代理、实例负载均衡与 TLS 证书终止；说明 WebSocket 升级头、读取超时、连接保活所需的完整设置，以及逐项验证和常见网络排障方法。
要把 vLLM 放到 nginx 后面，关键是先用官方镜像 vllm/vllm-openai 发布可访问的上游；对确有 WebSocket 接口的部署，再单独处理协议升级。负载均衡、TLS 与 WebSocket 各管一件事：请求分配、HTTPS 入口和持续连接；只调大一个超时参数，不能替代其余配置。下面按启动、接入、验证和排障顺序给出可合并的配置骨架。
先让 vllm/vllm-openai 发布可代理上游
vLLM 基于 PyTorch，进程间会共享数据，尤其是在张量并行推理时。单机接入可使用官方镜像 vllm/vllm-openai；vLLM Docker 部署文档给出的命令发布 8000 端口、挂载 Hugging Face 缓存，并使用 --ipc=host 或 --shm-size 让容器访问主机共享内存。其他引擎参数应放在镜像标签之后：
docker run --runtime nvidia --gpus all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
vllm/vllm-openai:latest \
--model Qwen/Qwen3-0.6B
其中，-p 8000:8000 是 nginx 需要指向的发布端口。若运行环境不能采用 --ipc=host，文档也列出了 --shm-size 这一替代方式。
反向代理：关闭缓冲并区分两类超时
先保留能把 location 请求转发到上述上游的基础规则，再在同一作用域加入以下设置：
proxy_buffering off;
proxy_read_timeout YOUR_VALUE;
proxy_connect_timeout YOUR_VALUE;
根据 nginx proxy module 文档，proxy_buffering 默认为 on，nginx 会尽快把上游响应读入缓冲区；设为 off 后，响应会在收到时同步传给客户端，适合 token streaming 和 SSE。上游应用也可以通过 X-Accel-Buffering: yes 或 X-Accel-Buffering: no 按响应控制缓冲。
proxy_read_timeout 默认是 60s，计算的是两次连续读取之间的间隔，不是整个响应耗时；proxy_connect_timeout 默认也是 60s，且通常不能超过 75s。将两个 YOUR_VALUE 分别按允许的上游静默间隔和可接受连接建立时间填写，不要把生成总时长直接当作读取超时。
负载均衡：先确定需要哪种分配规则
如果请求耗时差异明显，可以在 upstream 组中尝试 least_conn。先替换组名和各实例地址：
upstream YOUR_UPSTREAM_NAME {
least_conn;
server YOUR_UPSTREAM_ADDRESS_1;
server YOUR_UPSTREAM_ADDRESS_2;
}
nginx upstream module 文档说明，least_conn 会考虑服务器权重，把请求交给活动连接数较少的实例；另一种受支持的方法是 ip_hash，其 IPv4 哈希键使用客户端地址的前三个八位组，IPv6 则使用完整地址。
未指定分配方法时，nginx HTTP 负载均衡文档记录默认使用 round-robin；当部分请求耗时更长时，least_conn 可以更公平地控制实例负载。需要特别注意，round-robin 和 least_conn 都不保证同一客户端始终进入同一服务器，因此不能把它们直接当作会话固定方案。
TLS：配置证书而不是随意改协议
准备好证书文件和私钥文件后，在承载 HTTPS 流量的 server 中加入：
listen 443 ssl;
ssl_certificate YOUR_CERTIFICATE_PATH;
ssl_certificate_key YOUR_PRIVATE_KEY_PATH;
nginx HTTPS server 配置文档要求 listen 使用 ssl 参数，并配置 ssl_certificate 与 ssl_certificate_key。nginx 默认使用 TLSv1.2 TLSv1.3，因此通常不需要显式设置 ssl_protocols。私钥文件应限制访问权限，但必须能被 nginx master process 读取。
WebSocket：显式传递升级头
nginx 能代理 WebSocket，并不等于 vLLM 的某个 API 路径必然使用 WebSocket。先确认实际客户端会发起协议切换，再在对应 location 中加入：
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout YOUR_VALUE;
nginx WebSocket proxying 文档说明，Upgrade 和 Connection 是逐跳头，必须显式设置；客户端请求协议切换且上游返回 101 Switching Protocols 后，nginx 才会建立隧道。默认情况下，上游连续 60s 没有发送数据，代理连接会关闭；需要延长 proxy_read_timeout，或安排 pings 保持数据往来。
验证与排错：按层定位
- 上游与请求路径：这套骨架不定义 API 请求路径。应从当前版本的服务文档取得实际路径，先完成一次普通请求，再完成一次流式请求，避免把路径错误误判为代理故障。
- 流式输出：观察响应是否随上游数据到达而逐步传出；如果成批出现，重新检查
proxy_buffering off、应用返回的X-Accel-Buffering以及读取超时占位值。 - 负载均衡：记录多次请求对应的实例标识，并按所选分配规则判断，不要把“连续请求必须命中同一实例”作为唯一通过条件。
- TLS：使用实际目标域名检查证书匹配和私钥加载结果。先确认内网上游可达，再测试经过 HTTPS 的请求，可以快速缩小故障层级。
- WebSocket：记录握手结果，以及连接是否只在上游静默期间关闭；若是这种情况，应继续核对升级头、读取超时和 pings。
本文步骤依据文中所链接的官方文档整理，未执行运行或性能测量；正式使用前应按当前版本复核配置与命令。