客户端  →  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、负载均衡

如果你正在：

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

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

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

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

BugShare

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

一、解决方案概述