mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-30 23:14:37 +00:00
fdd56a839d
Co-authored-by: Subharup Nandi <Subharup-31@users.noreply.github.com> Co-authored-by: Steven Enamakel <enamakel@tinyhumans.ai>
241 lines
7.8 KiB
Markdown
241 lines
7.8 KiB
Markdown
---
|
||
description: 如何从源码构建 OpenHuman —— 工具链、vendored Tauri CLI 和本地桌面构建。
|
||
icon: wrench
|
||
lang: zh-CN
|
||
---
|
||
|
||
# 构建与安装 OpenHuman
|
||
|
||
本指南涵盖完整的桌面/源码安装路径和发布安装包。
|
||
|
||
如果你只需要在新机器上运行仓库根目录的 Rust crate，请使用[构建 Rust 核心](building-rust-core.zh-CN.md)。该页面记录了固定的 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 快速开始：
|
||
|
||
```bash
|
||
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 快速开始：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 从源码构建（本地编译）
|
||
|
||
从仓库根目录运行：
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
本地开发（而非生产构建）：
|
||
|
||
```bash
|
||
# 仅 Web UI 开发
|
||
pnpm dev
|
||
|
||
# 使用 vendored Tauri/CEF CLI 的桌面应用开发：从 workspace 根目录运行
|
||
pnpm --filter openhuman-app dev:app
|
||
```
|
||
|
||
## 安装最新稳定版（macOS/Linux x64）
|
||
|
||
主要安装命令：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
# 预览操作而不写入文件
|
||
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash -s -- --dry-run
|
||
```
|
||
|
||
## Windows（最新稳定版）
|
||
|
||
使用 PowerShell：
|
||
|
||
```powershell
|
||
irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex
|
||
```
|
||
|
||
Windows 安装器行为：
|
||
|
||
- 解析最新稳定版
|
||
- 下载 x64 的 MSI/EXE
|
||
- 可用时验证摘要
|
||
- 在安装包支持的情况下执行按用户安装
|
||
|
||
## ARM Linux 构建（aarch64）
|
||
|
||
ARM Linux 构建由于 CEF 和 GTK 依赖需要特殊处理。
|
||
|
||
### 前置条件
|
||
|
||
```bash
|
||
# 安装 xvfb 用于 headless 构建/测试
|
||
sudo apt install xvfb
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
cd app
|
||
pnpm tauri build --target aarch64-unknown-linux-gnu
|
||
```
|
||
|
||
### 运行 ARM 二进制文件
|
||
|
||
该二进制文件需要设置 CEF 库路径：
|
||
|
||
### 选项 1 —— 直接调用
|
||
|
||
```bash
|
||
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`）：
|
||
|
||
```bash
|
||
#!/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 包安装
|
||
|
||
```bash
|
||
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` 中处理：
|
||
|
||
```rust
|
||
// 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 构建）在窗口出现前退出，提示类似：
|
||
|
||
```text
|
||
[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 实例并重新运行。最快路径：
|
||
|
||
```bash
|
||
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 运行时很有用。
|
||
|
||
**手动清理（仍然有效）**
|
||
|
||
```bash
|
||
pkill -f "OpenHuman.app/Contents"
|
||
pkill -f "openhuman-core"
|
||
```
|