⏱️ 快速上手

Sponsored by Dave Waring

Follow along as I build my own AI powered digital brain.

关于用户角色和隐私的重要提示：

• 管理员创建： Open WebUI 上创建的第一个账户将获得管理员权限，可以控制用户管理和系统设置。
• 用户注册： 后续注册的用户初始状态为待批准，需要管理员批准才能访问。
• 隐私和数据安全： 所有数据（包括登录信息）都本地保存在您的设备上。Open WebUI 确保严格的保密性，不会发送外部请求，以增强隐私和安全性。
  • 所有模型默认为私有。 模型必须通过群组共享或设为公开才能被访问。如果模型被分配给某个群组，只有该群组的成员才能看到它。如果模型设为公开，实例中的任何人都可以看到它。

在下方选择您的首选安装方式：

• Docker： 官方支持并推荐大多数用户使用
• Python： 适用于低资源环境或想要手动设置的用户
• Kubernetes： 适用于需要扩展和编排的企业部署

Docker

Docker

Docker 快速部署 🐳

按照以下步骤使用 Docker 安装 Open WebUI。

步骤 1：Pull Open WebUI 镜像

首先从 GitHub Container Registry 拉取最新的 Open WebUI Docker 镜像。

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

重要配置参数

• 数据卷映射 (Volume Mapping: -v open-webui:/app/backend/data)：确保数据持久化存储，防止容器重启时数据丢失。
• 端口映射 (Port Mapping: -p 3000:8080)：将 WebUI 暴露在本地机器的 3000 端口上。

使用 GPU 支持

要启用 Nvidia GPU 支持，在 docker run 命令中添加 --gpus all：

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

单用户部署模式（禁用登录）

要在单用户部署中绕过登录页面，将 WEBUI_AUTH 环境变量设置为 False：

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

warning

在进行此配置后，您将无法在单用户模式和多账户模式之间切换。

高级部署配置：连接到其他服务器上的 Ollama

要将 Open WebUI 连接到位于其他主机上的 Ollama 服务器，添加 OLLAMA_BASE_URL 环境变量：

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

访问界面

容器启动后，在以下地址访问 Open WebUI：

http://localhost:3000

有关各项 Docker 参数的详细说明，请参阅 Docker 官方文档。

版本更新

要将本地 Docker 部署更新到最新版本，您可以使用 Watchtower 或手动升级容器。

选项 1：使用 Watchtower

使用 Watchtower，您可以自动化更新操作：

docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/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 --name open-webui ghcr.io/open-webui/open-webui:main

以上两种方法均可将您的 Docker 实例更新至最新版本并确保其正常运行。

Docker Compose

Docker Compose 部署指南

Docker Compose 是一个强大的工具，可以帮助您轻松管理多容器化的 Docker 应用程序。

如果您还没有安装 Docker，请参考我们的 Docker 安装教程。

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

重要提示： 请注意，Docker Compose 有两个主要版本。旧版本（V1）使用 docker-compose build 这样的命令格式，而新版本（V2）使用 docker compose build 格式（注意空格代替了连字符）。请确保使用 V2 版本的命令格式。

Docker Compose 配置示例

以下是一个基础的 Open WebUI Docker Compose 配置文件示例：

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

启动服务

使用以下命令启动所有服务：

docker compose up -d

部署辅助工具

项目提供了一个名为 run-compose.sh 的实用脚本工具。该脚本可以帮助您根据实际需求选择和组合不同的 Docker Compose 配置文件，使部署过程更加灵活和便捷。

---

GPU 支持说明： 如果您需要启用 Nvidia GPU 支持，需要进行以下修改：

1. 将镜像更改为 ghcr.io/open-webui/open-webui:cuda
2. 在服务配置中添加以下 GPU 设备配置：

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

这些配置将确保应用程序能够正确识别和使用系统中的 Nvidia GPU 资源。

Podman

Podman 部署指南

Podman 是一个无守护进程的容器引擎，专门用于开发、管理和运行 OCI（Open Container Initiative）容器，是 Docker 的优秀替代方案。

基础命令

• 启动容器：

  使用以下命令启动 Open WebUI 容器：

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

• 查看运行中的容器：

  使用以下命令查看所有正在运行的容器：

  podman ps

Podman 网络设置

如果遇到网络连接问题，您可能需要调整以下网络设置：

--network=slirp4netns:allow_host_loopback=true

有关更多配置说明，请参阅 Podman 官方文档。

Docker Swarm

Docker Swarm

这种安装方式需要 Docker Swarms 的相关知识，因为它使用堆栈文件在 Docker Swarm 中将 3 个隔离的容器部署为服务。

它包含了 ChromaDB、Ollama 和 OpenWebUI 的隔离容器。 此外，还包含了预设的环境变量以进一步说明配置。

根据您的硬件设置选择适当的命令：

• 准备工作：

  需要在主机上创建卷的目录，或者您可以指定自定义位置或卷。

  当前示例使用了一个隔离的目录 data，它位于与 docker-stack.yaml 相同的目录中。

  • 示例：

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

• GPU 支持配置：

  Docker-stack.yaml

  version: '3.9'
  
  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 守护进程。

• 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

Python

uv

uv 安装指南

uv 是一个高性能的 Python 包管理器和运行时管理器，可以为 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：

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

Python 版本更新指南

