1. 项目概述为什么选择 Docker 部署 Ollama如果你和我一样对本地运行大语言模型LLM感兴趣那么你一定听说过 Ollama。它以其简洁的命令行接口和丰富的模型库成为了许多开发者和研究者的首选工具。然而当你想在一个干净、可复现的环境中部署 Ollama或者需要在多台机器上保持一致的配置时原生的安装方式就显得有些力不从心了。依赖冲突、环境变量污染、升级回滚困难……这些都是我们实际开发中经常遇到的痛点。这正是mythrantic/ollama-docker这个项目要解决的问题。它不是一个简单的 Docker 镜像打包而是一个完整的、生产就绪的 Docker Compose 编排方案。它将 Ollama 的核心服务、Web 用户界面Ollama-WebUI、以及一个预配置了 LangChain 等工具的 Python 开发环境全部容器化。这意味着你只需要一个docker-compose up -d命令就能获得一个开箱即用、功能完整的本地 LLM 应用栈。我选择深入使用这个方案是因为它在“便捷性”和“可控性”之间找到了一个绝佳的平衡点。你既享受了 Docker 带来的环境隔离和一键部署的便利又保留了通过配置文件进行深度定制的能力。无论是想快速体验模型还是基于此进行二次开发这个项目都提供了一个极佳的起点。2. 核心架构与组件解析这个 Docker Compose 项目的精妙之处在于其清晰的服务划分和网络设计。它不是简单地把所有东西塞进一个容器而是遵循了微服务的最佳实践让每个组件各司其职。理解这个架构能帮助你在后续的定制和排错中游刃有余。2.1 服务组成与职责整个栈由三个核心服务组成它们通过 Docker 的内部网络进行通信对外则暴露必要的端口。1. Ollama 服务 (ollama)这是整个栈的大脑负责模型的拉取、加载和推理。它运行官方的ollama/ollama镜像。在默认的docker-compose.yaml中它将模型存储目录 (/root/.ollama) 挂载到了宿主机的./ollama目录下。这是一个关键设计它确保了即使容器被销毁你下载的几十GB的模型文件依然安全地保留在本地下次启动时可以直接使用无需重新下载。2. Ollama-WebUI 服务 (webui)这是用户与 Ollama 交互的图形化界面基于ghcr.io/open-webui/open-webui:main镜像。它通过内部网络连接到ollama服务通常是通过服务名ollama和端口11434。WebUI 本身不存储模型所有模型操作和对话请求都会转发给后端的 Ollama 服务。它对外暴露8080端口这就是我们通过浏览器访问的入口。3. 应用开发容器 (app)这是一个锦上添花的组件它运行一个包含 Python、LangChain、Jupyter 等工具的开发环境镜像例如python:3.11-slim。它的核心价值在于提供了一个立即可用的实验沙盒。容器内部已经通过requirements.txt安装了 LangChain 等库并且通过环境变量或 Docker 网络可以直接访问ollama服务。你可以通过docker exec进入这个容器立刻开始编写调用 Ollama 的 Python 脚本无需在本地配置任何 Python 环境。2.2 网络与数据持久化设计网络模式项目默认使用 Docker Compose 创建的默认桥接网络。在这个网络中服务之间可以使用服务名称作为主机名直接互相访问。例如在app容器里你可以用http://ollama:11434这个地址来调用 Ollama 的 API。这种设计简化了服务间通信的配置。数据持久化如前所述Ollama 的模型数据通过卷Volume或绑定挂载Bind Mount持久化到了宿主机。对于app容器项目通常也会将当前代码目录挂载到容器内的/workspace之类的位置实现代码的实时同步。WebUI 的配置和数据如对话历史也可能被持久化具体取决于所采用的 WebUI 镜像和配置。注意路径权限问题。在 Linux 系统上如果宿主机上的./ollama目录是由非 root 用户创建的而容器内的 Ollama 服务以 root 用户运行可能会因为权限问题导致无法写入模型文件。一个稳妥的解决方法是在首次启动前先手动创建目录并赋予宽松的权限mkdir -p ollama chmod 777 ollama。更安全的方式是在docker-compose.yaml中配置用户映射但这需要更深入的自定义。2.3 GPU 支持与性能考量对于拥有 NVIDIA GPU 的用户项目提供了docker-compose-ollama-gpu.yaml文件。这个文件与标准版本的主要区别在于ollama服务的配置中加入了deploy.resources.reservations.devices段并设置了runtime: nvidia。原理浅析这背后依赖的是 NVIDIA Container Toolkit之前叫 nvidia-docker2。它通过在宿主机上安装一个特殊的 Docker runtime使得容器内的进程能够直接调用宿主机 GPU 的驱动和 CUDA 库从而实现近乎原生的 GPU 计算性能。当你运行docker run --gpus all或使用上述 Compose 配置时Docker 会通过这个 runtime 启动容器并将必要的 GPU 设备文件和库文件映射到容器内。性能对比根据我的实测在支持 GPU 的配置下模型推理速度可以有数量级的提升。例如运行一个 7B 参数的模型CPU 推理可能只有每秒几个 token而使用一张中端 GPU如 RTX 3060则可以达到每秒几十个 token。这对于交互式对话或批量处理任务来说体验是天壤之别。选择建议有 NVIDIA GPU务必按照文档安装 NVIDIA Container Toolkit并使用-f docker-compose-ollama-gpu.yaml启动。这是释放 Ollama 潜力的关键。只有 CPU 或 AMD/Intel GPU使用标准的docker-compose.yaml。Ollama 也支持通过 CPU 或一些实验性的 ROCmAMD/SYCLIntel后端运行但性能会显著低于 NVIDIA GPU。对于 AMD GPU社区有相关教程但需要自行寻找和测试兼容的 Docker 镜像与驱动配置。3. 从零开始的完整部署实操理论说得再多不如动手跑一遍。下面我将带你完成一次从环境准备到模型对话的全流程部署并穿插我踩过的一些坑和对应的解决方案。3.1 基础环境准备与验证首先你需要一个安装了 Docker 和 Docker Compose 的 Linux 环境Windows/macOS 的 Docker Desktop 也内置了 Compose。1. 安装 Docker 与 Compose对于 Ubuntu/Debian 系统官方安装脚本是最快的方式# 安装 Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入 docker 组避免每次都要 sudo sudo usermod -aG docker $USER # 注销并重新登录使组生效 # 安装 Docker Compose Plugin (V2) sudo apt-get update sudo apt-get install docker-compose-plugin # 验证安装 docker compose version实操心得务必使用 Docker ComposePlugin (V2)其命令是docker compose中间没有横线。旧版的docker-compose带横线是独立的 Python 工具已逐渐被淘汰。新项目和新脚本都默认使用 V2 语法。2. 可选但强烈推荐配置 NVIDIA Container Toolkit如果你有 NVIDIA GPU这是必须的一步。项目的 README 提供了安装命令这里我补充一些上下文和验证步骤# 按照项目提供的命令安装工具包 # ... (安装命令同上文) ... # 安装后一个更全面的验证命令是 docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi这个命令会拉取一个包含 CUDA 基础环境的小镜像并运行nvidia-smi。如果成功输出 GPU 信息表则证明 Docker GPU 支持已正确配置。如果失败通常是因为 Docker 服务没有重启或者 NVIDIA 驱动未安装。请运行sudo systemctl restart docker并检查驱动nvidia-smi在宿主机能否运行。3.2 获取与配置项目1. 克隆项目并进入目录git clone https://github.com/mythrantic/ollama-docker.git cd ollama-docker此时你应该看到目录下有几个核心文件docker-compose.yaml,docker-compose-ollama-gpu.yaml,run.sh, 以及app/目录内含requirements.txt和示例代码。2. 预检查与目录准备在启动前先创建持久化目录并检查端口占用# 创建 Ollama 模型存储目录避免权限问题 mkdir -p ollama # 检查 8080 端口是否被占用Ollama-WebUI 默认端口 sudo lsof -i:8080 # 如果被占用你可以修改 docker-compose.yaml 中 webui 服务的 ports 映射例如改为 “8081:8080”3. 启动服务栈根据你的硬件情况选择命令# 如果你有 NVIDIA GPU 并已配置好 docker compose -f docker-compose-ollama-gpu.yaml up -d # 如果你只有 CPU docker compose up -d-d参数代表“后台运行”。第一次运行会拉取所有镜像需要一些时间。4. 验证服务状态使用以下命令查看容器是否正常运行docker compose ps你应该看到三个服务ollama,webui,app的状态都是Up。还可以查看实时日志来监控启动过程docker compose logs -f ollama # 重点关注 ollama 的日志看是否有错误3.3 模型管理与 WebUI 初体验服务启动后打开浏览器访问http://你的服务器IP:8080。1. 首次登录与模型下载首次访问 Ollama-WebUI通常会提示你注册或直接以管理员身份登录有些版本默认用户是admin密码在启动日志中。登录后进入Settings-Model页面。这里会列出可用的模型。你可以搜索并安装模型例如llama3.2:1b一个较小的测试模型或llama3.1:8b能力更强的模型。点击下载后任务会提交给后端的 Ollama 服务。你可以在 WebUI 的“任务”页面查看下载进度更推荐在终端查看 Ollama 容器的日志来获取更详细的信息docker compose logs -f ollama你会看到类似pulling manifest,downloading layer的日志。模型文件会保存在你之前创建的./ollama目录下。2. 进行第一次对话模型下载完成后回到 WebUI 主界面在左侧选择刚刚下载的模型。在中间的对话框里就可以开始像使用 ChatGPT 一样进行对话了。性能观察输入问题后留意回答的生成速度。如果使用了 GPU你应该能感受到流式输出非常流畅。如果是 CPU第一个 token 可能会有一段思考时间thinking...状态生成速度也较慢。3.4 深入开发容器使用 LangChain 调用 OllamaWebUI 适合交互而app容器才是进行自动化处理和集成的利器。1. 进入开发容器# 通过 exec 命令进入 app 容器的 bash 终端 docker compose exec app bash进入后你会发现身处一个干净的 Linux 环境/workspace目录下挂载着宿主机的项目文件。2. 运行示例代码查看app目录下的示例文件例如一个简单的example.pyfrom langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate # 初始化 Ollama LLM注意这里的 base_url 指向的是服务名 ‘ollama’ llm Ollama(base_urlhttp://ollama:11434, modelllama3.1:8b) # 构建一个简单的提示模板 prompt ChatPromptTemplate.from_messages([ (system, You are a helpful assistant. Respond in Chinese.), (human, {input}) ]) # 创建链 chain prompt | llm # 调用链 response chain.invoke({input: 请用一句话介绍你自己。}) print(response)在容器内运行它cd /workspace/app python example.py如果一切正常你将看到模型用中文做的自我介绍。这个例子证明了app容器内的 Python 环境可以无缝通过网络调用ollama服务。3. 使用 Jupyter Notebook 进行探索app容器可能也安装了 Jupyter。你可以启动它# 在容器内启动 Jupyter Lab允许所有 IP 访问 jupyter lab --ip0.0.0.0 --port8888 --no-browser --allow-root然后在宿主机浏览器访问http://你的服务器IP:8888注意 token 在启动日志中。这为数据分析和原型开发提供了更强大的交互环境。4. 高级配置、调优与故障排查基础部署完成后你可能需要根据自身需求进行调整。以下是几个常见的高级场景和问题解决方法。4.1 自定义配置与模型管理1. 修改 Ollama 服务配置Ollama 本身支持环境变量配置。你可以修改docker-compose.yaml中ollama服务的environment部分。例如限制 Ollama 使用的 CPU 核心数或设置监听地址services: ollama: image: ollama/ollama environment: - OLLAMA_NUM_PARALLEL2 # 限制并行请求数 - OLLAMA_HOST0.0.0.0:11434 # 明确指定监听地址默认就是如此 # ... 其他配置 ...2. 从宿主机管理模型你并不总是需要通过 WebUI 来管理模型。可以直接在宿主机上通过docker exec执行 Ollama 命令# 列出已下载的模型 docker compose exec ollama ollama list # 拉取一个新模型 docker compose exec ollama ollama pull codellama:7b # 删除一个模型 docker compose exec ollama ollama rm llama3.1:8b这种方式在脚本化自动化时非常有用。3. 使用不同的 WebUI 或版本你可能想尝试其他 WebUI 前端如open-webui的特定版本或ollama-webui的另一个分支。只需修改docker-compose.yaml中webui服务的image标签即可webui: image: ghcr.io/open-webui/open-webui:0.2.0 # 指定一个具体版本 # ... 其他配置 ...注意更换镜像后WebUI 的配置和数据格式可能不兼容最好先清理旧的卷数据。4.2 性能调优与资源限制1. 为容器分配更多资源默认情况下容器可以使用宿主机的所有资源。在生产环境或共享服务器上你可能需要限制。services: ollama: # ... 其他配置 ... deploy: # 注意在 Compose V2 中resources 放在 deploy 下更标准 resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] limits: cpus: 4.0 # 限制最多使用 4 个 CPU 核心 memory: 16G # 限制最多使用 16GB 内存对于app开发容器通常不需要太多资源可以适当限制 CPU 和内存避免其影响ollama服务。2. Ollama 模型参数调优在通过 API 调用模型时可以通过参数控制生成过程影响速度和质量llm Ollama( base_urlhttp://ollama:11434, modelllama3.1:8b, num_predict512, # 生成的最大 token 数 temperature0.7, # 创造性越低越确定 top_p0.9, # 核采样影响词的选择 )在 WebUI 的设置中通常也有类似的滑块可以调整这些参数。4.3 常见问题与故障排查实录即使按照步骤操作也可能会遇到问题。下面是我遇到过的几个典型问题及其解决方法。问题一WebUI 无法连接 Ollama提示 “Cannot connect to Ollama”现象WebUI 能打开但模型列表为空或尝试对话时报连接错误。排查步骤检查容器状态docker compose ps确认ollama和webui两个服务都是Up状态。检查 Ollama 日志docker compose logs ollama查看是否有启动错误。常见错误是模型文件损坏可以尝试删除./ollama目录下的模型文件重新下载。检查网络连通性进入webui容器内部测试连接。docker compose exec webui sh # 在容器内执行 apk add curl # 如果容器没有 curl先安装 curl http://ollama:11434/api/tags # 调用 Ollama 的 API 查看模型列表如果返回成功则网络是通的可能是 WebUI 配置问题。如果连接被拒绝或超时说明webui容器无法解析ollama这个主机名或端口不对。检查 Compose 文件确认webui服务的环境变量如OLLAMA_BASE_URL是否指向了正确的ollama:11434。问题二GPU 配置成功但推理速度依然很慢nvidia-smi显示 GPU 使用率为 0%现象使用了-gpu.yaml文件启动但模型推理时 GPU 不工作。排查步骤验证 GPU 透传在宿主机运行docker run --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi确认基础透传正常。检查 Ollama 容器内的 GPUdocker compose exec ollama nvidia-smi。如果报错“命令未找到”说明ollama/ollama基础镜像内没有nvidia-smi工具但这不绝对代表 GPU 不可用。可以安装它docker compose exec ollama apt update apt install -y nvidia-utils-535驱动版本号需匹配宿主机。检查 Ollama 是否识别到 GPU查看 Ollama 启动日志docker compose logs ollama。在开头部分寻找类似“CUDA is available”或“Using GPU”的字样。Ollama 在启动时会检测可用的计算后端。模型是否支持 GPU绝大多数主流模型都支持。可以尝试在 WebUI 或命令行中指定num_gpu参数强制使用更多 GPU 层数。问题三下载模型时网络超时或速度极慢现象拉取模型卡在某个百分比或速度只有几十 KB/s。解决方案使用镜像站Ollama 支持通过环境变量OLLAMA_MODELS设置镜像站。可以修改docker-compose.yaml为ollama服务添加环境变量environment: - OLLAMA_MODELShttps://mirror.ghproxy.com/ollama/models重启服务后重新拉取模型。注意镜像站的可用性和速度需要自行甄别。手动导入模型文件对于超大的模型如 70B可以先在网络条件好的机器上用ollama pull下载然后将~/.ollama目录下的blobs和manifests子目录打包复制到目标服务器的./ollama目录下再重启服务。Ollama 会自动识别已存在的模型文件。问题四app容器内无法安装 Python 包或运行脚本报错现象在app容器内pip install失败或运行 LangChain 脚本提示缺少模块。排查步骤检查网络容器内需要能访问外网以下载 PyPI 包。尝试ping 8.8.8.8。检查挂载确认宿主机的app/requirements.txt文件已正确挂载到容器内。进入容器查看/workspace/app/requirements.txt是否存在。重建开发环境有时容器内的 Python 环境可能混乱。最彻底的方法是删除并重建app容器docker compose stop app docker compose rm -f app # 删除容器但不删除卷你的代码在挂载卷里是安全的 docker compose up -d app # 重新创建并启动这会基于最新的Dockerfile或镜像重新构建一个干净的app环境。部署和运维这样一个由多个容器组成的服务栈遇到问题是常态。我的经验是善用docker compose logs和docker compose exec这两个命令前者帮你定位错误发生的时间点和上下文后者让你能进入“案发现场”进行实地勘察。大部分问题都能通过日志和容器内的直接测试找到根源。