大模型应用开发 / 系统课时

升级、降级与完整卸载

升级、降级与完整卸载

学习目标

完成本课后,你将能够:

  • 在升级前记录版本、模型和配置状态
  • 按 Windows、macOS、Linux 和 Docker 的方式更新 Ollama
  • 在验证失败时安全回退到指定版本
  • 区分卸载程序、保留模型和彻底删除数据

版本变更前必须记录什么

升级和降级不仅影响 Ollama 二进制,还可能影响模型支持、运行后端、驱动要求、CLI 行为和资源占用。操作前至少记录:

  • 当前 Ollama 版本
  • 安装方式
  • 当前模型列表
  • 模型存储目录
  • 自定义环境变量
  • 服务配置或容器参数
  • GPU 驱动版本
  • API 基础验证结果
  • 关键业务请求的测试结果

查看版本:

bash
ollama --version

预期输出:

text
ollama version is <CURRENT_VERSION>

查看模型列表:

bash
ollama list

预期输出示例:

text
NAME       ID          SIZE      MODIFIED
<MODEL>    <MODEL_ID>  <SIZE>    <MODIFIED>

没有模型时列表可能为空。Linux 记录服务配置:

bash
systemctl cat ollama

预期输出:

text
<当前 ollama.service 和 override 配置>

Docker 记录容器配置:

bash
docker inspect ollama > ollama-container-before-upgrade.json

预期结果:

text
当前目录生成 ollama-container-before-upgrade.json。

备份配置与模型清单

备份不一定要复制全部模型。模型通常可以重新下载,但自定义模型、Modelfile、适配器、离线环境和大体积模型可能需要完整备份。至少保存模型清单:

bash
ollama list > ollama-models-before-upgrade.txt

预期结果:

text
当前目录生成 ollama-models-before-upgrade.txt。

检查文件:

bash
cat ollama-models-before-upgrade.txt

预期输出:

text
<升级前的模型列表>

Windows PowerShell:

powershell
ollama list | Out-File -Encoding utf8 "ollama-models-before-upgrade.txt"
Get-Content "ollama-models-before-upgrade.txt"

预期输出:

text
<升级前的模型列表>

完整复制模型目录前必须先停止 Ollama,避免复制过程中仍有写入。模型目录可能很大,应先检查空间和备份策略。

Windows 更新

Windows 和 macOS 桌面应用会下载更新,并在菜单中提供“Restart to update”之类的应用更新入口。也可以重新下载最新官方安装程序覆盖安装。Windows 更新流程:

  1. 记录当前版本和模型清单。
  2. 等待正在运行的请求和模型下载完成。
  3. 从系统托盘退出 Ollama。
  4. 使用应用提供的重启更新入口,或下载最新版 OllamaSetup.exe。
  5. 完成安装后重新启动 Ollama。
  6. 打开新的 PowerShell。
  7. 验证版本、端口和 API。
  8. 运行一个已有模型完成回归测试。

验证:

powershell
ollama --version
Invoke-RestMethod "http://localhost:11434/api/tags" |
    ConvertTo-Json -Depth 6

预期输出:

text
ollama version is <NEW_VERSION>
{
  "models": [
    <MODEL_ITEMS>
  ]
}

<MODEL_ITEMS> 取决于本地模型。

Windows 降级

降级应使用官方发布页中对应版本的安装资产,不应从第三方下载站获取旧安装程序。流程:

  1. 保存当前模型和配置。
  2. 退出 Ollama。
  3. 卸载当前应用,或按该版本发布说明执行覆盖安装。
  4. 安装目标旧版本。
  5. 重新启动并验证版本。
  6. 检查旧版本是否仍支持当前模型。
  7. 运行固定测试集。

验证:

powershell
ollama --version

预期输出:

text
ollama version is <TARGET_VERSION>

如果旧版无法读取新版本产生的模型或配置,应恢复备份,或重新拉取兼容模型。不要假设所有跨版本数据都能双向兼容。

macOS 更新

