[OpenClaw] OpenWebUI 的部署指南

Open WebUI 部署指南

概述

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

环境要求

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

部署步骤

1. 创建持久化数据卷

bash 复制代码

docker volume create open-webui-data

2. 启动 Open WebUI 容器

bash 复制代码

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 密钥）：

bash 复制代码

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

管理命令

查看容器状态

bash 复制代码

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

查看容器日志

bash 复制代码

docker logs open-webui

重启容器

bash 复制代码

docker restart open-webui

停止容器

bash 复制代码

docker stop open-webui

删除容器

bash 复制代码

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

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

bash 复制代码

docker volume rm open-webui-data

注意事项

1. 数据持久化

数据卷已挂载 ：用户账户、聊天记录、模型缓存等数据存储在 open-webui-data 卷中

备份建议 ：定期备份数据卷内容

bash 复制代码

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 端口

bash 复制代码

# 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. 容器无法启动

bash 复制代码

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

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

2. 无法访问 WebUI

bash 复制代码

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

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

3. 数据丢失

bash 复制代码

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

更新步骤

1. 停止当前容器

bash 复制代码

docker stop open-webui

2. 拉取最新镜像

bash 复制代码

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

3. 重新启动容器

bash 复制代码

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）