> ## 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.

# 平台支援

> 各平台的產物格式、構建方式和驗證要求。

## 支援矩陣

| 平台 | 產物 | 關鍵依賴 |
| - | - | - |
| Linux x86\_64 | `.deb`、`.AppImage` | Vulkan 圖形會話 |
| Linux aarch64 | `.deb` | Vulkan；不提供 AppImage（linuxdeploy 無法交叉構建） |
| macOS aarch64 / x86\_64 | `.dmg` | 較新的 macOS；**未簽名、未公證** |
| Windows x86\_64 / aarch64 | NSIS `.exe` | **未簽名**；按當前使用者安裝 |
| Android arm64 | `.apk`、`.aab` | Android SDK/NDK、`cargo-ndk`；Stable 需要固定釋出金鑰 |
| iOS | `ios-unsigned.ipa`、`ios-simulator.app.zip`、`xcframework.zip` | macOS、Xcode、XcodeGen；真機 IPA 由安裝者重簽名 |
| TUI | 隨桌面包釋出的 `vibex` / `vibex.exe`；容器裡 `vibex-server tui` | 無額外執行階段；SSH/tmux 可用 |
| SSH / WSL 遠端執行階段 | 由桌面端配置 `vibex-server` | OpenSSH；Linux glibc 2.35+ 或 macOS；WSL2 |
| 自託管 Linux / 容器 | `ghcr.io/vibex-ai/vibex-server`、`ghcr.io/vibex-ai/vibex-relay-server` | Docker 或 Rust 二進位制，多架構 amd64/arm64 |

> [!WARNING]
>
> **簽名狀態是當前已知的限制：** macOS 與 Windows 安裝包沒有程式碼簽名，使用者首次開啟需要手動放行；iOS 釋出未簽名的真機 IPA 和模擬器構建，真機由安裝者重簽名。Android 在未配置倉庫金鑰時使用每次釋出生成的一次性 CI 金鑰，因此 RC 之間不能覆蓋升級；Stable 必須配置固定釋出金鑰。釋出前請確認這些狀態是否已有變化。

## 桌面平台邊界

權威執行階段是 Agent、檔案、Git、PTY、供應商、權限和持久化的所有者。平台差異應封裝在 `apps/desktop/src/platform` 或共享 facade 中，不要在 UI 裡複製業務分支。

## 釋出通道

通道是**編譯期身份**，不是執行階段開關：

| 通道 | 產品名 | 應用 ID | 資料目錄 |
| - | - | - | - |
| 預覽 | Vibex 預覽 | `dev.vibex.desktop.preview` | `desktop-preview` |
| RC | Vibex RC | `dev.vibex.desktop.rc` | `desktop-rc` |
| Stable | Vibex | `dev.vibex.desktop` | `desktop-stable` |

通道由 tag 推導（`*-preview.*` / `*-rc.*` / 純 semver）。釋出流程會斷言 tag、`Cargo.toml`、`package.json` 與 `Packager.<channel>.toml` 中的版本完全一致。執行階段覆蓋通道會被拒絕（`release_channel_override_rejected`）。

## 釋出工作流

`.github/workflows/release.yml` 在 `v*` tag 上全自動執行，桌面端矩陣覆蓋六個平台 / 架構組合：

| 平台 | Runner | 產物格式 |
| - | - | - |
| Linux x86\_64 | ubuntu-24.04 | `deb,appimage` |
| Linux aarch64 | ubuntu-24.04（交叉） | `deb` |
| macOS aarch64 | macos-14 | `dmg` |
| macOS x86\_64 | macos-14（交叉） | `dmg` |
| Windows x86\_64 | windows-2022 | `nsis` |
| Windows aarch64 | windows-2022（交叉） | `nsis` |

行動端在同一個 workflow 中構建：Android APK + AAB，iOS XCFramework + 未簽名模擬器應用。釋出 job 要求**全部**前置 job 成功才會建立 release，因此不會出現部分矩陣的殘缺釋出。

> [!NOTE]
>
> 工作流目前**沒有** macOS 公證和 Windows Authenticode 步驟。加入這兩步之前，安裝包會一直帶有平台警告。

## Android 構建

```bash theme={null}
pnpm build:mobile:android      # Debug
pnpm package:mobile:android    # Release（未簽名）
```

設定 `VIBEX_MOBILE_ANDROID_TARGETS`（空格分隔）可覆蓋 Debug ABI，Release 預設只構建 `arm64-v8a`。

