Open WebUI 部署指南

概述

Open WebUI 是一个基于 Web 的界面，用于与大型语言模型（LLM）进行交互。本文档记录了在本地服务器上部署 Open WebUI 的完整步骤。

环境要求

• Docker 已安装并运行
• Docker Compose（可选，本文使用 docker run 方式）
• 至少 4GB 可用内存（推荐 8GB+）
• 至少 10GB 可用磁盘空间

部署步骤

1. 创建持久化数据卷

docker volume create open-webui-data

2. 启动 Open WebUI 容器

docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -v open-webui-data:/app/backend/data \
  --restart always \
  ghcr.io/open-webui/open-webui:main

参数说明：

参数	说明
-d	后台运行容器
--name open-webui	容器名称
-p 3000:8080	端口映射（主机 3000 → 容器 8080）
-v open-webui-data:/app/backend/data	数据卷挂载（持久化用户数据、模型缓存等）
--restart always	容器异常退出时自动重启
ghcr.io/open-webui/open-webui:main	镜像名称与标签

3. 访问 WebUI

• 本地访问： http://127.0.0.1:3000
• 外网访问： http://<服务器IP>:3000

4. 初始化管理员账户

首次访问时，系统会引导您创建管理员账户：

• 邮箱： admin@localhost（或其他有效邮箱）
• 密码： 设置强密码（建议 12 位以上，包含大小写字母、数字和特殊字符）

配置说明

默认配置

项目	值
内部端口	8080
主机端口	3000
数据目录	/app/backend/data（容器内）
数据卷	open-webui-data
WebUI 版本	9bd84258d09eefe7bf975878fb0e31a5dadfe0f8

环境变量（可选）

如需自定义配置，可通过 -e 参数添加环境变量：

变量名	说明	默认值
WEBUI_SECRET_KEY	WebUI 密钥（用于加密）	自动生成
OPENAI_API_KEY	OpenAI API 密钥	空（本地模式）
OLLAMA_BASE_URL	Ollama 服务地址	/ollama
RAG_EMBEDDING_MODEL	RAG 嵌入模型	sentence-transformers/all-MiniLM-L6-v2
WHISPER_MODEL	语音识别模型	base

示例（添加 API 密钥）：

docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -v open-webui-data:/app/backend/data \
  -e OPENAI_API_KEY=sk-xxxxxxxx \
  --restart always \
  ghcr.io/open-webui/open-webui:main

管理命令

查看容器状态

docker ps --filter "name=open-webui"

查看容器日志

docker logs open-webui

重启容器

docker restart open-webui

停止容器

docker stop open-webui

删除容器

docker stop open-webui && docker rm open-webui

删除数据卷（⚠️ 警告：将清除所有用户数据）

docker volume rm open-webui-data

注意事项

1. 数据持久化

• 数据卷已挂载：用户账户、聊天记录、模型缓存等数据存储在 open-webui-data 卷中
• 备份建议：定期备份数据卷内容

  docker run --rm -v open-webui-data:/data -v $(pwd):/backup ubuntu tar czf /backup/open-webui-backup.tar.gz /data
  

2. 网络访问

• 本地访问：直接通过 http://127.0.0.1:3000 访问
• 外网访问：确保服务器防火墙允许 3000 端口

  # Ubuntu/Debian
  sudo ufw allow 3000/tcp
  
  # CentOS/RHEL
  sudo firewall-cmd --permanent --add-port=3000/tcp
  sudo firewall-cmd --reload
  

3. 资源占用

• 内存：基础服务约 500MB，启用 RAG/嵌入模型时约 2-4GB
• 磁盘：基础安装约 2GB，模型缓存可能占用 5-10GB
• CPU：低负载时约 5-10%，高负载时可能达 50%+

4. 安全建议

• 修改默认密码：首次设置后立即更改管理员密码
• 启用 HTTPS：生产环境建议通过 Nginx 反向代理启用 SSL
• 限制访问：通过防火墙或反向代理限制 IP 访问

5. 模型管理

• 默认嵌入模型：sentence-transformers/all-MiniLM-L6-v2（约 80MB）
• 语音识别模型：whisper-base（约 140MB）
• 模型缓存目录：/app/backend/data/cache/

故障排查

1. 容器无法启动

# 检查端口占用
sudo netstat -tlnp | grep :3000

# 检查容器日志
docker logs open-webui

2. 无法访问 WebUI

# 检查容器状态
docker ps --filter "name=open-webui"

# 检查端口映射
docker port open-webui

3. 数据丢失

# 恢复数据卷（需提前备份）
docker run --rm -v open-webui-data:/data -v $(pwd):/backup ubuntu tar xzf /backup/open-webui-backup.tar.gz -C /

更新步骤

1. 停止当前容器

docker stop open-webui

2. 拉取最新镜像

docker pull ghcr.io/open-webui/open-webui:main

3. 重新启动容器

docker start open-webui

参考链接

• 官方文档：https://docs.openwebui.com
• GitHub 仓库：https://github.com/open-webui/open-webui
• Docker Hub：https://hub.docker.com/r/openwebui/open-webui

---

部署时间： 2026-04-06 22:21
部署版本： ghcr.io/open-webui/open-webui:main
部署状态： ✅ 运行正常（healthy）