快速开始

让 Open WebUI 在你的机器上跑起来。请选择你偏好的安装方式。

Open WebUI 支持 macOS、Linux（x86_64 和 ARM64，包括 Raspberry Pi 与 NVIDIA DGX Spark）以及 Windows。

• Docker： 官方支持，适合大多数用户，也是推荐方案。需要先安装 Docker。
• Python： 适合低资源环境或手动部署。
• Kubernetes： 适合需要扩展与编排的企业级部署。

Docker

Docker

使用 Docker 快速开始

信息

必须支持 WebSocket。请确认你的网络配置允许 WebSocket 连接。

Docker Hub 现已可用

Open WebUI 镜像同时发布到了两个镜像仓库：

• GitHub Container Registry： ghcr.io/open-webui/open-webui
• Docker Hub： openwebui/open-webui

两者内容完全一致。你可以在下面的命令中把 ghcr.io/open-webui/open-webui 替换成 openwebui/open-webui。

1. 拉取镜像

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

2. 运行容器

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

参数	作用
-v open-webui:/app/backend/data	持久化存储，避免重启后数据丢失
-p 3000:8080	将界面暴露在本机的 3000 端口

3. 打开界面

访问 http://localhost:3000。

---

镜像变体

标签	适用场景
:main	标准镜像（推荐）
:main-slim	更小的镜像，首次使用时下载 Whisper 和 embedding 模型
:cuda	提供 Nvidia GPU 支持（需在 docker run 中加入 --gpus all）
:ollama	在容器内集成 Ollama，适合一体化部署

固定特定发布版本

生产环境建议固定版本，而不是使用浮动标签：

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

---

常见配置

GPU 支持（Nvidia）

docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda

与 Ollama 打包在一起

将 Open WebUI 和 Ollama 放在同一个容器中：

使用 GPU：

docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

仅 CPU：

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

连接另一台服务器上的 Ollama

docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

单用户模式（无登录）

docker run -d -p 3000:8080 -e WEBUI_AUTH=False -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

注意

切换到单用户模式后，不能再无缝切回多账户模式。

---

使用开发分支

提示

测试 dev 构建是很有价值的贡献方式之一。建议在测试实例中运行，并通过 GitHub 报告问题。

:dev 标签包含的是进入稳定版前的最新功能。

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

注意

不要在 dev 与生产之间共享数据卷。 dev 构建可能包含向后不兼容的数据库迁移。请始终使用单独卷（例如 -v open-webui-dev:/app/backend/data）。

如果你不想使用 Docker，也可以参考 开发 Open WebUI。

---

卸载

1. 停止并删除容器：

   docker rm -f open-webui

2. 删除镜像（可选）：

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

3. 删除数据卷（可选，会删除所有数据）：

   docker volume rm open-webui

更新

要把本地 Docker 安装更新到最新版本，你可以使用 Watchtower，或手动更新容器。

方案 1：使用 Watchtower

借助 Watchtower，你可以自动化更新流程：

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

（如果你的容器名称不是 open-webui，请将其替换成实际名称。）

方案 2：手动更新

1. 停止并删除当前容器：

   docker rm -f open-webui

2. 拉取最新版本：

   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

设置 WEBUI_SECRET_KEY

如果没有持久化的 WEBUI_SECRET_KEY，每次重建容器时你都会被登出。可通过 openssl rand -hex 32 生成。

有关版本固定、回滚、自动更新工具和备份流程，请参见完整更新指南。

Docker Compose

Docker Compose 配置

使用 Docker Compose 可以更方便地管理多容器 Docker 应用。

Docker Compose 需要额外安装 docker-compose-v2。

注意

注意： 一些旧版 Docker Compose 教程仍使用 version 1 语法，例如 docker-compose build。请确认你使用的是 version 2 语法，即 docker compose build（中间是空格，不是连字符）。

示例 docker-compose.yml

下面是一个用于部署 Open WebUI 的示例配置：

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

使用 Slim 镜像

如果你的环境存储空间或带宽有限，可以使用不预打包模型的 slim 镜像：

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main-slim
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

备注

说明： slim 镜像会在首次使用时下载所需模型（whisper、embedding 模型），因此第一次启动可能更慢，但镜像体积会明显更小。

启动服务

运行以下命令启动服务：

docker compose up -d

辅助脚本

