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

Docker 部署 Ollama

Docker 部署 Ollama

学习目标

完成本课后,你将能够:

  • 使用 Docker 启动 CPU 版 Ollama 容器
  • 通过命名卷持久化模型和配置
  • 验证容器状态、端口、API 和日志
  • 区分 CPU、NVIDIA GPU 与 AMD GPU 容器启动参数

容器部署解决什么问题

Docker 可以把 Ollama 二进制、运行库和基础环境封装在镜像中,降低宿主机安装差异。模型数据应单独存放在 Docker 卷中,这样删除并重建容器时不会自动删除模型。容器部署需要理解三个边界:

  • 镜像保存程序和运行依赖。
  • 容器是可替换的运行实例。
  • 数据卷保存模型和配置,应独立于容器生命周期。

Ollama Docker 部署结构

前置条件

检查 Docker:

bash
docker version

预期输出中应包含:

text
Client:
 Version: <DOCKER_VERSION>
...

Server:
 Engine:
  Version: <DOCKER_VERSION>
...

如果只有 Client 而没有 Server,说明 Docker 客户端存在,但守护进程没有运行或当前用户无法访问。验证容器运行能力:

bash
docker run --rm hello-world

预期输出中应包含:

text
Hello from Docker!

若当前用户需要 sudo 才能访问 Docker,后续命令统一加 sudo,或按团队安全规范配置 Docker 用户权限。

启动 CPU 版容器

执行:

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

预期输出:

text
<CONTAINER_ID>

参数说明:

参数 作用
-d 在后台运行容器
--name ollama 固定容器名称,便于后续管理
--restart unless-stopped Docker 启动后自动恢复,除非容器被人工停止
-v ollama:/root/.ollama 使用命名卷持久化模型和配置
-p 11434:11434 把宿主机端口映射到容器端口
ollama/ollama 使用官方镜像

检查容器:

bash
docker ps --filter name=ollama

预期输出示例:

text
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

宿主机执行:

bash
curl --fail --silent --show-error http://localhost:11434/api/tags

未下载模型时,预期输出可能是:

json
{"models":[]}

检查状态码:

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

预期输出:

text
200

若 API 无法连接,依次检查:

bash
docker ps --filter name=ollama
docker port ollama
docker logs --tail 100 ollama

预期输出示例:

text
<容器运行状态>
11434/tcp -> 0.0.0.0:11434
<最近 100 行容器日志>

验证数据卷

检查命名卷:

bash
docker volume inspect ollama

预期输出结构:

json
[
  {
    "Name": "ollama",
    "Driver": "local",
    "Mountpoint": "<VOLUME_PATH>",
    "Scope": "local"
  }
]

实际 JSON 还会包含其他字段。<VOLUME_PATH> 由 Docker 管理,不应直接依赖其宿主机内部路径修改数据。查看容器挂载:

bash
docker inspect ollama \
  --format '{{range .Mounts}}{{.Type}} {{.Name}} -> {{.Destination}}{{println}}{{end}}'

预期输出:

text
volume ollama -> /root/.ollama

在容器中执行 Ollama 命令

查看版本:

bash
docker exec ollama ollama --version

预期输出:

text
ollama version is <VERSION>

查看本地模型:

bash
docker exec ollama ollama list

预期输出示例:

text
NAME    ID    SIZE    MODIFIED

没有模型时通常只显示表头或空列表,具体格式随版本变化。运行模型:

bash
docker exec -it ollama ollama run <MODEL>

预期结果:

text
首次运行时下载 <MODEL>,完成后进入交互式会话。

<MODEL> 替换为模型库中实际存在且设备能够运行的模型标签。

查看容器日志和资源

查看最近日志:

bash
docker logs --tail 100 ollama

预期输出:

text
<最近 100 行 Ollama 容器日志>

持续跟踪:

bash
docker logs --follow ollama

预期结果:

text
终端持续输出新增日志,按 Control+C 结束。

查看资源:

bash
docker stats --no-stream ollama

预期输出示例:

text
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:

bash
docker run --rm --gpus all ubuntu nvidia-smi

预期输出中应包含:

text
NVIDIA-SMI <VERSION>
Driver Version: <DRIVER_VERSION>
...
<GPU_NAME>

停止并删除已有 CPU 容器:

bash
docker stop ollama
docker rm ollama

预期输出:

text
ollama
ollama

命名卷不会因删除容器而自动删除。启动 GPU 容器:

bash
docker run -d \
  --gpus=all \
  --name ollama \
  --restart unless-stopped \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  ollama/ollama

预期输出:

text
<CONTAINER_ID>

运行模型后验证:

bash
docker exec ollama ollama ps

预期输出示例:

text
NAME       ID          SIZE      PROCESSOR    CONTEXT    UNTIL
<MODEL>    <MODEL_ID>  <SIZE>    <PROCESSOR>  <CONTEXT>  <UNTIL>

PROCESSOR 应结合实际模型和显存情况判断,不能要求所有模型都显示 100% GPU。

启动 AMD GPU 容器

Linux AMD GPU 使用 ROCm 镜像和设备映射:

bash
docker run -d \
  --device /dev/kfd \
  --device /dev/dri \
  --name ollama \
  --restart unless-stopped \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  ollama/ollama:rocm

预期输出:

text
<CONTAINER_ID>

如果容器无法访问 /dev/kfd 或 /dev/dri,检查宿主机驱动、设备权限以及容器进程所需的组权限。

绑定本地目录与命名卷的选择

命名卷:

bash
-v ollama:/root/.ollama

优点:

  • 由 Docker 管理
  • 命令简洁
  • 不易因宿主机目录权限错误而失败

绑定目录:

bash
-v /data/ollama:/root/.ollama

优点:

  • 数据位置明确
  • 便于纳入服务器备份策略

使用绑定目录前必须创建并设置正确权限。不要在未知容器用户和权限的情况下直接把敏感系统目录挂入容器。

删除容器与删除数据的区别

只删除容器:

bash
docker rm -f ollama

预期输出:

text
ollama

数据卷仍存在:

bash
docker volume ls --filter name=ollama

预期输出示例:

text
DRIVER    VOLUME NAME
local     ollama

彻底删除模型数据:

bash
docker volume rm ollama

预期输出:

text
ollama

该命令不可逆,会删除卷中的模型与配置。执行前必须确认容器已停止、卷不再使用,并完成必要备份。

常见部署问题

1. 容器名称冲突

表现:

text
Conflict. The container name "/ollama" is already in use.

检查:

bash
docker ps -a --filter name=ollama

修复:启动已有容器、删除旧容器,或使用不同名称。

2. 端口已占用

检查:

bash
docker ps --format 'table {{.Names}}\t{{.Ports}}'

若宿主机 11434 已被其他服务占用,可先停止冲突服务。不要为了绕过问题随意把服务暴露到公网地址。

3. 删除容器后模型丢失

原因:启动时没有挂载数据卷,模型写入了容器可写层。修复:重建时固定使用 -v ollama:/root/.ollama,并验证挂载。

4. GPU 在宿主机可见但容器不可见

先运行:

bash
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。验收条件:每一步都能根据结果明确故障所属层次。

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

目录与阅读设置

阅读设置

17

记录一个想法

Docker 部署 Ollama

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

登录哪都通