故障排除指南

本指南帮助您诊断和解决使用 Ollama 时遇到的常见问题。

安装问题

安装失败

问题: 安装脚本执行失败

curl: (7) Failed to connect to ollama.com port 443: Connection refused

解决方案:

检查网络连接
使用代理：

bash

export https_proxy=http://proxy.example.com:8080
curl -fsSL https://ollama.com/install.sh | sh

手动下载安装包问题: 权限被拒绝

Permission denied

解决方案:

bash

# 使用 sudo 运行安装脚本
curl -fsSL https://ollama.com/install.sh | sudo sh
# 或添加用户到 ollama 组
sudo usermod -aG ollama $USER

服务启动失败

问题: systemd 服务无法启动

Failed to start ollama.service: Unit ollama.service not found.

解决方案:

bash

# 重新安装服务
sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama
# 检查服务状态
sudo systemctl status ollama

问题: 端口被占用

bind: address already in use

解决方案:

bash

# 查找占用端口的进程
sudo lsof -i :11434
sudo netstat -tulpn | grep :11434
# 终止进程或更改端口
export OLLAMA_HOST=0.0.0.0:8080
ollama serve

模型问题

模型下载失败

问题: 网络超时

Error: failed to download model: context deadline exceeded

解决方案:

检查网络连接
增加超时时间：

bash

export OLLAMA_REQUEST_TIMEOUT=600  # 10 分钟
ollama pull gemma3

使用代理或镜像源问题: 磁盘空间不足

Error: no space left on device

解决方案:

bash

# 检查磁盘空间
df -h
# 清理旧模型
ollama list
ollama rm unused-model
# 更改模型存储位置
export OLLAMA_MODELS=/path/to/larger/disk

问题: 模型损坏

Error: invalid model file

解决方案:

bash

# 重新下载模型
ollama rm gemma3
ollama pull gemma3
# 验证模型完整性
ollama show gemma3

模型运行问题

问题: 模型未找到

Error: model 'gemma3' not found

解决方案:

bash

# 检查已安装模型
ollama list
# 下载模型
ollama pull gemma3
# 检查模型名称拼写

问题: 内存不足

Error: failed to load model: not enough memory

解决方案:

检查系统内存：

bash

free -h

使用更小的模型
关闭其他应用程序
增加交换空间（不推荐）

GPU 问题

NVIDIA GPU 问题

问题: GPU 未被检测

No CUDA-capable device is detected

解决方案:

检查驱动安装：

bash

nvidia-smi

检查 CUDA 版本：

bash

nvcc --version

重新安装驱动：

bash

sudo apt purge nvidia-*
sudo apt autoremove
sudo apt install nvidia-driver-535
sudo reboot

问题: CUDA 版本不兼容

CUDA driver version is insufficient for CUDA runtime version

解决方案:

更新 NVIDIA 驱动
或降级 CUDA 版本
检查兼容性矩阵问题: GPU 内存不足

CUDA out of memory

解决方案:

bash

# 限制 GPU 内存使用
export OLLAMA_GPU_MEMORY_FRACTION=0.7
# 减少 GPU 层数
export OLLAMA_GPU_LAYERS=20
# 使用更小的模型
ollama run gemma3:7b-q4_0

AMD GPU 问题

问题: ROCm 未安装

No HIP-capable device found

解决方案:

bash

# 安装 ROCm
sudo apt update
sudo apt install rocm-dev rocm-libs
# 添加用户到组
sudo usermod -aG render,video $USER
# 重新登录

问题: GPU 架构不支持

Unsupported GPU architecture

解决方案:

bash

# 设置 GFX 版本
export HSA_OVERRIDE_GFX_VERSION=10.3.0
# 检查支持的架构
rocminfo | grep gfx

网络问题

API 连接问题

问题: 连接被拒绝

Connection refused

解决方案:

检查服务是否运行：

bash

sudo systemctl status ollama

检查端口绑定：

bash

netstat -tulpn | grep 11434

检查防火墙设置：

bash

sudo ufw allow 11434