釋出工作流會呼叫 `apps/mobile/scripts/sign-android-release.sh`：APK 使用 `zipalign` + `apksigner`，AAB 使用 `jarsigner`。RC / 預覽在沒有倉庫金鑰時生成一次性的 `vibex-ci` 金鑰；Stable 釋出必須配置 `VIBEX_ANDROID_KEYSTORE_BASE64` 和 `VIBEX_ANDROID_KEYSTORE_PASSWORD`，可選 `VIBEX_ANDROID_KEY_PASSWORD` 和倉庫變數 `VIBEX_ANDROID_KEY_ALIAS`（預設 `vibex`）。

> [!WARNING]
>
> 使用臨時金鑰意味著**每次 RC 釋出的 APK 簽名都不同**，使用者無法覆蓋升級，必須先解除安裝再安裝。這是當前 RC 階段的已知取捨。

## iOS 構建

```bash theme={null}
pnpm build:mobile:ios
pnpm package:mobile:ios   # 未簽名真機 IPA + 模擬器包
```

構建 `VibexFFI.xcframework` 並生成 Xcode 工程。簽名、Bundle identifier、真機 / 模擬器選擇和分發憑據都由本機 Xcode 流程決定，不要把證書或 provisioning profile 提交到倉庫。釋出產物是未簽名的真機 IPA，安裝者用自己的 Apple ID 重簽名；免費賬號的簽名有效期為 7 天。

## 桌面打包

```bash theme={null}
cargo install cargo-packager --version 0.11.8 --locked
pnpm prepare:pdfium
pnpm package:preview    # 或 package:rc / package:stable
```

Linux 用 cargo-packager 打包，PDFium 執行階段只在 **linux-x86\_64** 上隨包分發。Wayland 相關庫**不**隨包分發（宿主 ABI 邊界），依賴宿主機提供。

## 自動更新

`crates/app-update` 實現簽名更新：

* 從 GitHub Releases Atom feed 發現候選版本，按通道過濾。
* 校驗 `vibex-update.json` 的 Ed25519 簽名，並對產物做 SHA-256 校驗，URL 白名單限定在 releases 下載路徑。
* 啟動 30 秒後首次檢查，之後 RC / 預覽每 2 小時、Stable 每 6 小時檢查一次，帶抖動與退避。
* AppImage 走原地自我替換（帶 `.vibex-backup` 與 `pending-install.json` 崩潰恢復）；deb、macOS app 和 NSIS 拉起系統安裝器並要求重啟。
* 釋出流水線會把標記提交裡的 `docs/operations/release-notes-v<version>.md` 暫存為 `vibex-release-notes.md`，檔案缺失或沒有 `## English` 段落時直接讓釋出失敗；桌面端在限定大小和更短超時下從已驗證的標籤獲取它，並按介面語言選擇段落，依次回退到通用中文和英文。

只有編譯進公鑰的構建才會自動檢查。

## 行動端生命週期

行動端需要處理後臺、網路切換、斷線和重連。恢復時先用 Remote v2 獲取權威會話和時間線，再訂閱即時事件；不要用過期投影覆蓋權威狀態。

## TUI 與遠端執行階段

TUI 作為桌面包的第二個二進位制釋出：Linux `/usr/bin/vibex`、macOS `.app` 旁的 `vibex`、Windows `vibex.exe`；容器裡用 `vibex-server tui`。它是同一套執行階段協議的客戶端，不連結桌面 UI，也不開啟資料庫。

SSH / WSL 遠端執行階段由桌面端配置：通過 SSH 上傳並安裝 `vibex-server`，打開回環隧道，取得一次性配對碼並配對。釋出產物必須來自簽名清單；遠端會再次校驗 SHA-256。完整契約見 `docs/remote/ssh-runtime.md` 和 `.trellis/spec/backend/ssh-remote-runtime.md`。

## 自託管部署

推薦把服務繫結 loopback，再通過受控 HTTPS 反向代理或 Tailnet Serve 釋出。Host 和 Origin 必須獨立校驗，CORS 不得使用 `*`。閘道器只暴露協議與健康檢查端點，不提供瀏覽器 UI 或業務 API。

詳見[自託管無頭執行階段](https://vibex.peatboy.com/docs/zh-TW/self-hosted-server.md)與[自託管 Relay](https://vibex.peatboy.com/docs/zh-TW/relay.md)。


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