更新流程:

  1. 记录版本和模型清单。
  2. 从菜单栏退出 Ollama。
  3. 使用应用提供的重启更新入口,或下载最新 .dmg。
  4. 将新版应用替换到 /Applications。
  5. 启动 Ollama。
  6. 验证 CLI 链接、版本和 API。
bash
command -v ollama
ollama --version
curl --silent --output /dev/null --write-out "%{http_code}\n" \
  http://localhost:11434/api/tags

预期输出:

text
<OLLAMA_CLI_PATH>
ollama version is <NEW_VERSION>
200

macOS 降级

从官方发布页获取目标版本应用,退出当前 Ollama 后替换 /Applications/Ollama.app。降级后检查:

bash
ollama --version
ls -l "$(command -v ollama)"

预期输出:

text
ollama version is <TARGET_VERSION>
<CLI_LINK_INFORMATION>

若 CLI 链接仍指向已删除位置,重新建立指向新应用内 CLI 的链接。

Linux 更新

Linux 官方安装脚本可以重复执行以更新:

bash
curl -fsSL https://ollama.com/install.sh | sh

预期输出:

text
>>> Installing ollama to <INSTALL_PREFIX>
...
<安装完成信息>

更新后重启服务:

bash
sudo systemctl restart ollama
systemctl is-active ollama
ollama --version

预期输出:

text
active
ollama version is <NEW_VERSION>

验证 API:

bash
curl --silent --output /dev/null --write-out "%{http_code}\n" \
  http://localhost:11434/api/tags

预期输出:

text
200

Linux 安装指定版本

Linux 安装脚本支持通过 OLLAMA_VERSION 指定版本。

bash
curl -fsSL https://ollama.com/install.sh | \
  OLLAMA_VERSION=<TARGET_VERSION> sh

预期输出:

text
>>> Installing ollama to <INSTALL_PREFIX>
...
<目标版本安装完成信息>

<TARGET_VERSION> 必须替换为官方发布页中真实存在的版本号。重启并确认:

bash
sudo systemctl restart ollama
ollama --version
systemctl is-active ollama

预期输出:

text
ollama version is <TARGET_VERSION>
active

在生产服务器上,先在测试环境验证目标版本,再执行正式回退。

Docker 更新

Docker 更新的本质是拉取新镜像并重建容器。docker restart 不会更新镜像。查看当前镜像:

bash
docker inspect ollama \
  --format '{{.Config.Image}} {{.Image}}'

预期输出:

text
ollama/ollama <IMAGE_ID>

拉取最新镜像:

bash
docker pull ollama/ollama:latest

预期输出中应包含:

text
Status: Downloaded newer image for ollama/ollama:latest

若本地已是最新,也可能显示镜像已为最新版本。删除并重建容器:

bash
docker stop ollama
docker rm ollama
docker run -d \
  --name ollama \
  --restart unless-stopped \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  ollama/ollama:latest

预期输出:

text
ollama
ollama
<NEW_CONTAINER_ID>

模型保存在命名卷 ollama 中,因此重建容器后仍应存在。验证:

bash
docker exec ollama ollama --version
curl --silent --output /dev/null --write-out "%{http_code}\n" \
  http://localhost:11434/api/tags

预期输出:

text
ollama version is <NEW_VERSION>
200

Docker 固定版本和回退

使用版本标签固定镜像:

bash
docker pull ollama/ollama:<TARGET_VERSION>

预期输出:

text
<目标版本镜像拉取结果>

重建:

bash
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>

预期输出:

text
ollama
ollama
<CONTAINER_ID>

<TARGET_VERSION> 必须是官方镜像仓库中实际存在的标签。

生产环境不应长期使用无法追踪的 latest 作为唯一发布依据。应记录版本标签或镜像摘要,并通过测试后再更新。

升级后的回归检查

按以下顺序验证:

  1. 版本符合预期。
  2. 服务或容器处于运行状态。
  3. 端口 11434 正常监听。
  4. /api/tags 返回 200。
  5. 原模型仍能列出。
  6. 一个小模型可以成功加载。
  7. 固定测试提示词能得到可接受结果。
  8. GPU 使用情况与升级前一致。
  9. 日志中没有持续错误。
  10. 业务应用可以正常连接。