问题: 超时错误

Request timeout

解决方案:

bash

# 增加超时时间
export OLLAMA_REQUEST_TIMEOUT=300
# 检查网络延迟
ping localhost

代理问题

问题: 代理配置错误

Proxy authentication required

解决方案:

bash

# 设置代理认证
export https_proxy=http://username:password@proxy.example.com:8080
export http_proxy=http://username:password@proxy.example.com:8080
# 或使用无认证代理
export https_proxy=http://proxy.example.com:8080

问题: SSL 证书错误

SSL certificate verify failed

解决方案:

bash

# 添加自定义 CA 证书
export OLLAMA_CA_BUNDLE=/path/to/ca-bundle.crt
# 或临时跳过验证（不推荐）
export OLLAMA_INSECURE=1

性能问题

推理速度慢

问题: 响应时间过长 诊断步骤:

检查 GPU 使用情况：

bash

nvidia-smi  # NVIDIA
rocm-smi    # AMD

检查 CPU 使用情况：

bash

htop

检查内存使用：

bash

free -h

解决方案:

启用 GPU 加速
使用量化模型
调整批处理大小：

bash

export OLLAMA_BATCH_SIZE=512

内存泄漏

问题: 内存使用持续增长诊断:

bash

# 监控内存使用
watch -n 1 'free -h && echo "---" && ps aux | grep ollama'

解决方案:

重启 Ollama 服务：

bash

sudo systemctl restart ollama

调整模型缓存：

bash

export OLLAMA_KEEP_ALIVE=5m

限制并发请求：

bash

export OLLAMA_MAX_CONCURRENT_REQUESTS=2

日志和调试

启用详细日志

bash

# 设置调试模式
export OLLAMA_DEBUG=1
# 查看服务日志
sudo journalctl -u ollama -f
# 查看详细错误信息
ollama run gemma3 --verbose

日志文件位置

Linux:

系统日志: /var/log/ollama/
用户日志: ~/.ollama/logs/
systemd 日志: journalctl -u ollamamacOS:
应用日志: ~/Library/Logs/Ollama/
系统日志: Console.appWindows:
应用日志: %APPDATA%\Ollama\logs\
事件查看器: Windows Logs > Application

收集诊断信息

bash

#!/bin/bash
# 诊断脚本
echo "=== 系统信息 ==="
uname -a
cat /etc/os-release
echo "=== Ollama 版本 ==="
ollama --version
echo "=== GPU 信息 ==="
nvidia-smi 2>/dev/null || echo "NVIDIA GPU 未检测到"
rocm-smi 2>/dev/null || echo "AMD GPU 未检测到"
echo "=== 内存信息 ==="
free -h
echo "=== 磁盘空间 ==="
df -h
echo "=== 网络连接 ==="
netstat -tulpn | grep 11434
echo "=== 已安装模型 ==="
ollama list
echo "=== 服务状态 ==="
systemctl status ollama

Docker 问题

容器启动失败

问题: 容器无法启动

docker: Error response from daemon: could not select device driver

解决方案:

bash

# 检查 Docker 版本
docker --version
# 重新安装 NVIDIA Container Toolkit
sudo apt-get purge nvidia-container-toolkit
sudo apt-get install nvidia-container-toolkit
sudo systemctl restart docker

问题: GPU 在容器中不可用

NVIDIA-SMI has failed

解决方案:

bash

# 检查 NVIDIA Container Runtime
docker run --rm --gpus all nvidia/cuda:11.8-base-ubuntu20.04 nvidia-smi
# 重新配置 Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

容器网络问题

问题: 无法访问容器服务

curl: (7) Failed to connect to localhost port 11434

解决方案:

bash

# 检查端口映射
docker ps
# 检查容器日志
docker logs ollama
# 重新创建容器
docker stop ollama
docker rm ollama
docker run -d -p 11434:11434 --name ollama ollama/ollama

平台特定问题

Windows 问题

问题: Windows Defender 阻止

Windows protected your PC

解决方案:

