跳到内容

安全性

节点间通信

在多节点 vLLM 部署中，所有节点间的通信默认是不安全的，必须通过将节点放置在隔离的网络中来加以保护。这包括：

  1. PyTorch 分布式通信
  2. KV 缓存传输通信
  3. 张量并行、流水线并行和数据并行通信

节点间通信的配置选项

以下选项用于控制 vLLM 中的节点间通信：

1. 环境变量：

  • VLLM_HOST_IP：设置 vLLM 进程用于通信的 IP 地址

2. KV 缓存传输配置：

  • --kv-ip：用于 KV 缓存传输通信的 IP 地址（默认：127.0.0.1）
  • --kv-port：用于 KV 缓存传输通信的端口（默认：14579）

3. 数据并行配置：

  • data_parallel_master_ip：数据并行主节点的 IP（默认：127.0.0.1）
  • data_parallel_master_port：数据并行主节点的端口（默认：29500）

关于 PyTorch 分布式通信的说明

vLLM 使用 PyTorch 的分布式功能进行部分节点间通信。有关 PyTorch 分布式安全考虑因素的详细信息，请参阅 PyTorch 安全指南。

PyTorch 安全指南要点：

  • PyTorch 分布式功能仅用于内部通信
  • 它们并非为在不受信任的环境或网络中使用而设计
  • 出于性能考虑，不包含任何授权协议
  • 消息传输时未加密
  • 连接接受来自任何地方的访问，且没有校验

安全建议

1. 网络隔离：

  • 将 vLLM 节点部署在专用、隔离的网络中
  • 使用网络分段来防止未经授权的访问
  • 实施适当的防火墙规则

2. 配置最佳实践：

  • 务必将 VLLM_HOST_IP 设置为特定 IP 地址，而非使用默认值
  • 配置防火墙，仅允许节点间必要的端口通信

3. 访问控制：

  • 限制对部署环境的物理和网络访问
  • 为管理界面实施适当的身份验证和授权
  • 对所有系统组件遵循最小权限原则

4. 限制媒体 URL 的访问域名：

通过设置 --allowed-media-domains 限制 vLLM 可访问的媒体 URL 域名，以防止服务器端请求伪造 (SSRF) 攻击。（例如 --allowed-media-domains upload.wikimedia.org github.com www.bogotobogo.com）

此保护措施适用于在线服务 API（多模态输入）和批处理运行器 (vllm run-batch)，其中批处理转录/翻译请求中的 file_url 值会根据相同的允许列表进行验证。

如果没有域名限制，恶意用户可能会提供指向以下目标的 URL：

  • 针对内部服务：访问内部网络端点、云元数据服务（例如 169.254.169.254）或未打算公开访问的其他服务 (SSRF)。
  • 消耗过多资源：指向超大文件或响应缓慢的端点，导致服务器下载无限制的数据，从而耗尽内存、磁盘或网络带宽。

通过显式仅允许预期媒体来源的域名，您可以显著减少此类滥用的攻击面。

此外，考虑设置 VLLM_MEDIA_URL_ALLOW_REDIRECTS=0，以防止 HTTP 重定向被跟踪从而绕过域名限制。

安全与防火墙：保护暴露的 vLLM 系统

虽然 vLLM 的设计允许将不安全的网络服务隔离在私有网络中，但某些组件（如依赖项和底层框架）可能会在所有网络接口上开启不安全的服务，有时这些行为超出了 vLLM 的直接控制范围。

一个主要问题是 torch.distributed 的使用，vLLM 利用它进行分布式通信（即使在单机上运行 vLLM 时也是如此）。当 vLLM 使用 TCP 初始化时（请参阅 PyTorch TCP 初始化文档），PyTorch 会创建一个默认监听所有网络接口的 TCPStore。这意味着如果不采取额外的保护措施，任何能够通过任何网络接口访问您机器的主机都可能访问这些服务。

从 PyTorch 的角度来看，任何 torch.distributed 的使用都应默认视为不安全。 这是 PyTorch 团队已知且有意为之的行为。

防火墙配置指南

保护 vLLM 系统最好的方法是仔细配置防火墙，仅暴露所需的最小网络范围。在大多数情况下，这意味着：

  • 阻止除 API 服务器监听的 TCP 端口之外的所有传入连接。

  • 确保内部通信使用的端口（例如用于 torch.distributed 和 KV 缓存传输的端口）仅允许来自受信任的主机或网络访问。

  • 永远不要将这些内部端口暴露在公共互联网或不受信任的网络中。

有关具体的防火墙配置说明，请查阅您的操作系统或应用程序平台文档。

API 密钥身份验证的局限性

