> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenWebUI

> 使用 Docker Compose 部署 OpenWebUI，并通过 MixRoute 接入各类主流 AI 模型。

Open WebUI 是一个功能开源的 AI 交互界面，支持多种模型服务商接入，提供用户管理、对话记录持久化等能力。本指南介绍如何通过 Docker Compose 部署 Open WebUI，并接入 **MixRoute** 统一调用各类主流 AI 模型。

* 官方文档：[docs.openwebui.com/getting-started/quick-start](https://docs.openwebui.com/getting-started/quick-start/)
* 部署方式：Docker Compose

## 部署前准备

<Steps>
  <Step title="准备 MixRoute 凭证">
    1. 获取 MixRoute API 端点地址：`https://api.mixroute.ai/v1`
    2. 在 MixRoute 控制台生成您的 API Key。
    3. 确定需要使用的模型名称，如 `gpt-5.5`（需在 MixRoute 控制台已启用该模型）。
  </Step>

  <Step title="环境依赖检查">
    确认电脑或服务器已安装 **Docker**（包含 Docker Compose V2）。在终端执行：

    ```bash theme={null}
    docker -v
    docker compose version
    ```

    如果两条命令都能返回版本号，说明环境已就绪。如未安装，请前往 [Docker 官网](https://docs.docker.com/get-docker/) 下载安装 Docker Desktop（Windows/macOS）或 Docker Engine（Linux），安装完成后重新执行上述命令确认。
  </Step>
</Steps>

## 部署 OpenWebUI

### 1. 新建专用文件夹

打开终端，执行以下命令（创建名为 `openwebui` 的文件夹并进入）：

```bash theme={null}
mkdir openwebui
cd openwebui
```

### 2. 创建 docker-compose.yml

在 `openwebui` 文件夹内新建 `docker-compose.yml`，内容完整复制粘贴如下：

```yaml theme={null}
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      # 主机端口:容器端口
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

**字段说明：**

| 字段                   | 作用                                         |
| -------------------- | ------------------------------------------ |
| `image`              | 使用的 Open WebUI 官方镜像（`main` 为标准稳定版）         |
| `ports: "3000:8080"` | 将容器内的 8080 端口映射到本机的 3000 端口，之后通过 3000 端口访问 |
| `volumes`            | 数据持久化目录，防止容器重启/更新后聊天记录、账号等数据丢失             |
| `restart: always`    | 容器异常退出或系统重启后自动重新启动                         |

<Note>
  如果需要在服务器或局域网环境中使用 Open WebUI，可通过环境变量添加 `WEBUI_SECRET_KEY` 和 `WEBUI_URL`：

  * `WEBUI_SECRET_KEY`：可使用 `openssl rand -hex 32` 随机生成。
  * `WEBUI_URL`：填入公网 IP 或域名。

  如果本机 3000 端口已被占用，可把 `"3000:8080"` 改为例如 `"3010:8080"`，访问地址相应改为 `http://localhost:3010`。
</Note>

### 3. 启动服务

在 `docker-compose.yml` 所在目录下执行：

```bash theme={null}
docker compose up -d
```

* `up`：启动服务
* `-d`：后台运行

首次运行会自动下载镜像，根据网络情况需要等待几分钟。看到类似 `Container open-webui Started` 的提示，说明启动成功。

检查运行状态：

```bash theme={null}
docker compose ps
```

如果 `STATUS` 列显示 `Up`，说明服务正在正常运行。

## 访问并初始化账号

<Steps>
  <Step title="访问 Web 界面">
    打开浏览器访问 `http://localhost:3000`。

    如果部署在远程服务器上，把 `localhost` 换成服务器 IP 地址，例如 `http://服务器IP:3000`。
  </Step>

  <Step title="注册首个账号">
    第一次打开会看到注册页面，请填写信息完成注册。

    <Warning>
      第一个注册的账号会自动成为\*\*管理员（Administrator）\*\*账号，拥有用户管理和系统设置权限，请务必牢记这个账号的邮箱和密码。
    </Warning>
  </Step>

  <Step title="后续用户审批">
    之后如果有其他人注册，新账号默认是「待审批（Pending）」状态，需要管理员登录后台手动批准才能使用。
  </Step>
</Steps>

## 接入 MixRoute

Open WebUI 本身只是一个交互界面，需要连接至少一个模型服务商才能进行对话。Open WebUI 支持多种模型来源：

| 模型来源              | 说明                                    |
| ----------------- | ------------------------------------- |
| Ollama（本地模型）      | 免费在本机跑开源模型，无需联网调用                     |
| OpenAI            | 使用 OpenAI 的 API Key 接入 GPT 系列模型       |
| Anthropic         | 使用 Anthropic 的 API Key 接入 Claude 系列模型 |
| 其他兼容 OpenAI 接口的服务 | 例如中转平台、自建推理服务等                        |

推荐通过 **MixRoute** 统一接入，一次配置即可使用 200+ 主流 AI 模型，并在便捷使用的同时提供足够的隐私保护等级。

<Steps>
  <Step title="打开设置">
    登录 Open WebUI 后，点击左下角头像 →「设置」（Settings）。

    <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p1.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=8662d96843f01722dba99e6d51147235" alt="Openwebui P1" width="541" height="937" data-path="images/openwebui-p1.png" />
  </Step>

  <Step title="进入连接配置">
    进入「管理员设置」（Admin Settings）→「连接」（Connections）。

    <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p2.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=39c472a163ec27c4c3bb039ee5f7c678" alt="Openwebui P2" width="2962" height="765" data-path="images/openwebui-p2.png" />
  </Step>

  <Step title="填写 MixRoute 凭证">
    根据要接入的服务商，填写对应的 **API 地址（Base URL）** 和 **API Key**，保存即可。

    * **Base URL**：`https://api.mixroute.ai/v1`
    * **API Key**：填入您的 MixRoute API Key（例如 `sk-xxxxxxxx`）

          <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p3.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=f474eeace78f0a309e6e1017080643f3" alt="Openwebui P3" width="1081" height="1243" data-path="images/openwebui-p3.png" />
  </Step>

  <Step title="选择模型并开始对话">
    返回主界面，在模型选择框中就能看到新接入的模型，选中后即可开始对话。

    <Tip>
      经过测试，GPT 系列在 OpenWebUI 中表现良好，建议配合 GPT 模型使用。
    </Tip>
  </Step>
</Steps>

## 常用维护操作

### 停止服务

```bash theme={null}
docker compose stop
```

### 重新启动服务

```bash theme={null}
docker compose start
```

### 查看日志（排查问题用）

```bash theme={null}
docker compose logs -f
```

### 更新到最新版本

```bash theme={null}
docker compose pull
docker compose up -d
```

<Note>
  `pull` 会拉取最新镜像，`up -d` 会用新镜像重新创建容器，数据不会丢失（因为数据存储在 `volumes` 中，与容器本身分离）。
</Note>

### 彻底卸载

仅停止并删除容器（保留数据，可随时重新 `up -d` 恢复）：

```bash theme={null}
docker compose down
```

停止并删除容器 **同时删除全部数据**（聊天记录、账号等将永久丢失，谨慎操作）：

```bash theme={null}
docker compose down -v
```

## 常见问题

<Accordion title="浏览器打不开 http://localhost:3000？">
  * 确认容器是否正常运行：`docker compose ps`，查看 `STATUS` 是否为 `Up`。
  * 确认端口是否被其他程序占用，可尝试修改 `docker-compose.yml` 中的端口号后重新 `docker compose up -d`。
</Accordion>

<Accordion title="忘记了管理员密码怎么办？">
  可以在设置中重置密码；如无法登录，需通过数据库层面处理，建议先在 Discord/GitHub 社区寻求帮助，避免直接删除数据卷（会丢失全部数据）。
</Accordion>

<Accordion title="修改 docker-compose.yml 后如何生效？">
  修改保存文件后，在同一目录下重新执行：

  ```bash theme={null}
  docker compose up -d
  ```

  Docker Compose 会自动检测变化并重建容器。
</Accordion>

<Info>
  配置完成后，Open WebUI 所有的对话与能力都将基于您在设置中绑定的 MixRoute 端点进行驱动，享受强大且极具性价比的云端大模型服务。
</Info>