代码库中附带了一组辅助脚本，用于简化常见的 Docker 工作流：

• docker-compose-launcher.sh —— 交互式 Compose 启动器，具备 GPU 自动检测、可配置的 WebUI/API 端口、宿主机数据卷挂载以及可选的 Playwright 支持。运行 ./docker-compose-launcher.sh --help 查看完整参数列表。使用 --drop 可以销毁整个项目。
• docker-cleanup.sh —— 停止 Compose 项目并删除所有卷，包括持久化数据。销毁数据前会要求确认。
• docker-run.sh —— 构建 Open WebUI 镜像并运行单容器，通过 OPEN_WEBUI_PORT（默认 3000）对外暴露。
• docker-ollama.sh —— 拉取并运行官方 Ollama 容器，支持可选的 GPU 透传，通过 OLLAMA_PORT（默认 11434）对外暴露。
• docker-update-models.sh —— 遍历 Ollama 容器中已安装的每一个模型，并拉取其最新版本。

---

备注

说明： 如果需要 Nvidia GPU 支持，请把镜像从 ghcr.io/open-webui/open-webui:main 改为 ghcr.io/open-webui/open-webui:cuda，并在 docker-compose.yml 的服务定义中增加以下内容：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

这样就能在可用时让应用使用 GPU 资源。

卸载

如果要卸载通过 Docker Compose 运行的 Open WebUI，请按以下步骤操作：

1. 停止并删除服务： 在包含 docker-compose.yml 的目录中运行：

   docker compose down

2. 删除数据卷（可选，警告：会删除所有数据）： 如果你希望彻底移除数据（聊天、设置等）：

   docker compose down -v

   或手动删除：

   docker volume rm <your_project_name>_open-webui

3. 删除镜像（可选）：

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

扩展

Docker Desktop 扩展

Docker 发布了一个 Open WebUI Docker 扩展，它使用 Docker Model Runner 进行推理。你可以在这篇入门博客中了解更多：使用 Open WebUI + Docker Model Runner 在本地运行 AI

该扩展的故障排查步骤可在其 GitHub 仓库中查看：Open WebUI Docker 扩展 - 故障排查

虽然这是一个几乎零门槛体验 Open WebUI 的优秀方式，但它不是官方支持的安装方式，因此你可能会遇到意料之外的 bug 或行为差异。例如，该扩展面向单个本地用户设计，因此你无法在其中切换不同用户登录。如果在使用扩展时遇到问题，请前往其 GitHub 仓库提交 issue。

Podman

使用 Podman

Podman 是一个无守护进程的容器引擎，可用于开发、管理和运行 OCI 容器。

基础命令

• 运行容器：

  podman run -d --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main

• 查看运行中的容器：

  podman ps

Podman 网络

如果出现网络问题（尤其是在 rootless Podman 下），你可能需要调整网络桥接设置。

Slirp4netns 已逐步弃用

较早的 Podman 教程常建议使用 slirp4netns。不过，slirp4netns 正在被弃用，并将在 Podman 6 中移除。

现代替代方案是 pasta，它已成为 Podman 5.0+ 的默认方案。

访问宿主机（本地服务）

如果你把 Ollama 或其他服务直接运行在宿主机上，请使用特殊 DNS 名称 host.containers.internal 指向你的电脑。

现代方式（Pasta - Podman 5+ 默认）

通常无需额外参数，就可以通过 host.containers.internal 访问宿主机。

旧方式（Slirp4netns）

如果你的 Podman 版本较旧，且不支持 pasta：

1. 请先确认已安装 slirp4netns。
2. 使用以下参数启动容器，以允许访问宿主回环地址：

podman run -d --network=slirp4netns:allow_host_loopback=true --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main

连接配置

进入 Open WebUI 后，打开 设置 > 管理设置 > 连接，将你的 Ollama API 连接设为： http://host.containers.internal:11434

更多高级配置请参阅 Podman 官方文档。

卸载

如需卸载通过 Podman 运行的 Open WebUI，请执行以下步骤：

1. 停止并删除容器：

   podman rm -f openwebui

2. 删除镜像（可选）：

   podman rmi ghcr.io/open-webui/open-webui:main

3. 删除数据卷（可选，警告：会删除所有数据）： 如果你希望彻底清除数据（聊天、设置等）：

   podman volume rm open-webui

Quadlet

Podman Quadlet（systemd）

