Docker 部署 Ollama：搭建本地大模型推理 API

Ollama 提供模型下载、运行和 HTTP API，可以为命令行工具、桌面客户端、知识库或 Agent 提供本地推理服务。本文使用 v0.33.2 对应的官方镜像 ollama/ollama:0.33.2，正式部署采用单服务 Docker Compose，并把模型与服务配置保存在独立数据卷中。

默认配置只把 API 映射到宿主机 127.0.0.1:11434，适合单机调用或放在带认证的反向代理后面。Ollama Compose 属于单机自托管方案，不提供高可用、租户隔离或应用层访问控制；不要把 11434 端口直接暴露到公网。

部署结论

项目	本文采用的值
GitHub 地址	ollama/ollama
官方镜像	ollama/ollama:0.33.2
项目版本	v0.33.2
正式部署	Docker Compose，CPU 默认路径，可选 NVIDIA 或 AMD GPU 覆盖文件
快速体验	支持：docker run，仅用于临时检查 API，不保存模型
适用范围	个人工作站、单机开发环境、可信内网推理服务
主机架构	标准镜像：linux/amd64、linux/arm64；ROCm 镜像：linux/amd64
最低资源	官方未给出统一下限；内存、显存和磁盘需求取决于模型大小、上下文长度与并发量
对外端口	127.0.0.1:11434 -> 容器 11434/tcp
持久化位置	Docker 卷 ollama-data -> /root/.ollama
依赖服务	无独立数据库、缓存或消息队列；首次拉取模型需要访问模型仓库
验证范围	官方资料和 v0.33.2 发布配置核对；Compose 静态校验；未拉取镜像、未启动容器
部署日期	2026-08-31

Compose 便于固定镜像版本、端口、数据卷、健康检查和日志轮转。docker run 示例不挂载数据卷，容器停止后不会保留模型，只适合确认当前主机能否启动 Ollama API。

运行结构

Ollama 容器在 11434/tcp 提供 HTTP API。宿主机端口默认绑定回环地址，只有本机进程能够直接访问；模型清单、模型分片和服务配置写入 /root/.ollama，由 ollama-data 卷跨容器重建保留。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
  Client[本机应用或反向代理] -->|127.0.0.1:11434| API[Ollama API]
  API --> Runtime[CPU / NVIDIA / AMD 推理]
  API --> Data[(ollama-data<br/>模型与服务配置)]
  API --> Registry[Ollama 模型仓库]

模型下载可能占用数 GB 到数十 GB 磁盘；模型加载还会占用系统内存或显存。选型时先查看模型页面给出的大小，再为数据卷、备份和升级保留余量。

部署前准备

准备一台安装了 Docker Engine 和 Docker Compose v2 的 Linux 主机。Docker Desktop 也能运行 CPU 路径，但 macOS Docker Desktop 不支持把 Apple GPU 透传给 Linux 容器；需要 Metal 加速时应使用 macOS 原生 Ollama。

docker --version
docker compose version
docker info --format '{{.Architecture}}'

确认 11434 端口没有被占用：

ss -lntp | grep ':11434'

没有输出通常表示端口空闲。已有 Ollama 或其他服务监听时，先确认进程用途，再修改 Compose 的宿主机端口；不要直接终止来源不明的进程。

GPU 路径还有额外条件：

• NVIDIA GPU 需要受支持的驱动和 NVIDIA Container Toolkit。Ollama v0.33.2 文档要求 NVIDIA compute capability 5.0+，驱动版本通常为 550 或更新；compute capability 5.0 至 6.2 需要 570 或更新。
• AMD ROCm 路径需要受支持的 AMD GPU 和 Linux ROCm v7 驱动，并让容器访问 /dev/kfd 与 /dev/dri。
• 只使用 CPU 时不需要安装 GPU 容器运行时。

Docker 快速体验

下面的容器仅用于临时体验，不挂载模型目录，不能替代后续 Compose 正式部署：

docker run -d \
  --rm \
  --name ollama-trial \
  -p 127.0.0.1:11434:11434 \
  ollama/ollama:0.33.2

等待服务启动后查询版本：

curl -fsS http://127.0.0.1:11434/api/version

响应应为 JSON，并包含 "version":"0.33.2"。检查完成后停止容器：

docker stop ollama-trial

Docker Compose 正式部署

创建工作目录

