环境搭建

本指南涵盖完整的桌面/源码安装路径和发布安装程序。

前置要求

• git
• Node.js 24 或更新版本（见 app/package.json）
• pnpm@10.10.0（见根 package.json packageManager 字段）
• Rust 1.93.0 通过 rustup，包含 rustfmt 和 clippy（见 rust-toolchain.toml）
• CMake，用于原生 Rust 依赖
• Git 子模块在 app/src-tauri/vendor/ 下，用于 vendored CEF-aware Tauri CLI
• 平台桌面构建工具：macOS 上的 Xcode Command Line Tools，或 Linux 上的 Tauri GTK/WebKit/AppIndicator 包集

macOS Homebrew 快速开始

brew install node@24 pnpm rustup-init cmake
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

Arch Linux 快速开始

sudo pacman -S --needed nodejs npm rustup cmake base-devel clang openssl \
  alsa-lib xdotool libxtst libxi libevdev gtk3 webkit2gtk-4.1 \
  libayatana-appindicator librsvg patchelf nss nspr at-spi2-core \
  libcups libdrm libxkbcommon libxcomposite libxdamage libxfixes \
  libxrandr mesa pango cairo libxshmfence
npm install -g pnpm@10.10.0
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

从源码构建（本地编译）

从仓库根目录运行：

# 1) 克隆并进入仓库
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2) 获取 vendored Tauri/CEF 源
git submodule update --init --recursive

# 3) 安装 JS 依赖（workspace）
pnpm install

# 4) 构建桌面应用产物
pnpm build

本地开发：

# 仅 Web UI 开发
pnpm dev

# 桌面应用开发（使用 vendored Tauri/CEF CLI）
pnpm --filter openhuman-app dev:app

安装最新稳定发布（macOS/Linux x64）

主要安装命令：

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

Arch Linux 包

仓库在 packages/arch/openhuman-bin 包含 openhuman-bin AUR 配方。

Windows（最新稳定）

使用 PowerShell：

irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

ARM Linux 构建（aarch64）

ARM Linux 构建需要特殊处理。

前置要求

sudo apt install xvfb

构建

cd app
pnpm tauri build --target aarch64-unknown-linux-gnu

运行

二进制文件需要设置 CEF 库路径：

REL_DIR=app/src-tauri/target/aarch64-unknown-linux-gnu/release
CEF_DIR=$(ls -d "$REL_DIR"/build/cef-dll-sys-*/out/cef_linux_aarch64 2>/dev/null | head -n1)
export LD_LIBRARY_PATH="$CEF_DIR:$REL_DIR/deps:$REL_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
"$REL_DIR/OpenHuman" --no-sandbox

故障排除

macOS: pnpm dev:app 退出显示 "CEF cache is held by another OpenHuman instance"

症状

pnpm dev:app 在窗口出现前退出，消息类似：

[openhuman] CEF cache at /Users/<you>/Library/Caches/com.openhuman.app/cef is held by another OpenHuman instance

原因

CEF 通过 SingletonLock 符号链接持有其用户数据目录的独占锁。已安装的 .app 包和开发二进制文件使用相同的标识符 (com.openhuman.app)，所以不能并行运行。

修复

退出其他 OpenHuman 实例并重新运行：

pkill -f "OpenHuman.app/Contents"
pkill -f "openhuman-core"
pnpm dev:app

过时的 openhuman RPC 进程占用核心端口

症状

之前的 Tauri 构建或 openhuman-core run 留下了一个监听 OPENHUMAN_CORE_PORT（默认 7788）的进程。

当前行为

core_process::ensure_running 在启动时探测端口：

• 如果监听器识别为 OpenHuman 核心，它被当作过时进程并被终止
• 如果监听器是其他东西（或不是 HTTP），启动会大声失败

下一步

• 构建 Rust 核心 - 仅核心构建
• 架构 - 完整架构
• 测试策略 - 测试指南