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

# 雲端開發與遠端開發

> 把 Vibex 部署到伺服器，或讓手機連上你自己的桌面端。

Vibex 有兩種“人不在電腦前也能繼續幹活”的用法。先確認你要哪一種：

| 你想要的效果 | 這條路線的名字 | Agent 在哪臺機器上跑 | 誰連進來 |
| - | - | - | - |
| 把開發環境放到伺服器，公司電腦、家裡筆記本、手機都接著用同一個環境 | 雲端開發：部署**無頭執行階段** `vibex-server` | 伺服器 | 桌面端和行動端都作為客戶端連過去 |
| 手機或平板連你自己開機的電腦 | 遠端開發：桌面端 + 行動端 | 你自己的電腦 | 只有你配對過的移動裝置 |

> [!NOTE]
>
> **什麼是無頭執行階段**：可以理解成“沒有視窗的 Vibex”。Agent 會話、工作區、Git、終端機和供應商設定都由它負責，能力和桌面端完全一樣，只是它跑在伺服器上，你需要通過桌面端或手機連過去操作。它的程式名是 `vibex-server`。

兩條路線都靠**一次性配對**建立信任：第一次必須在裝置旁邊拿到配對碼或二維碼；配對成功後長期憑據儲存在兩端，之後會自動重連，不需要反覆配對。