mkdir -p "$HOME/apps/ollama"
cd "$HOME/apps/ollama"

保存 Compose 配置

将下面内容保存为 $HOME/apps/ollama/compose.yaml：

services:
  ollama:
    image: ollama/ollama:0.33.2
    restart: unless-stopped
    ports:
      - "127.0.0.1:11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  ollama-data:
    name: ollama-data

/root/.ollama 来自官方 Docker 运行参数。显式卷名 ollama-data 避免 Compose 项目目录改名后生成另一份空卷；健康检查调用容器内 Ollama CLI，不依赖额外安装 curl。

校验并启动

docker compose config
docker compose pull
docker compose up -d
docker compose ps

docker compose config 应输出规范化配置且没有错误。服务启动后，docker compose ps 应显示 ollama 为 Up，健康状态随后变为 healthy。

按需启用 GPU

CPU 主配置保持不变，GPU 参数放到单独的覆盖文件中。服务器更换 GPU 或临时回退 CPU 时，不需要改动模型卷。

NVIDIA GPU

将下面内容保存为 $HOME/apps/ollama/compose.nvidia.yaml：

services:
  ollama:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities:
                - gpu

先确认 Docker 能识别 NVIDIA 运行时，再合并配置启动：

nvidia-smi
docker compose -f compose.yaml -f compose.nvidia.yaml config
docker compose -f compose.yaml -f compose.nvidia.yaml pull
docker compose -f compose.yaml -f compose.nvidia.yaml up -d

Docker Compose 的 GPU 设备预留要求 capabilities: [gpu]。多卡主机可以把 count: all 改成 device_ids，两者不能同时配置。

AMD ROCm

将下面内容保存为 $HOME/apps/ollama/compose.amd.yaml：

services:
  ollama:
    image: ollama/ollama:0.33.2-rocm
    devices:
      - /dev/kfd:/dev/kfd
      - /dev/dri:/dev/dri

v0.33.2 官方发布工作流为 ROCm 构建追加 -rocm 后缀。ROCm 镜像只构建 linux/amd64，ARM64 主机不要使用这条路径。

rocminfo
docker compose -f compose.yaml -f compose.amd.yaml config
docker compose -f compose.yaml -f compose.amd.yaml pull
docker compose -f compose.yaml -f compose.amd.yaml up -d

SELinux 拒绝设备访问时，先检查审计日志。Ollama 硬件文档给出的主机级开关是 sudo setsebool container_use_devices=1；执行前应确认当前发行版使用 SELinux，不能把该命令当成所有 Linux 的通用步骤。

GPU 部署后，所有会重新合并或重建服务的 config、pull、up 命令都必须继续带上同一份覆盖文件。遗漏 compose.nvidia.yaml 或 compose.amd.yaml 会让新容器按 CPU 主配置启动。ps、logs、exec 和 restart 只操作已经创建的服务，可以直接使用主配置。

首次下载并运行模型

Ollama 服务启动后还没有本地模型。以下命令下载官方 Docker 文档示例采用的 llama3.2：

cd "$HOME/apps/ollama"
docker compose exec ollama ollama pull llama3.2
docker compose exec ollama ollama list

下载完成后，模型清单应出现 llama3.2、内容摘要和磁盘大小。随后运行一次非交互提示：

docker compose exec ollama ollama run llama3.2 "只回复：Ollama 已就绪"

模型大小和首次加载时间取决于具体标签与硬件。资源不足时选择更小的模型，而不是继续提高并发或上下文长度。

验证部署结果

下面四组检查由读者在目标主机执行。本文没有启动容器，因此预期结果是验收标准，不是本文的实测记录。

容器状态

cd "$HOME/apps/ollama"
docker compose ps

成功状态应为 Up 和 healthy。容器反复重启时直接查看日志，不要继续拉取模型。

应用响应

先验证版本和模型列表：

curl -fsS http://127.0.0.1:11434/api/version
curl -fsS http://127.0.0.1:11434/api/tags

第一个响应应包含 Ollama 版本；第二个响应应包含 models 数组。再调用一次生成接口：

curl -fsS http://127.0.0.1:11434/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"model":"llama3.2","prompt":"只回复 ok","stream":false}'

成功响应是 JSON，包含 response、done 等字段。404 或模型不存在错误通常表示模型名不匹配，应先运行 ollama list。

日志与健康状态

