大模型本地部署访问控制指南

说明如何配置本地大模型服务的监听地址、身份认证、接口密钥与私网范围，并通过 vLLM 指标与认证端点检查访问控制是否生效，同时避开常见配置错误。

大模型私有化部署的访问控制，应先限制可达范围，再落实用户身份和 API 密钥；模型端口能连通，不等于调用已经受控。可把 vLLM 放在受控主机上，由 LiteLLM Proxy CLI 快速开始所述的代理统一暴露接口，再用 OAuth2 Proxy 的 Nginx 集成说明校验登录，并用 WireGuard 官方说明所述的隧道限定私网访问。

部署前先确定进程和网络关系

vLLM GPU 安装文档列出的前置条件是 Linux、Python 3.10--3.13；使用 NVIDIA GPU 时，计算能力须为 7.5 或更高，预编译包包含 C++ 和 CUDA 12.9 二进制文件。vLLM 不原生支持 Windows，文档给出的 Windows 路线是在兼容的 Linux 发行版中使用 WSL。

这些只是运行前置条件，不代表模型进程已经安装完成，也不代表接口已经受保护。开始前应写清模型进程所在主机、网关入口、允许访问的客户端和凭据保管位置，避免部署完成后再补网络规则。

先限制监听入口，再决定谁能到网关

按照 LiteLLM 的 CLI 方式，可以把模型参数替换到命令中：

litellm --model YOUR_VALUE

同一快速开始记录的监听地址是：

http://0.0.0.0:4000

代理提供以下 OpenAI 风格入口：

POST /chat/completions
POST /completions
POST /embeddings
GET /models

监听地址只说明进程在哪里提供服务，不提供调用者身份。应在它前面叠加身份认证、接口密钥和私网范围。YOUR_VALUE 只是命令中的参数位置；如果要连接自建 vLLM，上游地址和模型名的具体配置应按当前 LiteLLM 配置文档填写，本文不补写未经确认的字段。

把匿名请求变成经过认证的请求

OAuth2 Proxy 可以放在已有 Nginx 反向代理之后。Nginx 的 auth_request 会通过以下端点检查请求：

/auth

该端点只返回下面两种状态，不会代理原请求：

202 Accepted
401 Unauthorized

使用这项 Nginx 集成时，OAuth2 Proxy 启动参数必须包含：

--reverse-proxy

完整 Nginx 配置中的其他参数应回到当前集成页核对，不要把 /auth 当成模型转发地址。验证时应分别发起已认证和未认证请求：检查结果是否落入上述两种状态，并确认只有通过认证的请求才继续进入上游处理。

用主密钥和虚拟密钥分开管理接口权限

根据 LiteLLM Virtual Keys 文档，使用虚拟密钥需要 PostgreSQL 数据库，并配置：

DATABASE_URL

主密钥是代理的管理密钥，用于创建其他密钥，值必须以 sk- 开头。可以通过配置文件设置：

general_settings:
  master_key: sk-YOUR_VALUE

也可以使用环境变量：

LITELLM_MASTER_KEY

创建密钥以及查看 key、user、team 维度信息所用端点如下：

/key/generate
/key/info
/user/info
/team/info

主密钥只放在网关管理路径中，普通应用应使用单独发放的虚拟密钥。不要仅凭密钥名称推断它能限制到某个具体 endpoint；更细的接口权限规则应以当前版本文档为准。

私网边界：大模型私有化部署只放行授权路径

WireGuard 官方说明指出，它通过 UDP 封装 IP 数据包，并为接口配置本端私钥和各 peer 的公钥。服务器配置应包含一个带私钥和监听端口的 [Interface]，并为每个客户端设置一个 [Peer]。可先核对以下字段；这不是可直接加载的完整配置：

[Interface]
PrivateKey = YOUR_VALUE
ListenPort = 51820

[Peer]
PublicKey = YOUR_VALUE
AllowedIPs = YOUR_VALUE

AllowedIPs 通过 Cryptokey Routing 把 peer 公钥与允许使用的隧道 IP 地址关联起来。不要把它留成无限制范围，否则该 peer 对应的地址授权也会随之扩大。

密钥分发和配置下发不属于 WireGuard 的处理范围。公钥、私钥如何交付，以及配置变更如何审计，需要另行管理；不能假设建立隧道后会自动完成这些工作。

分层验证访问控制是否生效

从允许的私网范围请求模型列表端点，确认网关能够正常响应；从计划外的网络范围确认连接在网络层被阻断，而不是仅依赖登录页面。
让已认证和未认证请求分别经过 Nginx 的认证流程，确认结果落在前述两种认证状态内，并检查未认证请求没有到达模型上游。
核对运行中的业务调用没有使用主密钥，虚拟密钥的创建和查询操作只出现在管理路径中。
通过 vLLM 生产指标文档检查监控端点，并确认能看到关键指标：

/metrics
vllm:num_requests_running
vllm:num_requests_waiting
vllm:kv_cache_usage_perc
vllm:e2e_request_latency_seconds

监控端点也应纳入访问控制，不要让管理面和监控面沿用与普通推理请求相同的开放范围。

常见错误是权限链只完成一层

最常见的错误不是模型无法启动，而是只保护其中一层入口：把监听地址当成身份认证、给推理接口加了登录却留下管理端点、遗漏 --reverse-proxy，或者以为 WireGuard 会自动分发密钥和下发配置。逐项检查网络可达性、登录状态、接口密钥和管理端点，才能确认访问控制形成闭环。

本文步骤依据正文所链接的官方文档整理，未做运行或测量；使用前应按当前版本文档复核。