简介：本资源是一份面向Linux/macOS开发者与AI初学者的Ollama本地大模型运行环境快速部署指南，聚焦解决大模型轻量化本地化部署中的安装门槛高、依赖配置复杂等实际问题。压缩包仅13KB，含3个核心文件：readme.txt提供安装前准备、步骤说明与常见问题解答；install.sh为可执行Shell脚本，封装系统检测、依赖安装与服务初始化逻辑；get.php则用于辅助下载Ollama二进制或镜像资源（适配Web托管场景）。三者协同构成轻量但完整的自动化安装闭环，无需手动编译或频繁查文档。目前已有437人学习下载，读者可直接复用脚本快速搭建Ollama服务，结合readme中的排错提示与环境校验方法，显著降低MacBook或Ubuntu服务器上首次运行Llama/Mistral等模型的试错成本。

1. Ollama 安装：不是“一键跑通”就完事，而是把本地大模型运行时环境真正焊死在你的机器上

你刚在终端敲下curl -fsSL https://ollama.com/install.sh | sh，回车后绿色文字刷屏，ollama run llama3也秒出响应——恭喜，你完成了 Ollama 的“安装幻觉”。但真实场景远比这残酷：某高校实验室的 A 同学在 M2 Mac 上跑通后，换到一台旧款 i5 笔记本却卡在Failed to start ollama service；某公司部署团队把 Ollama 打进 Docker 镜像，结果容器启动后ollama list为空，模型文件全丢了；还有人反复重装三次，直到发现/usr/local/bin/ollama是软链接，而实际二进制被杀毒软件静默拦截。Ollama 安装的本质，从来不是下载一个可执行文件，而是构建一套受控、可复现、可诊断的本地推理运行时环境——它要能扛住系统升级、权限变更、磁盘挂载点迁移、非 root 用户调用，还要让ollama serve真正作为守护进程存活，而不是前台进程一关终端就断。这份安装指南不讲“最简步骤”，只拆解你翻车前必须知道的五个底层事实：服务监听地址如何被硬编码、模型缓存路径为何不能随意挪动、systemd 单元文件里藏着哪三处默认陷阱、macOS Gatekeeper 如何悄悄改写二进制签名、以及 Windows Subsystem for Linux（WSL2）环境下 GPU 加速为何从一开始就是伪命题。适合所有已试过官网命令但仍在connection refused和permission denied之间反复横跳的实战派。

2. 安装原理与选型依据：为什么不用包管理器？为什么必须校验二进制？为什么服务模式是刚需？

Ollama 不是传统 CLI 工具，它的架构分三层：CLI 前端（ollama命令）、后台服务（ollama serve进程）、模型运行时（基于 llama.cpp 或 transformers 的沙箱）。这决定了安装不能只拷贝二进制——服务进程必须常驻、端口必须可绑定、模型存储必须可持久化。下面逐层拆解关键决策点。

2.1 为什么绕开 Homebrew / apt / Chocolatey？——包管理器无法满足服务生命周期控制

Homebrew 安装 Ollama（brew install ollama）看似省事，但它把ollama二进制放进/opt/homebrew/bin/，而服务单元文件（.plist或.service）仍需手动配置。更致命的是：Homebrew 不管理OLLAMA_MODELS环境变量的全局生效，导致非交互式 shell（如 cron、CI 脚本）中ollama list返回空。apt 同理——Debian/Ubuntu 的ollama包默认不启用 systemd 服务，且/etc/systemd/system/ollama.service文件权限为644，而实际需要640才能被systemctl --user正确加载。Chocolatey 在 Windows 上甚至不提供服务注册逻辑，纯靠用户手动建任务计划程序，稳定性归零。

提示：官方安装脚本install.sh的核心价值，是原子化完成三件事：下载带签名的二进制、写入正确权限的服务定义、设置跨会话生效的环境变量。任何跳过它的“捷径”，都在透支后续排错成本。

2.2 为什么必须校验二进制哈希？——签名验证不是玄学，是防止中间人篡改的最后防线

Ollama 官网提供的二进制由ollama.com域名 HTTPS 传输，但 DNS 劫持或代理污染仍可能替换下载内容。2023 年曾有报告指出某国内镜像站分发的ollama-darwin-arm64二进制被注入挖矿模块。正确做法是：下载后立即比对 SHA256 值。以 macOS ARM64 为例：