docker compose logs --tail=100 ollama
docker compose exec ollama ollama list

日志不应持续出现端口绑定、模型文件权限或 GPU 初始化错误。使用 GPU 运行过一次模型后，再检查实际处理器分配：

docker compose exec ollama ollama ps

PROCESSOR 列显示 100% GPU 才代表模型完整加载到 GPU；100% CPU 说明当前请求没有使用 GPU，混合百分比表示模型分布在系统内存与显存中。

持久化

先确认 ollama list 中存在已下载模型，再强制重建应用容器：

docker compose exec ollama ollama list
docker compose up -d --force-recreate ollama
docker compose exec ollama ollama list

重建前后应看到相同模型。第二次清单为空时，检查 Compose 是否仍把 ollama-data 挂载到 /root/.ollama，并用 docker volume inspect ollama-data 确认实际卷。

日常运维

cd "$HOME/apps/ollama"

# 查看状态
docker compose ps

# 查看最近日志
docker compose logs --tail=100 ollama

# 重启服务
docker compose restart ollama

# 查看本地模型
docker compose exec ollama ollama list

# 查看已加载模型及 CPU/GPU 分配
docker compose exec ollama ollama ps

不要把无边界的 docker compose logs -f 当作唯一监控方式。长期运行至少要监控容器健康、11434 响应、宿主机磁盘、内存或显存，以及模型请求错误率。

备份与恢复

ollama-data 保存模型文件和服务配置。模型通常可以重新下载，但私有模型、导入模型、服务配置和密钥文件可能无法从公共仓库恢复。备份前停止服务写入，换取一致的卷快照。

备份数据卷

下面使用一次性 Alpine 容器读取数据卷并生成带时间戳的压缩包：

cd "$HOME/apps/ollama"
mkdir -p backups
BACKUP_NAME="ollama-data-$(date +%Y%m%d-%H%M%S).tar.gz"

docker compose stop ollama
docker run --rm \
  -v ollama-data:/source:ro \
  -v "$PWD/backups":/backup \
  -e BACKUP_NAME="$BACKUP_NAME" \
  alpine:3.22 \
  sh -c 'tar -czf "/backup/$BACKUP_NAME" -C /source .'
docker compose start ollama

test -s "backups/$BACKUP_NAME"
tar -tzf "backups/$BACKUP_NAME" | head

test -s 成功且归档清单可读，只证明备份文件存在、格式可读；可靠备份还需要复制到另一块存储，并定期完成恢复演练。

恢复到新数据卷

恢复会中断服务。下面创建新卷 ollama-data-restored，不会覆盖现有 ollama-data，因此失败时仍可切回原卷。

cd "$HOME/apps/ollama"
ls -1 backups/ollama-data-*.tar.gz
read -r -p "输入要恢复的备份文件名：" RESTORE_FILE
test -f "backups/$RESTORE_FILE"

docker compose down
docker volume create ollama-data-restored
docker run --rm \
  -v ollama-data-restored:/target \
  -v "$PWD/backups":/backup:ro \
  -e RESTORE_FILE="$RESTORE_FILE" \
  alpine:3.22 \
  sh -c 'tar -xzf "/backup/$RESTORE_FILE" -C /target'

把 compose.yaml 末尾的卷名从 ollama-data 改为 ollama-data-restored：

volumes:
  ollama-data:
    name: ollama-data-restored

重新启动并核对模型：

docker compose up -d
docker compose ps
docker compose exec ollama ollama list

确认模型可列出且生成请求成功后，再决定是否保留原卷。本文不提供自动删除原卷的命令，避免在恢复尚未验证时丢失回退点。

升级与回滚

升级前阅读 Ollama Releases，确认目标版本的配置变化和硬件要求，然后完成数据卷备份。

1. 记录当前镜像 ollama/ollama:0.33.2 和 docker compose exec ollama ollama list 输出。
2. 备份 ollama-data，并确认压缩包可列出内容。
3. 把 compose.yaml 中的镜像标签改为目标版本，不要改成浮动的 latest。
4. 拉取新镜像、重建服务并执行四类验收。

docker compose config
docker compose pull
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:11434/api/version
docker compose exec ollama ollama list

NVIDIA 或 AMD 部署应把上述 config、pull、up 命令改为包含对应覆盖文件的形式；升级期间不能省略原有 GPU 配置。

