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