> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/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

## 部署前準備

**1. 準備 MixRoute 憑證**

> [!TIP]
>
> 目前站點支援模型的[智能路由](/docs/zh-Hant/api-reference/smart-routing)，能夠根據任務複雜程度分配執行模型。詳情見下文。

1. 取得 MixRoute API 端點地址：`https://api.mixroute.ai/v1`
2. 在 MixRoute 控制台生成您的 API Key。
3. 確認需要使用的模型名稱，如 `gpt-5.5`（需在 MixRoute 控制台已啟用該模型）。

**2. 環境依賴檢查**

確認電腦或伺服器已安裝 **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），安裝完成後重新執行上述命令確認。

## 部署 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`。

### 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`，說明服務正在正常執行。

## 存取並初始化帳號

**1. 存取 Web 介面**

打開瀏覽器存取 `http://localhost:3000`。

如果部署在遠端伺服器上，把 `localhost` 換成伺服器 IP 地址，例如 `http://伺服器IP:3000`。

**2. 註冊首個帳號**

第一次打開會看到註冊頁面，請填寫資訊完成註冊。

> [!WARNING]
>
> 第一個註冊的帳號會自動成為\*\*管理員（Administrator）\*\*帳號，擁有使用者管理和系統設定權限，請務必牢記這個帳號的郵箱和密碼。

**3. 後續使用者審批**

之後如果有其他人註冊，新帳號預設是「待審批（Pending）」狀態，需要管理員登入後台手動批准才能使用。

## 接入 MixRoute

Open WebUI 本身只是一個互動介面，需要連接至少一個模型服務商才能進行對話。Open WebUI 支援多種模型來源：

| 模型來源 | 說明 |
| - | - |
| Ollama（本地模型） | 免費在本機跑開源模型，無需聯網呼叫 |
| OpenAI | 使用 OpenAI 的 API Key 接入 GPT 系列模型 |
| Anthropic | 使用 Anthropic 的 API Key 接入 Claude 系列模型 |
| 其他相容 OpenAI 介面的服務 | 例如中轉平台、自建推理服務等 |

推薦透過 **MixRoute** 統一接入，一次設定即可使用 250 種主流 AI 模型，並在便捷使用的同時提供足夠的隱私保護等級。

**1. 打開設定**

登入 Open WebUI 後，點擊左下角頭像 →「設定」（Settings）。

![Openwebui P1](https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p1.png?fit=max\&auto=format\&n=qwAKZlzOFRKXXp1S\&q=85\&s=8662d96843f01722dba99e6d51147235)

**2. 進入連接配置**

進入「管理員設定」（Admin Settings）→「連接」（Connections）。

![Openwebui P2](https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p2.png?fit=max\&auto=format\&n=qwAKZlzOFRKXXp1S\&q=85\&s=39c472a163ec27c4c3bb039ee5f7c678)

**3. 填寫 MixRoute 憑證**

**智能路由節點接入憑證**

填入智能路由節點的憑證，填寫對應的 **API 地址（Base URL）** 和 **Smart Routing API Key**，儲存即可。

* **Base URL**：`https://api.mixroute.ai/v1`
* **API Key**：填入您的 Smart Routing API Key（例如 `sk-xxxxxxxx`）
* \*\*Model ID：\*\*填入模型選擇 **auto**

> [!NOTE]
>
> 智能路由功能約束和獲取見[文件](/docs/zh-Hant/api-reference/smart-routing)

**傳統API節點接入憑證**

根據要接入的服務商，填寫對應的 **API 地址（Base URL）** 和 **API Key**，儲存即可。

* **Base URL**：`https://api.mixroute.ai/v1`
* **API Key**：填入您的 MixRoute API Key（例如 `sk-xxxxxxxx`）
* \*\*Model ID：\*\*填入具體的模型ID，例如`gpt-5.5`，若讓其自動獲取

![Openwebui P3](https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p3.png?fit=max\&auto=format\&n=qwAKZlzOFRKXXp1S\&q=85\&s=f474eeace78f0a309e6e1017080643f3)

**4. 選擇模型並開始對話**

返回主介面，在模型選擇框中就能看到新接入的模型，選中後即可開始對話。

> [!TIP]
>
> 經過測試，GPT 系列在 OpenWebUI 中表現良好，建議配合 GPT 模型使用。

## 常用維護操作

### 停止服務

```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` 中，與容器本身分離）。

### 徹底解除安裝

僅停止並刪除容器（保留資料，可隨時重新 `up -d` 恢復）：

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

停止並刪除容器 **同時刪除全部資料**（聊天記錄、帳號等將永久遺失，謹慎操作）：

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

## 常見問題

> **瀏覽器打不開 [http://localhost:3000？](http://localhost:3000？)**
>
> * 確認容器是否正常執行：`docker compose ps`，檢視 `STATUS` 是否為 `Up`。
> * 確認埠是否被其他程式佔用，可嘗試修改 `docker-compose.yml` 中的埠號後重新 `docker compose up -d`。

> **忘記了管理員密碼怎麼辦？**
>
> 可以在設定中重設密碼；如無法登入，需透過資料庫層面處理，建議先在 Discord/GitHub 社群尋求協助，避免直接刪除資料卷（會遺失全部資料）。

> **修改 docker-compose.yml 後如何生效？**
>
> 修改儲存檔案後，在同一目錄下重新執行：
>
> ```bash theme={null}
> docker compose up -d
> ```
>
> Docker Compose 會自動檢測變化並重建容器。

> [!NOTE]
>
> 配置完成後，Open WebUI 所有的對話與能力都將基於您在設定中綁定的 MixRoute 端點進行驅動，享受強大且極具性價比的雲端大模型服務。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.