大模型本地部署内网接入指南

大模型的私有化部署要做到“内网可用”，关键是先让模型网关监听正确的服务地址，再建立受控隧道，最后由反向代理接入必要的访问控制。客户端应通过内网地址或隧道地址访问服务，并把鉴权、流式响应和断连检查放在同一条验证链中。

私有化部署前先确定接入边界

开始前，记录模型网关所在主机、具体内网 IP、端口和启动方式，并打开底层模型项目当前的 API 文档。再准备：

• WireGuard 服务端与客户端密钥、隧道网段和每个 peer 的 AllowedIPs；
• Nginx 上游地址与内网访问路径；
• 是否接入 OAuth2 Proxy，以及允许登录的账号范围；
• 实际调用端点、鉴权字段和流式参数。

0.0.0.0 出现在监听信息中时，代表绑定所有本机接口；客户端和 Nginx 上游仍应填写具体内网地址或隧道地址。网络可达性与登录控制也要分别验证。

先让 LiteLLM 在内网可达

以 LiteLLM 作为统一入口时，LiteLLM 的 Proxy CLI 快速开始给出的启动形式如下：

litellm --model YOUR_VALUE

该示例启动后监听 http://0.0.0.0:4000，并提供 POST /chat/completions、POST /embeddings、GET /models 等接口。进程出现监听提示只代表服务已经启动；内网客户端还应使用具体主机地址请求 /models，完成实际连通检查。

需要配置文件时，按 LiteLLM 的 config.yaml 说明启动：

litellm --config /path/to/config.yaml

general_settings 用于放置服务器设置，例如 master_key：

general_settings:
  master_key: YOUR_VALUE

真实凭据不要保留在示例或公开配置中。底层模型若使用不同鉴权方式，应以其当前项目文档为准，不能仅凭监听成功判断接口已经可用。

用 WireGuard 建立受控内网路径

按 WireGuard 官方说明，它在 UDP 上封装 IP 数据包：接口使用本端私钥和对端公钥，Cryptokey Routing 则把公钥与允许使用的隧道 IP 列表 AllowedIPs 关联起来。服务端配置的关键字段骨架如下：

[Interface]
PrivateKey = YOUR_VALUE
ListenPort = 51820

[Peer]
PublicKey = YOUR_VALUE
AllowedIPs = YOUR_VALUE

每个客户端使用独立的 [Peer]，并核对公钥与 AllowedIPs 的对应关系。密钥分发和 pushed configuration 不属于 WireGuard 的处理范围，应通过现有的安全管理流程完成；私钥只保留在对应端点。

生成密钥时，WireGuard 快速开始给出的命令是：

wg genkey | tee privatekey | wg pubkey > publickey

PersistentKeepalive 默认关闭，用于位于 NAT 或防火墙后的 peer；只有拓扑确实需要时才在对应 [Peer] 中配置。

用 Nginx 转发并接入登录控制

把 Nginx 上游指向 LiteLLM 主机的具体内网地址和端口。根据 ngx_http_proxy_module 文档，proxy_buffering 默认开启；设为 off 后，响应会在收到时同步传给客户端，适合 token streaming 和 SSE：

proxy_buffering off;

上游应用还可以通过 X-Accel-Buffering: yes 或 X-Accel-Buffering: no 逐次响应控制缓冲。proxy_read_timeout 默认为 60s，计算的是相邻两次读取之间的间隔，不是整段响应的总传输时间，因此长等待与持续传输要区别判断。

需要登录控制时，按 OAuth2 Proxy 的 Nginx 集成文档配置：Nginx 的 auth_request 调用 /auth，该端点只返回 202 Accepted 或 401 Unauthorized，不会代理业务请求，并且集成要求设置 --reverse-proxy。鉴权路径与模型调用路径应保持分离。

按顺序检查接入结果

使用你已经批准并配置的 HTTP 客户端，按以下顺序检查：

• 内网直连：从模型网关所在内网访问具体地址的 GET /models，记录响应状态。
• 隧道访问：从获授权的 WireGuard peer 重复请求，确认隧道地址可达。
• 代理访问：通过 Nginx 路径再次请求 /models，分别检查未授权和已授权请求。
• 流式响应：模型 API 支持流式输出时，检查内容是否随上游响应到达，而不是成批出现。
• 日志对应：记录客户端、Nginx、LiteLLM 与 WireGuard 的时间顺序，避免只凭其中一层的“启动成功”判断接入完成。

常见故障集中检查

• 把监听地址当作访问地址：客户端请求 0.0.0.0，应改为模型主机的具体内网 IP 或隧道 IP。
• 隧道建立但服务不可达：逐项核对 peer 公钥、AllowedIPs、隧道 IP 和防火墙路径，不要把密钥分发问题归到 WireGuard 隧道内部。
• 流式输出成批出现：检查 Nginx 的 proxy_buffering 以及上游返回的 X-Accel-Buffering。
• 等待后连接中断：对照上游产生下一段数据的时间检查 proxy_read_timeout，不要把它当作整段响应时限。
• 鉴权持续失败：检查 Nginx 的认证请求路径、/auth 状态和 --reverse-proxy 设置，并确认没有把鉴权端点当成模型端点。

本文步骤均按正文链接的官方文档整理，未做运行或测量；使用前请对照当前版本复核。

资料来源

• WireGuard 官方说明
• WireGuard 快速开始
• LiteLLM Proxy CLI 快速开始
• LiteLLM config.yaml 说明
• ngx_http_proxy_module 文档
• OAuth2 Proxy 的 Nginx 集成文档