# PR #50397 完整报告

- 仓库：`vllm-project/vllm`
- 标题：docs(security): document Ray cluster trust model and env var propagation
- 合并时间：2026-07-30 19:52
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/50397

---

## 执行摘要

本 PR 在 vLLM 安全指南中新增了一整节关于 Ray 集群信任模型与环境变量传播的文档，解释了 vLLM 默认将整个 Ray 集群视为单一信任域，并且 `RayExecutorV2` 会将驱动进程的环境变量传播到所有 Worker 进程。对于将凭据（如 `HF_TOKEN`）限定在驱动进程的部署场景，文档提供了明确的加固建议。

## 功能与动机

在多节点 Ray 部署中，`RayExecutorV2` 默认通过 `get_driver_env_vars()` 将驱动进程的所有环境变量（除少量 Worker 专用变量和用户显式排除的变量外）复制到 Worker 进程。如果运维人员将凭据仅限定在驱动进程所在节点，这一默认行为可能导致凭据泄露到 Worker 节点。此文档旨在帮助运维人员理解默认信任模型并采取适当隔离措施。

## 实现拆解

1. **信任假设**：明确 vLLM 将整个 Ray 集群视为单一信任域，任何能在集群中执行代码的主体（如提交 actor 或任务）都具有与驱动 /API 服务器相同的信任级别。这与 [Ray 官方安全模型 ](https://docs.ray.io/en/latest/ray-core/security.html) 一致。

2. **传播机制说明**：传播策略为 "copy-all-except-denylist"，通过 `vllm/v1/executor/ray_env_utils.py` 中的 `get_driver_env_vars()` 实现。Worker 端使用 `setdefault` 语义——填充缺失变量，但绝不覆盖已存在的值。

3. **风险场景**：当 GPU Worker 运行在不同节点、Pod 或信任域时，默认传播会将凭据复制到 Worker 环境。同一 OS 用户下的进程可通过 `/proc/<pid>/environ` 读取这些凭据。

4. **加固建议**：文档提供了一系列建议，包括：使用 Ray 运行时环境（如 `runtime_env`）明确限定传播变量；使用短期临时凭据；通过文件系统或专门的密钥管理服务传递凭据；利用现有的 `VLLM_RAY_PER_WORKER_ENV_VARS_DENY_LIST` 配置排除敏感变量等。

### 无可用关键源码片段（纯文档变更）。

## 评论区精华

> JPengLi：" 在 "When This Matters" 部分，考虑提及传播的环境变量也可能被 Ray Worker 产生的子进程继承，例如 'worker processes or child processes spawned by them.'"

该建议已被采纳，文档中已相应更新。

## 风险与影响

纯文档变更，无代码风险。但文档内容涉及安全实践，如果运维人员未阅读或误解文档，仍可能存在凭据泄露风险。影响面仅限于文档读者（运维人员、安全审计人员），提供明确的安全指导有助于降低因默认环境变量传播导致的凭据泄露风险。

## 关联脉络

暂无直接关联的其他 PR。可作为未来 Ray 安全相关变更的参考文档基础。