下面的步驟假設你已經裝好桌面端。Android 客戶端可以從 GitHub Releases 側載安裝；iOS 提供未簽名的真機 IPA 和模擬器包，真機需要用自己的 Apple ID 重簽名，詳見[安裝與平台](https://vibex.peatboy.com/docs/zh-TW/install.md)。

## 一、雲端開發：把 Vibex 部署到伺服器

Agent 會在伺服器上讀寫程式碼、執行命令，所以先把伺服器準備好，再用客戶端連過去。

### 開始之前

* 一臺裝了 Docker 的 Linux 伺服器。只有你一個人用：1 核 2 GB 記憶體起步；同時跑多個 Agent：建議 2 核 4 GB 以上。
* 程式碼要能在伺服器上訪問到：在伺服器上 `git clone`，或者把宿主機的程式碼目錄掛進容器（下面示例用的是掛載）。
* Agent 的賬號或 API Key 等客戶端連上以後再配置：在桌面端的 **配置中心** 裡新增（見 [配置中心](https://vibex.peatboy.com/docs/zh-TW/config-center.md)），**不要**寫進 compose 檔案，也不要提交到倉庫。

### 第 1 步：啟動執行階段

專案倉庫裡已經包含一份完整的 `docker-compose.yml` 配置檔案，可以直接檢視：[deploy/server/docker-compose.yml](https://github.com/vibex-ai/vibex/blob/main/deploy/server/docker-compose.yml)。下面這份是按本文場景裁剪的最小示例，儲存成 `docker-compose.yml` 放在伺服器上任意目錄即可：

```yaml theme={null}
services:
  vibex-server:
    # 用移動通道標籤：rc 跟隨最新候選版，latest 跟隨最新穩定版；
    # 需要固定版本時再改成具體的版本號
    image: ghcr.io/vibex-ai/vibex-server:rc
    container_name: vibex-server
    # 伺服器重啟後自動拉起；配合下面的 healthcheck 使用
    restart: unless-stopped
    # 共享宿主機網路：容器裡的迴環地址就是宿主機的迴環地址，
    # 免去橋接網路下發布埠需要非迴環繫結（迴環模式會拒絕這種繫結）的麻煩
    network_mode: host
    environment:
      # 執行階段資料目錄：資料庫、伺服器身份、Agent 安裝都在這裡
      VIBEX_HOME: /data
      VIBEX_DB_PATH: /data/vibex.db
      # 只寫 127.0.0.1 的話，手機和別的電腦連不進來
      VIBEX_BIND_ADDR: 0.0.0.0:8765
      # lan = 允許區域網訪問；公網部署要改成 public 並配 HTTPS
      VIBEX_DEPLOYMENT_MODE: lan
      # 執行階段自己籤一張證書：客戶端從配對連線串裡拿到指紋，不用買證書
      VIBEX_TLS_MODE: pinned_certificate
      # 客戶端撥號的地址，埠必須和 VIBEX_BIND_ADDR 一致
      VIBEX_PUBLIC_HOST: 192.168.1.10:8765
      # 允許客戶端在哪些目錄裡挑專案，冒號分隔；下面第 4 步會用到
      VIBEX_WORKSPACE_ROOTS: /data:/data/repos
    volumes:
      # 唯一需要備份的卷：資料庫 + 伺服器身份（丟了要重新配對所有裝置）
      - vibex-data:/data
      # 你的程式碼目錄：掛進來之後，路徑還要寫進 VIBEX_WORKSPACE_ROOTS
      - /srv/repos:/data/repos        # 改成你想讓 Vibex 開啟的程式碼目錄
volumes:
  vibex-data:
```

第 1 步示例只用了最必要的幾個變數；完整的變數清單（包括限流、事件容量、金鑰存放位置等）見[環境變數參考](https://vibex.peatboy.com/docs/zh-TW/reference/environment-variables.md)。

> [!NOTE]
>
> `image` 裡的 `rc` 跟隨最新候選版，`latest` 跟隨最新穩定版；需要固定版本時再改成具體版本號。已經克隆了倉庫時，也可以直接用倉庫裡的部署檔案從原始碼構建：`docker compose -f deploy/server/docker-compose.yml up --build -d vibex-server`。

啟動並取得配對資訊：

```bash theme={null}
docker compose up -d
docker logs vibex-server | grep -E 'pairing_(code|link)'
```

日誌裡會出現兩樣東西：

* `pairing_code=123-456-789`：一次性配對碼，預設 5 分鐘後過期。
* `pairing_link=vibex://pair#/code/...`：一條配對連線串，已經包含伺服器地址、一次性配對碼和伺服器證書（DER）。複製整條即可；客戶端會在發出第一個請求前固定這張證書，所以自簽證書的伺服器不需要系統 CA。

> [!WARNING]
>
> 配對碼和連線串等同於密碼，只在配對時用一次。不要發到群裡、Issue 或截圖裡。過期後可以隨時在伺服器上重新生成。

```bash theme={null}
docker exec vibex-server vibex-server pairing-code
```

### 如果伺服器在公網

公網部署只多一件事：**必須用 HTTPS**。讓 Caddy 自動申請證書，執行階段自己只監聽本機迴環地址：

```yaml theme={null}
services:
  vibex-server:
    image: ghcr.io/vibex-ai/vibex-server:latest
    container_name: vibex-server
    restart: unless-stopped
    network_mode: host
    environment:
      # 只監聽本機，公網流量一律走 Caddy；8765 不對公網開放
      VIBEX_BIND_ADDR: 127.0.0.1:8765
      # 公網部署：沒有可信 HTTPS 會拒絕啟動
      VIBEX_DEPLOYMENT_MODE: public
      VIBEX_TLS_MODE: trusted_https_proxy
      # 讓限流按真實客戶端 IP 計算；只有反代終結 TLS 時才設 true
      VIBEX_TRUST_FORWARDED_HEADERS: "true"
      # 客戶端實際訪問的域名，配對連線串裡用的也是它
      VIBEX_PUBLIC_HOST: vibex.example.com
      # 只接受這些域名/來源的請求，必須和上面一致
      VIBEX_ALLOWED_HOSTS: vibex.example.com
      VIBEX_ALLOWED_ORIGINS: https://vibex.example.com
      # 允許客戶端挑選專案的目錄，冒號分隔
      VIBEX_WORKSPACE_ROOTS: /data:/data/repos
    volumes:
      # 唯一需要備份的卷：資料庫 + 伺服器身份
      - vibex-data:/data
      - /srv/repos:/data/repos

  # 反向代理：自動申請並續期證書，把 443 的請求轉到執行階段的迴環埠
  caddy:
    image: caddy:2-alpine
    container_name: vibex-caddy
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config

volumes:
  vibex-data:
  caddy-data:
  caddy-config:
```

同目錄再放一個 `Caddyfile`：

```text theme={null}
vibex.example.com {
    reverse_proxy 127.0.0.1:8765
}
```

```bash theme={null}
docker compose up -d
docker logs vibex-server | grep -E 'pairing_(code|link)'
```

防火牆只需要放行 `80`、`443` 和 SSH；執行階段的 `8765` 保持在迴環地址上，不要暴露到公網。把域名和地址換成你自己的之後，`VIBEX_ALLOWED_HOSTS` 與 `VIBEX_ALLOWED_ORIGINS` 必須和實際訪問用的域名一致，否則請求會被直接拒絕。

> [!TIP]
>
> 不想把服務暴露在公網、又需要跨網路訪問時，可以在伺服器上裝 Tailscale，用 `tailscale serve --bg http://127.0.0.1:8765` 把它釋出到你的私有網路；然後把 `VIBEX_DEPLOYMENT_MODE` 設為 `public`、`VIBEX_TLS_MODE` 設為 `trusted_https_proxy`，並讓 `VIBEX_PUBLIC_HOST` 與 `VIBEX_ALLOWED_HOSTS` 都填 Tailscale 給你的主機名。

### 第 2 步：桌面端連過去

1. 點選標題欄的 **執行階段** 按鈕，開啟執行階段管理器。
2. 點 **新增執行階段…**，選 **連線串** 標籤，把上面那條 `vibex://pair#/code/...` 整條貼上進去，點 **配對**。伺服器用自簽證書時也走這條，因為證書指紋就在連線串裡。
3. 也可以選 **配對碼** 標籤，手動填 **伺服器地址** 和 **一次性配對碼**。
4. 配對成功後，執行階段的 **證書** 一欄會顯示 `sha256:` 指紋，可以和伺服器日誌裡的 `tls_fingerprint` 對一下。
5. 在詳情裡點 **切換到此執行階段** 切過去；從這一刻起，桌面端裡的會話、檔案、Git、終端機都來自伺服器。想回到用本機開發，在列表裡選中 **本機** 再點 **切換到此執行階段**。要移除這個執行階段，在詳情裡點 **移除**——它只刪除本機儲存的裝置憑據，伺服器上的裝置授權仍然存在，需要在那臺伺服器上撤銷。

### 第 3 步：手機連過去

1. 開啟行動端，選 **連線雲端伺服器**。
2. 填 **伺服器地址**（例如 `192.168.1.10:8765`）和 **配對碼**，點 **使用配對碼連線**。
3. 伺服器用自簽證書時，改把 `vibex://pair#/code/...` 連線串粘進 **連線串** 輸入框，它會同時帶上證書。
4. 確認配對資訊即可；這臺裝置能做什麼由伺服器生成配對碼時決定，預設是 **完全控制**。想給它更小的權限，就在伺服器上用 `docker exec vibex-server vibex-server pairing-code --permission read-only` 重新生成一個配對碼（可選 `read-only`、`approve-only`、`full-control`）。

### 第 4 步：讓 Agent 看到你的程式碼

Agent 在伺服器上執行，**它只能看到伺服器（容器）裡的目錄**。所以程式碼必須放在伺服器上：

* 在伺服器上 `git clone` 到 `/data/repos/你的專案`；或者
* 在 compose 裡把宿主目錄掛進容器（示例中的 `- /srv/repos:/data/repos`）。

然後確認容器內路徑寫在 `VIBEX_WORKSPACE_ROOTS` 裡（示例中的 `/data:/data/repos`）。回到客戶端：新建會話 → **專案目錄** → **選擇其他目錄**，你會看到 `/data` 和 `/data/repos` 兩個位置，進去選中專案即可。

> [!NOTE]
>
> 只掛載、不加進 `VIBEX_WORKSPACE_ROOTS`，客戶端瀏覽不到那個目錄；只加進 `VIBEX_WORKSPACE_ROOTS`、不掛載，執行階段裡也沒有這個路徑。

### 第 5 步：日常維護

| 你要做的事 | 怎麼做 |
| - | - |
| 升級到新版本 | 改 `image` 裡的版本號，然後 `docker compose pull && docker compose up -d --no-build`。用 `rc`、`latest` 這類浮動標籤時必須先 `pull`，否則容器會留在舊映象上 |
| 備份 | 備份 `/data` 卷。裡面有資料庫和伺服器身份；身份丟了，所有裝置都要重新配對 |
| 撤銷一臺裝置 | 在伺服器上執行 `docker exec vibex-server vibex-server revoke DEVICE_ID`。在客戶端裡 **移除** 一個執行階段只會刪除本機憑據，不會撤銷伺服器上的授權 |
| 看執行狀態 | `docker exec vibex-server vibex-server status`；改過環境變數後先跑 `docker exec vibex-server vibex-server config-check` 檢查配置 |
| 徹底刪掉執行階段 | `docker compose down`。**不要加 `-v`**，那會連 `/data` 一起刪除 |

## 二、遠端開發：手機連你自己的桌面端

這條路線的權威仍然是你的電腦：Agent、檔案、Git、終端機都在桌面端上跑，手機只是拿到一個可以檢視和操作的視窗。適合“人在外面，想看一眼進度、回一句話、批一個權限”。

### 開始之前

* 桌面端正在執行，電腦保持開機（睡眠會導致連線斷開）。
* 手機和電腦網路可達：同一個 Wi-Fi 最簡單；不在同一網路時用 Tailnet 或自建 Relay。

### 第 1 步：在桌面端釋出遠端訪問

1. 點選頂部工具欄的 **配對移動裝置** 圖示。對話方塊有兩個標籤：**配對** 用來發布新的配對，**已配對裝置 (N)** 用來管理已經持有授權的裝置。
2. 選擇連線方式：
   * **Tailnet**（推薦）：通過 Tailscale 等私有網路訪問，適合不在同一 Wi-Fi 的情況。
   * **自管 Direct HTTPS**：你自己有一個能指向這臺電腦的 HTTPS 地址。
   * **自建 Relay**：手機和電腦無法直連時，通過你自建的 Relay 轉發加密流量。
3. 按介面提示填寫地址（**Direct HTTPS** 填 `https://你的地址`，**Relay** 填 `https://你的 Relay 地址`），選擇這臺手機能做什麼（預設 **只讀**，見下面的[權限級別](#權限級別)），然後點 **釋出**。
4. 介面會出現二維碼和配對連結：**掃碼即可配對**，也可以 **複製連結** 發給手機。連結有效期很短，過期就點 **重新生成**。

> [!WARNING]
>
> 配對連結和二維碼等同於一次性密碼，不要發到公開渠道。手機配對時桌面端會彈出確認，只有你確認才會成功。

### 第 2 步：在手機上完成配對

* 和電腦在同一個 Wi-Fi：行動端會直接發現 **nearby desktops**，選中後確認即可。
* 不在同一網路：用手機掃碼，或者打開復制過來的 `vibex://` 連結。
* 也可以手動連線：在行動端選 **使用配對碼連線**，填入桌面端顯示的地址和配對碼。

權限級別在桌面端釋出配對時就已經選定，手機發起配對後桌面端會要求你確認；完成後手機會顯示桌面端的會話列表。

桌面端也可以連線 **SSH 或 WSL 遠端執行階段**（測試版）。這種執行階段只能通過桌面端的 SSH 隧道訪問，手機不能直接配對；手機仍然連線桌面端，由桌面端轉發到遠端執行階段。詳見 [SSH 與 WSL 遠端執行階段](https://vibex.peatboy.com/docs/zh-TW/ssh-runtime.md)。

### 第 3 步：在手機上能做什麼

| 能力 | 說明 |
| - | - |
| 會話 | 檢視時間線、傳送後續訊息、重新命名、刪除、分叉、批次選擇。 |
| 會話組與所有權樹 | 建立和保留會話組，檢視委派出的子會話；摺疊的組會說明自己藏了多少。 |
| 核准與詢問 | 批准或拒絕權限請求，填寫 elicitation 表單。 |
| 檔案 | 瀏覽巢狀檔案樹、按名稱或內容搜尋、**編輯並儲存檔案**、檢視圖片並定位到行。 |
| 右側欄 | 檔案樹、分頁差異、搜尋和可複製路徑。 |
| Git | 檢視狀態與差異、stage / unstage / revert / commit、檢視歷史、fetch / push、建立 worktree、選擇或收尾 worktree。 |
| 終端機 | 建立、附加、調整大小、傳送輸入；支援標籤、Return 鍵、觸控選擇文本和轉發給應用的滑鼠事件。 |
| 佇列與草稿 | 檢視佇列、把等待發送改到另一個整點、跨重啟保留草稿、召回已發訊息、編輯和分享。 |
| 目標 | 改寫、暫停、恢復或清除目標。 |
| 通知與觸感 | 通知預設開啟；手勢有觸感反饋；長按開啟行自己的操作。 |
| 用量 | 只顯示會話數量，並提示 "Usage details are available on the desktop host." |

**行動端沒有配置中心**，不能管理 Agent、供應商、MCP 或 Skill。它的設定只包含 Connection、會話 timeline、外觀、Notifications 和關於。

所有寫操作的真實結果始終由權威執行階段產生；行動端顯示的是它的投影。

### 執行階段切換與恢復

行動端的首屏把配對和執行階段切換合在一起：列出已儲存的執行階段及其可達性，選一個即可連線；配對入口在同一個頁面裡以 sheet 開啟。

* 恢復連線失敗時會回到配對頁，不會卡在空白連線頁。
* 斷連時已儲存的執行階段仍然保留；下次回到前臺會自動重試。
* 配對後客戶端不會退出；可以在已儲存的執行階段之間切換。
* 移除一個執行階段只刪除本機憑據，不會撤銷伺服器或桌面端上的裝置授權。

### 直連不通時：自建 Relay

手機和電腦都可能在公司網路或運營商 NAT 後面，互相連不上。這時用一臺你能訪問的伺服器跑 Relay，它只轉發加密幀，看不到內容：

```yaml theme={null}
services:
  relay-server:
    image: ghcr.io/vibex-ai/vibex-relay-server:rc
    container_name: vibex-relay-server
    restart: unless-stopped
    # 只把埠釋出到宿主機的迴環地址；公網入口交給 HTTPS 反代
    ports:
      - "127.0.0.1:9700:9700"
    environment:
      # 容器內監聽所有網絡卡，否則宿主機的埠轉發進不來
      VIBEX_RELAY_BIND_ADDR: 0.0.0.0:9700
      # 房間數、連線數、限流等上限都有預設值，需要時再按
      # 「環境變數參考」裡的 Relay 一節新增
```

```bash theme={null}
docker compose up -d
curl -fsS http://127.0.0.1:9700/health
```

要讓手機在公網用到它，需要給它一個 HTTPS/WSS 入口（例如用 Caddy 反向代理到 `127.0.0.1:9700`），然後在桌面端釋出遠端訪問時選 **自建 Relay**，填入 `https://你的 Relay 域名`。

Relay 是純轉發的：它不儲存你的會話、檔案或供應商設定，也不解密內容。它在記憶體裡維護房間和連線，重啟後房間會消失，裝置重連時會自動重建。

### 斷線與重連

網路切換、鎖屏或應用回到前臺後，客戶端會重新認證並補齊缺失的歷史：先顯示權威的會話和時間線狀態，再恢復即時更新。

| 現象 | 處理 |
| - | - |
| `stale` | 等待權威重新整理，不要根據舊快照重複執行有副作用的命令。 |
| `revoked` | 裝置已被撤銷，必須重新配對。 |
| `resync_required` | 客戶端檢測到序號或游標缺口，正在重新同步；以權威端的狀態為準。 |

## 權限級別

配對時給行動端選權限，按需要最小授權。級別由**發起端**在建立配對時決定，客戶端無法自行提權：

| 級別 | 能做什麼 | 適合 |
| - | - | - |
| **只讀**（`read_only`） | 檢視會話、檔案摘要、Git 狀態和差異、供應商摘要；所有寫操作被拒絕並記入審計 | 只想看進度 |
| **僅核准**（`approve_only`） | 在只讀基礎上，處理 Agent 的權限請求和詢問表單 | 在外面幫忙點“允許” |
| **完全控制**（`full_control`） | 傳送訊息、寫檔案、輸入終端機命令、執行 Git 寫操作（仍受桌面端能力限制） | 真的要在手機上幹活 |

撤銷裝置在權威端完成：

* **桌面端作為權威端**時，開啟 **配對移動裝置**，切到 **已配對裝置 (N)** 標籤，找到那臺裝置點 **撤銷** 並確認。列表顯示每臺裝置的狀態、權限和最後活動時間，可以 **重新整理裝置** 重新載入；裝置多於六臺時分頁顯示。
* **無頭執行階段作為權威端**時，在伺服器上執行 `docker exec vibex-server vibex-server revoke DEVICE_ID`（或直接執行 `vibex-server revoke DEVICE_ID`）。

撤銷會立刻斷開該裝置的活動連線，之後必須重新配對。在客戶端裡 **移除** 一個執行階段只刪除本機儲存的憑據，伺服器上的裝置授權仍然存在。

## 安全清單

* 執行階段的 `8765` 埠只在本機或內網開放；公網訪問必須走 HTTPS。權威端預設只監聽 loopback，不要使用未認證的公網監聽。
* 權限給最小的一檔，只在需要時才用 **完全控制**。
* 配對碼、二維碼和連線串不要發到公開渠道；它們用過一次就失效，也不要當作長期憑據。
* 定期撤銷不用的裝置。
* Relay 只轉發加密流量，不要把它當成權限邊界，也不要在它的日誌裡放業務資料。

## 遇到問題先看這裡

| 現象 | 常見原因 | 怎麼辦 |
| - | - | - |
| 手機掃碼提示配對過期 | 二維碼有效期很短 | 在桌面端點 **重新生成**，重新掃 |
| 手機連不上桌面端 | 不在同一網路，或路由器/NAT 攔截 | 改用 Tailnet，或部署自建 Relay |
| 桌面端連不上伺服器 | 地址或埠寫錯，防火牆沒放行 | 在伺服器上訪問一次配對連線串裡的地址；確認 `VIBEX_BIND_ADDR` 不是迴環地址 |
| 客戶端提示證書或主機被拒絕 | `VIBEX_PUBLIC_HOST`、`VIBEX_ALLOWED_HOSTS` 和實際訪問地址不一致 | 改成實際訪問用的域名/地址後重啟容器 |
| 看不到想開啟的專案目錄 | 程式碼不在伺服器上，或沒寫進 `VIBEX_WORKSPACE_ROOTS` | 按上面第 4 步掛載並加入白名單 |
| 會話列表不更新 | 網路切換後還在補齊歷史 | 等它同步完，或手動重新整理；持續不更新時檢查桌面端/伺服器是否還在執行 |
| 手機提示裝置已被撤銷 | 權威端撤銷過這臺裝置 | 重新配對一次 |
| 桌面端一直連著伺服器，想用本機 | 配對的憑據會自動恢復 | 開啟 **執行階段** 面板，選中 **本機** 後點 **切換到此執行階段** |

## 環境變數

上面示例只用了最必要的變數。`vibex-server`、Relay 和桌面端的完整變數清單、預設值與用途見[環境變數參考](https://vibex.peatboy.com/docs/zh-TW/reference/environment-variables.md)；部署形態、命令與健康檢查見[自託管無頭執行階段](https://vibex.peatboy.com/docs/zh-TW/self-hosted-server.md)，Relay 的端點、限制與推送配置見[自託管 Relay](https://vibex.peatboy.com/docs/zh-TW/relay.md)。

需要更底層的細節（配對握手、加密、同步契約）時，閱讀開發者指南中的 [Remote v2 與 Relay](https://vibex.peatboy.com/docs/zh-TW/developer/remote-protocol.md)。


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