Windows 11 + WSL2 + Docker Compose（Ollama + Open WebUI） 环境整理的完整操作手册，涵盖日常使用、故障处理、模型管理以及卸载全流程。

一、日常管理

所有操作均在 WSL 终端内执行，请先进入项目目录：

cd ~/ollama-server

1. 启动所有服务

docker compose up -d
  • -d 表示后台运行。
  • 该命令会同时启动 ollama 和 open-webui 两个容器。
  • 如果某些容器已经存在，会直接重启它们。

2. 停止所有服务

docker compose down
  • 此命令会停止并删除容器，但不会删除模型数据和 WebUI 用户数据（数据保存在卷里）。

3. 仅重启某个服务

docker compose restart ollama          # 重启 Ollama
docker compose restart open-webui      # 重启 WebUI

4. 查看运行状态

docker ps

输出列表中应包含 ollama 和 open-webui 两个容器。

5. 查看日志

# 查看所有容器日志（实时滚动）
docker compose logs -f

# 仅查看 Ollama 日志
docker compose logs -f ollama

# 仅查看 WebUI 日志
docker compose logs -f open-webui

按 Ctrl + C 退出日志追踪。

6. 更新镜像与容器

当 Ollama 或 Open WebUI 发布新版本时：

# 拉取最新镜像
docker compose pull

# 使用新镜像重建并启动容器
docker compose up -d

旧容器会被自动替换，模型数据和用户数据不会丢失。

7. 磁盘空间管理

  • 模型文件保存在 Docker 卷 ollama_data 中，路径类似：
    \\wsl$\Ubuntu-22.04\var\lib\docker\volumes\ollama_data\_data

  • 查看模型占用空间：

    docker exec -it ollama ollama list

    （列表不直接显示大小，但可通过删除不用的模型来释放空间）

  • 如果 WSL2 虚拟磁盘整体空间不足，可参考官方文档进行压缩，但一般正常使用不会占满。

二、故障排查与常见问题

问题 1：Docker 守护进程未运行

现象：执行 docker 命令提示 Cannot connect to the Docker daemon。
解决：启动 Docker Desktop（Windows 端），并确保 WSL 集成已启用。在 WSL 终端里可先运行：

sudo service docker start    # 适用于在 WSL 内安装的 Docker 引擎

如果使用 Docker Desktop，通常只需打开 Windows 上的 Docker Desktop 即可。

问题 2：容器中无法使用 GPU（nvidia-smi 不显示 ollama 进程或报错）

现象：Ollama 只使用 CPU，推理速度极慢，且 docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi 报错或看不到 GPU。
解决步骤：

  1. 检查 Windows 显卡驱动版本 ≥ 550。
  2. 确认在 WSL 中已安装 nvidia-container-toolkit 并配置 Docker 运行时：
    nvidia-ctk runtime configure --runtime=docker
sudo service docker restart
  3. 检查 docker-compose.yml 中 Ollama 服务是否包含 GPU 预留：
    deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1
          capabilities: [gpu]
  4. 如果上述都正确，尝试重启整个 WSL 发行版（在 PowerShell 中执行 wsl --shutdown，然后重新打开 WSL）。

问题 3：模型下载失败或中断

现象：docker exec -it ollama ollama pull <模型名> 长时间卡住或提示网络错误。
解决：

  • 检查网络连接，特别是访问 registry.ollama.ai 的能力（某些网络环境可能需要代理）。
  • 手动重试命令，Ollama 支持断点续传。
  • 若始终失败，可从 HuggingFace 手动下载 .gguf 文件，然后通过 Modelfile 导入。但通常简单重试即可。

问题 4：模型响应慢或内存不足

现象：14B 模型生成速度 < 5 token/s，或容器频繁重启。
原因分析：8GB 显存只能全 GPU 跑 7B 量化模型。14B 模型需要 CPU 参与混合推理，速度受 CPU 性能影响；若内存不足，可能触发 OOM。
优化建议：

  • 使用 7B 模型作为常用服务，14B 用于偶尔的低频任务。
  • 在 docker-compose.yml 中为 Ollama 设置 OLLAMA_NUM_GPU=999（强制把能放进 GPU 的层都放进去，但可能导致显存溢出，建议只对 7B 模型使用）。
  • 缩短上下文长度：在 API 调用时指定 max_tokens 或通过 Modelfile 设置较小的 num_ctx。

问题 5：Open WebUI 无法连接 Ollama

现象：网页界面显示“无法连接到 Ollama”或模型列表为空。
排查步骤：

  1. 确认 Ollama 容器正在运行：docker ps | grep ollama
  2. 检查 docker-compose.yml 中 open-webui 的 OLLAMA_BASE_URL 是否正确设置为 http://ollama:11434（如果两个容器在同一个 compose 网络内，直接用服务名）。
  3. 如果 WebUI 是单独启动的容器（不在同一 compose），确保它的 OLLAMA_BASE_URL 指向宿主机 IP（如 http://host.docker.internal:11434），且防火墙放行 11434 端口。
  4. 在 WSL 中测试 Ollama 直接可达：curl http://localhost:11434，应返回 Ollama is running。

