平台支持 - 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 与远程运行时

自托管部署