跳到主要内容

版本更新指南 (Updating)

紧跟最新功能，且绝不丢失您的任何数据资产。

您的所有核心数据（如对话历史、用户账户、系统配置、上传的文档等）均安全地存放在 Docker 卷（Volume）或本地数据库中，而不是在容器临时文件系统的内部。这意味着更新 Open WebUI 仅需将老旧的容器镜像物理替换为更新的版本，您的所有数据都将原封不动地完美保留。

选择您的版本更新策略​

在运行任何终端更新命令之前，请先明确您希望以何种方式跟踪软件版本的发布。最合理的策略完全取决于您如何使用 Open WebUI。

使用场景分类官方推荐推荐更新方案
个人娱乐 / 家庭实验室 (Homelab)使用 :main 镜像标签，在您想要体验最新特性时手动拉取更新
团队共享 / 部门自用实例锁定到具体的特定版本标签（例如 :v0.8.6），并搭配使用 Diun 接收版本更新通知
正式生产环境 / 核心业务线必须锁定特定版本，在升级前仔细阅读 GitHub 官方 Release Notes 确认无阻碍变化，并优先在 Staging 预发布环境自测通过

1. :main 标签 vs. 锁定具体版本 (Pinned Versions)​

使用 :main 镜像标签将始终指向核心仓库最新的构建版本。这非常方便，但由于属于滚动更新，可能在未提前预警的情况下引入破坏性的改变（Breaking Changes）。

为了系统的极致稳定性，建议为您的镜像锁死一个特定的 Release 发布版本标签：

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

您可以在 GitHub Releases 官方发布页面 上浏览所有可用的版本标签。

升级更新前的准备工作​

  1. 物理备份您的数据（参见下文的 系统备份与恢复 章节）。在涉及到含有数据库表结构迁移（Migrations）的版本大升级前，这一步至关重要，因为表结构迁移往往是不可逆的。
  2. 仔细研读 Release Notes 确认是否存在破坏性改动或必须调整的环境变量。
  3. 强制刷新浏览器缓存：在更新完成后，使用 Ctrl+F5 (Windows) 或 Cmd+Shift+R (Mac) 强制刷新浏览器，以防旧的前端静态资产缓存导致界面白屏或按钮失效。
正在运行多 Workers 进程或多副本集群？

必须优先在单个实例上安全跑通数据库迁移：在除了一台主实例之外的所有其他集群节点上，将 UVICORN_WORKERS=1 或 ENABLE_DB_MIGRATIONS=false 环境变量配好。详情请查阅 集群横向扩展指南。

手动更新流程​

# 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 参数。

必须显式配置 WEBUI_SECRET_KEY 变量以防每次升级被迫下线

如果您没有在环境变量中显式配置一个固定的 WEBUI_SECRET_KEY，系统在每次重建容器时都会随机生成一个新的密钥。这会导致之前所有登录用户的 Session 瞬间失效，被迫强制退出下线。请使用 openssl rand -hex 32 生成一个强随机密钥，并妥善跨越每一次版本更新进行保留。详情请参阅 全局系统环境变量配置参考手册。

验收与验证您的升级​

在升级完成后，请按照以下四个维度验证系统是否运行正常：

  1. 检查启动日志确认版本号： 
    docker logs open-webui 2>&1 | head -20
  2. 加载网页 UI 界面：直接访问 http://localhost:3000。您应该能顺畅看到登录界面。
  3. 若界面排版错乱或白屏，请立刻执行浏览器强制刷新（Ctrl+F5 / Cmd+Shift+R）。
  4. 如果日志中抛出数据库迁移报错，请对比 Release Notes 中的已知 Bug，并查阅 排障：连接错误处理 说明页面。

版本回滚策略 (Rolling Back)​

如果在更新后遇到棘手的问题，您可以通过锁定镜像到先前的版本标签来平滑执行回滚。

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
警告：数据库表迁移是单向不可逆的

如果在您刚才升级到的高版本中已经自动运行了数据库迁移（DB Migration），单纯将容器回滚到旧版本并不能自动回撤数据库中已经被改变的表结构。旧版本的代码在面对新版数据库结构时极易发生崩溃。在这种情况下，您必须将数据库恢复到升级之前备份的安全快照状态。有关特定数据库恢复的细节，请参阅 排障：手动数据库升级与修复 教程。

