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

在使用 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 位）：

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

建议：
每个使用方一个 Key
不要硬编码到代码仓库

2️⃣ 配置 Nginx（conf.d）

在 Nginx 的 conf.d 目录中创建配置文件，例如：

/etc/nginx/conf.d/ollama-api.conf

# 期望请求头格式：Authorization: Bearer <api-key>
map $http_authorization $is_valid_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_valid_key = 0) {
            return 401 'Unauthorized';
        }

        # 代理到本地模型服务
        proxy_pass http://127.0.0.1:11434;

        # 代理头设置
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 流式响应支持（Chat / Stream 模式必开）
        proxy_buffering off;
        proxy_cache off;
    }

    # 健康检查接口（可选，不做认证）
    location /health {
        access_log off;
        return 200 "OK";
    }
}

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

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

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

在 http 块中定义限流区域：

http {
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
}

在 server 或 location 中启用：

location / {
    # 单 IP 每秒最多 10 次请求，允许短暂突发
    limit_req zone=api_limit burst=20 nodelay;

    # 其他配置...
}

4️⃣ 重载 Nginx 配置

nginx -s reload

三、LangChain 客户端调用示例

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

# 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",
    api_key="your_api_key",
)

是不是非常像 OpenAI？

这也是这个方案最大的优点之一：
👉 调用方式完全统一，几乎零学习成本。

四、常见问题：map_hash 报错

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

could not build map_hash, you should increase map_hash_bucket_size: 64

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

http {
    map_hash_bucket_size 128;

    # 如果遇到 server_names_hash_bucket_size 报错
    # server_names_hash_bucket_size 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、负载均衡

如果你正在：

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

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

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

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