大模型应用开发 / 系统课时

使用 Nginx 反向代理

使用 Nginx 反向代理

学习目标

完成本课后,你将能够:

  • 通过 Nginx 转发 Ollama API
  • 关闭响应缓冲以保持流式输出
  • 设置连接、读取和请求体限制
  • 验证代理与直连结果并查看日志

代理架构

推荐让 Ollama 只监听本机:

text
客户端
→ Nginx :80/:443
→ Ollama 127.0.0.1:11434

Nginx 负责域名、TLS、认证、限流和访问日志。Ollama 默认端口不直接暴露到外部网络。

基础配置

创建站点配置,例如 /etc/nginx/conf.d/ollama.conf:

nginx
upstream ollama_backend {
    server 127.0.0.1:11434;
    keepalive 16;
}

server {
    listen 80;
    server_name ollama.example.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://ollama_backend;
        proxy_http_version 1.1;

        proxy_set_header Host localhost:11434;
        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;

        proxy_buffering off;
        proxy_request_buffering off;

        proxy_connect_timeout 10s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }
}

ollama.example.com 替换为真实域名。配置本身不包含 TLS 和认证,不能直接视为公网生产配置。

检查并加载配置

执行:

bash
sudo nginx -t
sudo systemctl reload nginx
systemctl is-active nginx

预期输出:

text
nginx: the configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful
active

验证代理

执行:

bash
curl --fail --silent --show-error http://ollama.example.com/api/tags

预期结果:

text
返回与直连 http://127.0.0.1:11434/api/tags 一致的 models 结构。

使用本机尚未配置 DNS 时,可以临时:

bash
curl --resolve ollama.example.com:80:127.0.0.1   http://ollama.example.com/api/tags

预期结果:

text
HTTP 请求通过 Nginx 返回模型列表。

验证流式响应

执行:

bash
curl --no-buffer http://ollama.example.com/api/generate   -H "Content-Type: application/json"   -d '{
    "model": "gemma3:1b",
    "prompt": "用五点说明反向代理注意事项。",
    "stream": true
  }'

预期输出:

text
{"response":"<CHUNK>","done":false,...}
{"response":"<CHUNK>","done":false,...}
...
{"done":true,...}

如果长时间无输出但直连正常,检查 proxy_buffering、上游超时和中间 CDN。

超时与请求体

  • proxy_connect_timeout:连接 Ollama 的等待时间。
  • proxy_read_timeout:等待上游下一段数据。
  • proxy_send_timeout:向上游发送请求的时间。
  • client_max_body_size:限制上传图片或大请求。

超时应覆盖模型加载和长生成,但不能无限大。应用层还应设置自己的总任务超时。

日志与隐私

Nginx 默认访问日志通常记录路径、状态、字节和耗时,不应把请求体写入日志。若使用调试模块、Lua 或自定义日志,确认不会保存提示词、图片 Base64 或密钥。查看日志:

bash
sudo tail -n 100 /var/log/nginx/access.log
sudo tail -n 100 /var/log/nginx/error.log

预期输出为最近代理请求和错误记录,路径可能因发行版配置不同。

常见代理错误

状态 可能原因
502 Ollama 未启动、地址错误、连接被拒绝
504 模型加载或生成超过代理超时
413 请求体超过 client_max_body_size
流式延迟 代理缓冲或中间层缓存
404 proxy_pass 路径拼接错误
连接重置 客户端取消、上游退出、超时

先直连 Ollama,再测试 Nginx,可以快速判断故障层。

本课练习

练习 1:部署本机代理

任务目标:隐藏默认端口。输入或初始条件:Nginx 与 Ollama 同机。

实现要求:保持 Ollama 监听 127.0.0.1,由 Nginx 转发。验收条件:外部只能访问 Nginx。

练习 2:测试流式缓冲

任务目标:验证实时输出。输入或初始条件:准备一个长回答。实现要求:比较直连和代理首块时间。验收条件:代理没有明显积累多个块后一次返回。

练习 3:模拟上游停止

任务目标:识别 502。输入或初始条件:先正常代理,再停止 Ollama。实现要求:观察状态和日志

验收条件:恢复服务后 Nginx 无需重启即可继续转发。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Nginx 反向代理

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通