建立版本更新通知监测机制​

比起每次都手动去 GitHub 页面瞅一眼，使用自动化监测工具来实时捕获最新发布是更专业的工程实践。以下推荐三种主流策略，从最稳健的仅通知到完全无人值守的全自动升级：

官方运维部署建议
  • 生产环境 / 核心业务系统：采用 Diun（仅通知告警） + 手动安全升级。
  • 专人管理的内部环境：采用 WUD（可视化 Web 面板展现 + 专人手动点击升级）。
  • 个人家庭实验室 / 玩票性质自用：采用 Watchtower（全自动拉取重建镜像，完全无人值守）。
  • 重要提示：在正式的生产线上，任何全自动的静默升级都是极度危险的，因为版本跨越可能会带来表结构损坏或功能重构，必须通过仅通知机制，由专职运维人员评估后再行手动干预。
核心特性比对Diun (仅监测通知)WUD (看板监测+手动触发)Watchtower (完全自动化)
自动更新容器❌❌ (支持在 UI 一键触发)✅
配备 Web 看板界面❌✅❌
通知渠道支持✅ (全面)✅✅
支持 Docker 29+✅✅✅ (需使用特定分叉镜像)
运行资源开销极低 (Very Low)中等 (Medium)低 (Low)

1. Diun (仅监测通知，推荐生产线使用)​

Diun 只负责实时监测并向您推送版本发布告警（支持配置 Email, 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=Asia/Shanghai
      - 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 官方技术文档。

2. WUD (What's Up Docker)​

为您的 Docker 容器更新提供了一个极度精美的 Web 可视化管理看板，支持在看板上一键触发容器升级。配置请参阅 WUD 官方技术文档。

3. Watchtower (全自动静默升级)​

完全自动化运维。一旦官方发布新镜像，Watchtower 会自动默默拉取最新版并自动重建您的容器，无需任何人机交互。

警告：请使用支持最新 Docker 29+ 的 Fork 分支

由于官方原版的 containrrr/watchtower 镜像已处于停更状态，在最新的 Docker 29+ 环境下会发生接口通信失败。请使用高度健壮的 Fork 维护版镜像：nicholas-fedor/watchtower 代替。

全自动静默更新的潜在隐患

如果新版本发布中含有重大表结构变更或破坏性变化，全自动的静默更新极易导致您的业务系统瞬间陷入白屏或崩溃崩溃。在重要的生产线上使用 Watchtower 前，必须三思，并确保自动备份脚本在完美运转。

一次性手动执行升级：

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 的所有数据均统一保存在 open-webui 这一挂载卷（Volume）的内部。这包含：

  • SQLite 数据库：存放着全站聊天记录、用户账户字典、管理员系统全局配置。
  • 上传的文件资源：文档对话中导入的 PDF/Word 原始文件、图片以及企业知识库原始素材。
  • 生成的衍生资产：图像生成（DALL-E 等）输出的本地缓存图、导出的历史会话包。

1. 执行一键备份 (Backup)​

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

强烈建议： 在执行每一次版本升级前，必须手动执行上述备份命令！对于正式服，强烈建议配置 Linux Cron 计划任务，执行每日或每周的自动化定时备份。

2. 执行一键恢复 (Restore)​

恢复操作具有高破坏性，请高度警惕

一键恢复命令在解压备份包前，会无条件彻底物理清空挂载卷内的所有当前现存数据！请在执行前，百分之百确认您选择的备份压缩包是正确的！

# 1. 停止运行中的服务以释放文件锁
docker stop open-webui

# 2. 物理清空卷并一键还原解压
docker run --rm -v open-webui:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-YYYYMMDD.tar.gz -C /"

# 3. 重新拉起服务
docker start open-webui

请在上述命令中，将 YYYYMMDD 替换为您想要还原的备份包的实际文件名日期。

有关特定数据库级别的灾备恢复，请查阅 排障：手动数据库升级与修复 专门指南。

关联阅读指南​

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.