1. Ubuntu 24.04 本地部署 Open WebUI + Ollama 完整指南
最近在折腾本地大语言模型部署,发现 Open WebUI 这个项目确实是个好东西。它提供了一个干净漂亮的 Web 界面来管理本地的 Ollama 服务,还能集成 SearXNG 实现联网搜索功能。作为一个长期在 Ubuntu 环境下工作的开发者,我决定把整个部署过程记录下来,分享给同样有兴趣的朋友们。
Open WebUI 本质上是一个基于 Docker 的 Web 应用,它通过 API 与本地运行的 Ollama 服务通信。这种架构设计有几个明显优势:首先,Web 界面比命令行友好多了;其次,Docker 部署方式避免了各种依赖问题;最重要的是,它保留了所有数据本地化的特性,这对注重隐私的用户来说非常关键。
2. 环境准备与基础配置
2.1 系统要求与前置条件
在开始之前,请确保你的 Ubuntu 24.04 系统满足以下要求:
- 至少 16GB 内存(运行 7B 模型的最低要求)
- 50GB 可用磁盘空间
- 已安装 Docker 和 Docker Compose
- 已安装 Git
- 已配置好 Ollama 服务并正常运行
如果你的系统还没装 Docker,可以执行以下命令安装:
bash复制sudo apt update
sudo apt install docker.io docker-compose git
sudo systemctl enable --now docker
注意:如果你打算使用 NVIDIA GPU 加速,还需要安装 NVIDIA 容器工具包。这部分内容不在本文讨论范围内,可以参考 NVIDIA 官方文档进行配置。
2.2 Ollama 基础配置
Ollama 是整套系统的核心,负责实际运行语言模型。安装 Ollama 非常简单:
bash复制curl -fsSL https://ollama.com/install.sh | sh
安装完成后,你可以下载并运行一个测试模型:
bash复制ollama pull llama2
ollama run llama2
如果一切正常,你应该能在终端与模型进行交互了。记住 Ollama 默认运行在 11434 端口,这个信息后面配置 Open WebUI 时会用到。
3. Open WebUI 部署详解
3.1 获取项目代码与初始配置
首先克隆 Open WebUI 的 GitHub 仓库:
bash复制git clone https://ghfast.top/https://github.com/open-webui/open-webui.git
cd open-webui
项目提供了一个示例环境文件,我们需要复制并修改它:
bash复制cp .env.example .env
关键的配置修改集中在 .env 文件中。由于我们已经在本地运行了 Ollama 服务,需要特别注意以下几个参数:
env复制# .env
OLLAMA_BASE_URL='http://host.docker.internal:11434'
OPENAI_API_BASE_URL=''
OPENAI_API_KEY=''
CORS_ALLOW_ORIGIN='*'
FORWARDED_ALLOW_IPS='*'
OLLAMA_BASE_URL 设置为 http://host.docker.internal:11434 是因为 Docker 容器需要通过特殊的主机名访问宿主机服务。这个设置比直接用 localhost 更可靠,特别是在不同操作系统环境下。
3.2 Docker Compose 配置调整
默认的 docker-compose.yml 文件包含了 Ollama 服务,但既然我们已经在宿主机运行了 Ollama,就需要简化配置:
yaml复制services:
open-webui:
build:
context: .
dockerfile: Dockerfile
image: ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
container_name: open-webui
volumes:
- open-webui:/app/backend/data
ports:
- ${OPEN_WEBUI_PORT-3000}:8080
environment:
- 'OLLAMA_BASE_URL=http://host.docker.internal:11434'
- 'WEBUI_SECRET_KEY='
extra_hosts:
- host.docker.internal:host-gateway
restart: unless-stopped
volumes:
open-webui: {}
主要修改包括:
- 移除了 Ollama 服务定义
- 移除了 open-webui 对 Ollama 的依赖
- 在环境变量中明确指定 Ollama 地址
- 添加了
extra_hosts配置确保容器能解析host.docker.internal
3.3 启动服务与验证
配置完成后,使用 Docker Compose 启动服务:
bash复制docker compose up -d
首次启动会下载 Open WebUI 的 Docker 镜像,这个过程可能会比较慢,取决于你的网络状况。启动完成后,你可以通过以下命令查看日志:
bash复制docker compose logs -f
当你看到类似下面的日志时,说明服务已经就绪:
code复制open-webui | INFO: Application startup complete.
open-webui | INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
现在,你可以在浏览器中访问 http://localhost:3000(或者你配置的其他端口)来使用 Open WebUI 了。
4. 连接 Ollama 与模型管理
4.1 管理员面板配置
首次登录 Open WebUI,你需要创建一个管理员账户。登录后,点击左下角的"设置"图标,进入管理员面板。
在"外部连接"设置中,确保 Ollama 基础 URL 正确设置为 http://host.docker.internal:11434。这个配置告诉 Open WebUI 如何连接到你的本地 Ollama 服务。
提示:如果你在配置过程中遇到连接问题,可以尝试在宿主机上执行
curl http://localhost:11434来验证 Ollama 服务是否正常运行。
4.2 模型管理与使用
Open WebUI 会自动检测 Ollama 中已安装的模型。你可以在对话界面右上角选择不同的模型进行交互。
如果你的硬件性能有限(比如只有 8GB 内存的笔记本),建议使用较小的模型,如 tinyllama 或 phi。这些模型对硬件要求较低,虽然能力有限,但响应速度更快:
bash复制ollama pull tinyllama
对于性能更强的机器,可以尝试更大的模型:
bash复制ollama pull llama2:13b
实测经验:在我的 16GB 内存笔记本上,7B 模型运行尚可,但 13B 模型就会明显卡顿。建议根据硬件情况选择合适的模型大小。
5. 联网搜索功能集成
5.1 SearXNG 部署与配置
Open WebUI 支持通过 SearXNG 实现联网搜索功能。SearXNG 是一个开源的元搜索引擎,可以聚合多个搜索引擎的结果。
部署 SearXNG 最简单的方式也是使用 Docker。以下是基本的 docker-compose.yml 配置:
yaml复制version: '3'
services:
caddy:
container_name: caddy
image: docker.io/library/caddy:2-alpine
restart: unless-stopped
ports:
- "8081:8081"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data:rw
- caddy-config:/config:rw
environment:
- SEARXNG_HOSTNAME=${SEARXNG_HOSTNAME:-http://localhost}
- SEARXNG_TLS=${LETSENCRYPT_EMAIL:-internal}
logging:
driver: "json-file"
options:
max-size: "1m"
max-file: "1"
volumes:
caddy-data:
caddy-config:
启动后,你需要配置 SearXNG 使用的搜索引擎。建议禁用那些需要特殊网络访问的引擎(如 Google),启用本地化更好的选择:
bash复制docker exec -it searxng sed -i 's/enabled : False/enabled : True/g' /etc/searxng/settings.yml
5.2 Open WebUI 搜索集成
在 Open WebUI 的管理员面板中,找到"搜索"设置部分:
- 开启"启用联网搜索"选项
- 设置 SearXNG 地址为
http://host.docker.internal:8080/search?q=<query> - 保存配置
现在,在聊天界面中你可以开启"联网搜索"选项,模型就能获取最新的网络信息来回答你的问题了。
避坑指南:如果搜索功能不工作,首先检查 SearXNG 服务是否正常运行,然后查看 Open WebUI 容器日志中是否有相关错误。常见问题包括网络连接问题和 SearXNG 配置错误。
6. 常见问题与优化建议
6.1 性能优化技巧
对于资源有限的机器,可以考虑以下优化措施:
- 模型选择:使用量化版本的小模型,如
llama2:7b-q4_0 - 对话长度:限制最大对话 tokens 数量(在模型设置中调整)
- 批处理大小:在 Ollama 启动参数中添加
--numa和--num_threads优化 CPU 使用 - GPU 加速:如果有 NVIDIA GPU,确保安装了正确的驱动和 CUDA 工具包
6.2 常见错误排查
问题1:Open WebUI 无法连接 Ollama
解决方案:
- 确认 Ollama 服务正在运行:
systemctl status ollama - 测试直接连接:
curl http://localhost:11434 - 检查 Docker 容器网络配置,确保
extra_hosts设置正确 - 查看 Open WebUI 容器日志:
docker compose logs open-webui
问题2:模型加载非常慢
可能原因:
- 首次使用模型需要下载,可以预先用
ollama pull下载 - 硬件性能不足,尝试更小的模型
- 内存不足导致频繁交换,检查
free -h输出
问题3:SearXNG 搜索无结果
检查步骤:
- 确认 SearXNG 服务正常运行
- 检查 SearXNG 日志:
docker compose logs searxng - 验证搜索引擎配置,确保至少有一个引擎启用
- 测试直接访问 SearXNG 接口
7. 进阶配置与使用技巧
7.1 多用户与权限管理
Open WebUI 支持多用户系统,你可以在管理员面板中创建和管理用户账户。对于家庭或小团队使用场景,可以考虑:
- 为不同成员创建独立账户
- 设置不同的模型访问权限
- 配置对话历史保留策略
- 管理 API 访问密钥
7.2 备份与数据迁移
所有用户数据和配置都存储在 Docker 卷中。要进行备份,可以使用以下命令:
bash复制docker compose stop
docker run --rm -v open-webui:/data -v $(pwd):/backup busybox tar cvf /backup/open-webui-backup.tar /data
docker compose start
恢复时:
bash复制docker compose stop
docker run --rm -v open-webui:/data -v $(pwd):/backup busybox tar xvf /backup/open-webui-backup.tar -C /
docker compose start
7.3 自定义主题与界面调整
Open WebUI 允许通过 CSS 自定义界面外观。你可以在管理员面板的"外观"设置中:
- 修改主色调和字体
- 调整布局和间距
- 添加自定义 CSS 规则
- 保存为主题预设供不同用户选择
8. 安全注意事项
虽然 Open WebUI 设计为本地使用,但仍需注意一些安全事项:
- 不要暴露到公网:除非你完全理解风险并做好了防护措施
- 定期更新:关注项目更新,及时获取安全补丁
- 模型安全:只从可信来源获取模型文件
- 数据加密:考虑对敏感对话启用端到端加密
- 访问控制:使用强密码并考虑启用双因素认证
对于生产环境使用,建议:
- 配置 HTTPS 加密
- 设置适当的防火墙规则
- 启用详细的访问日志
- 定期审计用户活动
这套本地部署方案在我的 Ubuntu 24.04 系统上运行稳定,即使在中低端硬件上也能提供可用的体验。最大的收获是发现小模型在特定任务上其实表现不错,特别是当你清楚它的局限性并合理设置预期时。对于开发者来说,Open WebUI 的 API 也足够丰富,可以方便地集成到自己的应用中。