云端部署
OpenHuman 是桌面应用，但其 Rust 核心 (openhuman-core) 是一个可以托管在云端的无头 JSON-RPC 服务器。单独部署核心适用于：
- 多设备访问，多个桌面客户端指向同一个托管核心
- 内部测试人员无需本地 Rust 工具链
- 长时运行的 cron 作业/webhook
本指南涵盖四种部署路径：
- DigitalOcean App Platform：一键部署
- DigitalOcean App Platform：通过 doctl 手动部署
- 任何 VPS：通过 Docker Compose
- Fly.io
部署内容
每种路径都部署一个在端口 7788 上运行 openhuman-core serve 的容器。公共主机应位于提供商的 TLS 后面，例如 https://core.example.com/rpc。
前置要求
| 设置 | 必需 | 说明 |
|---|---|---|
OPENHUMAN_CORE_TOKEN | 是 | Bearer token，生成：openssl rand -hex 32 |
BACKEND_URL | 是 | OpenHuman 后端（生产环境为 https://api.tinyhumans.ai） |
OPENHUMAN_APP_ENV | 否 | production 或 staging，默认 production |
OPENHUMAN_CORE_HOST | 否 | 默认 0.0.0.0 |
OPENHUMAN_CORE_PORT | 否 | 默认 7788 |
1. DigitalOcean App Platform：一键部署
点击按钮创建新的 App Platform 应用：
在首次部署完成前，进入 Settings → App-Level Environment Variables：
- 用强密钥替换
OPENHUMAN_CORE_TOKEN占位符 - 如需 staging，更改
OPENHUMAN_APP_ENV为staging
2. 任何 VPS via Docker Compose
适用于任何具有 Docker Engine ≥ 24 的主机。生产发布镜像：
docker pull ghcr.io/tinyhumansai/openhuman-core:latest
快速运行：
docker run -d --name openhuman-core -p 7788:7788 \
-e OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)" \
-e BACKEND_URL=https://api.tinyhumans.ai \
-e OPENHUMAN_APP_ENV=production \
-v openhuman-workspace:/home/openhuman/.openhuman \
ghcr.io/tinyhumansai/openhuman-core:latest
3. Fly.io
前置要求
flyctl已安装并认证- Fly.io 账户
步骤 1 — 启动应用
fly launch --no-deploy --config .fly/fly.toml
步骤 2 — 创建持久卷
fly volumes create openhuman_workspace --size 5 --region <your-region> --config .fly/fly.toml
重要：将工作区挂载到持久卷，否则数据会在每次重新部署时丢失。
步骤 3 — 设置密钥
fly secrets set OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)"
fly secrets set BACKEND_URL="https://api.tinyhumans.ai"
fly secrets set OPENHUMAN_APP_ENV="production"
步骤 4 — 部署
fly deploy --config .fly/fly.toml
步骤 5 — 连接桌面应用
在 app/.env.local 中：
OPENHUMAN_CORE_RUN_MODE=external
OPENHUMAN_CORE_RPC_URL=https://<your-app-name>.fly.dev/rpc
OPENHUMAN_CORE_TOKEN=<your-token>
持续部署
推送到 main 分支自动重新部署。
更新
# Docker Compose
git pull && docker compose build && docker compose up -d
# Fly.io
fly deploy --config .fly/fly.toml
日志
# Docker Compose
docker compose logs -f openhuman-core
# Fly.io
fly logs --config .fly/fly.toml
常见问题
Bearer Token 轮换
# 1. 生成新 token 并更新服务器端 .env
openssl rand -hex 32 > /tmp/new-token
sed -i.bak "s|^OPENHUMAN_CORE_TOKEN=.*|OPENHUMAN_CORE_TOKEN=$(cat /tmp/new-token)|" .env
# 2. 重启容器
docker compose up -d --force-recreate openhuman-core
# 3. 更新每个桌面客户端
TLS 问题
使用 Caddy、nginx 或 Traefik 作为反向代理：
core.example.com {
reverse_proxy localhost:7788
}