问题 6：端口冲突

现象：启动容器时报错 port is already allocated。
解决：宿主机上 11434 或 3000 端口已被其他程序占用。

  • 查找占用端口的进程：
    sudo lsof -i :11434
sudo lsof -i :3000
  • 修改 docker-compose.yml 中的端口映射，例如将 WebUI 的宿主机端口改为 3001:8080。

问题 7：容器意外退出

现象：docker ps -a 显示容器 Exited。
排查：

docker compose logs ollama        # 查看 Ollama 日志
docker compose logs open-webui    # 查看 WebUI 日志

根据错误提示处理。常见原因：显存不足导致 CUDA 错误、配置错误、镜像版本不兼容。

三、大模型下载与更换

1. 列出已下载的模型

docker exec -it ollama ollama list

2. 下载新模型

docker exec -it ollama ollama pull <模型名称>

推荐模型示例：

  • qwen2.5:7b-instruct-q4_K_M
  • qwen2.5:14b
  • llama3.1:8b
  • deepseek-r1:14b
  • nomic-embed-text（用于 RAG 嵌入）

3. 删除不需要的模型

docker exec -it ollama ollama rm <模型名称>

注意：删除后磁盘空间会立即释放。

4. 在 API 调用时切换模型

只需在请求 JSON 的 model 字段中填入已下载的模型名：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-r1:14b", "messages":[{"role":"user","content":"你好"}]}'

5. 在 Open WebUI 界面中切换

登录 http://localhost:3000，在聊天框左上角的下拉菜单中选择模型即可实时切换，无需重启任何服务。

6. 自定义模型（使用 Modelfile）

如果你从 HuggingFace 下载了特定的 .gguf 文件，可以创建 Modelfile 并导入：

# 将 .gguf 文件放入 WSL 的某个目录，例如 ~/models
# 创建 Modelfile，内容例如：
FROM ~/models/your-model.gguf
TEMPLATE """<|user|>
{{ .Prompt }}<|end|>
<|assistant|>"""

# 导入模型
docker exec -it ollama ollama create my-custom-model -f /path/to/Modelfile

（注意：路径需要在容器内部可访问，建议将文件映射进容器或使用 -v 挂载目录）

四、完全卸载（清理所有相关组件）

如果你决定不再使用本地 AI 服务，可以彻底清除所有容器、数据、镜像，甚至整个 WSL 环境。

1. 停止并删除容器和数据卷

进入 compose 项目目录：

cd ~/ollama-server
docker compose down -v   # -v 会同时删除所有关联的卷（包含模型和 WebUI 数据）

确认删除：

  • Docker 卷 ollama_data 和 open-webui_data 会被移除，所有下载的模型和聊天记录永久删除。

2. 删除 Docker 镜像（可选，释放磁盘空间）

docker rmi ollama/ollama:latest
docker rmi ghcr.io/open-webui/open-webui:main

如果还有其他镜像不需要，可以用 docker image prune -a 清理所有未使用的镜像。

3. 删除项目目录

rm -rf ~/ollama-server

4. 卸载 Docker Desktop（如果不再需要 Docker）

在 Windows 上通过 设置 → 应用 → 应用和功能 找到 Docker Desktop，点击卸载。
卸载后，WSL 中的 Docker 组件也会被移除（但 WSL 发行版本身依然存在）。

5. 移除 WSL2 发行版（可选，彻底清除 Linux 环境）

在 PowerShell（管理员）中：

# 列出所有 WSL 发行版
wsl -l -v

# 注销 Ubuntu-22.04（请根据实际名称修改）
wsl --unregister Ubuntu-22.04

警告：此操作会删除整个 WSL 发行版及其所有文件，包括你在这台机器上的其他 Linux 数据。

6. 关闭 WSL2 功能（极端的完全清理）

如果你完全不需要 WSL，可在“启用或关闭 Windows 功能”中取消勾选 适用于 Linux 的 Windows 子系统，然后重启。但一般无需这么做，保留 WSL 不影响性能。

五、快速命令速查表

任务命令
启动所有服务cd ~/ollama-server && docker compose up -d
停止所有服务docker compose down
查看运行状态docker ps
查看日志docker compose logs -f
进入 Ollama 容器docker exec -it ollama bash
拉取模型docker exec -it ollama ollama pull <模型名>
列出模型docker exec -it ollama ollama list
删除模型docker exec -it ollama ollama rm <模型名>
测试 APIcurl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen2.5:7b","messages":[{"role":"user","content":"你好"}]}'
完全卸载（删数据）docker compose down -v && rm -rf ~/ollama-server

六、同一个wifi下如何访问

要在同一个 WiFi 下的其他设备（手机、平板、另一台电脑）上访问你的本地 AI 服务，需要做两件事：让服务监听在“所有网络接口”（你之前已配置），以及在 Windows 防火墙上放行相应端口。下面一步步来。