点击"更多信息"
选择"仍要运行"
或添加到 Windows Defender 排除列表问题: 路径长度限制

The filename or extension is too long

解决方案:

powershell

# 启用长路径支持
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

macOS 问题

问题: 应用被阻止

"Ollama" cannot be opened because the developer cannot be verified

解决方案:

右键点击应用
选择"打开"
或在系统偏好设置中允许问题: 权限问题

Operation not permitted

解决方案:

bash

# 授予完全磁盘访问权限
# 系统偏好设置 > 安全性与隐私 > 隐私 > 完全磁盘访问权限

Linux 发行版特定问题

Ubuntu/Debian:

bash

# 依赖问题
sudo apt update
sudo apt install -f
# 仓库问题
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys <KEY>

CentOS/RHEL:

bash

# SELinux 问题
sudo setsebool -P httpd_can_network_connect 1
# 防火墙问题
sudo firewall-cmd --permanent --add-port=11434/tcp
sudo firewall-cmd --reload

获取帮助

社区支持

GitHub Issues: https://github.com/ollama/ollama/issues
Discord 社区: https://discord.gg/ollama
Reddit: r/ollama

报告问题

提交问题时请包含：

系统信息:
- 操作系统版本
- Ollama 版本
- GPU 型号和驱动版本
错误信息:
- 完整的错误消息
- 相关日志
重现步骤:
- 详细的操作步骤
- 预期结果 vs 实际结果
环境变量:
- 相关的环境变量设置

诊断信息收集

bash

# 生成诊断报告
ollama --version > diagnosis.txt
uname -a >> diagnosis.txt
nvidia-smi >> diagnosis.txt 2>&1
free -h >> diagnosis.txt
df -h >> diagnosis.txt
ollama list >> diagnosis.txt
sudo journalctl -u ollama --since "1 hour ago" >> diagnosis.txt

预防措施

定期维护

bash

# 每周执行
#!/bin/bash
# 清理未使用的模型
ollama prune
# 检查磁盘空间
df -h
# 更新 Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 重启服务
sudo systemctl restart ollama

监控脚本

bash

#!/bin/bash
# 健康检查脚本
HEALTH_URL="http://localhost:11434/api/tags"
if curl -f -s "$HEALTH_URL" > /dev/null; then
    echo "Ollama 服务正常"
else
    echo "Ollama 服务异常，尝试重启..."
    sudo systemctl restart ollama
fi

备份配置

bash

# 备份重要配置
tar -czf ollama-backup-$(date +%Y%m%d).tar.gz \
    ~/.ollama/ \
    /etc/systemd/system/ollama.service \
    /etc/environment

故障排除指南 ​

安装问题 ​

安装失败 ​

服务启动失败 ​

模型问题 ​

模型下载失败 ​

模型运行问题 ​

GPU 问题 ​

NVIDIA GPU 问题 ​

AMD GPU 问题 ​

网络问题 ​

API 连接问题 ​

代理问题 ​

性能问题 ​

推理速度慢 ​

内存泄漏 ​

日志和调试 ​

启用详细日志 ​

日志文件位置 ​

收集诊断信息 ​

Docker 问题 ​

容器启动失败 ​

容器网络问题 ​

平台特定问题 ​

Windows 问题 ​

macOS 问题 ​

Linux 发行版特定问题 ​

获取帮助 ​

社区支持 ​

报告问题 ​

诊断信息收集 ​

预防措施 ​

定期维护 ​

监控脚本 ​

备份配置 ​

故障排除指南

安装问题

安装失败

服务启动失败

模型问题

模型下载失败

模型运行问题

GPU 问题

NVIDIA GPU 问题

AMD GPU 问题

网络问题

API 连接问题

代理问题

性能问题

推理速度慢

内存泄漏

日志和调试

启用详细日志

日志文件位置

收集诊断信息

Docker 问题

容器启动失败

容器网络问题

平台特定问题

Windows 问题

macOS 问题

Linux 发行版特定问题

获取帮助

社区支持

报告问题

诊断信息收集

预防措施

定期维护

监控脚本

备份配置