vLLM 私有化部署教程：反向代理、HTTPS 与多用户权限配置

部署目标与适用场景

vLLM 是常用的大模型推理框架，优势在于吞吐高、OpenAI 兼容接口友好，适合企业内部知识助手、研发 Copilot、客服质检、文档生成等场景。私有化部署的核心不是“把服务跑起来”这么简单，而是要让模型服务只在受控入口被调用，支持 HTTPS、统一域名、多用户鉴权、调用审计和资源配额，避免显卡资源被滥用或接口被无关人员访问。

一个较稳妥的架构是：vLLM 仅监听本机或内网地址，Nginx 负责反向袋里和 HTTPS，前置鉴权服务负责用户身份、密钥、角色、限流和日志。vLLM 自带的 api-key 参数可满足单密钥保护，但不适合复杂团队管理；多用户场景建议增加网关层，不要把 vLLM 端口直接暴露在公网。

环境准备与版本建议

推荐使用 Linux 服务器，NVIDIA GPU，驱动、CUDA、PyTorch 与 vLLM 版本要匹配。部署前先确认显卡可见：执行 nvidia-smi 查看驱动和显存；再确认 Python 版本，通常建议 Python 3.10 或 3.11。生产环境不要直接使用 root 长期运行服务，应创建独立系统用户，例如 vllm，并将模型目录、日志目录权限限定给该用户。

安装方式可使用虚拟环境：先创建目录 /opt/vllm-app，再执行 python -m venv .venv，激活后安装 vLLM。若使用 CUDA 版 PyTorch，应按照官方推荐命令安装对应版本，随后执行 pip install vllm。模型文件建议放在 /data/models/模型名，提前确认模型许可、上下文长度、显存需求和量化方案，避免上线后因资源不足频繁中断。

启动 vLLM 推理服务

首次启动建议只监听 127.0.0.1，命令形态可参考：python -m vllm.entrypoints.openai.api_server --model /data/models/Qwen2.5-7B-Instruct --served-model-name qwen25 --host 127.0.0.1 --port 8000 --api-key 内部强密钥。这里的 --served-model-name 是客户端调用时填写的模型名，建议使用稳定短名称，避免模型目录变化影响业务。

常用参数还包括 --tensor-parallel-size 用于多卡切分，--max-model-len 控制最大上下文，--gpu-memory-utilization 控制显存使用比例。生产环境不建议一开始就把显存占满，可从 0.85 起步观察。若并发请求较多，要结合 max_num_batched_tokens、max_num_seqs 等参数做压测，不要只看单次响应速度。

配置 systemd 托管进程

为了让服务可重启、可观察、可开机自启，建议用 systemd 管理。服务文件中设置 User=vllm，WorkingDirectory=/opt/vllm-app，ExecStart 指向虚拟环境里的 python 命令，并配置 Restart=always。环境变量可写入 Environment=CUDA_VISIBLE_DEVICES=0,1，用来指定使用的显卡。

日志可先交给 journald，再由日志系统采集。需要注意，提示词和回答内容可能包含内部资料，生产日志不宜完整记录请求正文，至少要做脱敏、截断或关闭正文采集，只保留用户、模型名、耗时、状态码、token 数等必要指标。

Nginx 反向袋里与 HTTPS

反向袋里的作用是统一入口、隐藏后端端口、承载 TLS 证书、设置超时和上传限制。Nginx server 监听 443，server_name 指向业务域名，ssl_certificate 和 ssl_certificate_key 指向证书文件。location /v1/ 袋里到 http://127.0.0.1:8000/v1/，并设置 Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto 等头信息。

大模型接口常用流式输出，Nginx 需要关闭袋里缓冲或降低缓冲影响，例如 proxy_buffering off，并把 proxy_read_timeout 设置得足够长，如 600s。否则长回答可能出现中途断开。client_max_body_size 可按业务设置为 20m 或更高，但不建议无限制放开，以免异常请求占用资源。

