本地起 Ollama 後 curl 11434 報 Connection refused

Connection refused 跟 model not found 是兩碼事。前者連 11434 端口都沒建立；後者連上了但本地沒這個模型。先 curl 一次 /api/version，能把問題二分到「服務沒起」或「網絡綁定/容器邊界」一側。

Issue & Env（案發現場與環境）

業務場景：本地裝好 Ollama 準備跑 DeepSeek-R1，命令行 curl http://localhost:11434 直接報連接被拒；有時是同機能通、其它機器或容器裡就連不上。
環境：Ollama v0.34.x（與 v0.30+ 行為一致），本地預設端口 11434；macOS 桌面 app、Linux systemd 託管、Docker 容器三種部署都有各自的踩坑點。

StackTrace（堆疊日誌）

最常見的兩種客戶端報錯，原樣保留：

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

Ollama CLI 自己拋的：

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

注意 Connection refused 是 TCP 層立刻被內核拒掉，請求根本沒到 Ollama 進程；返回時間幾乎是 0。如果連接掛了一會兒才掛，多半是 Connection timed out，不是 refused，二者排錯方向不同。

Reproduce（復現程式碼）

乾淨裝一遍後最容易復現的場景：

# 1) 安装脚本跑完，没起服务就 curl
curl http://localhost:11434/api/version
# 期望返回 {"version":"0.34.x"}；实际：Connection refused

# 2) Ollama 在跑，但客户端跑在 Docker 容器里
docker run --rm alpine sh -c "apk add curl && curl http://localhost:11434/api/version"
# 期望：Connection refused（容器里的 localhost 指容器自己）

# 3) Linux 上 systemd 单元存在但没启动
sudo systemctl status ollama
# Active: inactive (dead) → curl 同样 Connection refused

Root Cause（根因分析）

Connection refused 在 Ollama 上收斂到三類原因。

一、服務進程沒起來

Linux 裝好後是 systemd 單元：sudo systemctl status ollama 看 Active 行是不是 active (running)。macOS 上 Ollama 是常駐 app，選單欄圖標消失 = 服務停止。Windows 上從托盤啟動，關掉托盤就是關掉服務。裝完沒啟動就直接 curl，必然 refused。

二、OLLAMA_HOST 預設只綁 127.0.0.1

這是官方 FAQ 直接給的策略：Ollama binds 127.0.0.1 port 11434 by default. Change the bind address with the OLLAMA_HOST environment variable. 也就是說同機能通，換個接口（另一個網卡、容器、遠程）就被拒。這是設計不是 bug。

注意 OLLAMA_HOST 是雙重身份：服務端拿它決定 bind 地址，客戶端拿它決定 dial 地址。同一臺機器的 systemd 單元把它配成 0.0.0.0:11434 後，ollama CLI 在本機走 127.0.0.1 還是通的；但如果把單元改成某個具體 LAN IP，本機 127.0.0.1 也會被拒。

三、容器裡的 localhost 指容器自己

跑在 Docker 容器裡的應用訪問 localhost:11434，命中的是容器自己的 loopback，不是宿主機的 Ollama。Docker Desktop（macOS/Windows）提供 host.docker.internal 這個特殊域名；Linux Docker 20.10+ 也支持，否則要 --network host 或 --add-host=host.docker.internal:host-gateway。

另外 macOS 桌面 app 不繼承 shell 的環境變數，把 OLLAMA_HOST 寫在 ~/.zshrc 裡對運行中的 app 沒用——官方 FAQ 給的是 launchctl setenv OLLAMA_HOST "0.0.0.0:11434"，然後完全退出並重啟 app。在 app 沒退乾淨的情況下改環境變數，聽起來改了，實際進程沒讀到。

四、systemd 單元的覆蓋關係

Linux 上 Ollama 的主單元文件是 vendor 自帶的（/etc/systemd/system/ollama.service 或 /lib/systemd/system/ollama.service），直接編輯主文件會在下次 ollama 包升級時被覆蓋。systemctl edit ollama 走的是 ollama.service.d/override.conf drop-in 機制，不會被升級覆蓋。每次改完都要 daemon-reload + restart，缺一不可——單 restart 不重讀新環境變數的情況常見。

驗證生效：

systemctl show ollama -p Environment
# Environment=OLLAMA_HOST=0.0.0.0:11434 PATH=/usr/local/sbin:...

如果輸出裡沒有 OLLAMA_HOST，說明 drop-in 沒生效，回頭檢查 [Service] 拼寫和重啟步驟。

The Fix（解決方案）

第一步：二分問題

curl http://127.0.0.1:11434/api/version

返回 {"version":"0.34.4"}：服務活，問題在網絡層或容器邊界。跳第三步。
Connection refused：服務沒起。走第二步。

第二步：起服務

macOS：從 Applications 裡啟動 Ollama，選單欄出現圖標即可。

Linux：讓 systemd 接管。

sudo systemctl status ollama
sudo systemctl start ollama
sudo systemctl enable ollama   # 开机自启
journalctl -u ollama -n 100 --no-pager   # 起不来就翻日志

臨時調試可以前臺跑，把日誌看在屏幕上：

ollama serve

第三步：需要外部訪問時改 OLLAMA_HOST

systemd 走 drop-in，不要直接改單元文件：

sudo systemctl edit ollama

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

sudo systemctl daemon-reload
sudo systemctl restart ollama
ss -tlnp | grep 11434   # 应该看到 0.0.0.0:11434

0.0.0.0 等於把 11434 暴露到所有網絡接口。Ollama 自己不帶鑑權，咖啡店 Wi-Fi 上這麼做就等於把模型列表和推理能力送給同網段的人。要麼綁具體 LAN IP，要麼前面加 nginx 代理 + 防火牆。

第四步：容器內連宿主機

Docker Desktop：

services:
  app:
    environment:
      OLLAMA_BASE_URL: http://host.docker.internal:11434

Linux Docker：

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

容器裡跑 Ollama 時則反過來——除了 -p 11434:11434，還得在容器內把 OLLAMA_HOST=0.0.0.0，否則容器裡的 Ollama 還是綁 127.0.0.1，對外不可達。

docker run -d --name ollama -p 11434:11434 \
  -e OLLAMA_HOST=0.0.0.0 \
  -v ollama:/root/.ollama \
  ollama/ollama

改完後再 curl 一次，確認是 Ollama is running 而不是 refused。

References（參考來源）

Ollama FAQ — Ollama 官方文檔ollama-docs
Ollama Connection Refused on Port 11434: 8 Causestroubleshooting-guide
Fix common Ollama errors: 500, timeouts and stalled pullstroubleshooting-guide