Ollama 报错 504 响应超时排查指南:反向代理与长连接配置实战避坑指南,手把手步骤拆解

最近不少朋友在群里反馈,用 Ollama 跑本地大模型的时候,通过 Nginx 或者 Caddy 反代出去,前端请求动不动就报 504 Gateway Timeout。尤其是用 Open WebUI、LobeChat 这类前端去连 Ollama 的 API,对话稍微长一点,或者模型加载慢一点,504 就准时出现。站长自己也踩过这个坑,表面上看是网关超时,实际上背后牵扯到反向代理缓冲区、流式响应、连接保持、模型加载耗时等多个层面。这篇排查指南不绕弯子,直接从实战出发,按步骤把 Ollama 报错 504 响应超时的根因和配置一次性讲透。

一、先搞清楚 504 是谁抛出来的

⚡ 【免费资源】DeepSeek/Ollama 部署排错手册 + 全套 AI 提示词资料包

站长已将大模型部署排错指南、常用环境配置文件及 AI 提效指令库整合分享至夸克网盘,可极速免费转存:

👉 点击前往夸克网盘一键免费转存全套资料包

很多人一看到 504 就以为是 Ollama 崩了,其实 504 是网关超时,通常由反向代理层抛出。Ollama 本身默认监听 11434 端口,如果你直接用 http://127.0.0.1:11434 访问没问题,但套了一层 Nginx 之后才出现 504,那问题基本锁定在 Nginx 与 Ollama 之间的通信上。站长建议第一步先做隔离测试:绕过反代,直接用 curl 请求 Ollama 的 API,观察响应时间。

time curl http://127.0.0.1:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "用一句话解释什么是反向代理",
  "stream": false
}'

如果这条命令本身就要跑很久才返回,说明瓶颈在 Ollama 推理侧,不是 Nginx 的锅。如果这条命令很快返回,但经过 Nginx 就 504,那问题就在代理配置上。这一步是排查 Ollama 报错 504 响应超时的分水岭,千万别跳过。

二、反向代理超时参数必须显式放大

🔥 【开发者算力福利】高并发 AI 部署 GPU / 独享云服务器限时特惠

本地算力不足或遇到 CUDA OOM 显存溢出?推荐搭配高性价比独享 GPU 云服务器:

👉 点击前往领取开发者限时优惠券

Nginx 默认的 proxy_read_timeout 是 60 秒,proxy_connect_timeout 也是 60 秒。大模型首次加载、长上下文推理、流式输出间隔较大时,很容易超过这个阈值。站长建议在 Nginx 的 location 块里至少配置以下参数:

