openhuman/gitbooks/developing/getting-set-up.zh-CN.md

description, icon, lang

description	icon	lang
如何从源码构建 OpenHuman —— 工具链、vendored Tauri CLI 和本地桌面构建。	wrench	zh-CN

构建与安装 OpenHuman

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

如果你只需要在新机器上运行仓库根目录的 Rust crate，请使用构建 Rust 核心。该页面记录了固定的 Rust 工具链、OS 包前置条件以及 openhuman-core 的精确 cargo 命令。

本指南涵盖两条路径：

1. 从源码构建并编译 OpenHuman
2. 安装最新的稳定发布二进制文件

前置条件

• git
• Node.js 24 或更高版本（见 app/package.json）
• pnpm@10.10.0（见根目录 package.json 的 packageManager 字段）
• 通过 rustup 安装的 Rust 1.93.0，含 rustfmt 和 clippy（见 rust-toolchain.toml）
• CMake，原生 Rust 依赖所需
• app/src-tauri/vendor/ 下的 Git 子模块，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 的桌面应用开发：从 workspace 根目录运行
pnpm --filter openhuman-app dev:app

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

主要安装命令：

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

安装器行为：

• 解析你平台的最新稳定 OpenHuman 发布版本
• 可用时验证产物摘要
• 本地安装（默认不需要 sudo）
• macOS：将 OpenHuman.app 安装到 ~/Applications
• Linux x64：将 AppImage 安装为 ~/.local/bin/openhuman 并写入桌面入口

实用 flag：

# 预览操作而不写入文件
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash -s -- --dry-run

Windows（最新稳定版）

使用 PowerShell：

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

Windows 安装器行为：

• 解析最新稳定版
• 下载 x64 的 MSI/EXE
• 可用时验证摘要
• 在安装包支持的情况下执行按用户安装

ARM Linux 构建（aarch64）

ARM Linux 构建由于 CEF 和 GTK 依赖需要特殊处理。

前置条件

# 安装 xvfb 用于 headless 构建/测试
sudo apt install xvfb

构建

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

运行 ARM 二进制文件

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

选项 1 —— 直接调用

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

选项 2 —— Wrapper 脚本（推荐）

保存到 ~/bin/openhuman 并赋予可执行权限（chmod +x ~/bin/openhuman）：

#!/bin/bash
REL_DIR=/path/to/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}"
exec "$REL_DIR/OpenHuman" --no-sandbox "$@"

DEB 包安装

DEB_FILE=$(ls app/src-tauri/target/aarch64-unknown-linux-gnu/release/bundle/deb/OpenHuman_*_arm64.deb | head -n1)
sudo dpkg -i "$DEB_FILE"

GTK 初始化修复

ARM 构建需要 GTK 在 Tauri 创建系统托盘之前初始化。这在 vendor/tauri-cef/crates/tauri-runtime-cef/src/lib.rs 中处理：

// CEF 初始化后，添加：
#[cfg(target_os = "linux")]
{
    gtk::init().ok();
}

如果托盘初始化失败并提示 "GTK has not been initialized"，请确保此修复已到位后重新构建。

全平台手动下载链接：

• 网站：https://tinyhuman.ai/openhuman
• 最新发布：https://github.com/tinyhumansai/openhuman/releases/latest

故障排除

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

症状

pnpm dev:app（或 Tauri 壳层的任何 debug 构建）在窗口出现前退出，提示类似：

[openhuman] CEF cache at /Users/<you>/Library/Caches/com.openhuman.app/cef is held by another OpenHuman instance (host <hostname>, pid 12345).
Quit the running instance and try again.
Workaround:
  pkill -f "OpenHuman.app/Contents"
  pkill -f "openhuman-core"

原因

CEF（Chromium Embedded Framework）通过 ~/Library/Caches/com.openhuman.app/cef 下的 SingletonLock 符号链接对其用户数据目录持有独占锁。已安装的 .app 包和开发二进制文件使用相同的标识符（com.openhuman.app），因此它们无法并排运行。如果没有 preflight，cef::initialize 会返回失败，而 vendored tauri-runtime-cef 会以 Rust 回溯和无可操作消息的方式 panic（这是 preflight 落地前的 issue #864）。

修复

退出另一个 OpenHuman 实例并重新运行。最快路径：

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

如果锁是由崩溃进程留下的（PID 已不存在），preflight 会自动移除陈旧的 SingletonLock，开发启动将继续，无需手动清理。

已知限制

开发和发布构建仍然共享 com.openhuman.app 作为缓存标识符。将开发隔离到单独的 com.openhuman.app.dev 缓存需要修改 vendored tauri-runtime-cef（缓存路径在运行时内部从 bundle 标识符构建，未暴露给 openhuman 壳层）。作为 #864 的后续跟踪。

核心端口上的陈旧 openhuman RPC 进程

症状

之前的 Tauri 构建或 openhuman-core run harness 在 OPENHUMAN_CORE_PORT（默认 7788）上留下了一个监听进程。在 issue #1130 之前，新的 Tauri 构建会静默附加到该监听器，导致版本漂移，以及新构建的 OPENHUMAN_CORE_TOKEN 不匹配时出现 401。

当前行为（issue #1130）

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

• 如果 GET / 将监听器识别为 OpenHuman 核心（JSON body 含 "name": "openhuman"），则将其视为之前运行的陈旧进程并主动终止（Unix 上 SIGTERM，750ms 后 SIGKILL；Windows 上 taskkill /F /T /PID）。Tauri 主机随后会生成自己的全新嵌入式核心。
• 如果监听器是其他东西（或不讲 HTTP），启动会大声失败，并在日志中显示冲突，而非静默附加。
• 设置 OPENHUMAN_CORE_REUSE_EXISTING=1 以选择回到遗留的 attach-to-anything 行为，在将 openhuman-core run 作为手动调试 harness 运行时很有用。

手动清理（仍然有效）

pkill -f "OpenHuman.app/Contents"
pkill -f "openhuman-core"