概述

--api-key 标志（或 VLLM_API_KEY 环境变量）为 vLLM 的 HTTP 服务器提供身份验证，但仅针对 /v1 路径前缀下的 OpenAI 兼容 API 端点。许多其他敏感端点在相同的 HTTP 服务器上暴露，且没有任何身份验证强制要求。

重要提示：不要仅依赖 --api-key 来保障 vLLM 的访问安全。生产环境部署需要额外的安全措施。

受保护的端点（需要 API 密钥）

配置 --api-key 后，以下 /v1 端点需要 Bearer 令牌认证：

  • /v1/models - 列出可用模型
  • /v1/chat/completions - 聊天补全
  • /v1/completions - 文本补全
  • /v1/embeddings - 生成嵌入
  • /v1/audio/transcriptions - 音频转录
  • /v1/audio/translations - 音频翻译
  • /v1/messages - Anthropic 兼容的消息 API
  • /v1/responses - 响应管理
  • /v1/score - 评分 API
  • /v1/rerank - 重排序 API

未受保护的端点（无需 API 密钥）

即使配置了 --api-key，以下端点也不需要身份验证：

推理端点：

  • /invocations - SageMaker 兼容端点（路由到与 /v1 端点相同的推理函数）
  • /inference/v1/generate - 生成补全
  • /pooling - 池化 API
  • /classify - 分类 API
  • /score - 评分 API（非 /v1 变体）
  • /rerank - 重排序 API（非 /v1 变体）

操作控制端点（始终启用）：

  • /pause - 暂停生成（导致拒绝服务）
  • /resume - 恢复生成
  • /scale_elastic_ep - 触发伸缩操作

实用工具端点：

  • /tokenize - 文本分词
  • /detokenize - 将 token 反分词
  • /health - 健康检查
  • /ping - SageMaker 健康检查
  • /version - 版本信息
  • /load - 服务器负载指标

分词器信息端点（仅在设置了 --enable-tokenizer-info-endpoint 时）：

此端点仅在设置了 --enable-tokenizer-info-endpoint 标志时可用。它可能会暴露敏感信息，如聊天模板和分词器配置。

  • /tokenizer_info - 获取包含聊天模板和配置的综合分词器信息

开发端点（仅在 VLLM_SERVER_DEV_MODE=1 时）：

这些端点仅在环境变量 VLLM_SERVER_DEV_MODE 设置为 1 时可用。它们旨在用于开发和调试，绝不应在生产环境中启用。

  • /server_info - 获取详细的服务器配置
  • /reset_prefix_cache - 重置前缀缓存（可能中断服务）
  • /reset_mm_cache - 重置多模态缓存（可能中断服务）
  • /reset_encoder_cache - 重置编码器缓存（可能中断服务）
  • /sleep - 使引擎进入睡眠状态（导致拒绝服务）
  • /wake_up - 从睡眠状态唤醒引擎
  • /is_sleeping - 检查引擎是否处于睡眠状态
  • /collective_rpc - 在引擎上执行任意 RPC 方法（极其危险）

性能分析器端点（仅在通过 --profiler-config 启用性能分析时）：

这些端点仅在启用性能分析时可用，且仅应在本地开发中使用。

  • /start_profile - 启动 PyTorch 性能分析器
  • /stop_profile - 停止 PyTorch 性能分析器

注意：/invocations 端点特别值得关注，因为它提供了对与受保护的 /v1 端点相同的推理功能的未经身份验证的访问。

安全隐患

能够访问 vLLM HTTP 服务器的攻击者可以：

  1. 绕过身份验证：通过使用非 /v1 端点（如 /invocations, /inference/v1/generate, /pooling, /classify, /score 或 /rerank）在无需凭据的情况下运行任意推理。
  2. 导致拒绝服务：通过在没有令牌的情况下调用 /pause 或 /scale_elastic_ep。
  3. 访问操作控制：操控服务器状态（例如，暂停生成）。
  4. 如果设置了 --enable-tokenizer-info-endpoint：访问敏感的分词器配置（包括聊天模板），这可能会揭示提示工程策略或其他实现细节。
  5. 如果设置了 VLLM_SERVER_DEV_MODE=1：通过 /collective_rpc 执行任意 RPC 命令、重置缓存、使引擎睡眠以及访问详细的服务器配置。

1. 最小化暴露的端点

严重警告：切勿在生产环境中设置 VLLM_SERVER_DEV_MODE=1。开发端点暴露了极其危险的功能，包括：

  • 通过 /collective_rpc 执行任意 RPC
  • 可能中断服务的缓存操作
  • 详细的服务器配置泄露

