执行摘要

• 一句话：修正 API key 保护范围文档，/inference 并非认证旁路
• 推荐动作：不建议为这份 PR 精读源码：改动只有 4 行文档，且已被评审方对照 GUARDED_PREFIX 验证过，可直接采纳。值得关注的是两点设计/流程问题：(1) 安全文档与鉴权中间件之间的手工同步模式本身就是缺陷源，建议提一个 follow-up，让受保护前缀清单由 GUARDED_PREFIX 生成或加一致性测试；(2) 若你正在写 vLLM 的部署/安全文档，建议顺手补齐 “Protected Endpoints” 小节中 /inference、/cohere 的具体端点，并复核旁路示例清单中的其余路径，避免同一页再次出现内部矛盾。

功能与动机

PR body 明确指出文档自相矛盾：同一页既说 /inference 受 --api-key 保护，又把它列为「无需凭据即可绕过认证」的示例路径，导致运维人员配置反向代理时无从取舍。作者还给出了可直接复现的 curl 验证：未设置 --api-key 时请求 /inference/v1/generate 返回 401 Unauthorized，设置后返回 200 OK，因此结论是「/inference IS protected by --api-key」。

实现拆解

1. 变更入口：唯一改动文件为 docs/usage/security.md，共 4 处等量替换（+4/-4），无源码、测试、配置或部署配套改动，属于纯文档事实性修正。

2. 概览段（### Overview）：把「--api-key 只保护 /v1 前缀下的 OpenAI 兼容端点，以及其他类似的 /v2、/inference 前缀」改写为「只保护 /v1、/v2、/inference 与 /cohere 前缀下的端点」，同时修正原先错误的粗体标记（**…/inference path prefix**`），使前缀清单成为后续两处改动的唯一基准。

3. 受保护端点小节：引导句由 “the following /v1 endpoints require Bearer token authentication” 泛化为 “the following endpoints require Bearer token authentication”，与新前缀清单自洽；但下方 /v1/models、/v1/chat/completions 等 bullet 列表本身未同步扩展。

4. 攻击面小节（Security Implications）：把 “non-/v1 endpoints like /invocations, /inference/v1/generate, …” 改为 “endpoints outside the protected path prefixes, such as /invocations, …”，并把 /inference/v1/generate 从旁路示例中移除——这是本次最实质的修正点，因为该路径实际受保护。

5. 插件路由小节第 3 条：把「--api-key 只保护 /v1、/v2、/inference」补成四项前缀（新增 /cohere），避免读者按旧文案把 /cohere 当作未认证面。

6. 验证方式（无自动化测试）：作者以 curl 实测给出 401/200 对比；评审方 claude[bot] 则把新文案与 vllm/entrypoints/serve/middleware/authenticate.py 中的 GUARDED_PREFIX = ("/v1", "/v2", "/inference", "/cohere")（本次未改动的源码事实源）逐项比对，确认一致。

关键文件：

• docs/usage/security.md（模块 安全文档；类别 docs；类型 documentation）: 唯一改动文件，修正了 --api-key 保护范围这一安全关键表述，并删除 /inference/v1/generate 这一错误的认证旁路示例；该页是运维配置反向代理 allowlist 的直接依据。
• vllm/entrypoints/serve/middleware/authenticate.py（模块 鉴权中间件；类别 source；类型 data-contract；符号 GUARDED_PREFIX）: 本次未改动的鉴权事实源：其中 GUARDED_PREFIX = ("/v1", "/v2", "/inference", "/cohere") 是评审方 claude[bot] 用来验证文档新文案准确的依据，也是未来判断文档是否再次漂移的基准。

关键符号：未识别

评论区精华