Linux 示例:

bash
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

预期输出:

text
ollama version is <VERSION>
active
200
<MODEL_LIST>
<最近 50 行服务日志>

Windows 卸载

通过 Windows“设置 → 应用 → 已安装的应用”找到 Ollama 并卸载。卸载程序后检查命令:

powershell
Get-Command ollama -ErrorAction SilentlyContinue

预期输出:

text
无输出。

检查默认数据目录:

powershell
Test-Path "$HOME\.ollama"

预期输出之一:

text
True

True 表示模型或配置仍存在。需要保留模型时不要删除该目录。彻底删除默认模型与配置:

powershell
Remove-Item -Recurse -Force "$HOME\.ollama"

预期结果:

text
命令正常结束,Test-Path "$HOME\.ollama" 输出 False。

若设置过 OLLAMA_MODELS,还要检查自定义目录。删除操作不可逆,应先确认备份。清理用户环境变量:

powershell
[Environment]::SetEnvironmentVariable("OLLAMA_MODELS", $null, "User")
[Environment]::SetEnvironmentVariable("OLLAMA_HOST", $null, "User")

预期结果:

text
命令正常结束;重新登录后用户级变量不再存在。

macOS 完整卸载

先从菜单栏退出 Ollama,再删除应用和 CLI 链接:

bash
sudo rm -rf /Applications/Ollama.app
sudo rm -f /usr/local/bin/ollama

预期结果:

text
命令正常结束,test -e /Applications/Ollama.app 返回非零状态。

删除应用状态和缓存:

bash
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"

预期结果:

text
命令正常结束,对应应用状态和缓存目录被删除。

只有需要彻底删除模型与配置时,才执行:

bash
rm -rf "$HOME/.ollama"

预期结果:

text
命令正常结束,test -e "$HOME/.ollama" 返回非零状态。

Linux 完整卸载

停止并禁用服务:

bash
sudo systemctl disable --now ollama

预期结果:

text
systemctl is-active ollama 输出 inactive,systemctl is-enabled ollama 输出 disabled。

删除服务文件和 override:

bash
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

预期结果:

text
systemctl status ollama 提示找不到 ollama.service。

记录二进制路径:

bash
OLLAMA_BIN="$(command -v ollama || true)"
printf '%s\n' "$OLLAMA_BIN"

预期输出:

text
<OLLAMA_BINARY_PATH>

仅当路径确认属于 Ollama 安装时,删除二进制和标准库目录:

bash
if [ -n "$OLLAMA_BIN" ]; then
  OLLAMA_PREFIX="$(dirname "$(dirname "$OLLAMA_BIN")")"
  sudo rm -f "$OLLAMA_BIN"
  sudo rm -rf "$OLLAMA_PREFIX/lib/ollama"
fi

预期结果:

text
命令正常结束,command -v ollama 不再输出路径。

删除服务用户和标准数据目录:

bash
sudo userdel ollama 2>/dev/null || true
sudo groupdel ollama 2>/dev/null || true
sudo rm -rf /usr/share/ollama

预期结果:

text
id ollama 提示用户不存在,标准模型目录被删除。

如果配置过自定义 OLLAMA_MODELS,该目录不会自动被以上命令删除,必须单独确认后处理。

Docker 完整卸载

删除容器:

bash
docker rm -f ollama

预期输出:

text
ollama

只卸载程序但保留模型时,到此停止。数据卷仍可用于后续重建。彻底删除模型数据:

bash
docker volume rm ollama

预期输出:

text
ollama

删除镜像:

bash
docker image rm ollama/ollama:latest

预期输出示例:

text
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:设计两种卸载方案

任务目标:区分保留数据和彻底删除。初始条件:选择当前平台。

实现要求:分别写出“卸载程序但保留模型”和“删除程序、模型、配置”的命令或操作。验收条件:每个删除动作都标明影响范围和不可逆数据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

升级、降级与完整卸载

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通