更新 OPL 数据空间

保持版本更新，同时不丢数据。

你的数据，例如聊天记录、用户、设置、上传文件，通常都保存在 Docker volume 或本地数据库里，而不是容器镜像本身。更新 OPL 数据空间的本质，是把容器镜像替换成更新版本；数据仍然留在原来的位置。

先决定更新策略

更新前，先决定你要如何跟踪版本：

Scenario	Recommended approach
个人 / homelab	使用 `:main`，需要时手动 pull 最新版本
共享 / 团队实例	固定到具体版本（例如 `:v0.8.6`），并用 Diun 只做更新通知
生产 / 关键环境	固定版本，先读 release notes，先在 staging 测试

`:main` 与固定版本

:main 永远指向最新构建，方便，但也可能无预警带入破坏性变化。

如果你更看重稳定性，建议固定到具体版本号，例如：

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

完整标签可以在 GitHub releases 查看。

更新前建议

先备份数据
阅读 release notes
更新后清理浏览器缓存

多 worker / 多副本部署

如果是多 worker 或多副本环境，先只在一个实例上运行迁移：把其他实例设为 UVICORN_WORKERS=1 或 ENABLE_DB_MIGRATIONS=false。详见 Scaling guide。

手动更新

Docker Run
Docker Compose
Python (pip)

docker rm -f open-webui
docker pull ghcr.io/open-webui/open-webui:main
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 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:

pip install -U open-webui
open-webui serve

固定 WEBUI_SECRET_KEY

如果 WEBUI_SECRET_KEY 不持久，每次容器重建时都会生成新 key，导致所有用户被强制登出。可以用 openssl rand -hex 32 生成一个固定值，并在后续更新中一直沿用。

更新后验证

更新完成后，建议检查：

日志里的版本号
```
docker logs open-webui 2>&1 | head -20
```
UI 是否能正常打开
若前端看起来异常，先强刷缓存
若日志中出现 migration 错误，先看 release notes 和 Connection Errors

回滚

如果新版本有问题，可以退回旧版本，但要注意数据库迁移风险。

Docker Run
Docker Compose
Python (pip)

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.yml 里的 image 改成旧版本：

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

然后执行：

docker compose pull
docker compose up -d

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

数据库迁移通常不可逆

如果新版本已经跑过数据库迁移，单纯把容器换回旧版本并不会自动回滚 schema。旧版本可能仍然无法启动。这种情况下，你需要恢复“更新前的备份”。若要做数据库级恢复，可参考 Manual Database Migration。

及时获知新版本

如果你不想手动盯 release，可以用工具监控更新：

Feature	Diun	WUD	Watchtower
自动更新容器	❌	❌（手动点）	✅
Web 界面	❌	✅	❌
通知	✅	✅	✅
Docker 29+	✅	✅	✅（fork 版）
资源占用	很低	中等	低

Diun

只负责通知，不会自动替你动容器。适合生产环境。

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 * * *
      - 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

WUD

带 Web UI 的更新监控工具，适合想看面板、但仍想手动触发更新的人。详见 WUD。

Watchtower

全自动更新容器。

注意

原始 containrrr/watchtower 已不再维护，并且与 Docker 29+ 不兼容。请改用 nicholas-fedor/watchtower fork。

注意

自动更新在生产环境里有风险。若新版本包含破坏性变化或数据库迁移，可能会直接打断你的服务。启用前请确保有备份，并清楚 release note 风险。

一次性更新：

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

先决定更新策略​

:main 与固定版本​

更新前建议​

手动更新​

更新后验证​

回滚​

及时获知新版本​

Diun​

WUD​

Watchtower​