1. 获取 Windows 主机的局域网 IP 地址

在 Windows 上打开 命令提示符 或 PowerShell，输入：

ipconfig

找到当前使用的无线网卡（Wi-Fi），记下 IPv4 地址，通常像 192.168.x.x，例如 192.168.1.100。

这个地址在其他设备上访问时会用到。

2. 在 Windows 防火墙中放行端口

你的 Docker 容器已经通过 ports 映射将 11434 和 3000 暴露到了 Windows 宿主机的所有网络接口上（因为 docker-compose.yml 中的端口写法默认为 0.0.0.0:宿主机端口:容器端口）。
为了让外部设备能够访问，需要在 Windows 防火墙中允许这两个端口的入站连接。

操作步骤：

  1. 打开 Windows 安全中心 → 防火墙和网络保护 → 高级设置（或直接搜索“高级安全 Windows Defender 防火墙”）。
  2. 在左侧点击 入站规则，然后右侧点击 新建规则…。
  3. 选择 端口 → 下一步。
  4. 选择 TCP，并在“特定本地端口”中输入 11434,3000 → 下一步。
  5. 选择 允许连接 → 下一步。
  6. 确保域、专用、公用三个配置文件都勾选（如果你只在家庭网络使用，至少勾选“专用”）→ 下一步。
  7. 为规则命名，例如 “Ollama and Open WebUI” → 完成。

💡 如果你使用了 WSL2 并启用了“公用”网络配置文件，请务必勾选，否则连不上。

3. 确认服务已监听在 0.0.0.0

在 WSL 终端中，你可以快速检查 Ollama 容器内是否监听了所有接口（应该已监听）：

docker exec ollama netstat -tlnp | grep 11434

如果输出显示 0.0.0.0:11434，就说明没问题。

你的 docker-compose.yml 中已设置 OLLAMA_HOST=0.0.0.0，所以 Ollama 会接受来自任何 IP 的请求。

4. 从其他设备访问

现在，在同一个 WiFi 下的任何设备上，打开浏览器，输入以下地址：

  • 访问 Open WebUI 网页界面：
    http://你的Windows主机IP:3000
    例如：http://192.168.1.100:3000

  • 直接调用 Ollama API（例如在手机上的 Termux 或电脑上测试）：
    http://192.168.1.100:11434
    应该会显示 “Ollama is running”。

在 WebUI 中：和在本机操作一样，注册账号后就能直接选择模型聊天。所有对话都发生在你的服务器上，数据不会离开你的局域网。

5. 常见问题排查

❌ 其他设备访问时提示“无法访问此网站”或连接超时

  • 检查 Windows 防火墙：确认是否创建了入站规则，并检查网络配置文件（专用/公用）是否正确。可以临时关闭防火墙测试一下（不推荐长期关闭）。
  • 检查 IP 地址：确保 Windows 的 Wi-Fi IP 没有变化，并且其他设备与 Windows 主机在同一个子网（例如都是 192.168.1.x）。
  • 检查 Docker 端口映射：在 Windows 主机上打开浏览器访问 http://localhost:3000，如果能打开，说明服务本身正常，问题在外部访问环节。
  • 路由器 AP 隔离：部分路由器开启了“AP 隔离”或“客户端隔离”，导致局域网设备之间无法互相访问。可以登录路由器后台查看并关闭该功能。
  • WSL2 网络模式：极少数情况下，WSL2 的 NAT 可能导致端口转发失效。如果上述方法均无效，可尝试在 Windows 上执行 netsh interface portproxy 做一次显式转发，但通常 Docker Desktop 已自动完成。如果你遇到这种情况，可以这样操作（需要管理员权限）：
    # 先找到 WSL2 的 IP 地址（在 WSL 中运行 ip addr show eth0）
# 假设 WSL IP 为 172.25.123.100
netsh interface portproxy add v4tov4 listenport=11434 listenaddress=0.0.0.0 connectport=11434 connectaddress=172.25.123.100
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=172.25.123.100
    之后还要在防火墙中允许这些端口。完成后重启 Docker 容器。但绝大多数情况下不需要这步。

❌ WebUI 页面打开但无法连接到 Ollama（模型列表为空）

这是因为 WebUI 的后端（运行在容器内）访问 Ollama 的地址是 http://ollama:11434，这是容器内部 DNS，不受外部访问影响。如果本地 WebUI 正常，从局域网访问也应该是正常的。如果不正常，检查 WebUI 容器日志：docker compose logs open-webui。

6. 固定 IP 地址（可选）

为了避免每次电脑重新连接 WiFi 后 IP 地址变化，你可以在路由器设置中为你的 Windows 电脑 MAC 地址绑定一个固定 IP，或者在 Windows 网卡设置中手动指定 IP（确保不与其他设备冲突）。这样你分享给别人的地址就不会变。

现在，拿出手机或平板，连上同一个 WiFi，打开浏览器访问 http://你的电脑IP:3000，就能像在电脑上一样使用你的本地 AI 服务了。

最近更新:
Contributors: shyarcher