Podman Quadlet 允许你把容器作为原生 systemd 服务进行管理。这是在使用 systemd 的 Linux 发行版（如 Fedora、RHEL、Ubuntu 等）上运行生产容器的推荐方式。

🛠️ 配置

1. 创建配置目录： 如果是 rootless 用户部署：

   mkdir -p ~/.config/containers/systemd/

2. 创建容器文件： 新建 ~/.config/containers/systemd/open-webui.container，内容如下：

   [Unit]
   Description=Open WebUI Container
   After=network-online.target
   
   [Container]
   Image=ghcr.io/open-webui/open-webui:main
   ContainerName=open-webui
   PublishPort=3000:8080
   Volume=open-webui:/app/backend/data
   
   # 网络：Podman 5+ 默认使用 Pasta
   # 如果需要访问宿主机服务（例如宿主机上的 Ollama）：
   AddHost=host.containers.internal:host-gateway
   
   [Service]
   Restart=always
   
   [Install]
   WantedBy=default.target

3. 重新加载 systemd 并启动服务：

   systemctl --user daemon-reload
   systemctl --user start open-webui

4. 设置开机自启：

   systemctl --user enable open-webui

📊 管理

• 查看状态：

  systemctl --user status open-webui

• 查看日志：

  journalctl --user -u open-webui -f

• 停止服务：

  systemctl --user stop open-webui

更新

更新镜像时，只需拉取新版本（podman pull ghcr.io/open-webui/open-webui:main），然后重启服务（systemctl --user restart open-webui）。

Kube Play

Podman Kube Play 配置

Podman 支持类似 Kubernetes 的语法来部署 Pod、卷等资源，而无需真正运行完整 Kubernetes 集群。更多关于 Kube Play。

如果你尚未安装 Podman，请查看 Podman 官方安装说明。

示例 play.yaml

下面是一个用于部署的 Podman Kube Play 示例文件：

apiVersion: v1
kind: Pod
metadata:
  name: open-webui
spec:
  containers:
    - name: container
      image: ghcr.io/open-webui/open-webui:main
      ports:
        - name: http
          containerPort: 8080
          hostPort: 3000
      volumeMounts:
        - mountPath: /app/backend/data
          name: data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName:  open-webui-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: open-webui-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

启动

运行以下命令启动 Pod：

podman kube play ./play.yaml

使用 GPU 支持

若需 Nvidia GPU 支持，请将容器镜像替换为 ghcr.io/open-webui/open-webui:cuda，并在 Pod 资源限制中声明所需设备（GPU）：

      [...]
      resources:
        limits:
          nvidia.com/gpu=all: 1
      [...]

important

要让 open-webui 容器成功访问 GPU， 你需要在 Podman Machine 中安装对应 GPU 的 Container Device Interface（CDI）。可参考 Podman GPU container access。

Swarm

Docker Swarm

这种安装方式要求你熟悉 Docker Swarm，因为它会使用 stack 文件在 Docker Swarm 中将 3 个独立容器部署为服务。

其中包含独立运行的 ChromaDB、Ollama 与 Open WebUI 容器。 另外还预填了一些环境变量，以便更直观地说明部署方式。

为什么要将 ChromaDB 作为独立容器运行

这个 stack 正确地将 ChromaDB 部署为独立的 HTTP 服务容器，Open WebUI 通过 CHROMA_HTTP_HOST 和 CHROMA_HTTP_PORT 与其连接。对于任何多 worker 或多副本部署，这都是必须的。

默认的 ChromaDB 模式（未设置 CHROMA_HTTP_HOST）使用本地基于 SQLite 的 PersistentClient，不具备 fork 安全性——多个 worker 进程并发写入会立刻导致 worker 崩溃。将 ChromaDB 作为独立服务运行，可以通过 HTTP 连接避免直接访问 SQLite。

如果你打算把 openWebUI 服务扩展到多个副本，还应同时把主数据库切换到 PostgreSQL，并配置 Redis。完整要求请参见 扩展与高可用指南。

请根据你的硬件情况选择相应命令：

• 开始前：

  需要先在宿主机上创建用于卷的数据目录，或者改用你自己的自定义路径 / 卷。

  当前示例使用的是与 docker-stack.yaml 位于同一目录下的隔离目录 data。

  • 例如：

    mkdir -p data/open-webui data/chromadb data/ollama