要使用 pip 将已安装的 Open-WebUI 包更新到最新版本，只需执行以下简单命令：

pip install -U open-webui

-U（或 --upgrade）参数用于指示 pip 将包升级到最新可用版本。定期更新可以确保您获得最新的功能和安全修复。

完成！您的 Open-WebUI 已成功更新到最新版本，现在可以使用所有最新特性了。

Conda

Conda 环境安装指南

1. 创建 Conda 环境：

   使用以下命令创建一个 Python 3.11 的新环境：

   conda create -n open-webui python=3.11

2. 激活 Conda 环境：

   切换到新创建的环境：

   conda activate open-webui

3. 安装 Open WebUI：

   使用 pip 安装最新版本：

   pip install open-webui

4. 启动 Open WebUI 服务：

   运行以下命令启动服务：

   open-webui serve

Python 版本更新指南

要使用 pip 将已安装的 Open-WebUI 包更新到最新版本，只需执行以下简单命令：

pip install -U open-webui

-U（或 --upgrade）参数用于指示 pip 将包升级到最新可用版本。定期更新可以确保您获得最新的功能和安全修复。

完成！您的 Open-WebUI 已成功更新到最新版本，现在可以使用所有最新特性了。

Venv

虚拟环境安装指南

使用 Python 内置的 venv 模块创建独立的 Python 环境，这可以避免依赖冲突并确保应用程序的稳定运行。

安装步骤

1. 创建虚拟环境：

   使用以下命令创建一个新的虚拟环境：

   python3 -m venv venv

2. 激活虚拟环境：

   根据您的操作系统选择相应的激活命令：

   • Linux/macOS 系统：

     source venv/bin/activate

   • Windows 系统：

     venv\Scripts\activate

3. 安装 Open WebUI：

   在激活的虚拟环境中安装 Open WebUI：

   pip install open-webui

4. 启动 Open WebUI 服务：

   运行以下命令启动服务：

   open-webui serve

Python 版本更新指南

要使用 pip 将已安装的 Open-WebUI 包更新到最新版本，只需执行以下简单命令：

pip install -U open-webui

-U（或 --upgrade）参数用于指示 pip 将包升级到最新可用版本。定期更新可以确保您获得最新的功能和安全修复。

完成！您的 Open-WebUI 已成功更新到最新版本，现在可以使用所有最新特性了。

Development

开发环境配置

对于想要贡献代码的开发者，请查看进阶主题中的开发指南。

Kubernetes

Helm

Helm 部署指南

Helm 是 Kubernetes 的包管理器，它可以帮助您简化 Kubernetes 应用程序的部署和管理流程。

前置要求

• 已配置并正常运行的 Kubernetes 集群
• 已正确安装并配置 Helm 工具
• 具有集群的管理员权限

安装步骤

1. 添加 Open WebUI Helm 仓库：

   运行以下命令添加官方仓库并更新本地缓存：

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

2. 安装 Open WebUI Chart：

   执行以下命令部署 Open WebUI：

   helm install openwebui open-webui/open-webui

3. 验证安装状态：

   检查 Pod 运行状态：

   kubectl get pods

访问服务

要从集群外部访问 Open WebUI，您可以：

• 配置端口转发：使用 kubectl port-forward 进行本地访问
• 设置负载均衡器：通过云服务提供商的负载均衡服务暴露服务
• 配置 Ingress：使用 Kubernetes Ingress 控制器管理外部访问

Kustomize

Kustomize 部署指南

Kustomize 是 Kubernetes 原生的配置管理工具，它允许您以声明式的方式自定义和管理 Kubernetes YAML 配置，无需使用模板。

前置要求

• 已配置并正常运行的 Kubernetes 集群
• 已正确安装并配置 Kustomize 工具（kubectl 1.14+ 已内置）
• 具有集群的管理员权限

安装步骤

1. 获取 Open WebUI 配置清单：

   克隆官方配置仓库并进入目录：

   git clone https://github.com/open-webui/k8s-manifests.git
   cd k8s-manifests

2. 部署应用：

   使用 Kustomize 应用配置清单：

   kubectl apply -k .

3. 验证部署状态：

   检查 Pod 运行状态：

   kubectl get pods

访问服务

要从集群外部访问 Open WebUI，您可以选择以下方式：

• 配置端口转发：使用 kubectl port-forward 进行本地访问
• 设置负载均衡器：通过云服务提供商的负载均衡服务暴露服务
• 配置 Ingress：使用 Kubernetes Ingress 控制器管理外部访问

Third Party

Pinokio.computer

Pinokio.computer 安装

通过 Pinokio.computer 安装，请访问他们的网站：

https://pinokio.computer/

此安装方式的支持通过他们的网站提供。

其他第三方集成

（随着第三方集成的可用性增加而添加相关信息。）

后续步骤

安装完成后，访问：

• http://localhost:3000 访问 Open WebUI。
• 或在使用 Python 部署时访问 http://localhost:8080/。

现在您可以开始使用 Open WebUI 了！

将 Open WebUI 与 Ollama 一起使用

如果您正在将 Open WebUI 与 Ollama 一起使用，请务必查看我们的 Ollama 入门指南，了解如何使用 Open WebUI 管理您的 Ollama 实例。

加入我们的社区

需要帮助？有问题？加入我们的社区：

• Open WebUI Discord
• GitHub Issues

获取最新功能、故障排除提示和公告！