常见报错排查：端口、显存和超时

报错不可怕，怕的是瞎试

每个把 Ollama 从教程搬到生产的人，都会经历一段与报错朝夕相处的日子。教程里一气呵成的流程，自家机器上总能卡在奇奇怪怪的地方：服务起不来、起来了连不上、连上了显存不够、显存够了又超时。这不是你运气差，是本地部署的正常体验，这些坑里面藏着对系统原理最实在的理解机会。

排查问题最大的忌讳是瞎试。报一个错，立刻去搜索引擎搜一段命令敲进去，不行再换一条。一下午敲了几十条命令，不仅没修好，连最初的长什么样都记不清了。正确的姿势是三步走：先读完整错误信息，再定位错误发生在链路的哪一段，最后才动手改。错误信息里往往直接写着答案，多数人只是没看完整。

这一章把本地知识库最常踩的三类坑掰开讲：端口连不通、显存不够用、请求超时。每类给出定位步骤和修复命令，大多数问题照着走一遍就能解决。建议收藏，出事时当字典查。

端口：连不上 Ollama 的第一道坎

Ollama 默认监听 11434 端口。服务装好却访问不了，排查顺序是这样。

第一步确认服务到底起没起。Linux 用 systemctl status ollama，Windows 看系统托盘图标或者任务管理器里有没有 ollama 进程。没跑起来一切白搭，先启动服务再看其他问题。进程在跑了，第二步确认端口是不是真的在监听：

netstat -ano | findstr :11434

Windows 上这条命令会列出监听 11434 的进程 PID。Linux 下换成 lsof -i :11434 或 ss -tlnp | grep 11434，注意 ss 命令能看到对应进程名，找起来更直观。正常情况能看到一个 LISTENING 状态的条目。如果没有，八成是 Ollama 没正常启动，去翻它的日志文件看具体原因。

第三步最容易踩坑的高频问题：端口被别的程序占了。同一个端口两个程序都想占，Ollama 可能悄悄启动失败而不报错。解决方式二选一：把占用的程序换端口，或者用环境变量把 Ollama 挪到别的端口，然后注意客户端请求地址要同步改。

环境变量改端口和监听地址是最常用的工程动作，一并在下面列出：

set OLLAMA_HOST=0.0.0.0:11435
ollama serve

注意监听地址这件事比端口更坑。Ollama 默认只绑 127.0.0.1，本机访问毫无问题，但局域网其他机器、包括同一台电脑上的 Docker 容器都连不上。改成 0.0.0.0 才允许所有网络接口访问，这是 Docker 部署 Dify、LangChain 等容器应用的前提条件。

Docker 场景还有一层。容器里的 localhost 指容器自己，配置文件里写 localhost:11434 必然连接失败。Linux 上宿主机地址可以用 172.17.0.1（默认 docker0 网桥），Windows 和 Mac 的 Docker Desktop 提供 host.docker.internal 这个域名直接解析到宿主机。跨容器通信最稳妥的办法是让所有容器加入同一个自定义 Docker 网络，用容器名互相访问。

别忘了防火墙。云服务器安全组里放行端口是常规操作，本地 Windows 防火墙有时也会拦下首次启动的服务。排查时先临时关掉防火墙验证是不是它的问题，确认后再正式加规则，避免一直裸奔在无防火墙状态。

Windows 上启动失败还有一类隐形问题：杀毒软件的端口拦截。企业统一部署的终端安全软件经常会拦掉它不认识的服务监听行为，表现是服务起来一阵子就被杀掉，日志里却看不出明显异常。遇到这种情况先加白名单再观察，别和代码死磕，方向错了再久也是白费。

显存：OOM 的各种形态

模型加载失败或者跑到一半崩掉，显存的嫌疑最大。它有三种表现方式，分辨清楚了修复方向完全不同。

第一种是直接加载失败，错误信息里写着 OOM 或者显存不足。原因是模型权重的体积超过显存总量。先用 nvidia-smi 看显卡总显存和已占用，再对比 ollama list 里模型的大小。八十亿参数 Q4 量化大约五 GB，十二 GB 的卡装它富余，装七十亿参数的 FP16 版本（约十四 GB）就吃紧。修复方式就一条：换更小的量化版本。