• 启用 GPU：

Docker-stack.yaml

services:
  openWebUI:
    image: ghcr.io/open-webui/open-webui:main
    depends_on:
        - chromadb
        - ollama
    volumes:
      - ./data/open-webui:/app/backend/data
    environment:
      DATA_DIR: /app/backend/data
      OLLAMA_BASE_URLS: http://ollama:11434
      CHROMA_HTTP_PORT: 8000
      CHROMA_HTTP_HOST: chromadb
      CHROMA_TENANT: default_tenant
      VECTOR_DB: chroma
      WEBUI_NAME: Awesome ChatBot
      CORS_ALLOW_ORIGIN: "*" # 当前默认值；正式上线前应修改
      RAG_EMBEDDING_ENGINE: ollama
      RAG_EMBEDDING_MODEL: nomic-embed-text-v1.5
      RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE: "True"
    ports:
      - target: 8080
        published: 8080
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3

  chromadb:
    hostname: chromadb
    image: chromadb/chroma:0.5.15
    volumes:
      - ./data/chromadb:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
      - ALLOW_RESET=TRUE
      - PERSIST_DIRECTORY=/chroma/chroma
    ports:
      - target: 8000
        published: 8000
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    healthcheck:
      test: ["CMD-SHELL", "curl localhost:8000/api/v1/heartbeat || exit 1"]
      interval: 10s
      retries: 2
      start_period: 5s
      timeout: 10s

  ollama:
    image: ollama/ollama:latest
    hostname: ollama
    ports:
      - target: 11434
        published: 11434
        mode: overlay
    deploy:
      resources:
        reservations:
          generic_resources:
            - discrete_resource_spec:
                kind: "NVIDIA-GPU"
                value: 0
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    volumes:
      - ./data/ollama:/root/.ollama

• 额外要求：

  1. 确保已启用 CUDA，请按你的操作系统和 GPU 对应说明完成。
  2. 启用 Docker GPU 支持，参见 Nvidia Container Toolkit
  3. 参考此指南，配置 Docker Swarm 使用 GPU
  • 请确认 /etc/nvidia-container-runtime/config.toml 中已启用 GPU Resource，并取消注释 swarm-resource = "DOCKER_RESOURCE_GPU" 以启用 GPU 资源广播。修改这些文件后，必须在每个节点上重启 Docker daemon。

• 仅 CPU：

  修改 docker-stack.yaml 中的 Ollama 服务，删除 generic_resources: 相关行：

      ollama:
    image: ollama/ollama:latest
    hostname: ollama
    ports:
      - target: 11434
        published: 11434
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    volumes:
      - ./data/ollama:/root/.ollama

• 部署 Docker Stack：

  docker stack deploy -c docker-stack.yaml -d super-awesome-ai

WSL

在 WSL（Windows Subsystem for Linux）中使用 Docker

本指南介绍如何在 Windows Subsystem for Linux（WSL）环境中安装 Docker 并运行 Open WebUI。

第 1 步：安装 WSL

如果你还没有安装 WSL，请参考 Microsoft 官方文档：

安装 WSL

第 2 步：安装 Docker Desktop

Docker Desktop 是在 WSL 环境中运行 Docker 最简单的方式。它会自动处理 Windows 与 WSL 之间的集成。

1. 下载 Docker Desktop： https://www.docker.com/products/docker-desktop/

2. 安装 Docker Desktop： 按照安装步骤完成，并在安装过程中确保选择 “WSL 2” 后端。

第 3 步：为 WSL 配置 Docker Desktop

1. 打开 Docker Desktop： 启动 Docker Desktop 应用。

2. 启用 WSL 集成：

   • 打开 设置 > 资源 > WSL 集成。
   • 确保勾选 “启用与我的默认 WSL 发行版集成”。
   • 如果你使用的不是默认 WSL 发行版，请在列表中单独勾选。

第 4 步：运行 Open WebUI

现在，你就可以在 WSL 终端里按标准 Docker 方式运行 Open WebUI：

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

重要说明

• 在 WSL 中运行 Docker 命令： 请始终从 WSL 终端中执行 docker 命令，而不是 PowerShell 或 Command Prompt。

• 文件系统访问： 使用卷挂载（-v）时，请确认对应路径对当前 WSL 发行版可访问。

Python

Python 版本兼容性

