第二章. 本地快速部署

在上一章中，我们了解了 Open WebUI 是什么。现在让我们动手实践，在本地环境中把它跑起来。本章将专注于本地部署，帮助你在最短时间内体验到 Open WebUI 的强大功能。

在开始之前，让我们明确一个目标：本章结束时，你将拥有一个运行在本地的 Open WebUI 实例，可以通过浏览器访问，并能够与 AI 模型进行对话。

2.1. 环境准备

在部署 Open WebUI 之前，我们需要先准备好基础环境。根据你选择的部署方式不同，需要准备的环境也不同。

Docker 环境准备

Docker 是我们强烈推荐的部署方式。如果你还没有安装 Docker，请按照以下步骤操作。

1

docker --version

1

wsl --install

1

docker --version

1
2

sudo apt update
sudo apt upgrade -y

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 安装必要的依赖
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

1

sudo usermod -aG docker $USER

1

newgrp docker

1
2

docker --version
docker compose version

1
2

sudo systemctl start docker
sudo systemctl enable docker

Python 环境准备（非 Docker 部署）

如果你选择使用 Python 直接安装 Open WebUI，需要准备 Python 环境。

1
2

python --version
pip --version

1

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

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1

brew install python@3.11

1
2

python3 --version
pip3 --version

1

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

1
2

sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip

1
2

python3 --version
pip3 --version

1

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

2.2. 使用 Docker Compose 部署

现在环境已经准备好了，让我们开始部署 Open WebUI。

我们直接使用 Docker Compose 进行部署——这是官方推荐的方式，也是最规范、最易维护的方案。所有配置集中在一个 YAML 文件中，启动、停止、更新都只需要一条命令。

💡 为什么不用 docker run？ 虽然一条 docker run 命令也能启动，但参数又长又容易出错，修改配置需要删除容器重建，多服务管理更是噩梦。Docker Compose 从一开始就解决了这些问题，没有理由绕弯路。

步骤 1：克隆官方仓库

1
2

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

仓库中已经包含了官方的 docker-compose.yaml，默认配置了 Open WebUI + Ollama 两个服务。

如果你的网络无法访问 GitHub，可以手动下载仓库的 ZIP 包，或者只创建一个目录并手动编写配置文件（见下方配置示例）。

步骤 2：根据场景选择配置

官方的 docker-compose.yaml 默认包含 Ollama 服务。但实际使用中，你可能不需要 Ollama（比如你只用 OpenAI API），或者你的 Ollama 已经安装在宿主机上。

我们推荐使用 docker-compose.override.yaml 或独立的配置文件来覆盖默认配置，这样官方文件保持不动，git pull 更新时不会产生冲突。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
    container_name: open-webui
    restart: unless-stopped
    ports:
      - ${OPEN_WEBUI_PORT-3000}:8080
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      # 连接外部 OpenAI 兼容 API
      - OPENAI_API_BASE_URL=https://api.openai.com/v1
      - OPENAI_API_KEY=sk-your-api-key-here
      - ENABLE_OPENAI_API=True
      # 关闭 Ollama（不需要本地模型）
      - ENABLE_OLLAMA_API=False
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  open-webui-data:

1

docker compose -f docker-compose.local.yaml up -d

1

docker compose up -d

1
2

# 在 Ollama 容器内下载模型
docker compose exec ollama ollama pull qwen2.5:7b

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
    container_name: open-webui
    restart: unless-stopped
    ports:
      - ${OPEN_WEBUI_PORT-3000}:8080
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  open-webui-data:

1

docker compose -f docker-compose.local.yaml up -d

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama-data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
    container_name: open-webui
    restart: unless-stopped
    ports:
      - ${OPEN_WEBUI_PORT-3000}:8080
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  ollama-data:
  open-webui-data:

1
2
3
4
5
6
7
8

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

1

docker compose -f docker-compose.local.yaml up -d

步骤 3：使用 .env 管理变量（可选）

如果你不想把 API Key 等敏感信息写在 YAML 文件中，可以创建一个 .env 文件：