# 下载二进制（不执行） curl -fL https://github.com/ollama/ollama/releases/download/v0.3.10/ollama-darwin-arm64 -o ./ollama-darwin-arm64 # 获取官方公布的 SHA256（来自 GitHub Release 页面的 .sha256 文件） curl -fL https://github.com/ollama/ollama/releases/download/v0.3.10/ollama-darwin-arm64.sha256 -o ./ollama-darwin-arm64.sha256 # 校验（输出 'OK' 表示通过） shasum -a 256 -c ./ollama-darwin-arm64.sha256

参数说明：

• -fL：-f表示失败不输出错误体，-L自动跟随重定向（GitHub Release 会 302 到 CDN）
• -c：指定校验文件，格式为SHA256_HASH filename
• 若输出./ollama-darwin-arm64: FAILED，立刻删除该文件，切勿尝试 chmod +x 运行

2.3 为什么必须启用ollama serve服务模式？——CLI 模式是调试玩具，服务模式才是生产基石

ollama run llama3看似直接，实则每次执行都隐式启动一个临时ollama serve进程，模型加载、KV cache 初始化全在内存中完成。问题在于：

• 多次调用ollama run会重复加载同一模型，内存占用翻倍；
• 终端关闭后进程终止，所有上下文丢失；
• 无法被其他进程（如 Python 的requests.post("http://localhost:11434/api/chat")）稳定调用。

服务模式强制将ollama serve作为守护进程运行，带来三大确定性：

1. 端口复用：所有请求走localhost:11434，无需关心进程 PID；
2. 模型热驻留：ollama pull后模型即加载进内存，ollama run变成毫秒级响应；
3. 资源隔离：可通过systemd --user或launchd设置内存限制（如MemoryMax=4G），防止单个模型吃光 RAM。

验证服务是否真正在后台运行：

# macOS 检查 launchd 状态（非 ps aux） launchctl list | grep ollama # Linux 检查 systemd 用户服务 systemctl --user is-active ollama # 统一验证：向 API 发起轻量请求（不触发模型加载） curl -s http://localhost:11434/api/tags | jq -r '.models[].name' 2>/dev/null | head -3

若返回模型名列表（如llama3,phi3,gemma），说明服务已就绪；若报Connection refused，证明服务未启动或端口被占。

3. 分平台安装实操：Mac、Linux、Windows WSL2 的差异化落地步骤

不同系统内核机制差异巨大，同一份安装脚本在各平台触发的底层行为完全不同。这里不提供“通用命令”，只给每种平台必须手敲、不可跳过的验证步骤。

3.1 macOS（Apple Silicon & Intel）：绕过 Gatekeeper 签名劫持与 LaunchAgent 权限陷阱

Apple Silicon（M1/M2/M3）和 Intel Mac 的安装路径一致，但 Gatekeeper 行为不同：ARM64 二进制默认被标记为“已损坏”，Intel 二进制则可能因公证（notarization）缺失被拦截。必须分步处理：

步骤 1：下载并解除隔离（关键！）

# 下载（注意 URL 中的 v0.3.10 版本号需与当前最新 Release 一致） curl -fL https://github.com/ollama/ollama/releases/download/v0.3.10/ollama-darwin-arm64 -o /tmp/ollama # 移动到标准位置 sudo mv /tmp/ollama /usr/local/bin/ollama # 解除 macOS 隔离属性（否则双击或 exec 会弹窗拒绝） sudo xattr -rd com.apple.quarantine /usr/local/bin/ollama # 赋予可执行权限（虽通常已有，但显式声明防意外） sudo chmod +x /usr/local/bin/ollama

步骤 2：配置 LaunchAgent（非 LaunchDaemon！）
Ollama 必须以当前用户身份运行，而非 root。因此使用~/Library/LaunchAgents/而非/Library/LaunchDaemons/。创建文件~/Library/LaunchAgents/ai.ollama.ollama.plist：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>ai.ollama.ollama</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/ollama</string> <string>serve</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string> </dict> <key>StandardOutPath</key> <string>/Users/$USER/Library/Logs/ollama.log</string> <key>StandardErrorPath</key> <string>/Users/$USER/Library/Logs/ollama.log</string> </dict> </plist>

注意：$USER需手动替换为你的用户名（如john），不能留$USER字符串；StandardOutPath路径必须存在，提前创建：mkdir -p ~/Library/Logs

步骤 3：加载并验证

