> ## 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），安裝完成後重新執行上述命令確認。

    <Note>
      較早版本的 Docker Compose 使用 `docker-compose`（中間有短橫線）的寫法，本手冊統一使用新版語法 `docker compose`（中間是空格）。
    </Note>
  </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>