1
2
3
4

# .env 文件（与 docker-compose 文件同目录）
WEBUI_DOCKER_TAG=main
OPEN_WEBUI_PORT=3000
OPENAI_API_KEY=sk-your-api-key-here

然后在 docker-compose.local.yaml 中用 ${OPENAI_API_KEY} 引用即可。.env 文件通常已被 .gitignore 忽略，不会被提交到版本库。

步骤 4：启动并验证

1
2
3
4
5
6
7
8

# 启动（根据你选择的方案）
docker compose -f docker-compose.local.yaml up -d

# 查看容器状态
docker compose -f docker-compose.local.yaml ps

# 查看日志（如果需要排查问题）
docker compose -f docker-compose.local.yaml logs --tail 50

你应该看到类似以下输出：

1
2

NAME           IMAGE                                COMMAND          STATUS                 PORTS
open-webui     ghcr.io/open-webui/open-webui:main   "bash start.sh"  Up 2 minutes (healthy) 0.0.0.0:3000->8080/tcp

状态为 Up ... (healthy) 表示服务已正常运行。

Docker Compose 常用命令速查

以下命令均以 -f docker-compose.local.yaml 为例，如果你使用官方默认的 docker-compose.yaml，去掉 -f 参数即可。

关于 Python 直接安装

如果你的环境无法使用 Docker（如某些受限的开发机），Open WebUI 也支持通过 Python 直接安装：

1
2
3
4
5
6

# 使用 uv（推荐）
uvx --python 3.11 open-webui@latest serve

# 或使用 pip
pip install open-webui
open-webui serve

Python 安装后访问 http://localhost:8080 。但这种方式环境依赖复杂、升级维护不便，仅建议用于临时体验或开发调试，不推荐用于长期使用。

2.3. 首次启动与验证

部署完成后，我们需要系统地验证各项功能是否正常工作。

第一步：确认容器状态

1

docker compose -f docker-compose.local.yaml ps

关键信息解读：

如果状态不正常，查看日志定位问题：

1

docker compose -f docker-compose.local.yaml logs --tail 50

第二步：访问 Web 界面

打开浏览器，访问 http://localhost:3000 。

你会看到 Open WebUI 的欢迎页面。

如果无法访问，按以下顺序排查：

1. 确认容器正在运行：docker compose -f docker-compose.local.yaml ps
2. 确认端口未被占用：lsof -i :3000（macOS/Linux）或 netstat -ano | findstr :3000（Windows）
3. 检查防火墙：确认没有阻止 3000 端口

第三步：创建管理员账号

首次访问时，你会看到注册页面。第一个注册的用户自动成为管理员，拥有系统最高权限。

⚠️ 重要：请务必牢记管理员的邮箱和密码。忘记密码需要手动操作数据库才能重置。

注册完成后，系统自动登录并进入主界面。

第四步：连接 AI 模型

根据你的部署方案，模型连接方式不同：

如果你使用了 Ollama：

模型选择器中应该已经显示了你下载的模型。如果没有，进入 管理员面板 → 设置 → 连接，确认 Ollama API URL 配置正确，点击刷新。

如果你只部署了 Open WebUI（方案一）：

你需要在配置文件中填写正确的 API 地址和密钥（已在 2.2 节的配置中完成），或者在 管理员面板 → 设置 → 连接 中手动配置：

1. 在 OpenAI API 区域填入 API Base URL 和 API Key
2. 点击保存，然后点击刷新按钮
3. 连接成功后，模型选择器中会出现可用模型

第六步：发送测试消息

选择一个模型，在输入框中输入：

1

你好，请用一句话介绍你自己

如果 AI 正常回复，恭喜你，Open WebUI 已经部署成功！🎉

常见启动问题排查

查看启动日志：

1

docker compose -f docker-compose.local.yaml logs --tail 100

问题 1：HuggingFace 连接失败（SSL 重连错误）

1
2
3
4
5