# 加载配置（无需重启） launchctl load ~/Library/LaunchAgents/ai.ollama.ollama.plist # 启动服务 launchctl start ai.ollama.ollama # 检查状态（应输出 'running'） launchctl list | grep ollama # 查看日志（首次启动会输出 'Listening on 127.0.0.1:11434'） tail -f ~/Library/Logs/ollama.log

3.2 Linux（systemd 系统）：修复用户级服务的 socket 激活与权限继承

大多数现代 Linux 发行版（Ubuntu 22.04+, Debian 12+, Fedora 38+）使用 systemd，但ollama install.sh生成的~/.config/systemd/user/ollama.service存在两个硬伤：

• 缺少RestartSec=5，导致服务崩溃后不会自动恢复；
• Environment=OLLAMA_HOST=127.0.0.1:11434写死 IP，当系统启用 IPv6 时可能绑定失败。

修正步骤：

# 创建用户级 systemd 目录（若不存在） mkdir -p ~/.config/systemd/user # 写入修正后的 service 文件 cat > ~/.config/systemd/user/ollama.service << 'EOF' [Unit] Description=Ollama Service After=network.target [Service] Type=simple ExecStart=/usr/bin/ollama serve Restart=always RestartSec=5 Environment="OLLAMA_HOST=0.0.0.0:11434" Environment="OLLAMA_MODELS=/home/$USER/.ollama/models" LimitNOFILE=65536 [Install] WantedBy=default.target EOF # 重载配置并启用 systemctl --user daemon-reload systemctl --user enable ollama systemctl --user start ollama # 验证（等待 5 秒后检查） systemctl --user is-active ollama # 应输出 'active' systemctl --user status ollama --no-pager | head -15

参数说明：

• RestartSec=5：崩溃后 5 秒重启，避免快速失败循环（fail-fast loop）；
• OLLAMA_HOST=0.0.0.0:11434：监听所有 IPv4 接口，兼容 IPv6 系统（0.0.0.0不影响安全性，因默认防火墙阻止外网访问）；
• LimitNOFILE=65536：提高文件描述符上限，防止高并发请求时Too many open files错误。

3.3 Windows WSL2：放弃 GPU 加速幻想，专注 CPU 推理稳定性

WSL2 是 Linux 内核兼容层，不提供对 Windows 主机 GPU 的直通支持。NVIDIA CUDA、AMD ROCm、Intel oneAPI 在 WSL2 中均不可用。所谓“WSL2 GPU 加速”实为营销话术——它只能调用 CPU 核心。因此安装目标应调整为：在资源受限的 WSL2 环境中，确保 Ollama 服务稳定、模型加载不 OOM、API 响应延迟可控。

关键操作：

1. 限制 WSL2 内存（防宿主机卡死）：在 Windows 的%USERPROFILE%\AppData\Local\Packages\对应发行版目录下，创建.wslconfig：

   [wsl2] memory=4GB processors=2 swap=2GB localhostForwarding=true

   修改后需wsl --shutdown重启 WSL2。

2. 安装 Ubuntu 22.04 LTS（非 24.04）：24.04 的 glibc 2.39 与 Ollama 二进制存在符号冲突，ollama serve启动即 segfault。22.04 的 glibc 2.35 兼容性最佳。

3. 使用--no-sandbox启动（仅 WSL2）：

   # 下载 Linux x64 二进制 curl -fL https://github.com/ollama/ollama/releases/download/v0.3.10/ollama-linux-amd64 -o /tmp/ollama sudo mv /tmp/ollama /usr/bin/ollama sudo chmod +x /usr/bin/ollama # 启动服务（加 --no-sandbox 避免 seccomp 策略拦截） /usr/bin/ollama serve --no-sandbox &

4. 从 Windows 访问 API：WSL2 的localhost不映射到 Windows，必须用http://127.0.0.1:11434（而非http://localhost:11434）。

4. 避坑：五个血泪经验总结——现象、原因、解决，一条都不能少

这些坑我全踩过，文档里不写，但你装第三遍时一定会撞上。按发生频率排序，每条都附可验证命令。

4.1 现象：ollama list显示空列表，但~/.ollama/models目录下有完整模型文件

原因：OLLAMA_MODELS环境变量未在服务进程中生效。CLI 命令读取该变量定位模型目录，但ollama serve进程启动时若未继承该变量，则默认使用/usr/share/ollama/.ollama/models（通常为空）。
解决：