Open WebUI 支持 Python 3.11 和 3.12。目前尚不支持 Python 3.13 —— 我们的部分依赖还需要发布兼容 3.13 的版本，在此之前，在 3.13 上安装会失败或在运行时崩溃。

• 生产环境请使用 Docker 镜像或 最新的 Python 3.11。这也是我们重点测试的组合。
• Python 3.12 同样可以工作，但我们收到过极个别的 3.12 上行为异常的报告，且在 3.11 上未能复现。如果你在 3.12 上遇到难以解释的问题，请先降到最新的 3.11 试试。

pip

使用 pip 安装

这是通过 Python 安装 Open WebUI 最简单的方式。

1. 安装 Open WebUI

pip install open-webui

2. 启动服务

open-webui serve

Open WebUI 现在运行在 http://localhost:8080。

出现 “open-webui: command not found”？

1. 如果你使用了虚拟环境，请确认它已经激活。
2. 也可以直接这样运行：python -m open_webui serve
3. 如果你想把数据存到指定位置：DATA_DIR=./data open-webui serve

卸载

1. 卸载包：

   pip uninstall open-webui

2. 删除数据（可选，会删除所有数据）：

   rm -rf ~/.open-webui

使用 Python 更新

如果你是通过 pip 在本地安装的 Open WebUI，可按以下方式升级到最新版本：

pip install -U open-webui

-U（或 --upgrade）标志会让 pip 升级到最新可用版本。

升级后，重启服务并确认能够正常启动：

open-webui serve

多 worker 环境

如果你以 UVICORN_WORKERS > 1 运行 Open WebUI（例如生产环境），则必须先确保更新迁移在单 worker 下完成，否则可能导致数据库 schema 损坏。

正确更新步骤：

1. 使用 pip 更新 open-webui。
2. 设置 UVICORN_WORKERS=1 后启动应用。
3. 等待应用完全启动并完成迁移。
4. 停止应用，再按目标 worker 数重新启动。

有关版本固定、回滚和备份流程，请参见完整更新指南。

uv

使用 uv 安装

uv 运行时管理器可以为 Open WebUI 这类应用提供顺畅的 Python 环境管理。按以下步骤开始：

1. 安装 uv

根据你的操作系统选择合适的安装命令：

• macOS/Linux：

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 运行 Open WebUI

安装好 uv 后，就可以直接运行 Open WebUI。建议设置 DATA_DIR，避免数据丢失。下面分别给出了各平台示例：

• macOS/Linux：

  DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

• Windows（PowerShell）：

  $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve

为什么要设置 DATA_DIR？

设置 DATA_DIR 可以确保你的聊天与设置保存到可预期的位置。如果不设置，uvx 可能会把数据放在进程结束后就被清理掉的临时目录中。

卸载

如果你是通过 uvx 运行 Open WebUI，可按以下方式移除：

1. 停止服务： 在运行它的终端中按 Ctrl+C。

2. 从 UV 中卸载： 运行 uv tool uninstall open-webui

3. 可用的清理命令： uvx 会以临时方式或从缓存中运行应用。如需移除缓存组件：

   uv cache clean

4. 删除数据（警告：会删除所有数据）： 删除你的数据目录（默认为 ~/.open-webui，或你在 DATA_DIR 中指定的路径）：

   rm -rf ~/.open-webui

使用 Python 更新

如果你是通过 pip 在本地安装的 Open WebUI，可按以下方式升级到最新版本：

pip install -U open-webui

-U（或 --upgrade）标志会让 pip 升级到最新可用版本。

升级后，重启服务并确认能够正常启动：

open-webui serve

多 worker 环境

如果你以 UVICORN_WORKERS > 1 运行 Open WebUI（例如生产环境），则必须先确保更新迁移在单 worker 下完成，否则可能导致数据库 schema 损坏。

正确更新步骤：

1. 使用 pip 更新 open-webui。
2. 设置 UVICORN_WORKERS=1 后启动应用。
3. 等待应用完全启动并完成迁移。
4. 停止应用，再按目标 worker 数重新启动。

有关版本固定、回滚和备份流程，请参见完整更新指南。

Conda

使用 Conda 安装

1. 创建 Conda 环境：

   conda create -n open-webui python=3.11

2. 激活环境：

   conda activate open-webui

3. 安装 Open WebUI：

   pip install open-webui