需要回滚程序时，把镜像标签改回 0.33.2，再运行 docker compose pull 和 docker compose up -d。官方没有承诺任意新版本的数据都能被旧版本读取；如果升级后模型或配置格式发生不兼容变化，应按上一节恢复升级前备份到新数据卷，再由旧镜像验证。

安全边界

• 保留 127.0.0.1:11434:11434 可以阻止局域网和公网直接访问 API。需要局域网访问时，优先绑定服务器的具体内网 IP，并配合防火墙限制来源网段。
• Ollama 本地 API 的官方 OpenAPI 定义没有应用层认证要求。跨主机访问应放在 VPN、SSH 隧道或带 TLS 与身份认证的反向代理后面。
• 不要为了浏览器集成把 OLLAMA_ORIGINS=* 作为默认配置。只添加实际需要的来源，减少任意网页调用本地模型的风险。
• 代理只配置 HTTPS_PROXY。Ollama 官方 FAQ 明确提示不要为模型拉取设置 HTTP_PROXY，错误的 HTTP_PROXY 可能干扰客户端连接服务。
• 模型可能包含受限许可或敏感训练内容。部署方仍需核对模型许可、数据处理边界和输出使用规则。
• Docker 卷备份可能包含私有模型、服务配置和密钥文件，应加密存储并限制访问权限。

常见问题

curl 无法连接 11434

先看容器状态和最近日志：

docker compose ps
docker compose logs --tail=100 ollama

本机调用必须访问 127.0.0.1:11434。其他机器无法访问是默认安全行为；确需内网共享时，将端口绑定改为服务器的具体内网 IP，并同步配置防火墙。

模型下载超时或中断

确认宿主机能访问模型仓库，并检查 Docker daemon 的 DNS 与代理设置。容器代理只设置 HTTPS_PROXY，例如在 Compose 服务中加入：

services:
  ollama:
    environment:
      HTTPS_PROXY: https://proxy.example.com

企业代理使用自签 CA 时，需要构建包含 CA 证书的派生镜像；不要通过关闭 TLS 校验绕过证书问题。

NVIDIA GPU 已安装但模型仍使用 CPU

依次检查主机驱动、NVIDIA Container Toolkit、覆盖文件是否参与启动，以及模型实际处理器分配：

nvidia-smi
docker compose -f compose.yaml -f compose.nvidia.yaml config
docker compose -f compose.yaml -f compose.nvidia.yaml up -d
docker compose exec ollama ollama ps

ollama ps 需要在模型加载期间检查。显存不足时，Ollama 可能把部分或全部模型放到系统内存。

Docker Desktop for Mac 没有使用 Apple GPU

macOS Docker Desktop 缺少 Ollama 所需的 GPU 透传，Linux 容器只能走 CPU。需要 Apple Metal 加速时，安装 macOS 原生 Ollama，并让容器化客户端通过宿主机地址访问原生服务。

重建容器后模型消失

检查当前配置和数据卷：

docker compose config
docker volume inspect ollama-data
docker compose exec ollama ollama list

常见原因是启动了另一份 Compose 配置、改过显式卷名，或临时 docker run 容器从未挂载 /root/.ollama。不要在确认卷内容前执行卷清理命令。

总结

Ollama v0.33.2 可以用单服务 Compose 提供本地推理 API。默认绑定回环地址、固定镜像版本、挂载 ollama-data 并设置健康检查，能够覆盖单机自托管的基础运行需求；NVIDIA 与 AMD 参数通过独立覆盖文件启用，便于保留 CPU 回退路径。公开或多人使用仍需要额外的认证、TLS、访问控制、容量评估和监控。

本文完成官方文档、Release、Dockerfile、镜像标签生成规则与 Compose 结构核对。当前环境无法连接 Docker daemon，Docker Hub Registry 元数据查询也超时，因此没有拉取镜像、检查远端 manifest、启动容器或运行模型；运行时验收需要在目标 Linux 主机执行。

参考资料

• Ollama GitHub 仓库
• Ollama v0.33.2 Release
• Ollama v0.33.2 Dockerfile
• Ollama v0.33.2 发布工作流
• Ollama 官方 Docker 文档
• Ollama API 介绍
• Ollama API：列出模型
• Ollama API：拉取模型
• Ollama API：获取版本
• Ollama FAQ
• Ollama 硬件支持
• Ollama 官方镜像
• Docker Compose GPU 支持