尧图网页设计 
简介这份资源面向需要在 Linux 或 macOS 环境下部署 Ollama 的开发者与运维人员提供一套轻量化的安装脚本与说明文档帮助快速完成环境准备、依赖检查与安装验证。压缩包共 3 个文件约 13KB包含 1 个 sh 安装脚本、1 个 php 下载入口和 1 个 txt 说明文档脚本负责批量执行安装与配置命令php 文件用于获取安装包txt 则记录安装前准备、步骤说明及常见问题处理思路。已有 437 人学习下载适合希望减少手动操作、按脚本流程完成部署的读者参考。通过阅读说明并执行脚本读者可了解类 Unix 系统下的自动化安装流程、权限与依赖处理方式以及安装后服务启动与验证的基本方法也可根据自身环境对脚本进行适当调整。1. 从一条ollama serve报错说起这套本地大模型运行环境到底值不值得装很多人第一次接触本地大模型是在一台已经装了 Python、Git、Node.js 的开发机上敲下ollama run qwen2.5结果卡在Error: connect: connection refused或者下载进度条走到 3% 就再也不动。这不是模型的问题而是 ollama 这套「本地模型运行时」的安装与配置没打通。ollama 的本质是一个把模型权重、推理引擎、HTTP 服务打包在一起的命令行工具装好之后你就能用一条命令拉起一个兼容 OpenAI 接口的本地服务供 FastAPI、CherryStudio、Dify、LM Studio 这类上层工具调用。它适合三类人想在内网或断网环境跑模型的开发者、需要给 IDE 配置本地补全的工程师、以及想用 Docker 或 WSL 做隔离部署的运维。这篇笔记按「装在哪 → 怎么装 → 怎么验证 → 坑在哪」的顺序拆一遍重点放在离线安装包、国内镜像源、模型存储路径迁移这几个真正会卡住人的环节。2. 安装前的选型与准备装在哪、用什么装、网络怎么绕2.1 三种安装方式的适用边界ollama 官方提供 Linux 一键脚本、Windows/macOS 安装包、以及 Docker 镜像三种分发形式。选哪种不是看哪个新而是看你的运行环境和后续维护成本。Linux 一键脚本适合干净的服务器或 WSL 环境它会自动创建ollama系统用户、注册 systemd 服务、把二进制放到/usr/local/bin。缺点是脚本默认从官方源拉取国内网络下大概率超时。Windows 安装包.exe适合个人开发机装完会在托盘常驻模型默认落在C:\Users\用户名\.ollama\models。Docker 方式适合需要版本隔离或批量部署的场景镜像里已经包含运行时但 GPU 直通需要额外配置--gpus参数。方式适用环境模型默认路径是否自带服务Linux 脚本服务器 / WSL/usr/share/ollama/.ollama/models是systemd 管理Windows 安装包个人开发机C:\Users\用户\.ollama\models是托盘进程Docker 镜像隔离部署 / 批量容器内/root/.ollama/models是容器主进程选型时先确认一件事你的模型文件打算放哪块盘。ollama 拉一个 7B 模型动辄 4~5GB14B 接近 9GB如果系统盘只有 50GB装完两三个模型就红了。所以安装前最好先把存储路径规划好后面第 4 章会讲怎么迁移。2.2 网络准备镜像源与离线包两条路国内直连官方源下载模型基本不可用常见做法是两条路并行。第一条是配置镜像源环境变量让 ollama 从国内可访问的地址拉取。第二条是提前下载离线安装包和模型文件适合完全断网的内网机器。镜像源配置的核心是OLLAMA_HOST和拉取地址两个变量。不同版本的 ollama 对镜像的支持方式略有差异稳妥做法是在启动服务前 export 环境变量# 设置 ollama 服务监听地址默认 127.0.0.1:11434 export OLLAMA_HOST0.0.0.0:11434 # 部分镜像方案通过该变量指定模型拉取源 export OLLAMA_MODELS/data/ollama/models # 启动服务Linux 下若已注册 systemd用 systemctl 代替 ollama serveOLLAMA_HOST改成0.0.0.0是为了让局域网内其他机器或 Docker 容器能访问只在本机用就保持默认。OLLAMA_MODELS指定模型存储目录这个变量必须在ollama serve之前设置服务启动后再改不生效。如果你的镜像方案是通过 HTTP 代理转发注意 ollama 的模型拉取走的是 HTTPS代理需要支持 CONNECT 方法。离线安装包这条路更适合内网。你需要准备三样东西ollama 的二进制或安装包、模型文件通常是blobs和manifests两个目录、以及一份Modelfile如果需要自定义模型。模型文件的目录结构必须和 ollama 预期一致否则ollama list会显示为空。常见做法是在一台能联网的机器上ollama pull好模型然后把整个models目录打包拷过去。提示离线拷贝模型时manifests目录里的路径层级不能改blobs里的文件名是哈希值改名会导致模型无法识别。2.3 依赖检查GPU 驱动与系统库装之前先确认 GPU 环境。NVIDIA 显卡需要驱动版本满足 ollama 要求通常 525 以上比较稳。用nvidia-smi看一眼驱动和 CUDA 版本如果命令不存在说明驱动没装或没进 PATH。AMD 显卡在 Linux 下需要 ROCm 支持Windows 下支持有限这点要有预期。# 检查 NVIDIA 驱动与显卡状态 nvidia-smi # 检查系统是否识别到 GPULinux lspci | grep -i nvidia # 查看 ollama 版本确认安装成功 ollama --versionnvidia-smi输出里重点看 Driver Version 和 CUDA Version 两行。Driver 太低会导致 ollama 回退到 CPU 推理速度差一个数量级。lspci用来确认系统层面认到了卡如果这里没有后面装什么都白搭。ollama --version是最简单的安装验证能打印版本号说明二进制可执行。CPU 推理也不是不能用7B 模型在 8 核 CPU 上大概每秒 3~5 个 token做简单问答够用但别指望流畅对话。内存方面7B 模型建议 16GB 起步14B 建议 32GB这是血泪经验内存不够会直接 OOM 被杀进程。3. 分平台实操Linux、Windows、Docker 三套安装流程3.1 Linux 与 WSL 下的脚本安装Linux 是最顺的平台但官方脚本在国内网络下经常卡住。稳妥做法是先把脚本下载到本地检查内容后再执行避免管道执行到一半断掉留下半成品。# 下载安装脚本到本地不直接管道执行 curl -fsSL https://ollama.com/install.sh -o ollama_install.sh # 查看脚本内容确认下载地址和安装逻辑 less ollama_install.sh # 赋予执行权限并运行 chmod x ollama_install.sh sudo ./ollama_install.sh第一步用-o把脚本存成文件而不是curl ... | sh这样网络断了可以重试也能先审一遍脚本。第二步用less看脚本里下载二进制的地址如果指向官方 CDN 且你网络不通就需要手动替换成镜像地址或改用离线包。第三步sudo执行是因为脚本要创建系统用户和写/usr/local/bin。装完后脚本会自动注册 systemd 服务用下面命令确认状态# 查看 ollama 服务状态 systemctl status ollama # 设置开机自启 sudo systemctl enable ollama # 查看服务日志排查启动失败 journalctl -u ollama -fsystemctl status显示active (running)才算成功。如果显示failed用journalctl看具体报错常见的是端口被占用或模型目录权限不对。enable是为了重启后服务自动拉起服务器环境建议开。WSL 环境下基本同理但要注意 WSL2 的网络是 NAT 模式Windows 主机访问 WSL 里的 ollama 需要端口转发或者直接把OLLAMA_HOST设成0.0.0.0并在 Windows 防火墙放行。3.2 Windows 安装包与路径修改Windows 下双击.exe安装包装完托盘会出现 ollama 图标。默认模型路径在 C 盘用户目录下这是最容易翻车的地方——C 盘空间不够时模型下到一半失败还得手动清理残留。修改模型路径的正确姿势是设置系统环境变量OLLAMA_MODELS然后重启 ollama 托盘进程。注意是「系统环境变量」不是「用户变量」因为 ollama 服务可能以不同权限运行。# 在 PowerShell 中设置用户级环境变量需重启 ollama [Environment]::SetEnvironmentVariable(OLLAMA_MODELS, D:\ollama\models, User) # 确认变量已写入 [Environment]::GetEnvironmentVariable(OLLAMA_MODELS, User) # 重启 ollama 进程托盘退出后重新启动或命令行 Stop-Process -Name ollama -Force ollama serve第一行把模型目录指到 D 盘第二行验证写入成功。第三行强制结束旧进程因为环境变量对已运行的进程不生效。改完路径后之前 C 盘下的模型不会自动迁移需要手动把models目录整个拷过去否则ollama list会看不到已有模型。Windows 下还有一个常见问题是ollama命令不在 PATH 里。安装包通常会加但如果用命令行提示找不到手动把安装目录一般是C:\Users\用户\AppData\Local\Programs\Ollama加到 PATH。3.3 Docker 部署与 GPU 直通Docker 方式适合需要干净隔离或批量复制的场景。官方镜像ollama/ollama已经包含运行时拉下来直接跑。# 拉取官方镜像 docker pull ollama/ollama # 启动容器映射端口和模型目录直通 GPU docker run -d \ --name ollama \ --gpus all \ -p 11434:11434 \ -v /data/ollama:/root/.ollama \ ollama/ollama # 进入容器拉取模型 docker exec -it ollama ollama pull qwen2.5 # 查看已加载模型 docker exec -it ollama ollama list--gpus all让容器能用宿主机 GPU前提是装了nvidia-container-toolkit没装的话这行会报错去掉就只能 CPU 跑。-v把模型目录挂到宿主机这样容器删了模型还在。-p映射端口宿主机其他程序通过localhost:11434访问。Docker 方式的一个坑是容器内OLLAMA_HOST默认只监听127.0.0.1容器外访问不到。需要在docker run时加-e OLLAMA_HOST0.0.0.0或者进容器改配置。另一个坑是模型存储路径在容器内是/root/.ollama挂载时别挂错层级。注意Docker 部署时如果宿主机已经跑了 ollama 服务端口 11434 会冲突先停掉宿主机服务或换端口映射。4. 避坑与排查安装后模型跑不起来的五类问题4.1 模型下载卡在 0% 或进度不动现象ollama pull执行后进度条长时间停在某个百分比或者直接报timeout。原因默认拉取源在国内网络下不稳定或者 DNS 解析到了不可达的地址。解决配置镜像源环境变量后重启服务或者改用离线包方式。如果已经下了一半先ollama rm删掉残留再重来断点续传在 ollama 里支持得并不好残留文件反而会干扰。4.2ollama list为空但模型文件明明在现象手动把模型目录拷到新机器ollama list什么都不显示。原因模型目录结构不对或者OLLAMA_MODELS指向的路径和实际存放路径不一致。解决确认OLLAMA_MODELS指向的目录下有manifests和blobs两个子目录且manifests里的路径层级完整。用ollama serve启动时看日志里打印的模型目录和实际路径对一下。4.3 GPU 没被调用推理速度极慢现象ollama run能跑但每秒只有几个 tokennvidia-smi显示 GPU 利用率接近 0。原因驱动版本不满足要求或者 ollama 没检测到 GPU回退到了 CPU。解决先升级 NVIDIA 驱动到 525 以上重启后确认nvidia-smi正常。Docker 方式检查是否加了--gpus all且装了nvidia-container-toolkit。Linux 下还可以看 ollama 启动日志里有没有no compatible GPUs found之类的提示。4.4 端口 11434 被占用导致服务起不来现象ollama serve报bind: address already in use。原因已经有一个 ollama 进程在跑或者别的程序占了这个端口。解决lsof -i:11434Linux/macOS或netstat -ano | findstr 11434Windows找到占用进程杀掉或改 ollama 监听端口。改端口用OLLAMA_HOST0.0.0.0:11435但上层调用方也要同步改。4.5 修改模型路径后旧模型消失现象改了OLLAMA_MODELS后之前下的模型全不见了。原因环境变量只改了路径旧模型还在原目录没有迁移。解决把旧目录下的models整个拷到新路径保持目录结构不变。拷完重启服务ollama list应该能重新看到。以后改路径前先备份这是后悔药。5. 进阶用 API 验证安装、FastAPI 调用与存储路径迁移技巧装完只是开始真正要确认的是这套环境能不能被上层程序稳定调用。ollama 默认在 11434 端口暴露 HTTP 接口兼容 OpenAI 的/v1/chat/completions格式这意味着大部分现成的 OpenAI 客户端改个 base_url 就能用。先用 curl 做一次最小验证# 确认服务在监听 curl http://localhost:11434/api/tags # 用 OpenAI 兼容接口发一次对话请求 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5, messages: [{role: user, content: 用一句话说明什么是本地推理}] }第一个请求返回已安装模型列表能返回 JSON 说明服务正常。第二个请求走 OpenAI 兼容层model字段填ollama list里看到的模型名。如果返回 404检查模型名拼写返回 500看 ollama 服务日志里的具体报错。接着用 FastAPI 包一层这是把 ollama 接进现有 Python 项目的常见做法from fastapi import FastAPI from pydantic import BaseModel import httpx app FastAPI() class ChatRequest(BaseModel): prompt: str model: str qwen2.5 app.post(/chat) async def chat(req: ChatRequest): # 调用 ollama 的 OpenAI 兼容接口 async with httpx.AsyncClient(timeout120) as client: resp await client.post( http://localhost:11434/v1/chat/completions, json{ model: req.model, messages: [{role: user, content: req.prompt}] } ) return resp.json()timeout120是必须的本地模型首次加载慢默认超时会直接断。model做成参数是为了方便切换不同模型。这段代码没有做流式输出如果需要打字机效果把stream设为True并用StreamingResponse转发。最后说存储路径迁移。前面提过改OLLAMA_MODELS后旧模型不会自动搬正确流程是先停服务用rsync或cp -r把整个models目录拷到新盘确认拷贝完整后再改环境变量最后启动服务验证ollama list。Linux 下如果模型目录在/usr/share/ollama注意权限属于ollama用户拷贝后要chown -R ollama:ollama新目录否则服务读不了。# 停服务 sudo systemctl stop ollama # 拷贝模型目录到新盘保留权限和时间戳 sudo rsync -avh /usr/share/ollama/.ollama/models/ /data/ollama/models/ # 修改服务配置里的 OLLAMA_MODELSsystemd 用 override sudo systemctl edit ollama # 在编辑器中加入 # [Service] # EnvironmentOLLAMA_MODELS/data/ollama/models # 重载配置并启动 sudo systemctl daemon-reload sudo systemctl start ollama # 验证模型列表 ollama listrsync -avh的-a保留权限和时间戳-v显示进度-h让大小可读。systemctl edit会创建一个 override 文件比直接改原 service 文件更安全升级时不会被覆盖。改完必须daemon-reload否则新配置不生效。从那以后我每次迁移模型目录都强制走一遍「停服务 → rsync → 改配置 → daemon-reload → 验证 list」这五步少一步就可能出现模型列表为空或者权限报错。这套流程在 Linux、WSL、Docker 挂载场景下都适用区别只是路径和权限用户不同。希望帮到你。本文还有配套的精品资源点击获取 Ollama本地大模型安装配置全指南：离线部署、镜像加速与避坑实践
简介这份资源面向需要在 Linux 或 macOS 环境下部署 Ollama 的开发者与运维人员提供一套轻量化的安装脚本与说明文档帮助快速完成环境准备、依赖检查与安装验证。压缩包共 3 个文件约 13KB包含 1 个 sh 安装脚本、1 个 php 下载入口和 1 个 txt 说明文档脚本负责批量执行安装与配置命令php 文件用于获取安装包txt 则记录安装前准备、步骤说明及常见问题处理思路。已有 437 人学习下载适合希望减少手动操作、按脚本流程完成部署的读者参考。通过阅读说明并执行脚本读者可了解类 Unix 系统下的自动化安装流程、权限与依赖处理方式以及安装后服务启动与验证的基本方法也可根据自身环境对脚本进行适当调整。1. 从一条ollama serve报错说起这套本地大模型运行环境到底值不值得装很多人第一次接触本地大模型是在一台已经装了 Python、Git、Node.js 的开发机上敲下ollama run qwen2.5结果卡在Error: connect: connection refused或者下载进度条走到 3% 就再也不动。这不是模型的问题而是 ollama 这套「本地模型运行时」的安装与配置没打通。ollama 的本质是一个把模型权重、推理引擎、HTTP 服务打包在一起的命令行工具装好之后你就能用一条命令拉起一个兼容 OpenAI 接口的本地服务供 FastAPI、CherryStudio、Dify、LM Studio 这类上层工具调用。它适合三类人想在内网或断网环境跑模型的开发者、需要给 IDE 配置本地补全的工程师、以及想用 Docker 或 WSL 做隔离部署的运维。这篇笔记按「装在哪 → 怎么装 → 怎么验证 → 坑在哪」的顺序拆一遍重点放在离线安装包、国内镜像源、模型存储路径迁移这几个真正会卡住人的环节。2. 安装前的选型与准备装在哪、用什么装、网络怎么绕2.1 三种安装方式的适用边界ollama 官方提供 Linux 一键脚本、Windows/macOS 安装包、以及 Docker 镜像三种分发形式。选哪种不是看哪个新而是看你的运行环境和后续维护成本。Linux 一键脚本适合干净的服务器或 WSL 环境它会自动创建ollama系统用户、注册 systemd 服务、把二进制放到/usr/local/bin。缺点是脚本默认从官方源拉取国内网络下大概率超时。Windows 安装包.exe适合个人开发机装完会在托盘常驻模型默认落在C:\Users\用户名\.ollama\models。Docker 方式适合需要版本隔离或批量部署的场景镜像里已经包含运行时但 GPU 直通需要额外配置--gpus参数。方式适用环境模型默认路径是否自带服务Linux 脚本服务器 / WSL/usr/share/ollama/.ollama/models是systemd 管理Windows 安装包个人开发机C:\Users\用户\.ollama\models是托盘进程Docker 镜像隔离部署 / 批量容器内/root/.ollama/models是容器主进程选型时先确认一件事你的模型文件打算放哪块盘。ollama 拉一个 7B 模型动辄 4~5GB14B 接近 9GB如果系统盘只有 50GB装完两三个模型就红了。所以安装前最好先把存储路径规划好后面第 4 章会讲怎么迁移。2.2 网络准备镜像源与离线包两条路国内直连官方源下载模型基本不可用常见做法是两条路并行。第一条是配置镜像源环境变量让 ollama 从国内可访问的地址拉取。第二条是提前下载离线安装包和模型文件适合完全断网的内网机器。镜像源配置的核心是OLLAMA_HOST和拉取地址两个变量。不同版本的 ollama 对镜像的支持方式略有差异稳妥做法是在启动服务前 export 环境变量# 设置 ollama 服务监听地址默认 127.0.0.1:11434 export OLLAMA_HOST0.0.0.0:11434 # 部分镜像方案通过该变量指定模型拉取源 export OLLAMA_MODELS/data/ollama/models # 启动服务Linux 下若已注册 systemd用 systemctl 代替 ollama serveOLLAMA_HOST改成0.0.0.0是为了让局域网内其他机器或 Docker 容器能访问只在本机用就保持默认。OLLAMA_MODELS指定模型存储目录这个变量必须在ollama serve之前设置服务启动后再改不生效。如果你的镜像方案是通过 HTTP 代理转发注意 ollama 的模型拉取走的是 HTTPS代理需要支持 CONNECT 方法。离线安装包这条路更适合内网。你需要准备三样东西ollama 的二进制或安装包、模型文件通常是blobs和manifests两个目录、以及一份Modelfile如果需要自定义模型。模型文件的目录结构必须和 ollama 预期一致否则ollama list会显示为空。常见做法是在一台能联网的机器上ollama pull好模型然后把整个models目录打包拷过去。提示离线拷贝模型时manifests目录里的路径层级不能改blobs里的文件名是哈希值改名会导致模型无法识别。2.3 依赖检查GPU 驱动与系统库装之前先确认 GPU 环境。NVIDIA 显卡需要驱动版本满足 ollama 要求通常 525 以上比较稳。用nvidia-smi看一眼驱动和 CUDA 版本如果命令不存在说明驱动没装或没进 PATH。AMD 显卡在 Linux 下需要 ROCm 支持Windows 下支持有限这点要有预期。# 检查 NVIDIA 驱动与显卡状态 nvidia-smi # 检查系统是否识别到 GPULinux lspci | grep -i nvidia # 查看 ollama 版本确认安装成功 ollama --versionnvidia-smi输出里重点看 Driver Version 和 CUDA Version 两行。Driver 太低会导致 ollama 回退到 CPU 推理速度差一个数量级。lspci用来确认系统层面认到了卡如果这里没有后面装什么都白搭。ollama --version是最简单的安装验证能打印版本号说明二进制可执行。CPU 推理也不是不能用7B 模型在 8 核 CPU 上大概每秒 3~5 个 token做简单问答够用但别指望流畅对话。内存方面7B 模型建议 16GB 起步14B 建议 32GB这是血泪经验内存不够会直接 OOM 被杀进程。3. 分平台实操Linux、Windows、Docker 三套安装流程3.1 Linux 与 WSL 下的脚本安装Linux 是最顺的平台但官方脚本在国内网络下经常卡住。稳妥做法是先把脚本下载到本地检查内容后再执行避免管道执行到一半断掉留下半成品。# 下载安装脚本到本地不直接管道执行 curl -fsSL https://ollama.com/install.sh -o ollama_install.sh # 查看脚本内容确认下载地址和安装逻辑 less ollama_install.sh # 赋予执行权限并运行 chmod x ollama_install.sh sudo ./ollama_install.sh第一步用-o把脚本存成文件而不是curl ... | sh这样网络断了可以重试也能先审一遍脚本。第二步用less看脚本里下载二进制的地址如果指向官方 CDN 且你网络不通就需要手动替换成镜像地址或改用离线包。第三步sudo执行是因为脚本要创建系统用户和写/usr/local/bin。装完后脚本会自动注册 systemd 服务用下面命令确认状态# 查看 ollama 服务状态 systemctl status ollama # 设置开机自启 sudo systemctl enable ollama # 查看服务日志排查启动失败 journalctl -u ollama -fsystemctl status显示active (running)才算成功。如果显示failed用journalctl看具体报错常见的是端口被占用或模型目录权限不对。enable是为了重启后服务自动拉起服务器环境建议开。WSL 环境下基本同理但要注意 WSL2 的网络是 NAT 模式Windows 主机访问 WSL 里的 ollama 需要端口转发或者直接把OLLAMA_HOST设成0.0.0.0并在 Windows 防火墙放行。3.2 Windows 安装包与路径修改Windows 下双击.exe安装包装完托盘会出现 ollama 图标。默认模型路径在 C 盘用户目录下这是最容易翻车的地方——C 盘空间不够时模型下到一半失败还得手动清理残留。修改模型路径的正确姿势是设置系统环境变量OLLAMA_MODELS然后重启 ollama 托盘进程。注意是「系统环境变量」不是「用户变量」因为 ollama 服务可能以不同权限运行。# 在 PowerShell 中设置用户级环境变量需重启 ollama [Environment]::SetEnvironmentVariable(OLLAMA_MODELS, D:\ollama\models, User) # 确认变量已写入 [Environment]::GetEnvironmentVariable(OLLAMA_MODELS, User) # 重启 ollama 进程托盘退出后重新启动或命令行 Stop-Process -Name ollama -Force ollama serve第一行把模型目录指到 D 盘第二行验证写入成功。第三行强制结束旧进程因为环境变量对已运行的进程不生效。改完路径后之前 C 盘下的模型不会自动迁移需要手动把models目录整个拷过去否则ollama list会看不到已有模型。Windows 下还有一个常见问题是ollama命令不在 PATH 里。安装包通常会加但如果用命令行提示找不到手动把安装目录一般是C:\Users\用户\AppData\Local\Programs\Ollama加到 PATH。3.3 Docker 部署与 GPU 直通Docker 方式适合需要干净隔离或批量复制的场景。官方镜像ollama/ollama已经包含运行时拉下来直接跑。# 拉取官方镜像 docker pull ollama/ollama # 启动容器映射端口和模型目录直通 GPU docker run -d \ --name ollama \ --gpus all \ -p 11434:11434 \ -v /data/ollama:/root/.ollama \ ollama/ollama # 进入容器拉取模型 docker exec -it ollama ollama pull qwen2.5 # 查看已加载模型 docker exec -it ollama ollama list--gpus all让容器能用宿主机 GPU前提是装了nvidia-container-toolkit没装的话这行会报错去掉就只能 CPU 跑。-v把模型目录挂到宿主机这样容器删了模型还在。-p映射端口宿主机其他程序通过localhost:11434访问。Docker 方式的一个坑是容器内OLLAMA_HOST默认只监听127.0.0.1容器外访问不到。需要在docker run时加-e OLLAMA_HOST0.0.0.0或者进容器改配置。另一个坑是模型存储路径在容器内是/root/.ollama挂载时别挂错层级。注意Docker 部署时如果宿主机已经跑了 ollama 服务端口 11434 会冲突先停掉宿主机服务或换端口映射。4. 避坑与排查安装后模型跑不起来的五类问题4.1 模型下载卡在 0% 或进度不动现象ollama pull执行后进度条长时间停在某个百分比或者直接报timeout。原因默认拉取源在国内网络下不稳定或者 DNS 解析到了不可达的地址。解决配置镜像源环境变量后重启服务或者改用离线包方式。如果已经下了一半先ollama rm删掉残留再重来断点续传在 ollama 里支持得并不好残留文件反而会干扰。4.2ollama list为空但模型文件明明在现象手动把模型目录拷到新机器ollama list什么都不显示。原因模型目录结构不对或者OLLAMA_MODELS指向的路径和实际存放路径不一致。解决确认OLLAMA_MODELS指向的目录下有manifests和blobs两个子目录且manifests里的路径层级完整。用ollama serve启动时看日志里打印的模型目录和实际路径对一下。4.3 GPU 没被调用推理速度极慢现象ollama run能跑但每秒只有几个 tokennvidia-smi显示 GPU 利用率接近 0。原因驱动版本不满足要求或者 ollama 没检测到 GPU回退到了 CPU。解决先升级 NVIDIA 驱动到 525 以上重启后确认nvidia-smi正常。Docker 方式检查是否加了--gpus all且装了nvidia-container-toolkit。Linux 下还可以看 ollama 启动日志里有没有no compatible GPUs found之类的提示。4.4 端口 11434 被占用导致服务起不来现象ollama serve报bind: address already in use。原因已经有一个 ollama 进程在跑或者别的程序占了这个端口。解决lsof -i:11434Linux/macOS或netstat -ano | findstr 11434Windows找到占用进程杀掉或改 ollama 监听端口。改端口用OLLAMA_HOST0.0.0.0:11435但上层调用方也要同步改。4.5 修改模型路径后旧模型消失现象改了OLLAMA_MODELS后之前下的模型全不见了。原因环境变量只改了路径旧模型还在原目录没有迁移。解决把旧目录下的models整个拷到新路径保持目录结构不变。拷完重启服务ollama list应该能重新看到。以后改路径前先备份这是后悔药。5. 进阶用 API 验证安装、FastAPI 调用与存储路径迁移技巧装完只是开始真正要确认的是这套环境能不能被上层程序稳定调用。ollama 默认在 11434 端口暴露 HTTP 接口兼容 OpenAI 的/v1/chat/completions格式这意味着大部分现成的 OpenAI 客户端改个 base_url 就能用。先用 curl 做一次最小验证# 确认服务在监听 curl http://localhost:11434/api/tags # 用 OpenAI 兼容接口发一次对话请求 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5, messages: [{role: user, content: 用一句话说明什么是本地推理}] }第一个请求返回已安装模型列表能返回 JSON 说明服务正常。第二个请求走 OpenAI 兼容层model字段填ollama list里看到的模型名。如果返回 404检查模型名拼写返回 500看 ollama 服务日志里的具体报错。接着用 FastAPI 包一层这是把 ollama 接进现有 Python 项目的常见做法from fastapi import FastAPI from pydantic import BaseModel import httpx app FastAPI() class ChatRequest(BaseModel): prompt: str model: str qwen2.5 app.post(/chat) async def chat(req: ChatRequest): # 调用 ollama 的 OpenAI 兼容接口 async with httpx.AsyncClient(timeout120) as client: resp await client.post( http://localhost:11434/v1/chat/completions, json{ model: req.model, messages: [{role: user, content: req.prompt}] } ) return resp.json()timeout120是必须的本地模型首次加载慢默认超时会直接断。model做成参数是为了方便切换不同模型。这段代码没有做流式输出如果需要打字机效果把stream设为True并用StreamingResponse转发。最后说存储路径迁移。前面提过改OLLAMA_MODELS后旧模型不会自动搬正确流程是先停服务用rsync或cp -r把整个models目录拷到新盘确认拷贝完整后再改环境变量最后启动服务验证ollama list。Linux 下如果模型目录在/usr/share/ollama注意权限属于ollama用户拷贝后要chown -R ollama:ollama新目录否则服务读不了。# 停服务 sudo systemctl stop ollama # 拷贝模型目录到新盘保留权限和时间戳 sudo rsync -avh /usr/share/ollama/.ollama/models/ /data/ollama/models/ # 修改服务配置里的 OLLAMA_MODELSsystemd 用 override sudo systemctl edit ollama # 在编辑器中加入 # [Service] # EnvironmentOLLAMA_MODELS/data/ollama/models # 重载配置并启动 sudo systemctl daemon-reload sudo systemctl start ollama # 验证模型列表 ollama listrsync -avh的-a保留权限和时间戳-v显示进度-h让大小可读。systemctl edit会创建一个 override 文件比直接改原 service 文件更安全升级时不会被覆盖。改完必须daemon-reload否则新配置不生效。从那以后我每次迁移模型目录都强制走一遍「停服务 → rsync → 改配置 → daemon-reload → 验证 list」这五步少一步就可能出现模型列表为空或者权限报错。这套流程在 Linux、WSL、Docker 挂载场景下都适用区别只是路径和权限用户不同。希望帮到你。本文还有配套的精品资源点击获取