nvidia-smi 的输出值得多看一眼。除了显存数字，它还列出当前所有占用显存的进程。发现一个陌生的 python 进程占着两三个 GB，八成是之前调试没关干净的脚本，kill 掉空间立刻就回来。Windows 任务管理器里勾上 GPU 列也能看，信息一样只是没那么专业。排查资源类问题的诀窍是先回收再扩容，很多 OOM 根本不需要花钱换卡。

第二种隐蔽得多，模型加载成功，平时用得好好的，某次长对话中途报错。这就是上一章 ol-0402 讲的 KV 缓存膨胀：上下文越长缓存越大，累积到一定程度把显存顶爆。修复方式是把 num_ctx 调小，或者在应用层控制对话历史的长度，别让一个会话无限滚下去。

第三种是多个模型抢资源。Ollama 默认会常驻最近用过的模型，显卡上同时挂着两三个，剩下的空间不够新请求的。用 ollama list 能看到，然后用 ollama rm 删掉不需要的，或者在配置里设置 OLLAMA_KEEP_ALIVE 设定自动卸载时间，让闲置模型自己退出。

纯 CPU 环境没有显存问题，但有内存问题，逻辑完全一样。用任务管理器看内存占用，八 GB 内存跑七B 量化模型勉强，十六 GB 才宽裕。顺带提一个 Windows 特有的小问题：某些集显设备会和系统共享内存，任务管理器里看到的占用可能比预期高，属于正常现象，不是内存泄漏。

超时：请求卡死在哪里

链路长了，超时的原因就层出不穷。关键是搞清楚卡在哪一段，而不是盲目把超时时间调长。

先做最简单的拆分：只有长上下文请求超时、短问题一切正常，那是模型在长时间提示上的计算慢，参考 ol-0402 的优化手段，别在这里瞎改超时阈值。所有请求都慢、偶发抽风，往系统资源方向查。有规律地卡住，看时间点和任务调度有没有关系，比如每天固定时点磁盘备份把 IO 占满。

JSON 格式错误导致的超时是另一个高频坑。调用方传的 JSON 少了个引号，服务端解析报错，客户端收到 500 而不是正常回答，看起来像卡死。验证方式是先用最简单的 curl 命令跑一遍：

curl http://localhost:11434/api/generate -d "{\"model\":\"llama3.1\",\"prompt\":\"你好\",\"stream\":false}"

这条能通就是代码端的问题，不通才是服务端配置。写代码调试时建议先 curl 再上应用，少走很多弯路。

日志是超时排查的主角。打开服务日志后重放一次超时请求，看时间戳能确认几个事实：请求是否真的到达 Ollama，到达后排队了多久，模型实际生成用了多长时间。曾经有个案例应用层报超时，日志里却是模型在六秒内正常完成了生成，一查是反向代理把响应憋住了没往回送。没有日志的排查是盲人摸象，先让日志开口再谈别的。

还有一种超时发生在网络层面而不是模型层面。客户端走过的每一跳代理都可能施加自己的超时限制，公司内网的安全代理尤其爱干这事，默认值常常只有三十秒。定位方法是在服务端本地直接测一遍排除中间环节，逐跳逼近客户端，哪一跳断的一清二楚。

并发场景的超时最值得警惕。用户量一上来，请求在 Ollama 内部排队，队列等的时间算进总超时里就各种超。治本之道是限流加扩容：在网关层加并发限制，同一时刻放行不超过压测过的阈值；同时跑多个 Ollama 实例做负载均衡，用不同端口分担流量。一个实例不够的时候先想想是不是哪里配置不对，盲目堆实例前先确保单实例本身已经是健康的。

扩容前先做个体检：同一个实例的日志里如果大量出现排队等待提示，说明是处理不过来，加实例有用；如果日志显示 CPU 或显卡根本没满载，请求却慢，瓶颈可能在外部存储或网络，加实例等于治标不治本。这部分监控的实施可以参考 ol-0404 里的 API 与指标接口部分，拿到数据再扩容，心里才有底。

企业里常见还有代理服务器的超时。Nginx 等反向代理默认六十秒超时，模型回答超过这个时长会被网关强行掐断，用户看到 504。修复方式是按实际耗时把 proxy_read_timeout 调大，同时压榨生成速度让单次回答本身快一点。链路上每个环节都有自己的超时设置，出问题时从外向内逐个核对。

排查问题的通用套路

三个症状之外，送你一套对所有报错通用的排查框架。