• Linux：编辑~/.config/systemd/user/ollama.service，在[Service]下添加：

  Environment="OLLAMA_MODELS=/home/$USER/.ollama/models"

• macOS：在~/Library/LaunchAgents/ai.ollama.ollama.plist的<dict>内添加：

  <key>EnvironmentVariables</key> <dict> <key>OLLAMA_MODELS</key> <string>/Users/yourname/.ollama/models</string> </dict>

• 验证：systemctl --user show ollama | grep OLLAMA_MODELS（Linux）或launchctl getenv OLLAMA_MODELS（macOS）

4.2 现象：ollama run llama3报错failed to get model "llama3": model not found，但ollama pull llama3成功

原因：ollama pull下载的是模型 manifest（JSON 描述）和 blob（二进制权重），但服务进程未重新加载 manifest 缓存。Ollama 服务启动后会缓存模型列表，pull不触发刷新。
解决：

• 重启服务（最可靠）：

  # macOS launchctl stop ai.ollama.ollama && launchctl start ai.ollama.ollama # Linux systemctl --user restart ollama

• 或发送 reload 信号（部分版本支持）：

  curl -X POST http://localhost:11434/api/refresh

• 验证：curl http://localhost:11434/api/tags | jq '.models | length'应返回1（llama3）或更多。

4.3 现象：服务启动后curl http://localhost:11434返回404 Not Found，但curl http://localhost:11434/api/version正常

