更新 Open WebUI

保持最新，同时不丢失你的数据。

你的数据（聊天、用户、设置、上传文件）存放在 Docker 卷或本地数据库中，而不在容器内部。更新 Open WebUI，本质上就是把容器镜像替换成更新版本；数据会保持原样。

---

选择更新策略

在执行任何命令前，先决定你想如何跟踪版本发布。最佳方案取决于你如何使用 Open WebUI。

场景	推荐做法
个人 / homelab	使用 :main 标签，需要最新版本时手动拉取
共享 / 团队实例	固定特定版本（例如 :v0.8.6），并使用 Diun 接收更新通知
生产 / 关键系统	固定版本，升级前查看发布说明，先在预发布环境测试

:main 与固定版本

:main 标签始终指向最新构建。它使用方便，但也可能在没有预告的情况下包含破坏性变更。

如果你更重视稳定性，请固定到具体的发行标签：

ghcr.io/open-webui/open-webui:v0.9.6
ghcr.io/open-webui/open-webui:v0.9.6-cuda
ghcr.io/open-webui/open-webui:v0.9.6-ollama

你可以在 GitHub releases 页面 查看所有可用标签。

---

更新前准备

1. 备份数据（见下方 备份与恢复）。尤其在遇到包含数据库迁移的版本时更要如此，因为回滚通常不容易。
2. 查看 发布说明，确认是否有破坏性变更。
3. 更新后清理浏览器缓存（Ctrl+F5 / Cmd+Shift+R），避免旧前端资源残留。

正在运行多个 worker 或副本？

请先只在单实例上运行迁移：将 UVICORN_WORKERS=1，或在除一个实例外的所有实例上设置 ENABLE_DB_MIGRATIONS=false。详见扩展指南。

---

手动更新

Docker Run

# 1. 停止并删除容器（卷中的数据会保留）
docker rm -f open-webui

# 2. 拉取最新镜像（或把 :main 替换成固定版本）
docker pull ghcr.io/open-webui/open-webui:main

# 3. 重新创建容器
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="your-secret-key" \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

如需 NVIDIA GPU 支持，请在 docker run 命令中加入 --gpus all。

Docker Compose

docker compose pull
docker compose up -d

请确认你的 docker-compose.yml 包含 WEBUI_SECRET_KEY：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - WEBUI_SECRET_KEY=your-secret-key
    restart: unless-stopped

volumes:
  open-webui:

Python (pip)

pip install -U open-webui

-U 标志会升级到最新版本。然后重启服务：

open-webui serve

设置 WEBUI_SECRET_KEY，避免每次更新都被登出

如果没有持久化的 WEBUI_SECRET_KEY，容器每次重建都会生成新密钥，导致所有会话失效。可通过 openssl rand -hex 32 生成，并在后续更新中持续复用。详情见环境变量参考。

验证更新

更新后，请确认一切工作正常：

1. 在日志里检查版本：

   docker logs open-webui 2>&1 | head -20

2. 打开界面： 访问 http://localhost:3000，应看到登录页。
3. 如果界面显示异常， 清理浏览器缓存（Ctrl+F5 / Cmd+Shift+R）。
4. 如果日志里看到迁移错误， 请查看发布说明中的已知问题，以及连接错误 故障排查页面。

---

回滚

如果更新引发问题，你可以通过固定旧版本标签回退到之前的版本。

Docker Run

docker rm -f open-webui
docker pull ghcr.io/open-webui/open-webui:v0.8.3
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="your-secret-key" \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:v0.8.3

Docker Compose

将 docker-compose.yml 中的镜像标签改为：

image: ghcr.io/open-webui/open-webui:v0.8.3

然后执行：

docker compose pull
docker compose up -d

Python (pip)

pip install open-webui==0.8.3
open-webui serve

数据库迁移不可逆

如果你更新到的版本执行了数据库迁移，仅回滚容器并不会撤销迁移。旧版本可能无法兼容新数据库结构。在这种情况下，你需要恢复更新前创建的备份。针对数据库级恢复，请参见 数据库迁移。

---

持续接收更新通知

与其手动反复检查，不如使用工具来监控新版本。下面按“最安全”到“最省心”的顺序列出几种选择。

推荐

• 生产 / 关键系统： Diun（只通知）+ 手动更新
• 托管环境： WUD（可视化面板 + 手动触发）
• Homelab / 个人使用： Watchtower（全自动）

功能	Diun	WUD	Watchtower
自动更新容器	❌	❌（通过 UI 手动触发）	✅
Web 界面	❌	✅	❌
通知	✅	✅	✅
Docker 29+	✅	✅	✅（fork 版本）
资源占用	很低	中等	低

Diun

只负责通知。它会在有更新可用时提醒你（邮件、Slack、Discord、Telegram 等），但不会触碰你的容器。何时更新、如何更新，都由你决定。

services:
  diun:
    image: crazymax/diun:latest
    container_name: diun
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data:/data
    environment:
      - TZ=America/New_York
      - LOG_LEVEL=info
      - DIUN_WATCH_WORKERS=10
      - DIUN_WATCH_SCHEDULE=0 */6 * * *  # 每 6 小时一次
      - DIUN_PROVIDERS_DOCKER=true
      - DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
      - DIUN_NOTIF_MAIL_PORT=587
      - DIUN_NOTIF_MAIL_USERNAME=your-email@gmail.com
      - DIUN_NOTIF_MAIL_PASSWORD=your-app-password
      - DIUN_NOTIF_MAIL_FROM=your-email@gmail.com
      - DIUN_NOTIF_MAIL_TO=your-email@gmail.com
    restart: unless-stopped

完整配置与通知选项请查看 Diun 文档。

What's Up Docker (WUD)

用于监控容器更新并手动触发升级的 Web UI。安装方式见 WUD 文档。

Watchtower

全自动方案。它会拉取新镜像并自动重建容器，无需人工干预。

注意

原始的 containrrr/watchtower 已不再维护，且在 Docker 29+ 下会失效。请改用 nicholas-fedor/watchtower fork。

注意

如果新版本包含破坏性变更或数据库迁移，自动更新可能直接破坏你的部署。生产环境启用自动更新前，请务必先查看发布说明，并始终做好备份。

一次性更新：

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --run-once open-webui

持续运行（每 6 小时检查一次）：

docker run -d --name watchtower --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --interval 21600 open-webui

将 WATCHTOWER_CLEANUP=true 设为开启即可自动移除旧镜像。更多调度、通知和仅监控模式配置见 Watchtower 文档。

---

备份与恢复

所有数据都保存在 open-webui Docker 卷中，包括：

• 数据库：聊天、用户、设置、管理员配置
• 已上传文件：文档、图片、知识库内容
• 生成内容：图片生成结果、导出数据

备份

docker run --rm -v open-webui:/data -v $(pwd):/backup \
  alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz /data

建议在每次更新前以及固定周期（按你的使用频率决定每天或每周）进行备份。

恢复

警告

恢复命令会在解压前删除卷中的所有内容。请确认你恢复的是正确的备份文件。

docker stop open-webui
docker run --rm -v open-webui:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-YYYYMMDD.tar.gz -C /"
docker start open-webui

请将 YYYYMMDD 替换为实际备份文件日期。

数据库级恢复请参见 数据库迁移。

---

相关指南

• 扩展 Open WebUI：多 worker 与多实例部署
• 连接错误：更新后连通性问题排查
• 环境变量参考：包含 WEBUI_SECRET_KEY 在内的全部配置项
• 发布说明：每个版本的变更日志