如果您尝试通过 ollama pull
从企业网络、VPN 或外部代理服务器下载模型,您可能已经遇到过类似
dial tcp: lookup registry.ollama.ai 或
context deadline exceeded 的错误。
Ollama 默认情况下并不总是正确地获取系统的代理设置,而模型的较大体积(从 2 到 70+ GB)加剧了这个问题 —
连接在下载中途断开。本文将讨论如何正确设置环境变量,配置 Docker 和 systemd 中的代理,
并分析最常见的拉取错误及其解决方法。
Ollama 如何与网络和代理工作
Ollama 是一个客户端-服务器应用程序:本地服务器 (ollama serve)
接收来自 CLI 的命令并向模型注册表 registry.ollama.ai 和存储模型层的 CDN 发出网络请求。
命令 ollama pull llama3 实际上执行了一系列 HTTPS 请求,
类似于 Docker pull:首先请求模型的清单,然后顺序或并行下载二进制层(权重的 GGUF 文件)。
一个重要的细节:网络请求是由 服务器进程 Ollama 执行的,而不是 CLI 命令。这意味着,代理设置的环境变量
需要在运行 ollama serve 的地方设置,
而不是在您调用 ollama pull 的终端中。
如果服务作为 systemd 单元或在 Docker 容器中运行,普通 bash 会话中的变量导出不会对其产生影响 —
这是“代理似乎已设置,但拉取仍然无法工作”的最常见原因。
HTTP_PROXY、HTTPS_PROXY、NO_PROXY 环境变量
Ollama 是用 Go 编写的,而 Go 的标准 HTTP 库从经典的环境变量中读取代理设置:
HTTP_PROXY— 普通 HTTP 请求的代理HTTPS_PROXY— HTTPS 请求的代理(这正是下载模型所需的,因为注册表通过 TLS 工作)NO_PROXY— 需要排除在代理之外的主机列表(例如,Ollama 的本地 API 在 127.0.0.1:11434 上)
值的格式:http://user:password@host:port 用于需要身份验证的代理
或 socks5://host:port 用于 SOCKS5。Go 支持这两种格式,
但对于 SOCKS5,确保 Ollama 的二进制文件是以支持该代理的方式构建的 — 在大多数当前版本中都是如此,但在出现错误时,最好先
在 HTTP/HTTPS 代理上进行测试,以排除这一变量。
重要: 请同时使用小写和大写字母指定变量
(http_proxy 和 HTTP_PROXY)。
某些 Linux 发行版仅读取小写,而 Go 应用程序有时期望大写 — 最好同时设置这两种格式,以免猜测。
在 Linux 和 macOS 上的设置
如果您直接从终端启动 Ollama(而不是作为系统服务),只需在启动服务器之前导出变量:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
为了在会话之间保留设置,请将这些行添加到 ~/.bashrc,
~/.zshrc 或 ~/.profile
具体取决于您使用的 shell。编辑后,运行 source ~/.bashrc
并重启 Ollama 进程 — 环境变量仅在进程启动时读取,不支持热重载。
在 macOS 上,如果 Ollama 作为应用程序安装(而不是通过 Homebrew),终端中的环境变量可能无法传递到
通过 GUI 启动的进程。在这种情况下,更可靠的方法是通过 launchctl setenv 设置变量:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# 然后完全重启 Ollama 应用程序(退出托盘,而不仅仅是关闭窗口)
在 Windows 上的设置
在 PowerShell 中,变量通过以下命令为当前会话设置:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
如果 Ollama 作为后台服务运行(系统托盘中的图标),会话变量是不够的 — 服务在您打开 PowerShell 之前
就在系统登录时启动。需要通过
“设置 → 系统 → 关于 → 高级系统设置 → 环境变量” 在用户或系统级别设置变量,然后完全结束
ollama.exe 进程并重启应用程序。
Docker 中的 Ollama 代理
如果 Ollama 在容器中运行(这是服务器部署的常见情况),主机的环境变量不会自动传递到容器内部 —
需要通过 -e 或 environment 部分
在 docker-compose 中显式传递:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
在 docker-compose.yml 中类似:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
更改变量后,需要重新创建容器(docker compose up -d --force-recreate),
简单的重启是不够的,因为环境变量在创建容器时被固定。
Ollama 的 systemd 服务代理
在 Linux 服务器上,Ollama 通常通过官方安装脚本作为 systemd 服务安装。在这种情况下,环境变量
通过覆盖文件设置,而不是通过终端中的 export:
sudo systemctl edit ollama.service
在打开的编辑器中添加:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
然后应用更改:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
最后一条命令将显示进程实际看到的变量 — 这是确保配置已应用的方便方法, 在再次尝试执行拉取之前。
拉取错误分析及其解决
我们将分析通过代理下载模型时最常见的错误消息及其解决方法。
dial tcp: lookup registry.ollama.ai: no such host
DNS 解析在代理后不起作用 — 通常这意味着请求试图直接发送,绕过代理服务器,或者机器根本无法访问
DNS(封闭的企业网络)。解决方案:确保 HTTPS_PROXY
确实被进程获取(参见上面的 systemctl show 命令),
并且代理服务器本身能够解析外部域(SOCKS5 代理在其一侧解析 DNS,HTTP 代理也是如此,但某些本地代理不这样做)。
proxyconnect tcp: dial tcp: connection refused
Ollama 尝试连接到代理,但被拒绝。检查端口和主机是否有拼写错误,确保代理服务器确实在外部监听 指定的端口(而不仅仅是在 localhost),并且防火墙没有阻止到代理端口的出站连接。
407 Proxy Authentication Required
代理要求提供用户名和密码,但未提供或提供不正确。确保环境变量中的用户名和密码嵌入在 URL 中
格式为 http://user:password@host:port,并且密码中的特殊字符
(例如 @ 或 :)
通过 URL 编码进行编码(%40, %3A)。
x509: certificate signed by unknown authority
这是企业代理带有 TLS 检查(MITM)的迹象,它用自己的根证书替换 SSL 证书。Ollama 的 Go 客户端不信任
该证书。解决方案是将企业根证书添加到系统受信任的证书颁发机构存储中
(在 Linux 上通常通过 update-ca-certificates 在将 .crt 文件复制到
/usr/local/share/ca-certificates/ 后进行)。不建议全局禁用证书检查 — 这会导致流量被拦截。
context deadline exceeded / i/o timeout 在下载层时
连接在下载大型模型层(通常是 4-40 GB 的文件)中途断开。此类错误几乎总是表明代理服务器的不稳定性 或低带宽,而不是 Ollama 本身。免费的或过载的公共代理会中断长时间的 TCP 会话, 特别是当下载超过几分钟时。在这种情况下,切换到更稳定的通道是有帮助的 — 例如,数据中心代理,它们提供高速 和稳定的连接,以便下载大型文件而不出现中断。
为 Ollama 选择哪种代理类型
选择代理类型取决于您需要 Ollama 代理的原因。如果任务是简单地绕过企业防火墙的限制, 几乎任何稳定的 HTTP(S) 代理都可以使用。但如果目标是绕过模型注册表的地理限制 或隐藏请求来自数据中心(某些 CDN 限制已知云服务提供商的 IP 范围的速度), 代理类型的选择就变得至关重要。
| 代理类型 | 速度 | 何时在 Ollama 中使用 |
|---|---|---|
| 数据中心 | 高 | 下载大型模型层(4-40+ GB)而不出现中断,从不同数据中心位置进行测试 |
| 住宅 | 中 | 绕过注册表的地理限制,当数据中心的 IP 受到区域速率限制时 |
| 移动 | 可变 | 在完全阻止云服务提供商的 IP 范围时的极端情况,由于速度波动,对大型下载的效率较低 |
对于大多数与 Ollama 相关的场景 — 当需要稳定地下载几十 GB 的模型时 — 最佳选择仍然是 数据中心代理:它们提供最大带宽 和最小延迟,这在下载大型二进制层时至关重要。只有在数据中心的地址确实受到模型注册表的限制时, 才应考虑连接住宅 IP。
连接诊断
在花时间调试 Ollama 之前,请直接通过 curl 检查代理 — 这将排除应用程序问题 和代理服务器本身问题之间的混淆:
# 通过代理检查注册表的可用性
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# 测量通过代理的下载速度
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# 启动 ollama serve 并记录详细日志
OLLAMA_DEBUG=1 ollama serve
如果 curl 成功获得响应,而 ollama pull 仍然失败 —
问题几乎肯定在于环境变量没有传递到服务器进程(服务以不同用户、不同 shell 或作为没有覆盖的 systemd 单元运行)。请返回 systemd 部分并检查 systemctl show ollama --property Environment 的输出。
如果 curl 也在下载大型文件时中断或显示不稳定的速度 — 原因在于代理服务器, 应考虑更换为更稳定的代理提供商,以便传输大量数据。
结论
设置 Ollama 通过代理的关键在于三个要点:环境变量必须为进程设置
ollama serve,而不是您调用拉取的终端;
代理的 URL 格式必须包含正确编码的用户名和密码;在证书错误的情况下,需要将企业根证书添加到受信任的存储中,而不是禁用 TLS 检查。大多数拉取错误并不是 Ollama 本身的缺陷,
而是网络设置未应用于所需进程或代理服务器无法承受长时间传输大型文件的结果。
如果您的主要任务是稳定快速地下载几十 GB 的模型而不出现连接中断,建议尝试 数据中心代理 — 它们提供高带宽, 适合下载大型模型层。如果使用代理的原因是绕过模型注册表的地理限制, 请关注 住宅代理,它们较少受到 应用于云服务提供商 IP 范围的区域限制。