4. 启动服务：

   open-webui serve

出现 “open-webui: command not found”？

如果终端提示找不到命令：

1. 请确认 Conda 环境已经激活（conda activate open-webui）。
2. 如果仍报错，可以直接通过 Python 运行：python -m open_webui serve
3. 如果你想把数据存到指定位置，可使用（Linux/Mac）：DATA_DIR=./data open-webui serve；或（Windows）：$env:DATA_DIR=".\data"; open-webui serve

卸载

1. 删除 Conda 环境：

   conda remove --name open-webui --all

2. 删除数据（警告：会删除所有数据）： 删除你的数据目录（通常是 ~/.open-webui，除非你另行配置）：

   rm -rf ~/.open-webui

使用 Python 更新

如果你是通过 pip 在本地安装的 Open WebUI，可按以下方式升级到最新版本：

pip install -U open-webui

-U（或 --upgrade）标志会让 pip 升级到最新可用版本。

升级后，重启服务并确认能够正常启动：

open-webui serve

多 worker 环境

如果你以 UVICORN_WORKERS > 1 运行 Open WebUI（例如生产环境），则必须先确保更新迁移在单 worker 下完成，否则可能导致数据库 schema 损坏。

正确更新步骤：

1. 使用 pip 更新 open-webui。
2. 设置 UVICORN_WORKERS=1 后启动应用。
3. 等待应用完全启动并完成迁移。
4. 停止应用，再按目标 worker 数重新启动。

有关版本固定、回滚和备份流程，请参见完整更新指南。

Venv

使用虚拟环境

使用 venv 创建隔离的 Python 环境。

Venv 步骤

1. 创建虚拟环境：

   python3 -m venv venv

2. 激活虚拟环境：

   • 在 Linux/macOS 上：

     source venv/bin/activate

   • 在 Windows 上：

     venv\Scripts\activate

3. 安装 Open WebUI：

   pip install open-webui

4. 启动服务：

   open-webui serve

出现 “open-webui: command not found”？

如果终端提示找不到命令：

1. 请确认虚拟环境已经激活（第 2 步）。
2. 如果仍报错，可直接通过 Python 运行：python -m open_webui serve
3. 如果你想把数据存到指定位置，可使用：DATA_DIR=./data open-webui serve

卸载

1. 删除虚拟环境： 直接删除 venv 文件夹即可：

   rm -rf venv

2. 删除数据（警告：会删除所有数据）： 删除你的数据目录（通常为 ~/.open-webui，除非你另行配置）：

   rm -rf ~/.open-webui

使用 Python 更新

如果你是通过 pip 在本地安装的 Open WebUI，可按以下方式升级到最新版本：

pip install -U open-webui

-U（或 --upgrade）标志会让 pip 升级到最新可用版本。

升级后，重启服务并确认能够正常启动：

open-webui serve

多 worker 环境

如果你以 UVICORN_WORKERS > 1 运行 Open WebUI（例如生产环境），则必须先确保更新迁移在单 worker 下完成，否则可能导致数据库 schema 损坏。

正确更新步骤：

1. 使用 pip 更新 open-webui。
2. 设置 UVICORN_WORKERS=1 后启动应用。
3. 等待应用完全启动并完成迁移。
4. 停止应用，再按目标 worker 数重新启动。

有关版本固定、回滚和备份流程，请参见完整更新指南。

Kubernetes

Helm

Kubernetes 上的 Helm 配置

Helm 可以帮助你管理 Kubernetes 应用。

前置要求

• 已准备好 Kubernetes 集群
• 已安装 Helm

Helm 步骤

1. 添加 Open WebUI Helm 仓库：

   helm repo add open-webui https://open-webui.github.io/helm-charts
   helm repo update

2. 安装 Open WebUI Chart：

   helm install openwebui open-webui/open-webui

3. 验证安装：

   kubectl get pods

注意

如果你计划在集群环境中通过多个节点 / pods / workers 扩展 Open WebUI，就需要配置 NoSQL 键值数据库（Redis）。 另外还有一些环境变量必须在所有服务实例之间保持一致，否则会出现一致性问题、会话异常和其他故障！

