在使用 LangChain 开发大模型应用时，我们经常会遇到这样的场景：

使用在线模型（如 OpenAI、通义千问等）时，自带 API Key 认证机制
本地部署的 Ollama、vLLM 等模型服务，默认 没有任何认证

在 本地或局域网环境下问题还不明显；但一旦你需要：

将模型服务暴露到公网
提供给团队其他成员使用
作为内部 AI 平台或推理服务

那么“ 无认证”就意味着：

任何人只要知道地址，就可以无限制地调用你的模型服务。

这不仅有安全风险，还可能带来 资源滥用和成本失控。

本文介绍一种 简单、官方、优雅的解决方案：

使用 Nginx 为本地大模型服务添加 API Key 认证

无需改动 Ollama / vLLM，也无需额外开发复杂的鉴权系统。

一、解决方案概述

Nginx 作为高性能 Web 服务器和反向代理，本身就具备非常灵活的请求处理能力。

我们可以利用 Nginx 的能力，在模型服务前面加一层 API Key 校验：

客户端  →  Nginx（API Key 校验）  →  Ollama / vLLM
┌──────────────────────────┐
│        Client             │
│  LangChain / SDK / curl   │
└─────────────┬────────────┘
│
│ Authorization: Bearer API_KEY
▼
┌──────────────────────────┐
│          Nginx            │
│  • API Key 校验 (map)     │
│  • 限流 (limit_req)       │
│  • 日志 / 代理 / TLS      │
└─────────────┬────────────┘
│
▼
┌──────────────────────────┐
│     Model Server          │
│  Ollama / vLLM            │
│  127.0.0.1:11434          │
└──────────────────────────┘

方案特点

✅ 零侵入：模型服务本身无需任何改动
✅ 配置即用：纯 Nginx 配置实现
✅ 性能稳定：Nginx 原生能力，几乎无额外开销
✅ 可扩展：后续可无缝接入 HTTPS、限流、日志、负载均衡

二、具体实施步骤

1️⃣ 生成 API Key

首先生成一个足够安全的随机字符串作为 API Key：

openssl rand -hex 16

示例输出（32 位）：

```
> 建议：
> 
> * 每个使用方一个 Key
> * 不要硬编码到代码仓库
---
## 2️⃣ 配置 Nginx（conf.d）
在 Nginx 的 `conf.d` 目录中创建配置文件，例如：
`/etc/nginx/conf.d/ollama-api.conf`

nginx

期望请求头格式：Authorization: Bearer

map $http authorization $isvalid_key { default 0; "Bearer your-api-key-1" 1; "Bearer your-api-key-2" 1; "Bearer your-api-key-3" 1; }

server { listen 21434; server_name your-domain.com; # 替换为你的域名

location / {

API Key 校验

if ($is validkey = 0) { return 401 'Unauthorized'; }

代理到本地模型服务

proxy pass http://127.0.0.1:11434;

代理头设置

proxy setheader Host $host; proxy setheader X-Real-IP $remote addr; proxyset header X-Forwarded-For $proxyadd xforwarded for; proxyset_header X-Forwarded-Proto $scheme;

流式响应支持（Chat / Stream 模式必开）

proxy buffering off; proxycache off; }

健康检查接口（可选，不做认证）

location /health { access_log off; return 200 "OK"; } }

至此，你已经为 Ollama / vLLM 加上了一道 **API Key 防线**。

---

## 3️⃣ 增加限流保护（强烈建议）

为了防止 API Key 泄露后被恶意刷请求，可以增加限流。

在 `http` 块中定义限流区域：

nginx http { limit reqzone $binary remoteaddr zone=api_limit:10m rate=10r/s; }

在 `server` 或 `location` 中启用：

nginx location / {

单 IP 每秒最多 10 次请求，允许短暂突发

limit req zone=apilimit burst=20 nodelay;

其他配置...

}

## 4️⃣ 重载 Nginx 配置

bash nginx -s reload

# 三、LangChain 客户端调用示例

配置完成后，客户端只需像调用在线模型一样，携带 `api_key` 即可。

python

pip install -U langchain langchain-openai

from langchain_openai import ChatOpenAI

llm = ChatOpenAI( model="qwen3:32b", base url="http://192.168.31.33:21434/v1", apikey="your apikey", )

**是不是非常像 OpenAI？**

> 这也是这个方案最大的优点之一：

> ? 调用方式完全统一，几乎零学习成本。

---

# 四、常见问题：map_hash 报错

如果你的 API Key 较长（例如 >64 字符），Nginx 启动时可能出现错误：

could not build map hash, you should increase maphash bucketsize: 64

解决方法：在 `http` 块中增加配置：

nginx http { map hashbucket_size 128;

如果遇到 server nameshash bucketsize 报错

server nameshash bucketsize 128;

} ```

五、安全与生产建议

API Key 管理

不要提交到 Git 仓库
建议使用环境变量或配置管理系统

日志审计

启用 Nginx access log
可按 API Key 或 IP 分析调用情况

网络隔离

对外仅开放 Nginx 端口
Ollama / vLLM 原始端口仅监听 127.0.0.1

HTTPS（强烈建议）

API Key 明文传输必须配合 TLS 使用

六、总结

通过 Nginx + API Key 的方式，我们可以非常优雅地为本地大模型服务补齐「认证」这一关键能力：

? 无需修改 Ollama / vLLM
? 性能损耗极低
? 与 LangChain / OpenAI 调用方式高度一致
?️ 后续可轻松扩展限流、HTTPS、负载均衡

如果你正在：

构建私有大模型平台
在内网或公网部署推理服务
希望用 最小成本提升安全性

那么，这个方案非常值得你直接落地使用。

希望这篇文章能对你有所帮助 ?

欢迎转发、收藏，也欢迎交流更高级的模型服务治理方案。

为本地部署的大模型添加API Key认证：Nginx实现方案