大模型应用开发 / 系统课时
升级、降级与完整卸载
升级、降级与完整卸载
学习目标
完成本课后,你将能够:
- 在升级前记录版本、模型和配置状态
- 按 Windows、macOS、Linux 和 Docker 的方式更新 Ollama
- 在验证失败时安全回退到指定版本
- 区分卸载程序、保留模型和彻底删除数据
版本变更前必须记录什么
升级和降级不仅影响 Ollama 二进制,还可能影响模型支持、运行后端、驱动要求、CLI 行为和资源占用。操作前至少记录:
- 当前 Ollama 版本
- 安装方式
- 当前模型列表
- 模型存储目录
- 自定义环境变量
- 服务配置或容器参数
- GPU 驱动版本
- API 基础验证结果
- 关键业务请求的测试结果
查看版本:
ollama --version预期输出:
ollama version is <CURRENT_VERSION>查看模型列表:
ollama list预期输出示例:
NAME ID SIZE MODIFIED
<MODEL> <MODEL_ID> <SIZE> <MODIFIED>没有模型时列表可能为空。Linux 记录服务配置:
systemctl cat ollama预期输出:
<当前 ollama.service 和 override 配置>Docker 记录容器配置:
docker inspect ollama > ollama-container-before-upgrade.json预期结果:
当前目录生成 ollama-container-before-upgrade.json。备份配置与模型清单
备份不一定要复制全部模型。模型通常可以重新下载,但自定义模型、Modelfile、适配器、离线环境和大体积模型可能需要完整备份。至少保存模型清单:
ollama list > ollama-models-before-upgrade.txt预期结果:
当前目录生成 ollama-models-before-upgrade.txt。检查文件:
cat ollama-models-before-upgrade.txt预期输出:
<升级前的模型列表>Windows PowerShell:
ollama list | Out-File -Encoding utf8 "ollama-models-before-upgrade.txt"
Get-Content "ollama-models-before-upgrade.txt"预期输出:
<升级前的模型列表>完整复制模型目录前必须先停止 Ollama,避免复制过程中仍有写入。模型目录可能很大,应先检查空间和备份策略。
Windows 更新
Windows 和 macOS 桌面应用会下载更新,并在菜单中提供“Restart to update”之类的应用更新入口。也可以重新下载最新官方安装程序覆盖安装。Windows 更新流程:
- 记录当前版本和模型清单。
- 等待正在运行的请求和模型下载完成。
- 从系统托盘退出 Ollama。
- 使用应用提供的重启更新入口,或下载最新版
OllamaSetup.exe。 - 完成安装后重新启动 Ollama。
- 打开新的 PowerShell。
- 验证版本、端口和 API。
- 运行一个已有模型完成回归测试。
验证:
ollama --version
Invoke-RestMethod "http://localhost:11434/api/tags" |
ConvertTo-Json -Depth 6预期输出:
ollama version is <NEW_VERSION>
{
"models": [
<MODEL_ITEMS>
]
}<MODEL_ITEMS> 取决于本地模型。
Windows 降级
降级应使用官方发布页中对应版本的安装资产,不应从第三方下载站获取旧安装程序。流程:
- 保存当前模型和配置。
- 退出 Ollama。
- 卸载当前应用,或按该版本发布说明执行覆盖安装。
- 安装目标旧版本。
- 重新启动并验证版本。
- 检查旧版本是否仍支持当前模型。
- 运行固定测试集。
验证:
ollama --version预期输出:
ollama version is <TARGET_VERSION>如果旧版无法读取新版本产生的模型或配置,应恢复备份,或重新拉取兼容模型。不要假设所有跨版本数据都能双向兼容。
macOS 更新
更新流程:
- 记录版本和模型清单。
- 从菜单栏退出 Ollama。
- 使用应用提供的重启更新入口,或下载最新
.dmg。 - 将新版应用替换到
/Applications。 - 启动 Ollama。
- 验证 CLI 链接、版本和 API。
command -v ollama
ollama --version
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags预期输出:
<OLLAMA_CLI_PATH>
ollama version is <NEW_VERSION>
200macOS 降级
从官方发布页获取目标版本应用,退出当前 Ollama 后替换 /Applications/Ollama.app。降级后检查:
ollama --version
ls -l "$(command -v ollama)"预期输出:
ollama version is <TARGET_VERSION>
<CLI_LINK_INFORMATION>若 CLI 链接仍指向已删除位置,重新建立指向新应用内 CLI 的链接。
Linux 更新
Linux 官方安装脚本可以重复执行以更新:
curl -fsSL https://ollama.com/install.sh | sh预期输出:
>>> Installing ollama to <INSTALL_PREFIX>
...
<安装完成信息>更新后重启服务:
sudo systemctl restart ollama
systemctl is-active ollama
ollama --version预期输出:
active
ollama version is <NEW_VERSION>验证 API:
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags预期输出:
200Linux 安装指定版本
Linux 安装脚本支持通过 OLLAMA_VERSION 指定版本。
curl -fsSL https://ollama.com/install.sh | \
OLLAMA_VERSION=<TARGET_VERSION> sh预期输出:
>>> Installing ollama to <INSTALL_PREFIX>
...
<目标版本安装完成信息><TARGET_VERSION> 必须替换为官方发布页中真实存在的版本号。重启并确认:
sudo systemctl restart ollama
ollama --version
systemctl is-active ollama预期输出:
ollama version is <TARGET_VERSION>
active在生产服务器上,先在测试环境验证目标版本,再执行正式回退。
Docker 更新
Docker 更新的本质是拉取新镜像并重建容器。docker restart 不会更新镜像。查看当前镜像:
docker inspect ollama \
--format '{{.Config.Image}} {{.Image}}'预期输出:
ollama/ollama <IMAGE_ID>拉取最新镜像:
docker pull ollama/ollama:latest预期输出中应包含:
Status: Downloaded newer image for ollama/ollama:latest若本地已是最新,也可能显示镜像已为最新版本。删除并重建容器:
docker stop ollama
docker rm ollama
docker run -d \
--name ollama \
--restart unless-stopped \
-v ollama:/root/.ollama \
-p 11434:11434 \
ollama/ollama:latest预期输出:
ollama
ollama
<NEW_CONTAINER_ID>模型保存在命名卷 ollama 中,因此重建容器后仍应存在。验证:
docker exec ollama ollama --version
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags预期输出:
ollama version is <NEW_VERSION>
200Docker 固定版本和回退
使用版本标签固定镜像:
docker pull ollama/ollama:<TARGET_VERSION>预期输出:
<目标版本镜像拉取结果>重建:
docker stop ollama
docker rm ollama
docker run -d \
--name ollama \
--restart unless-stopped \
-v ollama:/root/.ollama \
-p 11434:11434 \
ollama/ollama:<TARGET_VERSION>预期输出:
ollama
ollama
<CONTAINER_ID><TARGET_VERSION> 必须是官方镜像仓库中实际存在的标签。
生产环境不应长期使用无法追踪的 latest 作为唯一发布依据。应记录版本标签或镜像摘要,并通过测试后再更新。
升级后的回归检查
按以下顺序验证:
- 版本符合预期。
- 服务或容器处于运行状态。
- 端口
11434正常监听。 /api/tags返回200。- 原模型仍能列出。
- 一个小模型可以成功加载。
- 固定测试提示词能得到可接受结果。
- GPU 使用情况与升级前一致。
- 日志中没有持续错误。
- 业务应用可以正常连接。
Linux 示例:
ollama --version
systemctl is-active ollama
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags
ollama list
sudo journalctl -u ollama -n 50 --no-pager预期输出:
ollama version is <VERSION>
active
200
<MODEL_LIST>
<最近 50 行服务日志>Windows 卸载
通过 Windows“设置 → 应用 → 已安装的应用”找到 Ollama 并卸载。卸载程序后检查命令:
Get-Command ollama -ErrorAction SilentlyContinue预期输出:
无输出。检查默认数据目录:
Test-Path "$HOME\.ollama"预期输出之一:
TrueTrue 表示模型或配置仍存在。需要保留模型时不要删除该目录。彻底删除默认模型与配置:
Remove-Item -Recurse -Force "$HOME\.ollama"预期结果:
命令正常结束,Test-Path "$HOME\.ollama" 输出 False。若设置过 OLLAMA_MODELS,还要检查自定义目录。删除操作不可逆,应先确认备份。清理用户环境变量:
[Environment]::SetEnvironmentVariable("OLLAMA_MODELS", $null, "User")
[Environment]::SetEnvironmentVariable("OLLAMA_HOST", $null, "User")预期结果:
命令正常结束;重新登录后用户级变量不再存在。macOS 完整卸载
先从菜单栏退出 Ollama,再删除应用和 CLI 链接:
sudo rm -rf /Applications/Ollama.app
sudo rm -f /usr/local/bin/ollama预期结果:
命令正常结束,test -e /Applications/Ollama.app 返回非零状态。删除应用状态和缓存:
rm -rf "$HOME/Library/Application Support/Ollama"
rm -rf "$HOME/Library/Saved Application State/com.electron.ollama.savedState"
rm -rf "$HOME/Library/Caches/com.electron.ollama"
rm -rf "$HOME/Library/Caches/ollama"
rm -rf "$HOME/Library/WebKit/com.electron.ollama"预期结果:
命令正常结束,对应应用状态和缓存目录被删除。只有需要彻底删除模型与配置时,才执行:
rm -rf "$HOME/.ollama"预期结果:
命令正常结束,test -e "$HOME/.ollama" 返回非零状态。Linux 完整卸载
停止并禁用服务:
sudo systemctl disable --now ollama预期结果:
systemctl is-active ollama 输出 inactive,systemctl is-enabled ollama 输出 disabled。删除服务文件和 override:
sudo rm -f /etc/systemd/system/ollama.service
sudo rm -rf /etc/systemd/system/ollama.service.d
sudo systemctl daemon-reload
sudo systemctl reset-failed预期结果:
systemctl status ollama 提示找不到 ollama.service。记录二进制路径:
OLLAMA_BIN="$(command -v ollama || true)"
printf '%s\n' "$OLLAMA_BIN"预期输出:
<OLLAMA_BINARY_PATH>仅当路径确认属于 Ollama 安装时,删除二进制和标准库目录:
if [ -n "$OLLAMA_BIN" ]; then
OLLAMA_PREFIX="$(dirname "$(dirname "$OLLAMA_BIN")")"
sudo rm -f "$OLLAMA_BIN"
sudo rm -rf "$OLLAMA_PREFIX/lib/ollama"
fi预期结果:
命令正常结束,command -v ollama 不再输出路径。删除服务用户和标准数据目录:
sudo userdel ollama 2>/dev/null || true
sudo groupdel ollama 2>/dev/null || true
sudo rm -rf /usr/share/ollama预期结果:
id ollama 提示用户不存在,标准模型目录被删除。如果配置过自定义 OLLAMA_MODELS,该目录不会自动被以上命令删除,必须单独确认后处理。
Docker 完整卸载
删除容器:
docker rm -f ollama预期输出:
ollama只卸载程序但保留模型时,到此停止。数据卷仍可用于后续重建。彻底删除模型数据:
docker volume rm ollama预期输出:
ollama删除镜像:
docker image rm ollama/ollama:latest预期输出示例:
Untagged: ollama/ollama:latest
Deleted: sha256:<IMAGE_DIGEST>如果镜像仍被其他容器引用,Docker 会拒绝删除,应先检查相关容器,而不是直接使用强制参数。
常见版本管理错误
1. 升级前没有记录版本
结果:出现问题后无法确认是否真正升级,也无法选择回退目标。
修复:把版本、模型、服务配置和测试结果纳入变更记录。
2. 把重启当作更新
systemctl restart、docker restart 和重启桌面应用都只重启当前程序,不会自动替换为指定新版本。
3. 降级后不做模型兼容验证
旧版本可能不支持新模型格式或新能力。必须用现有模型和固定测试集进行验证。
4. 卸载程序时误删模型
程序目录和模型目录是两类数据。先决定“保留数据”还是“彻底清理”,再执行删除。
5. 生产环境直接跟随 latest
没有版本固定和回归测试时,无法稳定复现部署。容器和服务器都应记录明确版本。
本课练习
练习 1:制作升级前清单
任务目标:建立可回退的升级记录。初始条件:当前 Ollama 正常运行并已有模型。
实现要求:记录版本、模型、目录、环境变量、服务配置和 API 验证结果。
验收条件:另一位维护者可以仅根据清单恢复原运行方式。
练习 2:完成一次可回退更新
任务目标:验证更新流程。初始条件:选择测试环境或非关键设备。
实现要求:升级 Ollama,完成版本、API、模型、GPU 和固定提示词回归检查。
验收条件:保存升级前后对比;任一关键检查失败时有明确回退步骤。
练习 3:设计两种卸载方案
任务目标:区分保留数据和彻底删除。初始条件:选择当前平台。
实现要求:分别写出“卸载程序但保留模型”和“删除程序、模型、配置”的命令或操作。验收条件:每个删除动作都标明影响范围和不可逆数据。