Open WebUI 是一个功能强大、可自托管的AI交互平台，支持 Ollama 本地模型 和 OpenAI 兼容的 API。它提供了丰富的功能，如RAG（检索增强生成）、网页搜索、多模型对话、RBAC权限管理等，并且可以完全离线运行。

本教程将指导你通过 Docker（推荐）、Python pip 和 源码 等多种方式完成部署。

📦 第一步：部署前准备

在开始部署前，请根据你的选择准备相应的环境。

部署方式 前提条件
Docker (推荐) 安装 Docker 和 Docker Compose，支持 GPU 需要 NVIDIA Container Toolkit
Python pip Python 3.11 (必须)，pip，建议使用虚拟环境
源码开发 Node.js, Python 3.11, pnpm, Docker (用于依赖服务)
  • 网络说明：如果在中国大陆或离线环境，可能需要配置镜像或设置 HF_HUB_OFFLINE=1 环境变量。

🐳 第二步：使用 Docker 部署（推荐方式）

Docker 是最简单、最推荐的部署方式。以下根据不同场景提供命令。

2.1 基础部署（Ollama 在同一台机器上）

如果 Ollama 运行在 同一台主机 上，使用以下命令。--add-host=host.docker.internal:host-gateway 允许容器内访问主机的服务。

1
2
3
4
5
6
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main
  • 访问：启动后，打开浏览器访问 http://localhost:3000。
  • 数据持久化：-v open-webui:/app/backend/data 将数据库和文件存储在 Docker 卷中。

2.2 Ollama 在不同服务器上

如果 Ollama 运行在 其他服务器 上，需要通过 -e OLLAMA_BASE_URL 指定其地址。

1
2
3
4
5
6
docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=https://your-ollama-server.com \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

2.3 仅使用 OpenAI API（或其他兼容 API）

如果只使用云端 API（如 OpenAI, Groq, DeepSeek 等），无需本地 Ollama，只需设置环境变量。

1
2
3
4
5
6
docker run -d -p 3000:8080 \
  -e OPENAI_API_KEY=你的密钥 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

你可以在 WebUI 的设置界面中，进一步添加其他兼容的 API 端点（如 https://api.deepseek.com/v1）。

2.4 使用 GPU 加速（NVIDIA）

如果主机有 NVIDIA GPU，使用 :cuda 标签并添加 --gpus all 参数（需提前安装 NVIDIA Container Toolkit）。

1
2
3
4
5
6
7
docker run -d -p 3000:8080 \
  --gpus all \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:cuda

2.5 使用 Bundled Ollama 镜像（一体式方案）

这个镜像（:ollama 标签）将 Open WebUI 和 Ollama 打包在同一个容器中，适合希望一键部署本地模型的用户。

  • 带 GPU 支持：

    1
    2
    3
    4
    5
    6
    7
    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 模式：

    1
    2
    3
    4
    5
    6
    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

注意：--add-host=host.docker.internal:host-gateway 在部分 :ollama 镜像中可能不需要，视具体网络配置而定。

🐍 第三步：使用 Python pip 安装

此方式适合非 Docker 环境，或希望进行二次开发的用户。

  1. 确保 Python 3.11 环境（建议使用 conda 或 venv 创建虚拟环境）：

    1
    python --version  # 确认是 3.11

  2. 安装 Open WebUI：

    1
    pip install open-webui

  3. 启动服务：

    1
    open-webui serve

    服务默认运行在 http://localhost:8080。你可以通过 --port 和 --host 参数调整。

⚙️ 第四步：使用 Docker Compose（进阶）

项目提供了 docker-compose.yaml 文件，便于管理多服务（如包含 Ollama、PostgreSQL、Redis 等）的部署。

  1. 克隆仓库（或下载 docker-compose.yaml）：

    1
    2
    git clone https://github.com/open-webui/open-webui.git
    cd open-webui

  2. （可选）配置环境变量：复制 .env.example 为 .env，并修改所需参数（如数据库连接、API密钥等）。

  3. 启动所有服务：

    1
    docker-compose up -d

  4. 停止服务：

    1
    docker-compose down

🔧 第五步：配置与使用

  1. 首次访问：浏览器打开 http://localhost:3000 (Docker) 或 http://localhost:8080 (pip)。
  2. 注册账户：首次访问需要创建一个管理员账户（这是本地实例的第一个用户，拥有最高权限）。
  3. 连接模型：
    • 本地 Ollama：如果 Ollama 运行在主机上且使用推荐 Docker 命令，WebUI 会自动检测到。
    • 云端 API：登录后，点击左下角用户头像 → 设置 → 连接，添加 OpenAI 或其他兼容 API 的密钥和基础 URL。
  4. 开始对话：在顶部选择模型，即可开始聊天。

🩺 常见问题与排障

  • 容器内无法连接 Ollama (127.0.0.1:11434)：
    这是最常见的问题。在 Docker 命令中添加 --add-host=host.docker.internal:host-gateway 并设置 -e OLLAMA_BASE_URL=http://host.docker.internal:11434。或者使用 --network=host 模式（此时访问端口变为 8080）。
  • 数据库连接或迁移失败：
    检查 Docker 卷 (-v open-webui:/app/backend/data) 是否正确挂载，确保目录有写入权限。如果使用外部 PostgreSQL，请检查 .env 或环境变量中的连接字符串。
  • 更新版本：
    • Docker：停止并删除旧容器，拉取新镜像后重新运行。
    • pip：执行 pip install -U open-webui，然后重启服务。
    • 注意：更新前请备份 data 目录或 Docker 卷，以防数据丢失。
  • 登录后页面空白或报错：
    尝试清除浏览器缓存，或使用浏览器的隐身模式访问。检查浏览器控制台是否有错误信息。
  • 中国用户访问慢或无法拉取镜像：
    • 使用国内镜像加速器（如阿里云、中科大）配置 Docker。
    • 对于 Python 安装，可使用国内 PyPI 镜像（如 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple open-webui）。

⚖️ 许可与声明

Open WebUI 的代码库包含多种许可证。当前代码库主要遵循 Open WebUI 许可证，该许可证在 Apache 2.0 基础上附加了保留 “Open WebUI” 品牌标识的要求。此外，项目也包含早期贡献者依据其原始许可证提交的代码。详细的许可变更历史和适用条款，请参阅项目根目录下的 LICENSE 和 LICENSE_HISTORY 文件。

现在，你已经可以通过最适合你的方式成功部署 Open WebUI。开始探索这个强大的AI交互平台，并将其与你的本地模型或云API结合使用吧。如需更详细的配置选项，建议查阅 官方文档。