平台支援 - Vibex

支援矩陣

平台	產物	關鍵依賴
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

簽名狀態是當前已知的限制： 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，因此不會出現部分矩陣的殘缺釋出。

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

Android 構建

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）。

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

iOS 構建

pnpm build:mobile:ios
pnpm package:mobile:ios   # 未簽名真機 IPA + 模擬器包

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

桌面打包

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。詳見自託管無頭執行階段與自託管 Relay。

​支援矩陣

​桌面平台邊界

​釋出通道

​釋出工作流

​Android 構建

​iOS 構建

​桌面打包

​自動更新

​行動端生命週期

​TUI 與遠端執行階段

​自託管部署

支援矩陣

桌面平台邊界

釋出通道

釋出工作流

Android 構建

iOS 構建

桌面打包

自動更新

行動端生命週期

TUI 與遠端執行階段

自託管部署