Dify本地部署Ollama模型时连接失败如何解决？

Question

Dify本地部署Ollama模型时连接失败，最常见的原因是Dify服务无法访问Ollama API端点。典型表现为启动后日志报错“Failed to connect to Ollama: Connection refused”或“HTTPConnectionPool(host='localhost', port=11434): Max retries exceeded”。根本原因通常有三：① Ollama服务未启动（`ollama serve`未运行或后台进程异常退出）；② Dify配置中`OLLAMA_BASE_URL`指向错误（如误配为`http://127.0.0.1:11434`但Ollama实际监听`0.0.0.0:11434`，或Docker网络隔离导致`localhost`解析失败）；③ 容器间网络不通（Dify与Ollama分属不同Docker网络，或使用`host.docker.internal`在Linux上默认不可用）。解决需按序排查：确认`ollama ps`有运行实例 → 检查`OLLAMA_BASE_URL`是否适配部署拓扑（容器内应填宿主机IP或正确网络别名）→ Docker环境建议共用`--network host`或自定义bridge并显式链接。

Answer 1

```html

一、现象层：错误日志的语义解码

当Dify启动时抛出 "Failed to connect to Ollama: Connection refused" 或 "HTTPConnectionPool(host='localhost', port=11434): Max retries exceeded"，这并非模型加载失败，而是HTTP客户端在TCP连接阶段即被拒绝——本质是网络可达性中断，而非API协议或鉴权问题。该错误位于OSI模型第4层（传输层）与第7层（应用层）交界处，需优先排除基础设施连通性。

二、诊断层：三层根因树状分析

• ① 进程层失效：Ollama守护进程未运行（systemctl status ollama 返回 inactive），或 ollama serve 被SIGKILL强制终止后未自动恢复；
• ② 地址解析层错配：Dify容器内配置 OLLAMA_BASE_URL=http://localhost:11434，但Linux容器中 localhost 指向容器自身环回接口（127.0.0.1），而Ollama实际监听宿主机 0.0.0.0:11434；
• ③ 网络拓扑层隔离：Dify与Ollama分别运行于 bridge 和 host 网络模式，或跨自定义Docker网络未启用 --link/network-alias。

三、验证层：可执行的交叉验证矩阵

检查项	宿主机命令	容器内命令	预期输出
Ollama进程状态	ps aux | grep ollama	curl -s http://host.docker.internal:11434/api/tags | jq '.models[0].name'	非空JSON或进程PID
TCP端口监听	ss -tlnp | grep :11434	nc -zv host.docker.internal 11434	state = ESTABLISHED

四、解决层：部署拓扑适配方案

根据实际环境选择以下任一策略：

1. 单机开发模式：在宿主机启动Ollama（systemctl enable --now ollama），Dify配置 OLLAMA_BASE_URL=http://host.docker.internal:11434（macOS/Windows默认可用；Linux需手动添加：echo '172.17.0.1 host.docker.internal' >> /etc/hosts）；
2. Docker Compose协同模式：定义统一bridge网络，显式声明服务依赖与别名：

services:
  ollama:
    image: ollama/ollama
    ports: ["11434:11434"]
    networks: [dify-net]
  dify:
    image: langgenius/dify:latest
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    networks: [dify-net]
    depends_on: [ollama]

五、进阶层：生产级健壮性加固

graph LR
  A[Dify启动] --> B{OLLAMA_BASE_URL是否含scheme?}
  B -->|否| C[自动补全http://]
  B -->|是| D[发起HTTP HEAD探测]
  D --> E{响应码200?}
  E -->|否| F[触发重试策略：指数退避+3次]
  E -->|是| G[加载模型元数据]
  F --> H[写入告警事件至Prometheus Alertmanager]

六、避坑层：高频反模式清单

• ❌ 在Docker容器中硬编码 localhost:11434 —— 容器网络命名空间隔离导致解析失败；
• ❌ 使用 docker run --network host 启动Dify却未对Ollama做同样操作 —— 网络模式不一致引发端口冲突；
• ❌ 忽略SELinux/AppArmor策略 —— 某些发行版（如RHEL/CentOS）默认阻止容器访问宿主机11434端口；
• ✅ 推荐做法：通过 docker network inspect 获取网关IP，配置为 OLLAMA_BASE_URL=http://172.18.0.1:11434。

七、监控层：可观测性埋点建议

在Dify源码 api/core/model_runtime/llm/ollama/ollama.py 的 _invoke 方法中注入以下指标：

• ollama_connection_total{status="success|failed",host="ollama"}
• ollama_request_duration_seconds_bucket{le="0.1","0.5","1.0"}
• 结合Grafana面板实时追踪连接成功率与P95延迟，阈值设为连续5分钟成功率<95%即告警。

```