同样，绝不要在生产环境中启用性能分析器端点。

谨慎使用 --enable-tokenizer-info-endpoint：仅在需要暴露分词器配置信息时才启用 /tokenizer_info 端点。此端点会揭示可能包含敏感实现细节或提示工程策略的聊天模板和分词器设置。

2. 在反向代理后部署

最有效的方法是将 vLLM 部署在反向代理（如 nginx、Envoy 或 Kubernetes 网关）之后，该代理可以：

  • 明确地仅允许终端用户访问您希望暴露的端点
  • 阻止所有其他端点，包括未经身份验证的推理和操作控制端点
  • 在代理层实施额外的身份验证、速率限制和日志记录

请求参数资源限制

某些 API 请求参数会对资源消耗产生巨大影响，并可能被滥用来耗尽服务器资源。/v1/completions 和 /v1/chat/completions 端点中的 n 参数控制每个请求生成的独立输出序列数量。极大的数值会导致引擎分配与 n 成比例的内存、CPU 和 GPU 时间，这可能导致宿主机内存不足，并阻止服务器处理其他请求。

为缓解此问题，vLLM 通过 VLLM_MAX_N_SEQUENCES 环境变量（默认：16384）强制执行可配置的 n 参数上限。超出此限制的请求在到达引擎前会被拒绝。

建议

  • 面向公众的部署：考虑将 VLLM_MAX_N_SEQUENCES 设置为适合您工作负载的值（例如 64 或 128），以限制单个请求的破坏范围。
  • 反向代理层：除了 vLLM 的内置限制外，考虑在反向代理处实施请求体验证和速率限制，以进一步限制滥用性负载。
  • 监控：监控每个请求的资源消耗，以检测可能表明滥用的异常模式。

工具服务器和 MCP 安全

vLLM 支持通过 --tool-server 参数连接到外部工具服务器。这使得模型能够通过 Responses API (/v1/responses) 调用工具。工具服务器支持适用于所有模型——它不仅限于特定的模型架构。

重要提示：默认情况下不启用任何工具服务器。必须通过配置显式选择启用。

内置演示工具 (GPT-OSS)

传递 --tool-server demo 可启用内置演示工具，这些工具适用于任何支持工具调用的模型。工具实现不属于 vLLM 的一部分——它们由单独安装的 gpt-oss 包提供。vLLM 仅提供委派给 gpt-oss 的轻量级包装器。

  • 代码解释器 (python)：通过 Docker 执行 Python（通过 gpt_oss.tools.python_docker）
  • Web 浏览器 (browser)：通过 Exa API 进行搜索，需要 EXA_API_KEY（通过 gpt_oss.tools.simple_browser）

代码解释器 (Python 工具) 安全风险

代码解释器在 Docker 容器内执行模型生成的代码。然而，默认情况下容器未配置网络隔离。它会继承宿主机的 Docker 网络配置（例如默认网桥网络或 --network=host），这意味着：

  • 容器可能能够访问宿主机网络和局域网。
  • 从容器中可达的内部服务可能被 SSRF (服务器端请求伪造) 攻击。
  • 云元数据服务（例如 169.254.169.254）可能被访问。
  • 如果从容器中可以访问易受攻击的内部服务（如 torch.distributed 端点），则它们可能被攻击。

这尤其令人担忧，因为正在执行的代码是由模型生成的，可能会受到对抗性输入（提示注入）的影响。

控制内置工具的可用性

内置演示工具通过两个设置进行控制：

  1. --tool-server demo：启用内置演示工具（浏览器和 Python 代码解释器）。

  2. VLLM_GPT_OSS_SYSTEM_TOOL_MCP_LABELS：当通过 Responses API 中的 mcp 工具类型请求内置工具时，此逗号分隔的允许列表控制允许使用哪些工具标签。有效值为：

  3. container - 容器工具
  4. code_interpreter - Python 代码执行工具
  5. web_search_preview - 网络搜索/浏览器工具

如果未设置此变量或为空，则不会启用通过 MCP 工具类型请求的内置工具。

要专门禁用 Python 代码解释器，请从 VLLM_GPT_OSS_SYSTEM_TOOL_MCP_LABELS 中排除 code_interpreter。

考虑自定义实现：GPT-OSS Python 工具是一个参考实现。对于生产环境部署，请考虑实现具有更严格隔离保证的自定义代码执行沙箱。有关指导，请参阅 GPT-OSS 文档。

报告安全漏洞

如果您认为已发现 vLLM 中的安全漏洞，请遵循该项目的安全策略进行报告。有关如何报告安全问题及项目安全策略的更多信息，请参阅 vLLM 安全策略。