location /ollama/ {
    proxy_pass http://127.0.0.1:11434/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    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_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    send_timeout 300s;

    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

注意 proxy_buffering off 这一条。Ollama 的流式响应如果被 Nginx 缓冲,前端会感觉“卡住不动”,最终触发超时。关闭缓冲后,token 可以实时吐给前端。另外 proxy_http_version 1.1 和 Connection "" 是为了启用长连接,避免每次请求都重新握手。

三、流式响应与 chunked 传输的坑

💡 关联延伸阅读:如果你在配置过程中遇到相关报错,请参阅站长之前的解决教程:DeepSeek API 多模型接入与路由配置教程:多模型路由切换报错怎么办?

Ollama 的 /api/chat 和 /api/generate 默认支持 stream 模式。如果你在前端调用时设置了 stream: true,但 Nginx 没有正确处理 chunked 传输,就会出现响应头已返回、body 迟迟不来的情况,最终 504。站长实测,除了关闭 proxy_buffering,还要确保 Nginx 没有开启 gzip 压缩流式响应。gzip 会等待缓冲区满才压缩输出,直接破坏流式体验。

gzip off;
proxy_set_header Accept-Encoding "";

有些教程会让你在 Nginx 里加 proxy_set_header Accept-Encoding ""; 来禁用后端压缩,这一步对 Ollama 同样有效。因为 Ollama 返回的是 JSON 流,压缩意义不大,反而增加延迟。

四、检查 Ollama 自身的并发与加载超时

Ollama 默认的模型加载是懒加载,第一次请求某个模型时会从磁盘加载到显存,这个过程可能几十秒甚至更久。如果你的 Nginx 超时设了 300 秒还是 504,那就要看 Ollama 服务端日志了。用 journalctl -u ollama -f 或者直接看 Ollama 启动终端输出,观察是否有 llama runner 相关的超时或 OOM 信息。

另外,Ollama 有一个环境变量 OLLAMA_KEEP_ALIVE,控制模型在内存中保持多久。默认是 5 分钟,如果设为 0,每次请求都要重新加载模型,504 概率飙升。站长建议至少设为 30m 或 -1(永久保持),前提是显存足够。

export OLLAMA_KEEP_ALIVE=30m
export OLLAMA_NUM_PARALLEL=1
export OLLAMA_MAX_LOADED_MODELS=1

如果你用 systemd 管理 Ollama,把这些变量写进 /etc/systemd/system/ollama.service 的 Environment 字段里,然后 systemctl daemon-reload && systemctl restart ollama。

五、Caddy 用户的对应配置

如果你用的是 Caddy 而不是 Nginx,504 同样会出现。Caddy 的 reverse_proxy 默认超时时间较长,但流式响应需要显式关闭缓冲。站长给出一个可用的 Caddyfile 片段:

your.domain.com {
    reverse_proxy 127.0.0.1:11434 {
        flush_interval -1
        transport http {
            read_timeout 300s
            write_timeout 300s
            dial_timeout 30s
        }
    }
}

flush_interval -1 是 Caddy 关闭响应缓冲的关键,等价于 Nginx 的 proxy_buffering off。少了这一条,流式输出会被 Caddy 攒着,前端一样等到超时。

六、前端调用侧的超时也要同步放大

有时候 Nginx 和 Ollama 都没问题,但前端框架自带的 HTTP 客户端超时了,也会报 504 或者类似错误。比如 Open WebUI 默认的请求超时可能只有 30 秒,LobeChat 也有自己的 timeout 设置。站长建议把前端请求超时调到 300 秒以上,并且确认前端没有开启自己的响应缓冲。

如果你用 Python 的 requests 库直接调 Ollama,记得设置 timeout=(10, 300),元组第一个是连接超时,第二个是读取超时。用 httpx 的话,timeout=httpx.Timeout(300.0, connect=10.0)。这些细节不处理,照样会误报 504。

七、系统层面的文件描述符与连接数

高并发场景下,Nginx 的 worker_connections 和系统 ulimit -n 也可能导致连接被丢弃,表现为 504。站长建议检查以下两项:

ulimit -n
cat /proc/sys/net/core/somaxconn
cat /proc/sys/net/ipv4/tcp_max_syn_backlog

如果 ulimit -n 只有 1024,而你的并发请求较多,Nginx 可能无法及时建立到 Ollama 的连接。在 systemd 服务里加上 LimitNOFILE=65535,并调整内核参数 net.core.somaxconn=65535。这些属于系统调优,但确实能解决一部分隐蔽的 504。

八、用日志定位真正的超时点

排查 Ollama 报错 504 响应超时,最忌讳瞎猜。站长习惯同时开三个终端:一个 tail -f /var/log/nginx/error.log,一个 journalctl -u ollama -f,一个用 curl -N 直接压测。Nginx 错误日志里如果出现 upstream timed out (110: Connection timed out) while reading response header from upstream,说明是 Ollama 没及时返回响应头;如果是 while reading upstream,说明响应头返回了但 body 超时。这两种情况处理方式不同,前者要查模型加载,后者要查流式输出和缓冲。

curl -N http://127.0.0.1:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "写一段关于超时排查的短文"}],
  "stream": true
}'

用 -N 参数禁用 curl 自身的缓冲,观察 token 是否逐个返回。如果这里就是一批一批返回,那说明 Ollama 侧或模型侧有问题;如果这里很流畅,但经过 Nginx 就卡顿,那问题百分百在代理配置。

九、总结与检查清单

Ollama 报错 504 响应超时排查指南的核心思路就一句话:先隔离,再分层,最后逐项放大超时和关闭缓冲。站长把关键检查点整理成清单,方便你逐条核对:

1. 绕过反代直连 Ollama,确认推理本身是否超时。
2. Nginx 设置 proxy_read_timeout、proxy_send_timeout、proxy_connect_timeout 均不低于 300 秒。
3. 关闭 proxy_buffering,禁用 gzip,启用 HTTP/1.1 长连接。
4. Caddy 用户设置 flush_interval -1 和 transport 超时。
5. Ollama 侧设置 OLLAMA_KEEP_ALIVE 避免频繁加载模型。
6. 前端 HTTP 客户端超时同步放大到 300 秒以上。
7. 检查系统 ulimit 和内核连接队列参数。
8. 用 curl -N 和 Nginx error log 定位超时发生在响应头还是响应体阶段。

把这八条过一遍,绝大多数 Ollama 504 问题都能定位并解决。如果还是不行,那就要考虑是不是模型太大导致显存不足、Ollama 进程被 OOM Killer 干掉,或者网络层有防火墙中断长连接。站长建议把 Ollama 和反代放在同一台机器上,减少网络跳数,能规避很多莫名其妙的超时。配置改完记得重启服务,别只 reload,有些环境变量和连接池参数必须重启才生效。

站长推荐
⚡ 开发者实操必备资源与算力限时特惠通道

阅读完本教程准备实操?站长已将 AI 部署排错手册、提示词全集与服务器限时优惠整理如下,即拿即用:

滚动至顶部