> ## 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-server，讓桌面端和行動端共享同一個權威執行階段。

`vibex-server` 是 Vibex 的**無頭權威執行階段**。它和桌面端內嵌的執行階段是同一套 `DesktopRuntime` 核心，只是換成守護程序的形態：桌面端多一個 GPUI 視窗，服務端多一套守護程序生命週期。兩者對外暴露**完全相同**的 Remote v2 閘道器，所以配對後的行動端分辨不出自己連的是哪一種。

> [!NOTE]
>
> `vibex-server` 是**單使用者**執行階段：它擁有一個 Vibex home、一個數據庫和一個閘道器，不是多租戶服務。主機管理員就是使用者。

## 什麼時候用它

* 想讓會話和 Agent 常駐在一臺伺服器上，筆記本關機也不中斷。
* 想在桌面端和手機之間共享同一批會話、工作區和憑據。
* 團隊裡有一臺常開的開發機，希望從任意裝置接入。

只需要轉發流量、不需要託管執行階段的話，用 [Relay](https://vibex.peatboy.com/docs/zh-TW/relay.md) 就夠了。

## 快速開始

容器映象是多架構的（`linux/amd64`、`linux/arm64`），每個釋出都會更新：

```bash theme={null}
export VIBEX_SERVER_IMAGE=ghcr.io/vibex-ai/vibex-server:rc
docker compose -f deploy/server/docker-compose.yml pull vibex-server
docker compose -f deploy/server/docker-compose.yml up -d --no-build vibex-server
docker logs vibex-server | grep -E 'pairing_(code|link)|tls_fingerprint'
curl -fsS http://127.0.0.1:8765/api/v2/info
```

映象 tag 規則：`rc` 跟隨最新的候選版本，`latest` 只指向穩定版，`edge` 和 `sha-<commit>` 跟隨預設分支。

啟動日誌會列印 `server_id`、`endpoint`、一次性 `pairing_code`（形如 `NNN-NNN-NNN`）、`pairing_link`、`tls_fingerprint`，以及一段二維碼。把它們交給客戶端去配對，見[遠端訪問與行動端](https://vibex.peatboy.com/docs/zh-TW/remote-mobile.md)。

需要新的配對碼時隨時重新生成：

```bash theme={null}
docker exec vibex-server vibex-server pairing-code
docker exec vibex-server vibex-server pairing-code --permission read-only --ttl-ms 600000
docker exec vibex-server vibex-server pairing-code --json
```

## 命令

```text theme={null}
Usage: vibex-server [serve|status|stop|pairing-code|revoke|config-check|tui]

  serve [--no-pairing]                    執行權威無頭執行階段
  status [--json]                         報告執行階段與配對狀態
  stop                                    安全停止由本 home 啟動的執行階段
  pairing-code [--permission <level>] [--ttl-ms N] [--json]
                                          生成一次性配對碼及其連線串
  revoke DEVICE_ID [--reason TEXT]        撤銷已配對裝置
  config-check                            校驗 VIBEX_* 部署配置
  tui                                     在容器裡啟動 Vibex TUI
```

不帶引數等同於 `serve`。`--permission` 接受 `read-only`、`approve-only`、`full-control`（預設 `full-control`）。`status --json` 適合指令碼和容器健康檢查；`stop` 只停止這個 home 的執行階段，不會刪除資料。

容器裡也可以直接使用 TUI：

```bash theme={null}
docker exec -it vibex-server vibex-server tui
```

TUI 與桌面端、行動端是同一類客戶端：它連線這個執行階段，讀取同一批會話，不會在容器裡再啟動一個後端。詳見 [Vibex TUI](https://vibex.peatboy.com/docs/zh-TW/tui.md)。

## 部署形態

### 只監聽本機（預設）

預設繫結 `127.0.0.1:8765`，不對外發布任何埠。適合先用 SSH 隧道或反向代理把流量引進來。

### 區域網：自簽證書 + 指紋固定

沒有域名和 CA 的場景（家用或辦公室區域網），執行階段提供**自己簽發的證書**，客戶端從連線串裡學到這張證書並固定它——信任來自連線串本身，而不是網路。

```bash theme={null}
VIBEX_BIND_ADDR=0.0.0.0:8765 \
VIBEX_DEPLOYMENT_MODE=lan \
VIBEX_TLS_MODE=pinned_certificate \
VIBEX_PUBLIC_HOST=192.168.1.10:8765 \
VIBEX_HEALTHCHECK_URL=https://127.0.0.1:8765/api/v2/info \
  docker compose -f deploy/server/docker-compose.yml up --build -d vibex-server
```

* `VIBEX_PUBLIC_HOST` 必須是客戶端實際撥號的地址，**含埠**，並且是數值型區域網地址（`192.168.x.x`、`10.x.x.x`、`172.16–31.x.x`，或鏈路本地 / 唯一本地 IPv6）。
* 證書在整個執行階段身份生命週期內保持不變，重啟容器**不需要**重新配對。刪除 `/data` 才會失效。
* `pinned_certificate` 真的在閘道器上終止 TLS，監聽口從來不是明文。沒有指紋的客戶端根本連不上。

### 公網 HTTPS

公網暴露需要 `VIBEX_DEPLOYMENT_MODE=public`，並選擇一種 TLS 策略：

**反向代理終止 TLS：**

```bash theme={null}
VIBEX_PUBLIC_HOST=vibex.example.com \
VIBEX_DEPLOYMENT_MODE=public \
VIBEX_TLS_MODE=trusted_https_proxy \
VIBEX_TRUST_FORWARDED_HEADERS=true \
VIBEX_ALLOWED_HOSTS=vibex.example.com \
VIBEX_ALLOWED_ORIGINS=https://vibex.example.com \
  docker compose -f deploy/server/docker-compose.yml --profile caddy up -d
```

只有在 `trusted_https_proxy` 模式下才能開啟 `VIBEX_TRUST_FORWARDED_HEADERS`，其它模式會拒絕轉發頭。

**閘道器自己終止 TLS：** 設定 `VIBEX_TLS_MODE=server_certificate`，並把 `VIBEX_TLS_CERT_FILE` / `VIBEX_TLS_KEY_FILE`（PEM）掛進容器。

> [!WARNING]
>
> 閘道器會在啟動時校驗配置組合：Public 監聽缺少可信 TLS、`VIBEX_ALLOWED_HOSTS` 裡出現 loopback、或在非可信代理模式下信任轉發頭，都會**拒絕啟動**。這是有意設計的，避免配置錯誤悄悄退化成未認證的公網服務。

### systemd（不用 Docker）

倉庫提供了一份加固過的 unit 檔案，直接以宿主機程序執行，環境變數契約相同：

```bash theme={null}
systemctl status vibex-server
journalctl -u vibex-server -o cat | grep -E 'pairing_(code|link)|tls_fingerprint'
```

狀態目錄預設為 `/var/lib/vibex-server`，詳見倉庫 `deploy/server/systemd.md`。

## 環境變數

完整清單與預設值見[環境變數參考](https://vibex.peatboy.com/docs/zh-TW/reference/environment-variables.md)。最常用的幾個：

| 變數 | 預設值 | 說明 |
| - | - | - |
| `VIBEX_HOME` | `/data` | 執行階段 home：資料庫、Agent 安裝、身份金鑰。 |
| `VIBEX_DB_PATH` | `$VIBEX_HOME/vibex.db` | 權威 SQLite 路徑。 |
| `VIBEX_WORKSPACE_ROOTS` | `$VIBEX_HOME` | 逗號分隔的絕對路徑，限制客戶端可選的專案目錄。 |
| `VIBEX_BIND_ADDR` | `127.0.0.1:8765` | 閘道器監聽地址。 |
| `VIBEX_DEPLOYMENT_MODE` | `loopback` | `loopback` / `lan` / `public`。 |
| `VIBEX_TLS_MODE` | `VIBEX_DEPLOYMENT_MODE=loopback` 時為 `loopback_http`，其它模式為 `trusted_https_proxy` | TLS 終止方式，共四種取值： `loopback_http` —— 明文 HTTP，只允許迴環地址，僅用於本機開發除錯； `trusted_https_proxy` —— 由你信任的反向代理（Caddy、Nginx 等）終止 TLS，`VIBEX_PUBLIC_HOST`、`VIBEX_ALLOWED_HOSTS`、`VIBEX_ALLOWED_ORIGINS` 必須與實際訪問的域名一致，也只有這個模式允許 `VIBEX_TRUST_FORWARDED_HEADERS=true`； `pinned_certificate` —— 執行階段用自簽證書自己終止 TLS，客戶端從配對連線串裡固定 `sha256:` 指紋，適合沒有域名和 CA 的區域網； `server_certificate` —— 執行階段用你提供的 PEM 終止 TLS，必須同時設定 `VIBEX_TLS_CERT_FILE` 與 `VIBEX_TLS_KEY_FILE`。 |
| `VIBEX_PUBLIC_HOST` | 未設定 | 向配對客戶端通告的地址，也用於生成連線串。 |

> [!NOTE]
>
> `VIBEX_WORKSPACE_ROOTS` 的每一項都必須是絕對路徑；掛載點暫時不存在時它只是匹配不到東西，不會報錯。

## 憑據儲存

提供商 API Key 存在**伺服器主機上**，絕不進資料庫，也絕不返回給客戶端。

桌面端會把金鑰寫入作業系統鑰匙串。無頭伺服器通常沒有可用的鑰匙串（預設容器 seccomp 配置會拒絕 Linux 鑰匙串後端所需的 keyutils 系統呼叫），因此它改為寫入執行階段 home 裡的 `provider-secrets.json`，權限為僅屬主可讀（`0600`）。這是自託管的明確取捨：主機管理員就是使用者。

```bash theme={null}
VIBEX_PROVIDER_SECRET_STORE=keychain   # 強制使用系統鑰匙串
VIBEX_PROVIDER_SECRET_STORE=file       # 強制使用主機金鑰檔案
```

閘道器不記錄金鑰、配對碼或認證令牌；憑據值寫入後**只寫不讀**，不會再返回給任何客戶端。

## 安全建議

1. **保持 loopback 預設值**，再用 Tailscale Serve 或受控反向代理釋出。
2. 公網部署必須配置 `VIBEX_ALLOWED_HOSTS`（精確主機名，否則返回 `421`）和 `VIBEX_ALLOWED_ORIGINS`（否則返回 `403`）。原生客戶端不傳送 `Origin`，不受影響。
3. 用 `vibex-server status` 定期檢查已配對裝置，用 `revoke` 及時清理。
4. `VIBEX_WORKSPACE_ROOTS` 只列真正需要的目錄。
5. 閘道器只暴露協議與健康檢查端點，不提供瀏覽器 UI，也不提供業務 API。

## 健康檢查

```bash theme={null}
curl -fsS http://127.0.0.1:8765/api/v2/info
```

`/health` 和 `/api/info` 屬於 [Relay](https://vibex.peatboy.com/docs/zh-TW/relay.md)；無頭執行階段的資訊端點是 `/api/v2/info`。


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