第一步，复现并隔离。找到一条稳定复现的最小操作路径，是某个特定问题触发还是所有请求都出问题。能稳定复现的问题等于解决了一半。第二步，看日志。Ollama 的日志 Windows 在 %LOCALAPPDATA%\Ollama\server.log，Linux 通常是 journalctl -u ollama。报错堆栈往往直接指出问题文件和原因。第三步，二分排除。怀疑切片代码就只跑检索看看，怀疑模型就换一个模型试试，逐段验证直到锁定故障组件。

最后一句话：改配置前先备份，出问题能回滚。多少英雄好汉改了环境变量重启就忘改了哪里，只能对着空荡荡的服务器发呆。

走一个完整的实例把套路串起来。某天下午用户反馈知识库问答偶发转圈，几分钟后又恢复。第一步隔离：发现只有长对话会触发，新会话完全正常。第二步翻日志，看到超时时段有 KV cache 超限的警告。第三步验证假设：拿来两位用户的历史会话记录，复现成功。第四步动手：num_ctx 从一万六降到八千，同时清理了一批三个月前的常驻模型。监控三天，问题消失。整个流程没动一行业务代码，核心就是把症状、证据、假设、验证串成线。

常见问题

Docker 里 Ollama 连不上，错误是连接被拒绝

经典中的经典。按顺序检查：宿主机上 Ollama 是否在跑；是否设置 OLLAMA_HOST=0.0.0.0 让它接受非本机连接；docker run 时有没有用 host 网络模式或正确映射端口；容器内访问地址写的是 host.docker.internal 还是 localhost。四个都查完，九成的连接被拒绝都能定位。Windows 下最省心的组合是 Docker Desktop 加 host.docker.internal 直连。

同样的模型之前能跑，今天突然 OOM

先看是不是显存被别的程序占了，nvidia-smi 一目了然。排除了占用，再看是不是最近改过 num_ctx 或者历史对话变长了，KV 缓存随对话累积是隐形大户。最后一招临时验证：重启 Ollama 服务后再试一次，能用就是运行时状态漂移，常驻模型冲突最常见。

超时到底设多少合适

没有标准答案，只有测量办法。压测你自己的典型请求，取 P95 耗时乘以二再取整，就是起步阈值。流式输出场景首字延迟小，可以把应用层超时设短一点，让用户少干等。还要给整条链路的每个组件单独设阈值，网关的、应用的、模型的三层各管各的，别一个全局大数字兜全部，那样出问题时无法定位是哪一环慢。

远程访问 Ollama 一定要改成 0.0.0.0 吗，有没有安全风险

有风险，但改还是要改，区别在于你怎么收口。0.0.0.0 让同网络的所有机器都能调用你的模型，图方便的同时也敞开了门。规范做法是改完监听地址后在防火墙里只放行特定 IP 段，或者套一层 Nginx 加上认证，对外只暴露代理端口，内部地址藏好。还有一招更省事：Ollama 本身不带鉴权，你可以在应用层校验请求头里带个自定义密钥，不符的直接挡回去，别指望服务自带金钟罩。千万别把 11434 直接映射到公网，让互联网上所有人免费用你的显卡算力，这种事故赛季每天都有。

上面所有命令我在 Windows 上找不到 netstat 和 lsof

netstat 是 Windows 自带的，在 PowerShell 或 CMD 里直接敲就行，注意参数是 -ano 而不是 Linux 的习惯。lsof 是 Linux 专属，Windows 上用 netstat -ano | findstr 加任务管理器对照 PID 就是等价操作。如果你习惯 Linux 工具链，装上 Git Bash 或者 WSL 体验会好很多，书里大部分命令都能直接跑。

下载模型一半失败，再 pull 报错怎么办

先分清是网络慢还是真断了。Ollama 的拉取支持断点续传，直接重跑 ollama pull 一般会接着上次进度走，不用从头再来。如果反复卡在同一个百分比，多半是代理或镜像问题，检查 HTTP_PROXY 和 HTTPS_PROXY 是否设置正确，公司网络下尤其常见，把代理变量echo 出来看一眼比猜来猜去快得多。磁盘空间不足也会报一串看不懂的错，pull 之前留够模型体积一点五倍以上的余量，量化版本的临时文件也会占地方。拉完用 ollama list 确认大小和预期一致，缺斤少两的模型跑起来会各种灵异报错。