原因：Ollama 的根路径/无响应是设计如此，它只暴露/api/*端点。但此现象常被误判为服务未启动。
解决：

• 不要测试/，必须测试 API 端点：

  # 正确测试方式（返回 JSON） curl -s http://localhost:11434/api/version | jq -r '.version' # 或测试模型列表 curl -s http://localhost:11434/api/tags | jq -r '.models[0].name'

• 若上述命令返回curl: (7) Failed to connect，才是真服务故障。

4.4 现象：Linux 上systemctl --user start ollama后is-active返回inactive，status显示Failed with result 'exit-code'

原因：用户级 systemd 要求XDG_RUNTIME_DIR环境变量存在且权限正确（700）。WSL2 或最小化安装的 Ubuntu 常缺失此变量。
解决：

# 创建 runtime 目录（$XDG_RUNTIME_DIR 通常为 /run/user/$(id -u)） mkdir -p /run/user/$(id -u) chmod 700 /run/user/$(id -u) chown $USER:$USER /run/user/$(id -u) # 将变量写入 shell 配置（~/.bashrc 或 ~/.zshrc） echo 'export XDG_RUNTIME_DIR="/run/user/$(id -u)"' >> ~/.bashrc source ~/.bashrc # 重新加载 systemd 用户实例 systemctl --user daemon-reload systemctl --user start ollama

4.5 现象：macOS 上launchctl start后日志显示listen tcp 127.0.0.1:11434: bind: address already in use

原因：端口被其他进程（如旧版 Ollama、Docker 容器、或另一个用户的 ollama 实例）占用。lsof -i :11434在 macOS 上常因权限不足无法显示全部进程。
解决：

# 用 root 权限查看（需输入密码） sudo lsof -i :11434 # 若看到 PID，强制 kill sudo kill -9 PID # 若无输出，检查是否被 launchd 其他 job 占用 launchctl list | grep -E "(11434|ollama)" # 清理残留（删除旧 plist 并 unload） rm ~/Library/LaunchAgents/ai.ollama.ollama.plist launchctl unload ~/Library/LaunchAgents/ai.ollama.ollama.plist 2>/dev/null

5. 进阶验证与长期维护：用三个真实命令建立你的 Ollama 健康度仪表盘

安装完成只是起点。真正的稳定性，体现在你能用三行命令，在 10 秒内判断：服务是否活着、模型是否可用、推理是否正常。我把这套验证逻辑固化为日常巡检脚本，已运行 11 个月零中断。

5.1 健康度仪表盘：三命令定义“可用”标准

我定义 Ollama “可用”必须同时满足：

1. 服务进程存活（ollama serve进程存在且监听端口）；
2. 模型注册就绪（API 能列出至少一个模型）；
3. 推理链路通畅（能完成一次最小 chat 请求，不超时、不报错）。

对应验证命令（Linux/macOS 通用）：

# 命令 1：检查服务进程与端口（返回 0 表示 OK） if pgrep -f "ollama serve" >/dev/null && ss -tln | grep -q ":11434"; then echo "✅ 服务进程与端口正常" else echo "❌ 服务未运行或端口未监听" exit 1 fi # 命令 2：检查模型注册（返回模型数量，应 ≥1） MODEL_COUNT=$(curl -s http://localhost:11434/api/tags 2>/dev/null | jq -r '.models | length' 2>/dev/null || echo 0) if [ "$MODEL_COUNT" -ge 1 ]; then echo "✅ 已注册 $MODEL_COUNT 个模型" else echo "❌ 模型未注册，请执行 ollama pull <model>" exit 1 fi # 命令 3：发起最小 chat 测试（10 秒超时，返回 'success' 表示 OK） if timeout 10 curl -s -X POST http://localhost:11434/api/chat \ -H "Content-Type: application/json" \ -d '{"model":"llama3","messages":[{"role":"user","content":"Hello"}]}' \ | jq -r 'select(.done == true) | "success"' 2>/dev/null | grep -q "success"; then echo "✅ 推理链路通畅" else echo "❌ 推理失败，请检查模型是否加载、内存是否充足" exit 1 fi

参数说明：

• timeout 10：严格限制 10 秒，防止单次请求卡死；
• jq -r 'select(.done == true)'：只接受done:true的完整响应，过滤流式响应中的中间 chunk；
• grep -q "success"：静默匹配，避免输出干扰。

5.2 长期维护：模型缓存清理与服务热更新策略

Ollama 的~/.ollama/models目录会随ollama pull不断膨胀。一个llama3:70b模型占 42GB，三个月不清理，磁盘必爆。但ollama rm <model>有风险：若该模型正被ollama run使用，会触发 panic。安全清理流程如下：

步骤 1：确认模型未被使用

# 列出所有正在运行的模型（需 Ollama v0.3.8+） curl -s http://localhost:11434/api/ps | jq -r '.processes[] | "\(.model) \(.status)"' # 输出示例：llama3:latest running # 若目标模型状态为 'running'，先停止所有相关会话

步骤 2：执行清理（原子化）

# 1. 停止服务（避免新请求进入） systemctl --user stop ollama # Linux launchctl stop ai.ollama.ollama # macOS # 2. 删除模型（安全，因服务已停） ollama rm llama3:70b # 3. 启动服务 systemctl --user start ollama

步骤 3：服务热更新（不中断业务）
当 Ollama 发布新版（如 v0.3.11），想无缝升级：

# 下载新二进制（保持同名） curl -fL https://github.com/ollama/ollama/releases/download/v0.3.11/ollama-darwin-arm64 -o /tmp/ollama-new # 校验哈希（必须！） shasum -a 256 -c <(curl -s https://github.com/ollama/ollama/releases/download/v0.3.11/ollama-darwin-arm64.sha256) # 替换二进制（原子操作） sudo mv /tmp/ollama-new /usr/local/bin/ollama sudo chmod +x /usr/local/bin/ollama # 重启服务（用户无感，API 连接会短暂 502，<1 秒） systemctl --user restart ollama

5.3 最后一条习惯：每次ollama pull后，强制执行一次ollama serve --verbose

这是我的后悔药。--verbose会输出模型加载的详细日志，包括：

• 权重文件是否完整（checksum match）；
• GPU 层是否启用（macOS 显示metal: true，Linux 显示cuda: false）；
• KV cache 分配大小（如kv cache: 2048 tokens）；
• 是否触发 mmap（mmap: true表示内存映射加载，节省 RAM）。

执行：

ollama serve --verbose 2>&1 | head -20

典型健康输出：

time=2024-05-20T10:30:22.123Z level=INFO source=server.go:123 msg="Starting Ollama server" time=2024-05-20T10:30:22.456Z level=INFO source=llm.go:89 msg="Loading model" model=llama3:latest time=2024-05-20T10:30:25.789Z level=INFO source=llm.go:156 msg="Model loaded" duration=3.333s kv_cache=2048 metal=true

若出现checksum mismatch或mmap: false，说明模型文件损坏或磁盘空间不足，必须ollama rm后重拉。

从那以后我每次ollama pull后都强制走一遍ollama serve --verbose | head -20，哪怕只是扫一眼kv_cache行。这 5 秒钟，省去我平均每次 27 分钟的排查时间。希望帮到你。

本文还有配套的精品资源，点击获取