requests.exceptions.SSLError: HTTPSConnectionPool(host='huggingface.co', port=443):
Max retries exceeded ... certificate verify failed
Retrying in 1s [Retry 1/5].
Retrying in 2s [Retry 2/5].
...

原因：Open WebUI 启动时会从 HuggingFace 下载 RAG 嵌入模型（sentence-transformers/all-MiniLM-L6-v2），网络无法访问 huggingface.co 时会反复重试。

影响：仅影响 RAG 文档问答功能，不影响 正常对话。服务最终会跳过下载并正常启动。

解决方案：

问题 2：端口被占用

1

Error: Bind for 0.0.0.0:3000 failed: port is already allocated

解决方案：修改配置文件中的端口映射，或在 .env 中设置 OPEN_WEBUI_PORT=3001。

问题 3：Ollama 连接失败

1

WARNING: Ollama connection failed: Connection refused

解决方案：

• 不需要 Ollama：添加环境变量 ENABLE_OLLAMA_API=False
• Ollama 在宿主机：确认 Ollama 服务已启动，且配置了 extra_hosts 和正确的 OLLAMA_BASE_URL

快速排查清单

2.4. 数据持久化与备份

数据持久化是部署中非常重要的一环。如果配置不当，容器重启后所有数据都会丢失。

Docker 卷的工作原理

在前面的部署命令中，我们使用了 -v open-webui:/app/backend/data 参数。这个参数创建了一个名为 open-webui 的 Docker 卷，并将其挂载到容器内的 /app/backend/data 目录。

Open WebUI 的所有数据都存储在这个目录中，包括：

查看 Docker 卷

你可以通过以下命令查看已创建的 Docker 卷：

1
2
3
4
5

# 列出所有卷
docker volume ls

# 查看卷的详细信息（包括在宿主机上的实际存储路径）
docker volume inspect open-webui

备份数据

定期备份数据是一个好习惯。以下是几种备份方式：

方法 1：直接复制卷数据

1
2
3
4
5
6
7
8

# 创建备份目录
mkdir -p ~/open-webui-backup

# 使用临时容器将卷数据复制出来
docker run --rm \
  -v open-webui:/data \
  -v ~/open-webui-backup:/backup \
  alpine tar czf /backup/open-webui-backup-$(date +%Y%m%d).tar.gz -C /data .

方法 2：使用绑定挂载代替命名卷

如果你希望数据直接存储在宿主机的指定目录（方便备份和管理），可以在 Docker Compose 中使用绑定挂载：

1
2
3
4

services:
  open-webui:
    volumes:
      - ./data:/app/backend/data    # 数据存储在当前目录的 data 文件夹中

这样你可以直接对 ./data 目录进行备份，无需通过 Docker 命令。

方法 3：导出数据库

Open WebUI 使用 SQLite 数据库，你可以直接复制数据库文件：

1
2

# 从容器中复制数据库文件
docker cp open-webui:/app/backend/data/webui.db ~/open-webui-backup/webui.db

恢复数据

从备份恢复：

1
2
3
4
5
6
7
8
9
10
11

# 停止容器
docker compose down

# 恢复备份数据到卷
docker run --rm \
  -v open-webui:/data \
  -v ~/open-webui-backup:/backup \
  alpine sh -c "cd /data && tar xzf /backup/open-webui-backup-20260210.tar.gz"

# 重新启动
docker compose up -d

数据迁移

如果你需要将 Open WebUI 迁移到另一台服务器：

1. 在旧服务器上备份数据（使用上述备份方法）
2. 将备份文件传输到新服务器
3. 在新服务器上创建 Docker 卷并恢复数据
4. 使用相同的 Docker Compose 配置启动服务

2.5. 本章小结

在本章中，我们完成了 Open WebUI 的本地部署，从环境准备到首次验证，走通了完整流程。

现在你已经拥有了一个运行在本地的 Open WebUI 实例。在下一章中，我们将深入配置，包括连接多个 AI 模型、自定义界面、管理用户权限等进阶操作。