• 唯一的实质性讨论是「文案是否与实现一致」：claude[bot] 在评审中给出结论 “Docs-only fix; verified against GUARDED_PREFIX = ("/v1", "/v2", "/inference", "/cohere") in vllm/entrypoints/serve/middleware/authenticate.py — the new text is accurate.”，并特别确认「including removal of /inference/v1/generate from the 'bypass' example list (it is in fact guarded) and the added /cohere prefix mention」。
• 流程性插曲：claude[bot] 首轮评论说明 “This pull request is from a fork — automated review is disabled.”，需维护者手动敲 @claude review 才触发单次评审；DarkLight1337 照做后拿到上述核对结论。
• 签署与 CI：作者因 “I did not sign-off my original commit” 追加了 Signed-off-by；DarkLight1337 执行 /ci run，Buildkite CI #88375 在 head commit 98f7cf492614 上触发。

• 最终结论：DarkLight1337 以一句 “Thanks” 批准，无 reviewer 提出反例或要求扩大核对范围（例如旁路清单中其余的 /pooling、/score、/rerank 未被逐项验证）。

  • 文档文案与 authenticate.py 事实源的一致性核对 (correctness): 文档表述与实现完全一致，评审方未发现事实性错误，DarkLight1337 据此批准。
  • fork PR 的自动评审被禁用，需维护者手动触发 (other): 属于流程约束而非代码问题，评审最终正常完成。
  • 粗体标记错误一并修正 (style): 随正文改写一并修复，无争议。

风险与影响

• 风险：
  • 文档-实现漂移会复发：GUARDED_PREFIX 是唯一事实源，而本文档是手写副本；本次靠人工比对修复，没有任何自动化校验（如由常量生成受保护前缀清单、或加一致性测试）。将来新增前缀（例如再引入 /v3 之类）时，同样会出现「概览段、受保护端点段、插件路由段三处各自漏改」的风险。
  • 本次修订留下可见缺口：概览段已声明保护四个前缀，但 “Protected Endpoints” 小节仍只列出 /v1/* 端点（/v1/models、/v1/chat/completions 等），读者可能误认为 /inference、/cohere 下没有受保护端点。
  • 旁路示例清单未被穷尽核对：/invocations、/generative_scoring、/pooling、/classify、/score、/rerank 是否确实都在受保护前缀之外，PR 与评审均未逐条给出源码或实测证据；若其中之一实际挂在 /v1 或 /cohere 下，会复现同类错误。
  • 反向代理误配风险（安全相关）：该页是运维配置 allowlist 的直接依据；旧文案会让人把受保护的 /inference/* 当作可公开路径暴露，或对其重复做鉴权，属于可用性/安全双重误配。本次修正降低而非增加该风险。
  • 无回归风险：纯文档改动，不触碰运行时行为、API 契约、性能或兼容性；build-docs 标签下的 Read the Docs 预览是唯一构建面。
• 影响：
  • 对用户（部署方/运维）：直接受益方。现在可以准确知道 --api-key 覆盖 /v1、/v2、/inference、/cohere，反向代理不必再为 /inference/v1/generate 做「它到底有没有鉴权」的猜测，减少漏保护或重复鉴权两类误配。
  • 对系统：零运行时影响，不涉及任何代码路径、内核、调度或模型行为。
  • 对团队/流程：确立了「安全文档中的受保护前缀必须与 authenticate.py 的 GUARDED_PREFIX 对齐」的隐性约定；同时暴露了该同步完全依赖人工，提示后续需要机制化手段。此外也记录了一次 fork PR 评审流程细节：自动评审默认关闭，需维护者 @claude review 手动启用。
  • 风险标记：文档与实现依赖人工同步, 无自动化一致性校验, 受保护端点列表未补齐, 旁路示例清单未逐条验证

关联脉络

• PR #56414 [Docs] Add Nebius Serverless AI deployment guide: 同一批次的纯文档 PR，都面向部署/运维读者；与本 PR 无文件重叠，关联仅为文档质量线层面的同类工作。
• PR #56459 [ROCm][Docker] Pin AINIC apt repo to snapshot 1.117.5-a-77: 同样带有 docs 改动（docs/features/moriio_connector_usage.md）的构建配套 PR，说明近期 vLLM 在安全/部署类文档上存在一批持续修订；与本 PR 无直接代码依赖。