证书可以使用企业内部证书或可信证书服务签发。证书续期要纳入运维流程，避免到期后客户端全部失败。80 端口可只用于跳转到 443，生产调用统一使用 HTTPS，内部系统也应尽量使用加密链路。

多用户权限配置思路

vLLM 原生更偏推理服务，不负责复杂账号体系。团队使用时建议在 Nginx 前或 Nginx 后增加鉴权层。常见做法有三种：第一，Nginx 通过 auth_request 调用内部鉴权服务，鉴权服务校验用户密钥并返回是否放行；第二，部署一个轻量 API 网关，由网关转发到 vLLM，并实现用户、角色、配额；第三，在业务后端统一封装模型调用，普通用户不直接接触 vLLM 接口。

权限模型可以按“用户—用户组—模型—动作”设计。例如研发组可调用 qwen25 和 coder 模型，运营组只能调用文案模型；管理员可以查看用量统计，普通用户只能查看个人用量。每个用户分配独立 Key，Key 只显示一次，支持禁用、轮换和过期时间。不要多人共用同一个 Key，否则无法定位异常调用来源。

限流策略建议分层：单用户每分钟请求数、单用户每日 token 上限、单模型并发上限、全局排队长度。对于高成本模型可设置更严格额度。鉴权服务在放行前写入用户标识到请求头，例如 X-User-Id，网关日志再记录该字段，便于统计和审计。注意不要把用户 Key 继续转发给后端日志系统明文保存。

接口测试与客户端接入

部署完成后先在服务器本机测试 vLLM，再测试 Nginx HTTPS 入口。OpenAI 兼容客户端通常只需要修改 base_url、api_key 和 model。base_url 可设为 https://ai.example.com/v1，model 使用启动时的 served-model-name。若采用网关鉴权，客户端 Key 应由网关签发，vLLM 自身 api-key 只作为后端保护密钥，由网关代持。

上线前至少做三类测试：普通对话请求、流式输出请求、超长上下文请求。还要模拟错误 Key、无权限模型、超额请求和并发请求，确认返回码清晰，例如 401 表示未认证，403 表示无权限，429 表示超过限额，5xx 才表示服务端异常。

常见问题排查

如果启动时报显存不足，先降低 max-model-len 或 gpu-memory-utilization，必要时换用量化模型或减少并发。多卡部署时要确认显卡互联和 tensor-parallel-size 参数，模型大小与卡数不匹配也会失败。

如果通过 Nginx 访问出现 502，通常是 vLLM 未启动、端口不对、只监听了错误地址，或 systemd 环境变量未生效。先 curl http://127.0.0.1:8000/v1/models 验证后端，再看 Nginx error.log。若流式输出卡住，检查 proxy_buffering、proxy_read_timeout，以及客户端是否支持流式读取。

如果权限配置“不生效”，要确认请求是否真的经过网关，Nginx location 是否匹配正确，是否存在绕过路径直连 vLLM。服务器防火墙或安全组应禁止外部访问 8000 端口，只开放 443 给调用方。

安全边界与上线建议

私有化部署不等于天然安全。模型服务可能处理内部文档、代码和客户资料，应明确数据边界：哪些内容可输入模型，哪些内容必须脱敏，哪些业务禁止接入。模型输出也应在业务侧做必要校验，尤其是涉及配置建议、代码生成和自动化操作时，不应让模型结果未经确认直接执行。

生产上线建议保留灰度阶段：先开放给少量用户，观察 GPU 利用率、平均延迟、失败率、排队长度和 token 消耗，再逐步扩大范围。配置文件、证书、密钥要放在受控目录，并纳入备份和轮换流程。模型升级时不要直接替换线上目录，可新开 served-model-name 做并行验证，确认兼容后再切换流量；需要回退时，只需把网关路由指回旧模型，风险更低。

最终，一套可靠的 vLLM 私有化方案应同时满足性能、可用性和权限治理：后端专注推理，袋里层负责安全入口，鉴权层负责用户和额度，监控层负责问题发现。按这个思路建设，才能让大模型能力稳定地服务于团队，而不是变成难以管理的单机接口。