Spring AI 接 Ollama 报 Connection refused

Connection refused 和 model not found 是两码事。前者是压根没连上 Ollama 的 11434 端口，后者是连上了但本地没这个模型。先 curl 一次 /api/tags，就能把问题劈成「服务没起」和「网络绑定不对」两半。

Issue & Env（案发现场与环境）

• 业务场景：Spring AI 接本地 Ollama，一调用就失败；同一台机器上跑 Ollama CLI 也连不上。
• 环境：以 Spring AI 1.1.x 为基线，Ollama 本地安装或跑在容器里，默认端口 11434。
• 关键区分：站内另有一篇讲 model not found, try pulling it first 的文章，那篇是模型不存在，这篇是端口压根连不上。

StackTrace（堆栈日志）

Spring AI 侧抛的是连接层异常：

org.springframework.web.client.ResourceAccessException: I/O error on POST request for "http://localhost:11434/api/chat": Connection refused
    at org.springframework.web.client.RestClient$DefaultRequestBodyUriSpec.exchange(RestClient.java:834)
Caused by: java.net.ConnectException: Connection refused

Ollama CLI 侧：

Error: could not connect to ollama app, is it running?

curl 侧：

curl: (7) Failed to connect to 127.0.0.1 port 11434: Connection refused

注意 ResourceAccessException 不是 HTTP 业务错误。它说明连接还没建立就挂了，请求根本没到 Ollama。Ollama 返回的 4xx、5xx 是另一类问题。

Reproduce（复现代码）

最常见的一段配置：

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3.1

调用代码：

chatClient.prompt().user("hi").call().content();

只要这个时候 Ollama 没在跑，或者应用连不到这个地址，就会抛 Connection refused。

Root Cause（根因分析）

服务进程没起来或被 OOM 杀掉

Ollama 没启动，或者被系统 OOM killer 杀了。macOS 上 Ollama 是常驻 app，退出 Dock 图标就等于停了服务。Linux 上用 systemd 托管时，进程崩掉不一定自动重启。

默认只绑 127.0.0.1

Ollama 默认监听 127.0.0.1:11434，只接受本机回环连接。同机应用能连，其他机器或容器连不上。这不是故障，是默认安全策略。

容器里的 localhost 指容器自己

应用跑在 Docker 容器里时，localhost 指容器自身，不是宿主机。宿主机的 Ollama 对容器来说在另一台「机器」上，所以直接 localhost 必然连不上。

The Fix（解决方案）

第一步：先 curl 做二分

curl http://127.0.0.1:11434/api/tags

• 能返回 JSON 模型列表：服务活着，问题在网络绑定或容器网络。跳到第三步。
• 报 Connection refused：服务没起，先看第二步。

第二步：确认服务状态

macOS 上确认 Ollama.app 在跑，或手动起一个：

ollama serve

Linux 交给 systemd 托管时：

sudo systemctl status ollama
sudo systemctl start ollama

如果怀疑刚被 OOM 杀过，翻一下日志能看到线索：

journalctl -u ollama -n 100

第三步：需要跨机或容器访问时改绑定

临时指定监听地址：

OLLAMA_HOST=0.0.0.0:11434 ollama serve

systemd 托管时用 drop-in 持久化：

sudo systemctl edit ollama

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

改完重载并重启：

sudo systemctl daemon-reload && sudo systemctl restart ollama

0.0.0.0 会把端口暴露到局域网，别直接开到公网，需要时前面加防火墙。

第四步：容器内连宿主机

Docker Desktop（macOS / Windows）用专用域名：

http://host.docker.internal:11434

Linux 上走 host 网络，或者手动加一条 host 映射：

docker run --network host your-app
docker run --add-host=host.docker.internal:host-gateway your-app

第五步：改 Spring AI 的 base-url

把地址换成容器能访问到的那个：

spring:
  ai:
    ollama:
      base-url: http://host.docker.internal:11434

改完重启应用，再回来调一次。base-url 是排查的最后一环，先确认底层端口通了，再动它才有意义。

References（参考来源）

• Ollama FAQ — Ollama 官方文档ollama-docs
• Ollama Chat — Spring AI 官方文档spring-docs
• Ollama connection refused 排查（含容器场景）troubleshooting-guide