大模型应用开发 / 系统课时
使用 Nginx 反向代理
使用 Nginx 反向代理
学习目标
完成本课后,你将能够:
- 通过 Nginx 转发 Ollama API
- 关闭响应缓冲以保持流式输出
- 设置连接、读取和请求体限制
- 验证代理与直连结果并查看日志
代理架构
推荐让 Ollama 只监听本机:
text
客户端
→ Nginx :80/:443
→ Ollama 127.0.0.1:11434Nginx 负责域名、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 无需重启即可继续转发。
按自己的节奏,确认真正理解。