重要： 默认向量数据库（ChromaDB）使用的是本地基于 SQLite 的客户端，不适用于多副本或多 worker 部署。SQLite 连接不具备 fork 安全性，多个进程并发写入会直接导致 worker 崩溃。你必须通过 VECTOR_DB 切换到外部向量数据库（PGVector、Milvus、Qdrant），或者通过 CHROMA_HTTP_HOST 将 ChromaDB 作为独立 HTTP 服务运行。

关于完整扩展流程，请参见 扩展 Open WebUI。若需排查多副本问题，请查看 扩展与高可用指南。

更新时的关键要求

如果你运行的是多副本 / 多 pod（replicaCount > 1）或设置了 UVICORN_WORKERS > 1，那么在更新期间你必须先缩容到单副本 / 单 pod。

1. 将部署缩容到 1 个副本。
2. 应用更新（新镜像版本）。
3. 等待 pod 完全就绪（数据库迁移完成）。
4. 再扩容回目标副本数。

如果不这样做，可能会因为并发迁移导致数据库损坏。

访问 WebUI

你可以通过端口转发，或配置 Ingress 来访问 Open WebUI。

Ingress 配置（Nginx）

如果你使用的是 NGINX Ingress Controller，可以启用 session affinity（粘性会话）以提升 WebSocket 稳定性。请在 Ingress 资源上添加以下注解：

metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "open-webui-session"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

这样可以让用户会话尽量保持落在同一个 pod 上，从而减少多副本环境中的 WebSocket 问题（不过只要 Redis 配置正确，这一项的重要性会下降）。

卸载

1. 卸载 Helm Release：

   helm uninstall openwebui

2. 删除 Persistent Volume Claims（警告：会删除所有数据）： Helm 默认不会自动删除 PVC，以防止误删数据。如果你想彻底清除，需要手动删除：

   kubectl delete pvc -l app.kubernetes.io/instance=openwebui

桌面端

桌面应用

从 github.com/open-webui/desktop 下载桌面应用。它可在你的系统上原生运行 Open WebUI，无需 Docker 或手动配置。

信息

用于生产环境时，请通过 Docker 或 Python 安装。

第三方

Pinokio.computer

通过 Pinokio.computer 安装

如需通过 Pinokio.computer 安装，请访问其官网：

https://pinokio.computer/

该安装方式的支持由其官网提供。

---

安装完成后

首次登录

• 管理员账户： 第一个创建的账户会获得管理员权限，负责用户管理与系统设置。
• 新注册用户： 后续注册的账户会以 待审核 状态开始，需要管理员批准。
• 隐私： 默认情况下，所有数据（包括登录信息）都存储在你的本地设备上。Open WebUI 默认不会发起外部请求。所有模型默认都是私有的，只有显式共享后其他人才能访问。

连接模型提供商

Open WebUI 至少需要一个模型提供商才能开始聊天。请选择你的方案：

提供商	指南
Ollama（本地模型）	从 Ollama 开始 →
OpenAI	从 OpenAI 开始 →
任意兼容 OpenAI 的 API	兼容 OpenAI 的提供商 →
Anthropic	从 Anthropic 开始 →
llama.cpp	从 llama.cpp 开始 →
vLLM	从 vLLM 开始 →

连接 Agent

想要的不只是模型？AI Agent 可以执行终端命令、读写文件、搜索网页、维护记忆并串联复杂工作流——而这一切都通过 Open WebUI 熟悉的聊天界面完成。

Agent	描述	指南
Hermes Agent	Nous Research 的自主 Agent，支持终端、文件操作、网页搜索、记忆和可扩展技能	设置 Hermes Agent →
OpenClaw	开源自托管 Agent，支持 shell 访问、文件操作、网页浏览和消息集成	设置 OpenClaw →

更多关于 Agent 与提供商差异的说明，请阅读 连接 Agent 概览 →

第一次使用 Open WebUI？

如果这是你第一次接触 Open WebUI，建议下一步阅读 新用户必读。它把每个新用户迟早都需要知道的六件事——插件、工具调用、任务模型、上下文管理、RAG 与 Open Terminal——集中放在了一页里。

探索功能

连接完成后，继续看看 Open WebUI 还能做什么：功能总览 →

实验性：Open Responses

Open WebUI 对 Open Responses 规范提供实验性支持。更多说明请参见 Open Responses 入门指南。

---

社区

• Discord —— 提问、讨论与获取支持
• GitHub Issues —— 提交 bug 和功能请求
• 想帮忙？ 欢迎测试开发分支并反馈问题，无需写代码。