Open WebUI 基于 Docker 的容器化部署流程。内容涵盖系统环境要求、多容器架构说明、基础服务启动、端口与连接高级配置、GPU 加速设置（NVIDIA/AMD）、数据持久化方案、安全加固措施以及监控日志管理。此外，还提供了常见问题排查指南和资源优化、备份等最佳实践，旨在帮助用户快速搭建稳定高效的本地 AI 交互平台。
Open WebUI 是一个可扩展、功能丰富且用户友好的自托管 WebUI，设计用于完全离线操作，支持各种大型语言模型（LLM）运行器，包括 Ollama 和兼容 OpenAI 的 API。本文将详细介绍如何通过 Docker 容器化方式部署 Open WebUI，包括基础部署、GPU 加速、数据持久化、高级配置及最佳实践指南，帮助用户快速搭建稳定高效的 AI 交互平台。
Open WebUI 的 Docker 部署采用多容器架构，通过 Docker Compose 实现服务编排。核心组件包括 Ollama 服务（模型运行时）和 Open WebUI 应用服务，两者通过内部网络通信，形成完整的本地 AI 服务栈。
主要容器及数据卷说明：
ollama卷存储模型权重和运行时数据，open-webui卷保存用户配置、对话历史和应用状态在开始部署前，需确保系统满足以下要求：
# 检查 Docker 版本
docker --version && docker compose version
# 验证 Docker 服务状态
systemctl status docker || service docker status
如未安装 Docker，可参考官方安装指南。对于 GPU 支持，还需安装 NVIDIA Container Toolkit。
Open WebUI 提供多种部署方式，推荐使用官方提供的 docker-compose.yaml 进行一键部署，自动处理服务依赖和网络配置。
git clone https://github.com/open-webui/open-webui.git
cd open-webui
使用默认配置启动 Ollama 和 Open WebUI 服务：
# 使用默认配置启动
docker compose up -d
# 或使用官方提供的启动脚本
bash run-compose.sh
docker-compose.yaml 定义了基础服务配置，包括：
OPEN_WEBUI_PORT 修改# 检查容器状态
docker compose ps
# 查看服务日志
docker compose logs -f open-webui
服务启动后，访问 http://localhost:3000 即可打开 Open WebUI 界面。首次访问需创建管理员账户，完成初始配置。
Open WebUI 支持丰富的配置选项，可通过环境变量、自定义 Compose 文件或启动脚本参数实现个性化部署。
修改 WebUI 访问端口（例如改为 80 端口）：
# 临时指定端口
OPEN_WEBUI_PORT=80 docker compose up -d
# 或修改配置文件
sed -i 's/OPEN_WEBUI_PORT-3000/OPEN_WEBUI_PORT-80/' docker-compose.yaml
当 Ollama 服务运行在外部服务器或已有实例时，通过环境变量指定连接地址：
# 连接远程 Ollama 服务
OLLAMA_BASE_URL=https://ollama.example.com docker compose up -d
# 或修改 compose 文件中的环境变量
environment:
- OLLAMA_BASE_URL=http://external-ollama:11434
通过 docker-compose.api.yaml 扩展配置，暴露 Ollama API 供外部访问：
docker compose -f docker-compose.yaml -f docker-compose.api.yaml up -d
该文件会额外映射 Ollama 的 11434 端口，支持外部工具直接调用模型 API。
对于需要运行大模型的场景，启用 GPU 加速可显著提升推理性能。Open WebUI 提供完整的 GPU 支持方案，兼容 NVIDIA 和 AMD 显卡。
# 基础 GPU 配置
docker compose -f docker-compose.yaml -f docker-compose.gpu.yaml up -d
# 或通过启动脚本指定 GPU 数量
bash run-compose.sh --enable-gpu[count=1]
docker-compose.gpu.yaml 通过 Docker 的设备请求功能，将 GPU 资源分配给 Ollama 容器：
services:
ollama:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
对于 AMD 显卡，使用 ROCm 驱动和专用镜像：
# 使用 AMD GPU 专用配置
docker compose -f docker-compose.yaml -f docker-compose.amdgpu.yaml up -d
注意：GPU 支持需对应镜像版本，NVIDIA 使用
:cuda标签，AMD 使用:rocm标签，可在 Dockerfile 中查看构建细节。
为防止数据丢失和实现模型迁移，需正确配置数据持久化策略。Open WebUI 提供两种数据管理方式：Docker 卷（推荐）和主机目录挂载。
docker-compose.yaml 默认使用命名卷存储数据：
volumes:
ollama: {} # 存储 Ollama 模型和配置
open-webui: {} # 存储 WebUI 用户数据和设置
查看数据卷位置：
# 查看卷详细信息
docker volume inspect open-webui
如需直接访问数据文件，可使用主机目录挂载：
# 使用自定义目录存储 Ollama 数据
bash run-compose.sh --data[folder=./ollama-data]
或修改 docker-compose.data.yaml：
services:
ollama:
volumes:
- ./ollama-data:/root/.ollama # 主机目录替换默认卷
注意：需确保挂载目录权限正确，避免容器访问权限问题。
生产环境部署需注意安全配置，防止未授权访问和数据泄露。
通过环境变量设置 WebUI 管理员密码：
# 启动时设置初始密码
WEBUI_SECRET_KEY="your_strong_password" docker compose up -d
或在 WebUI 设置界面（/settings/admin）配置用户认证和权限控制。
生产环境应避免直接暴露 Ollama API 端口，仅保留 WebUI 访问入口。如需外部访问，建议通过反向代理（如 Nginx）添加认证和 HTTPS。
使用 Watchtower 自动更新容器镜像：
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower --interval 86400 open-webui ollama
# 实时查看 WebUI 日志
docker compose logs -f open-webui --tail=100
# 查看 Ollama 模型加载日志
docker compose logs ollama | grep "loaded model"
Open WebUI 容器内置健康检查机制，可通过 Docker 状态查看：
# 查看容器健康状态
docker inspect --format='{{.State.Health.Status}}' open-webui
健康检查通过访问 /health 端点实现，配置在 Dockerfile 中：
HEALTHCHECK CMD curl --silent --fail http://localhost:${PORT}/health | jq -ne 'input.status == true' || exit 1
症状：docker compose ps 显示容器状态为 Exited 或 Restarting
排查步骤：
# 查看错误日志
docker compose logs --tail=50 open-webui
# 检查端口占用
netstat -tulpn | grep 3000
# 或配置的其他端口
常见原因：端口冲突、数据卷权限问题、GPU 驱动不兼容。可尝试更换端口或重建数据卷。
症状：WebUI 显示'无法连接到 Ollama'错误
解决方案：
docker compose exec ollama ollama list--add-host=host.docker.internal:host-gateway 确保容器互通docker run --network=host ...症状：模型运行缓慢，日志显示使用 CPU 推理
检查命令：
# 验证 GPU 是否对 Docker 可见
docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
如无输出，需重新安装 NVIDIA Container Toolkit 并重启 Docker 服务。
根据硬件情况调整资源限制，在 docker-compose.yaml 中添加：
services:
open-webui:
deploy:
resources:
limits:
cpus: '4'
memory: 8G
reservations:
cpus: '2'
memory: 4G
通过环境变量文件实现配置隔离：
# 创建环境变量文件
cp .env.example .env.prod
# 编辑自定义配置
vi .env.prod
# 使用指定环境文件启动
docker compose --env-file .env.prod up -d
结合 CI/CD 工具实现自动构建和部署，示例 GitHub Actions 配置：
name: Deploy Open WebUI
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Start services
run: docker compose up -d
定期备份数据卷，防止意外数据丢失：
# 备份 Ollama 模型数据
docker run --rm -v ollama:/source -v $(pwd):/backup alpine \
tar -czf /backup/ollama-backup-$(date +%F).tar.gz -C /source .
# 备份 WebUI 数据
docker run --rm -v open-webui:/source -v $(pwd):/backup alpine \
tar -czf /backup/webui-backup-$(date +%F).tar.gz -C /source .
通过 Docker 容器化部署 Open WebUI，用户可快速搭建本地 AI 服务平台，同时保证环境一致性和部署灵活性。本文介绍的基础部署、高级配置、GPU 加速和数据持久化方案，覆盖了从开发测试到生产环境的全场景需求。
未来版本中，Open WebUI 将进一步优化容器化体验，包括更小的镜像体积、更灵活的插件系统和增强的监控能力。用户可通过官方仓库提交反馈或贡献代码，共同完善这一开源项目。
官方文档：INSTALLATION.md 配置文件模板：docker-compose.yaml 启动脚本：run-compose.sh Docker 构建文件：Dockerfile
通过本文档的最佳实践指南，相信您已成功部署 Open WebUI 服务。如需进一步定制或扩展功能，可参考官方文档或加入社区交流。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online