大模型应用开发 / 系统课时
Docker 部署 Ollama
Docker 部署 Ollama
学习目标
完成本课后,你将能够:
- 使用 Docker 启动 CPU 版 Ollama 容器
- 通过命名卷持久化模型和配置
- 验证容器状态、端口、API 和日志
- 区分 CPU、NVIDIA GPU 与 AMD GPU 容器启动参数
容器部署解决什么问题
Docker 可以把 Ollama 二进制、运行库和基础环境封装在镜像中,降低宿主机安装差异。模型数据应单独存放在 Docker 卷中,这样删除并重建容器时不会自动删除模型。容器部署需要理解三个边界:
- 镜像保存程序和运行依赖。
- 容器是可替换的运行实例。
- 数据卷保存模型和配置,应独立于容器生命周期。

前置条件
检查 Docker:
docker version预期输出中应包含:
Client:
Version: <DOCKER_VERSION>
...
Server:
Engine:
Version: <DOCKER_VERSION>
...如果只有 Client 而没有 Server,说明 Docker 客户端存在,但守护进程没有运行或当前用户无法访问。验证容器运行能力:
docker run --rm hello-world预期输出中应包含:
Hello from Docker!若当前用户需要 sudo 才能访问 Docker,后续命令统一加 sudo,或按团队安全规范配置 Docker 用户权限。
启动 CPU 版容器
执行:
docker run -d \
--name ollama \
--restart unless-stopped \
-v ollama:/root/.ollama \
-p 11434:11434 \
ollama/ollama预期输出:
<CONTAINER_ID>参数说明:
| 参数 | 作用 |
|---|---|
-d |
在后台运行容器 |
--name ollama |
固定容器名称,便于后续管理 |
--restart unless-stopped |
Docker 启动后自动恢复,除非容器被人工停止 |
-v ollama:/root/.ollama |
使用命名卷持久化模型和配置 |
-p 11434:11434 |
把宿主机端口映射到容器端口 |
ollama/ollama |
使用官方镜像 |
检查容器:
docker ps --filter name=ollama预期输出示例:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
<ID> ollama/ollama "/bin/ollama…" <CREATED> Up <TIME> 0.0.0.0:11434->11434/tcp ollama验证 API
宿主机执行:
curl --fail --silent --show-error http://localhost:11434/api/tags未下载模型时,预期输出可能是:
{"models":[]}检查状态码:
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags预期输出:
200若 API 无法连接,依次检查:
docker ps --filter name=ollama
docker port ollama
docker logs --tail 100 ollama预期输出示例:
<容器运行状态>
11434/tcp -> 0.0.0.0:11434
<最近 100 行容器日志>验证数据卷
检查命名卷:
docker volume inspect ollama预期输出结构:
[
{
"Name": "ollama",
"Driver": "local",
"Mountpoint": "<VOLUME_PATH>",
"Scope": "local"
}
]实际 JSON 还会包含其他字段。<VOLUME_PATH> 由 Docker 管理,不应直接依赖其宿主机内部路径修改数据。查看容器挂载:
docker inspect ollama \
--format '{{range .Mounts}}{{.Type}} {{.Name}} -> {{.Destination}}{{println}}{{end}}'预期输出:
volume ollama -> /root/.ollama在容器中执行 Ollama 命令
查看版本:
docker exec ollama ollama --version预期输出:
ollama version is <VERSION>查看本地模型:
docker exec ollama ollama list预期输出示例:
NAME ID SIZE MODIFIED没有模型时通常只显示表头或空列表,具体格式随版本变化。运行模型:
docker exec -it ollama ollama run <MODEL>预期结果:
首次运行时下载 <MODEL>,完成后进入交互式会话。<MODEL> 替换为模型库中实际存在且设备能够运行的模型标签。
查看容器日志和资源
查看最近日志:
docker logs --tail 100 ollama预期输出:
<最近 100 行 Ollama 容器日志>持续跟踪:
docker logs --follow ollama预期结果:
终端持续输出新增日志,按 Control+C 结束。查看资源:
docker stats --no-stream ollama预期输出示例:
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
<ID> ollama <CPU> <MEMORY> <PERCENT> <NET> <BLOCK> <PIDS>模型未加载时占用较低;加载模型后内存或显存会明显变化。
启动 NVIDIA GPU 容器
前置条件:
- 宿主机 NVIDIA 驱动正常。
nvidia-smi可执行。- NVIDIA Container Toolkit 已安装。
- Docker 运行时已配置。
先验证容器可以访问 GPU:
docker run --rm --gpus all ubuntu nvidia-smi预期输出中应包含:
NVIDIA-SMI <VERSION>
Driver Version: <DRIVER_VERSION>
...
<GPU_NAME>停止并删除已有 CPU 容器:
docker stop ollama
docker rm ollama预期输出:
ollama
ollama命名卷不会因删除容器而自动删除。启动 GPU 容器:
docker run -d \
--gpus=all \
--name ollama \
--restart unless-stopped \
-v ollama:/root/.ollama \
-p 11434:11434 \
ollama/ollama预期输出:
<CONTAINER_ID>运行模型后验证:
docker exec ollama ollama ps预期输出示例:
NAME ID SIZE PROCESSOR CONTEXT UNTIL
<MODEL> <MODEL_ID> <SIZE> <PROCESSOR> <CONTEXT> <UNTIL>PROCESSOR 应结合实际模型和显存情况判断,不能要求所有模型都显示 100% GPU。
启动 AMD GPU 容器
Linux AMD GPU 使用 ROCm 镜像和设备映射:
docker run -d \
--device /dev/kfd \
--device /dev/dri \
--name ollama \
--restart unless-stopped \
-v ollama:/root/.ollama \
-p 11434:11434 \
ollama/ollama:rocm预期输出:
<CONTAINER_ID>如果容器无法访问 /dev/kfd 或 /dev/dri,检查宿主机驱动、设备权限以及容器进程所需的组权限。
绑定本地目录与命名卷的选择
命名卷:
-v ollama:/root/.ollama优点:
- 由 Docker 管理
- 命令简洁
- 不易因宿主机目录权限错误而失败
绑定目录:
-v /data/ollama:/root/.ollama优点:
- 数据位置明确
- 便于纳入服务器备份策略
使用绑定目录前必须创建并设置正确权限。不要在未知容器用户和权限的情况下直接把敏感系统目录挂入容器。
删除容器与删除数据的区别
只删除容器:
docker rm -f ollama预期输出:
ollama数据卷仍存在:
docker volume ls --filter name=ollama预期输出示例:
DRIVER VOLUME NAME
local ollama彻底删除模型数据:
docker volume rm ollama预期输出:
ollama该命令不可逆,会删除卷中的模型与配置。执行前必须确认容器已停止、卷不再使用,并完成必要备份。
常见部署问题
1. 容器名称冲突
表现:
Conflict. The container name "/ollama" is already in use.检查:
docker ps -a --filter name=ollama修复:启动已有容器、删除旧容器,或使用不同名称。
2. 端口已占用
检查:
docker ps --format 'table {{.Names}}\t{{.Ports}}'若宿主机 11434 已被其他服务占用,可先停止冲突服务。不要为了绕过问题随意把服务暴露到公网地址。
3. 删除容器后模型丢失
原因:启动时没有挂载数据卷,模型写入了容器可写层。修复:重建时固定使用 -v ollama:/root/.ollama,并验证挂载。
4. GPU 在宿主机可见但容器不可见
先运行:
docker run --rm --gpus all ubuntu nvidia-smi如果该命令失败,问题位于 Docker GPU 运行时,不在 Ollama 模型本身。
5. macOS Docker Desktop 无法使用本机 GPU 加速
Docker Desktop for macOS 不提供 Ollama 所需的本机 GPU 透传。需要 Apple 芯片加速时,应优先使用 macOS 原生 Ollama 应用,而不是把容器当作 GPU 方案。
本课练习
练习 1:部署 CPU 容器
任务目标:完成最小可用 Docker 部署。初始条件:Docker 服务正常。
实现要求:创建命名卷、启动容器、验证端口与 /api/tags。
验收条件:容器状态为 Up,API 返回 200,卷挂载到 /root/.ollama。
练习 2:验证数据持久化
任务目标:证明模型数据独立于容器。初始条件:容器中已下载一个测试模型。
实现要求:删除容器,使用同一数据卷重建,再检查模型列表。
验收条件:新容器仍能看到原模型,且没有重新下载完整模型文件。
练习 3:定位 GPU 不可见
任务目标:区分宿主机驱动、Docker 运行时和 Ollama 三层问题。
初始条件:NVIDIA 宿主机运行正常,但容器内没有 GPU。
实现要求:依次验证宿主机 nvidia-smi、测试容器 nvidia-smi、Ollama 容器和 ollama ps。验收条件:每一步都能根据结果明确故障所属层次。