Ollama服务未启动或端口被占用导致连接失败

Question

常见问题：启动 Ollama 客户端（如 `ollama run llama3`）时提示“connection refused”或“failed to connect to ollama server”，日志显示 `dial tcp 127.0.0.1:11434: connect: connection refused`。根本原因通常是：① Ollama 后台服务未运行（Linux/macOS 未执行 `ollama serve`，Windows 服务未启动或系统托盘图标缺失）；② 默认端口 11434 被其他进程（如另一实例、Docker 容器、Web 服务器）占用，导致服务无法绑定。可通过 `curl http://localhost:11434/health` 检测服务状态，用 `lsof -i :11434`（macOS/Linux）或 `netstat -ano | findstr :11434`（Windows）排查端口占用，并结合 `ps aux | grep ollama` 或任务管理器确认进程是否存在。此问题高频发生于多环境共存、开发调试重启不彻底或容器化部署冲突场景。

Answer 1

```html

一、现象层：客户端连接失败的典型报错表现

执行 ollama run llama3 时，终端持续输出：
failed to connect to ollama server: Get "http://127.0.0.1:11434/api/tags": dial tcp 127.0.0.1:11434: connect: connection refused。
该错误并非模型加载失败，而是底层 HTTP 客户端根本无法建立 TCP 连接——说明服务端监听进程缺失或端口不可达。此为最表层可观测信号，是所有诊断流程的起点。

二、进程层：Ollama 后台服务是否真实运行？

• Linux/macOS：需显式启动守护进程：ollama serve（前台阻塞）或 systemctl --user start ollama（后台服务）；若仅安装未启动，则无监听进程。
• Windows：依赖 Windows Service（Ollama Service）或系统托盘进程 ollama.exe；任务管理器中若无对应进程，或服务状态为“已停止”，即为根因。
• 验证命令：ps aux | grep -v grep | grep ollama（Linux/macOS）、Get-Service Ollama | Select Status,Name（PowerShell）。

三、网络层：端口 11434 是否被独占或冲突？

Ollama 默认绑定 127.0.0.1:11434，但该端口极易被抢占：

占用场景	典型进程	检测命令
Docker 容器映射	docker run -p 11434:11434 ...	docker ps --filter "port=11434" -q
本地开发服务器	Next.js dev server、FastAPI 调试实例	lsof -i :11434（macOS/Linux）
遗留 Ollama 实例	崩溃后未清理的 zombie process	netstat -ano | findstr :11434（Windows）

四、协议层：服务健康接口是否可访问？

即使进程存在，也可能因配置错误或初始化失败导致 HTTP 监听未就绪。应主动探测：

curl -v http://localhost:11434/health
# 正常响应：{"status":"ok","version":"0.1.42","uptime":123}
# 异常响应：curl: (7) Failed to connect to localhost port 11434: Connection refused

五、环境层：多上下文共存引发的隐性冲突

在 CI/CD 流水线、WSL2 与宿主 Windows 共享端口、Docker Desktop + Ollama Desktop 同时安装等场景下，会出现：

• WSL2 中 ollama serve 绑定 127.0.0.1，但 Windows 主机无法直连（需配置 networkingMode: host 或使用 WSL2 IP）；
• Docker Desktop 内置的 ollama/ollama 镜像与本地二进制版共用 11434，形成端口竞争；
• IDE（如 VS Code Remote-Containers）自动拉起 Ollama 容器，却未暴露端口至宿主机。

六、配置层：自定义绑定地址与端口的覆盖策略

可通过环境变量强制重定向：

export OLLAMA_HOST=127.0.0.1:8080
export OLLAMA_ORIGINS="http://localhost:3000,http://192.168.1.100:8080"
ollama serve
# 客户端自动适配新地址：ollama run llama3 → 连接 127.0.0.1:8080

七、诊断流程图：结构化排障路径

graph TD
  A[执行 ollama run llama3 报 connection refused] --> B{curl http://localhost:11434/health?}
  B -- 200 OK --> C[检查模型缓存与权限]
  B -- Connection refused --> D{ollama 进程是否存在？}
  D -- 是 --> E[检查端口占用]
  D -- 否 --> F[启动服务：ollama serve 或重启 Windows Service]
  E -- 端口被占 --> G[kill 占用进程 或 修改 OLLAMA_HOST]
  E -- 端口空闲 --> H[检查防火墙/SELinux 是否拦截 loopback]

八、生产级加固建议（面向5年+工程师）

• 在 systemd 用户服务中添加 Restart=always 和 RestartSec=5，避免 SIGTERM 后静默退出；
• 使用 journalctl --user-unit=ollama -f 实时追踪服务日志，而非依赖前台输出；
• 容器化部署时，采用 host.docker.internal:11434 替代 localhost:11434，规避 Docker 网络命名空间隔离；
• 编写 Bash/Zsh hook，在 cd 进入 LLM 项目目录时自动校验 ollama list 可达性。

九、高级调试技巧：TCP 层抓包验证

当上述方法均无效时，启用底层网络观测：

# Linux 示例：捕获 loopback 上 11434 端口的 SYN 尝试
sudo tcpdump -i lo 'tcp port 11434 and (tcp-syn or tcp-ack)' -nn -vv

# 若无 SYN 包发出 → 客户端未尝试连接（环境变量/配置错误）
# 若有 SYN 但无 SYN-ACK → 服务未监听或被 DROP（iptables/nftables 规则）

十、跨平台统一检测脚本（附带退出码语义）

以下 Bash 脚本可嵌入 CI 或运维巡检：

#!/bin/bash
set -e
PORT=11434
if ! command -v ollama &> /dev/null; then echo "ERR: ollama not in PATH"; exit 1; fi
if ! pgrep -f "ollama serve" &> /dev/null; then echo "ERR: ollama process not found"; exit 2; fi
if lsof -i :$PORT &> /dev/null; then
  if curl -sf http://localhost:$PORT/health | jq -e '.status=="ok"' &> /dev/null; then
    echo "OK: Ollama healthy on port $PORT"
    exit 0
  else
    echo "ERR: port $PORT occupied but service unhealthy"
    exit 3
  fi
else
  echo "ERR: port $PORT not bound"
  exit 4
fi

```