尧图网页设计 
OpenHuman 云部署实战指南headless openhuman-core JSON-RPC 服务的四条部署路径【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhumanOpenHuman 本身是桌面应用但其 Rust 编写的核心openhuman-core是一个可独立托管的 headless JSON-RPC 服务器监听7788端口。本文基于仓库文档 cloud-deploy.md 及对应的部署配置.do/app.yaml、docker-compose.yml、.fly/fly.toml、Dockerfile 与 src/core/auth.rs 等实现源码完整覆盖 DigitalOcean App Platform一键 doctl 手动、任意 VPS 上的 Docker Compose、Fly.io 四条部署路径以及 bearer token 管理、持久化卷权限修复、无 Docker 安装与自更新契约等生产运维要点。读完你可以把 core 独立部署到云端供多台桌面客户端访问并正确配置长期运行的 cron/webhook 场景。你要部署的是什么headless openhuman-coreOpenHuman 的 Rust 核心openhuman-core是一个 headless JSON-RPC 服务器独立部署它适用于三类场景多设备访问多台桌面客户端指向同一个托管 core内部测试者没有本地 Rust 工具链的同事也可以连入同一 core长时任务需要比笔记本会话存活更久的 cron 任务 / webhook。所有部署路径部署的其实是同一个东西一个运行openhuman-core serve的单一容器监听7788端口。公开主机应置于提供商的 TLS 之后如https://core.example.com/rpc仅私有网络localhost、RFC1918 内网、Tailscale tailnet不可被公网触达时可用明文 HTTP如http://100.x.x.x:7788/rpc。从源码看容器实际暴露的端点及其鉴权策略定义在 src/core/auth.rs 中GET /health—— 公开的 liveness 探针所有部署路径的 healthcheck 都用它源码中的PUBLIC_PATHS白名单包含/、/health、/auth、/auth/telegram、/oauth/mcp/callback、/schema、/events等只读或流式路径POST /rpc—— bearer 保护的 JSON-RPC 入口所有可执行面都走这里GET /events、GET /ws/dictation—— 流式通道浏览器EventSource/WebSocket无法设置自定义 header因此这些路由由 handler 内部强制校验 bind-token / bearerQUERY_TOKEN_PATHS允许?token…查询参数形式。桌面应用已经知道如何与远程 core 通信在app/.env.local中设置OPENHUMAN_CORE_RPC_URL与OPENHUMAN_CORE_TOKEN后启动即可。远程 UI 的现状core 远程、UI 本地OpenHuman 当前支持的远程部署形态是core 远程、UI 本地在 Linux 服务器上运行openhuman-core桌面客户端指向其 RPC URL。已部署的 core 尚不作为生产级 Web 应用提供完整的 React/Tauri UI。桌面专属能力托盘控制、原生 deep link、CEF 账号扫描、OS keychain 集成、窗口/屏幕交互仍然依赖 Tauri 外壳。在私有服务器上获得浏览器可访问的 UI目前推荐用 Vite web 构建作为开发/预览面连接远程 core# 在服务器上用显式 token 启动 core。 export OPENHUMAN_CORE_HOST0.0.0.0 export OPENHUMAN_CORE_PORT7788 export OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) openhuman-core serve # 在另一个 shell 中仅在 loopback 上服务 UI。 pnpm --dir app dev -- --host 127.0.0.1 --port 1420然后从工作站把两个端口隧道过来ssh -L 1420:127.0.0.1:1420 -L 7788:127.0.0.1:7788 userserver打开http://127.0.0.1:1420在首次运行界面选择 remote/core 选项填入http://127.0.0.1:7788/rpc和服务器上的OPENHUMAN_CORE_TOKEN值。如果从非 loopback 来源服务浏览器 UI必须把该 origin 精确加入 core 的 CORS 白名单export OPENHUMAN_CORE_ALLOWED_ORIGINShttps://openhuman-ui.example.comLoopback Vite originhttp://127.0.0.1:1420、http://localhost:1420自动放行公网http://origin 不推荐因为每次 RPC 调用都携带 bearer token。Bearer Token 单一可信源远程部署的第一规则所有/rpc调用都携带Authorization: Bearer token。从 src/core/auth.rs 的源码看token 初始化有三条路径全部汇入进程级OnceLock单一可信源所有传输层通过get_rpc_token()读取内存直传桌面 Tauri 专用init_rpc_token_with_value由 Tauri 外壳把内存中的 bearer 直接交给内嵌 coretoken 从不出现在进程环境里避免出现在/proc/pid/environ或 macOSps eww中环境变量Docker / 云 / systemd 部署的正式通道init_rpc_token读取OPENHUMAN_CORE_TOKEN原样使用从不写文件standalone CLI 回退仅当前两者都未提供时core 生成全新的 256-bit token 并写入{workspace}/core.tokenUnix 上 owner 只读供 CLI 客户端cat读取。两条启动路径被刻意设计为互斥OPENHUMAN_CORE_TOKEN环境变量由调用方Tauri shell、Docker、App Platform、systemd unit预置。core 原样使用不写任何文件{workspace}/core.token文件仅当OPENHUMAN_CORE_TOKEN未设置时由 core 首次启动生成。独立openhuman core run用它这样 CLI 客户端可以读文件。经验法则任何远程 / 容器化部署永远显式设置OPENHUMAN_CORE_TOKEN。不要依赖容器里的core.token——临时文件系统会在重新部署时丢失它容器外的客户端读到的会是陈旧或空值。混用这两条路径是我重新部署后 dashboard 返回 401的最常见原因。要检查运行中的 core 正在使用哪个来源在宿主机或docker compose exec进容器运行 scripts/print-core-token.shscripts/print-core-token.sh --where # 打印 env 或 file:/path scripts/print-core-token.sh --redact # 前 8 个 hex 字符 …可安全写日志 scripts/print-core-token.sh # 完整值可直接管道给客户端桌面应用的首次运行选择器在 Core RPC URL token 输入框旁还有一个Test connection按钮它会用你输入的 token 向该 URL 发core.ping在持久化配置前内联报告Connected ✓/Auth failed/Unreachable。开始前必须准备的环境变量变量必需说明OPENHUMAN_CORE_TOKEN是客户端发往/rpc的 bearer token用openssl rand -hex 32生成。任何拿到此 token 的人都可驱动整个 core。BACKEND_URL是core 与之通信的 Tinyhumans 后端生产为https://api.tinyhumans.ai。OPENHUMAN_APP_ENV否production或staging默认production。OPENHUMAN_CORE_HOST否容器内默认0.0.0.0Dockerfile 中显式ENV OPENHUMAN_CORE_HOST0.0.0.0。OPENHUMAN_CORE_PORT否默认7788。RUST_LOG否info足够排障时用debug。OPENHUMAN_WORKSPACE目录容器内为/home/openhuman/.openhuman保存 core 的配置、sqlite 数据库和 skill 状态。每个生产部署都必须把它挂到持久卷上否则重启即丢数据。这一点在 docker-compose.yml 中通过命名卷openhuman-workspace落实在 Fly.io 路径中通过[[mounts]]落实。路径一DigitalOcean App Platform仓库内置 App Platform 部署规范 .do/app.yaml它同时服务两个入口页面一键部署按钮从该仓库的.do/app.yaml创建应用和doctl命令行。从该 spec 源码可以看到实际部署形态name: openhuman-core region: nyc services: - name: core dockerfile_path: Dockerfile # 用仓库根 Dockerfile 构建 github: repo: tinyhumansai/openhuman branch: main deploy_on_push: false # 改为 true 即可开启 git push 滚动重部署 instance_count: 1 instance_size_slug: basic-xs http_port: 7788 health_check: http_path: /health # 30s 一次初始延迟 20s envs: - key: OPENHUMAN_CORE_HOST # 0.0.0.0 - key: OPENHUMAN_CORE_PORT # 7788 - key: OPENHUMAN_APP_ENV # production - key: BACKEND_URL # https://api.tinyhumans.ai - key: RUST_LOG # info - key: OPENHUMAN_CORE_TOKEN # type: SECRET占位值 CHANGE_ME_BEFORE_DEPLOY一键部署后的关键操作务必在首次部署完成前打开Settings → App-Level Environment Variables把占位的OPENHUMAN_CORE_TOKEN替换为强随机值openssl rand -hex 32并标记为加密若部署 staging把OPENHUMAN_APP_ENV改为staging、BACKEND_URL改为https://staging-api.tinyhumans.ai点SaveApp Platform 会用新 secret 重新部署。App Platform 负责 TLS、崩溃自动重启、日志流以及在deploy_on_push: true时按git push滚动重部署。持久化注意App Platform Basic 档不提供块存储。core 的 workspace 落在容器临时文件系统里重新部署即丢失。需要持久化时挂载托管数据库或升级到支持卷的档位自托管替代方案见下面 Docker Compose 路径开箱即带持久卷。用 doctl 手动部署# 一次性安装并认证 doctl。 doctl auth init # 编辑 .do/app.yaml把 OPENHUMAN_CORE_TOKEN 设为真实值 # 或 create 时通过 --spec 配合 envsubst 注入。然后 doctl apps create --spec .do/app.yaml # 观察构建 doctl apps list doctl apps logs app-id --type build --follow编辑 spec 后更新既有应用doctl apps update app-id --spec .do/app.yaml路径二任意 VPS 上的 Docker Compose适用于任何装有 Docker Engine ≥ 24 和 Compose 插件的宿主机DigitalOcean Droplet、Hetzner、Linode、EC2 或家庭服务器。每个生产 release 会向 GHCR 发布多标签镜像docker pull ghcr.io/tinyhumansai/openhuman-core:latest # 跟踪最新生产构建 docker pull ghcr.io/tinyhumansai/openhuman-core:v1.2.4 # 按 GitHub Release tag 固定 docker pull ghcr.io/tinyhumansai/openhuman-core:1.2.4 # 按 SemVer 固定镜像是linux/amd64。arm64 主机应拉取同一 GitHub Release 附带的独立 tarballopenhuman-core-version-aarch64-unknown-linux-gnu.tar.gz或在 arm64 构建机上从源码构建。用已发布镜像快速启动docker run -d --name openhuman-core -p 7788:7788 \ -e OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) \ -e BACKEND_URLhttps://api.tinyhumans.ai \ -e OPENHUMAN_APP_ENVproduction \ -v openhuman-workspace:/home/openhuman/.openhuman \ ghcr.io/tinyhumansai/openhuman-core:latest用仓库内 Compose 文件docker-compose.yml 默认从仓库 Dockerfile 本地构建镜像若改用已发布镜像把build:换成image: ghcr.io/tinyhumansai/openhuman-core:latest即可。该 Compose 文件包含一组值得注意的加固项从源码看read_only: truetmpfs: /tmp容器根文件系统只读cap_drop: ALL后仅回填CHOWN、SETUID、SETGID三个能力——分别对应 entrypoint 的卷权限修复chown和gosu降权setuid/setgid其余能力全部拒绝restart: unless-stopped宿主机重启后 core 自动回来命名卷openhuman-workspace挂到/home/openhuman/.openhumanmem_limit默认 4g与cpus默认 2.0可通过OPENHUMAN_CORE_MEM_LIMIT/OPENHUMAN_CORE_CPUS覆盖容器级 healthcheck 每 30s 探测curl -fsS http://localhost:7788/health。完整流程# 在服务器上 git clone https://github.com/tinyhumansai/openhuman.git cd openhuman # 配置 secret cp .env.example .env # 编辑 .env至少设置 # BACKEND_URLhttps://api.tinyhumans.ai # OPENHUMAN_CORE_TOKENopenssl rand -hex 32 的结果 # OPENHUMAN_APP_ENVproduction # 构建并启动 docker compose up -d # 验证 docker compose ps curl -fsS http://localhost:7788/health.env模板见仓库根 .env.example其中OPENHUMAN_CORE_PORT7788等默认值与上表一致。无 Docker 的 headless 安装宿主跑不了 Docker 时取最新 GitHub Release 附带的独立 CLI tarball# 选择与宿主架构匹配的 tarball。 ARCH$(uname -m) case $ARCH in x86_64) TARGETx86_64-unknown-linux-gnu ;; aarch64) TARGETaarch64-unknown-linux-gnu ;; *) echo Unsupported arch: $ARCH; exit 1 ;; esac VERSION1.2.4 # 改成你想要的 release curl -fsSL https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz \ | tar -xz -C /usr/local/bin openhuman-core --version然后在你偏好的服务管理器systemd、supervisord…下以相同环境变量运行openhuman-core serve。从源码看serve与run是同一入口src/core/cli.rs 中run | serve run_server_command(...)启动完整的 HTTP/JSON-RPC 服务器。Headless 自更新契约headless 部署应把openhuman.update_apply视为安全原语它下载 release 资产、把新二进制原子地写到当前二进制旁边然后返回进程不会自行退出。openhuman.update_run遵循config.update.restart_strategyself_replace默认暂存二进制、发布进程内重启请求让运行中的 core 自行重生supervisor暂存二进制并返回restart_requestedfalse由外层服务管理器负责重启进程。长时间运行的 Linux 服务建议配置[update] restart_strategy supervisor rpc_mutations_enabled false或等价环境变量OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGYsupervisor OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse推荐的 systemd 姿态Restartalways ExecReload/bin/kill -HUP $MAINPID运维流程调openhuman.update_check发现新 release配置restart_strategy supervisor或在update.toml/ 环境变量中设置让 core 只暂存二进制而不 re-exec 自身然后调openhuman.update_apply或openhuman.update_run。注意restart_strategy是配置项不是RPC 参数显式重启单元systemctl restart openhuman。下载或暂存失败时运行中的二进制保持不动、也不请求重启若暂存的新二进制重启后出问题回滚方法就是从包管理器、镜像 tag 或 release 产物恢复旧二进制再重启 supervisor。更新、日志、token 轮换与 TLS更新compose 构建流git pull docker compose build docker compose up -d对暴露 RPC 的生产部署建议保持OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse走既有的镜像 tag 或包管理流程做滚动发布。日志docker compose logs -f openhuman-core轮换 bearer tokenOPENHUMAN_CORE_TOKEN是公网与完整 RPC 权限之间唯一的屏障应定期轮换并在任何疑似泄露后立即轮换# 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 rm /tmp/new-token .env.bak # 2. 重启容器使新值生效。 docker compose up -d --force-recreate openhuman-core # 3. 确认运行中容器使用新 token脱敏。 docker compose exec openhuman-core /bin/sh -c \ echo -n $OPENHUMAN_CORE_TOKEN | head -c 8; echo … # 4. 更新所有桌面客户端Switch mode → 重新粘贴或改 app/.env.local # 中的 OPENHUMAN_CORE_TOKEN 后重启。仍持旧 token 的客户端在下次 /rpc # 调用会得到 HTTP 401 —— 这是预期行为不是回归。App Platform 上同理在Settings → App-Level Environment Variables中编辑 secret等平台重新部署。没有额外的 token 文件需要删除环境变量就是唯一状态。TLS在:7788前面用 Caddy、nginx 或 Traefik 做反向代理最小Caddyfilecore.example.com { reverse_proxy localhost:7788 }路径三Fly.ioFly.io 很适合openhuman-core自动处理 TLS、所有档位支持持久卷、可自动停机闲置机器省成本。前置条件安装并认证flyctlfly auth login有 Fly.io 账号。Step 1启动应用fly launch --no-deploy --config .fly/fly.tomlFly.io 会自动检测到仓库根Dockerfile选择离用户近的区域并在询问时跳过首次部署。Step 2配置 .fly/fly.toml——仓库已提供模板填入fly launch时选择的应用名与区域app your-app-name primary_region your-region [build] dockerfile Dockerfile [env] OPENHUMAN_CORE_HOST 0.0.0.0 OPENHUMAN_CORE_PORT 7788 OPENHUMAN_WORKSPACE /home/openhuman/.openhuman RUST_LOG info [[mounts]] source openhuman_workspace destination /home/openhuman/.openhuman [http_service] internal_port 7788 force_https true auto_stop_machines stop auto_start_machines true # min_machines_running 0 空闲时完全停机最省钱但空闲后首请求 # 要付冷启动代价容器启动 Rust 二进制初始化数秒。设为 1 可保热。 min_machines_running 0 processes [app] [[http_service.checks]] interval 30s timeout 5s grace_period 10s method GET path /health [[vm]] memory 1gb cpus 1Step 3创建持久卷不挂卷每次重部署都会丢数据fly volumes create openhuman_workspace --size 5 --region your-region --config .fly/fly.tomlStep 4设置 secrets# 必需 fly secrets set OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) fly secrets set BACKEND_URLhttps://api.tinyhumans.ai fly secrets set OPENHUMAN_APP_ENVproduction # 任何公网可达部署都建议 fly secrets set OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse fly secrets set OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGYsupervisor # 可选 —— 错误上报与分析 fly secrets set OPENHUMAN_CORE_SENTRY_DSNhttps://keyoorg.ingest.sentry.io/project fly secrets set OPENHUMAN_ANALYTICS_ENABLEDtrue保存OPENHUMAN_CORE_TOKEN的值后面连接桌面应用要用。任何拿到它的人都可驱动 core请按密码对待疑似泄露后用fly secrets set OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32)轮换。Step 5部署并验证fly deploy --config .fly/fly.toml curl -fsS https://your-app-name.fly.dev/healthStep 6把桌面应用指向托管 core详见下一节。持续部署在.github/workflows/fly-deploy.yml添加 push 触发的工作流name: Fly Deploy on: push: branches: - main paths: - src/** - Cargo.toml - Cargo.lock - Dockerfile - .fly/fly.toml - scripts/docker-entrypoint-core.sh jobs: deploy: name: Deploy openhuman-core runs-on: ubuntu-latest concurrency: deploy-group steps: - uses: actions/checkoutv4 # 把 Fly action 固定到 tag/commit SHA 而不是 master——跟踪活动分支 # 意味着信任该分支上所有后续提交包括被攻陷账号推的提交。 - uses: superfly/flyctl-actions/setup-flyctl1.5 - run: flyctl deploy --remote-only --config .fly/fly.toml env: FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}用fly tokens create deploy生成部署 token存为仓库 secretFLY_API_TOKEN。更新与日志fly deploy --config .fly/fly.toml fly logs --config .fly/fly.toml版本固定部署时更新.fly/fly.toml中的镜像 tag 后重部署[build] image ghcr.io/tinyhumansai/openhuman-core:v1.2.4已知坑卷上的 UID 不匹配从Dockerfile构建的镜像创建openhuman用户为UID 10001Dockerfile 中useradd --uid 10001 --gid 10001 ... openhuman而预构建 GHCR 镜像历史上用UID 1000——在两者之间切换会让持久卷里已写下的文件归属旧 UID启动时Permission denied (os error 13)。同类问题还会出现在跨镜像升级后幸存的 Docker 命名卷以及任何被root身份的docker exec写过的 workspace——docker exec不走 entrypoint默认以 root 落盘会留下root:root的config.tomlcore 以 0600 权限写它运行时用户根本打不开。scripts/docker-entrypoint-core.sh 现在会自动修复每次启动递归chown workspace跳过已正确归属的条目。若修复无法执行cap_drop: ALL且未cap_add: CHOWNentrypoint 会拒绝启动并打印应执行的chown命令——这比启动一个/health返回 200 但所有 config RPC 都报Permission denied的僵尸容器更好。容器日志中找[docker-entrypoint] pre-heal/FATAL行。手动修复旧容器Flyfly ssh console --config .fly/fly.toml chown -R openhuman:openhuman /home/openhuman/.openhuman/ exit fly machine restart --config .fly/fly.tomlDocker 等价操作。UID 从容器内的用户动态推导而非硬编码保证对任何镜像都正确docker exec -u 0 openhuman-core sh -c \ chown -Rh $(id -u openhuman):$(id -g openhuman) /home/openhuman/.openhuman docker restart openhuman-core修复前先查看当前归属。注意docker exec默认是root所以要对运行时用户显式询问docker exec openhuman-core sh -c id openhuman; ls -ln /home/openhuman/.openhuman/config.toml把桌面应用指向托管 core在桌面应用的环境文件app/.env.local中# 使用托管 core而不是派生本地 sidecar。 OPENHUMAN_CORE_RUN_MODEexternal OPENHUMAN_CORE_RPC_URLhttps://core.example.com/rpc OPENHUMAN_CORE_TOKEN与服务器相同的 token无公网 IP 的私有 tailnet VM 则用 tailnet 地址OPENHUMAN_CORE_RUN_MODEexternal OPENHUMAN_CORE_RPC_URLhttp://100.x.x.x:7788/rpc OPENHUMAN_CORE_TOKEN与服务器相同的 token重启桌面应用即可。App.tsx中的 provider 链会把所有 RPC 调用路由到远程 core其余无需改动。应用选择器会拒绝公网http://主机任何公网可达的 core 必须走 HTTPS。排障云运行时上 OAuth 后登录失败症状浏览器中 OAuth 完成关闭此页返回应用桌面端却显示登录错误——而同一账号在本地内嵌运行时登录正常issue #3025。根因几乎总在远程 core而非桌面端。auth_store_session会先让 core 拿新会话 token 去后端校验GET /auth/me再持久化云运行时上这次调用发生在你的服务器上因此远程 core 到不了后端 / 无法认证后端时就会失败BACKEND_URL未设置或错误。它是必需项见环境变量表生产必须为https://api.tinyhumans.ai或 staging 地址。缺失是最常见原因服务器到后端不通出口防火墙、DNS、TLS 拦截→ core 在/auth/me上看到网关/超时core 版本过旧。旧版本没有allowPendingBackendValidation同步校验无宽限把服务器升级到当前 releaseRPC token 错误。token 不匹配表现为/rpc的 HTTP 401重贴 token见 token 轮换一节。在远程 core 日志中查Session validation failed (GET /auth/me)及其 status/reason。桌面端现在会对这些情况给出云环境专属的可操作提示而不是通用的再试一次issue #3025。命名卷归属与 Docker entrypoint 机制Docker 默认以root:root创建命名卷。core 以非 root 的openhuman用户UID 10001运行若不先修复归属启动横幅后的第一次写入init_rpc_token → write_token_file写入$OPENHUMAN_WORKSPACE就会抛Permission denied (os error 13)。镜像内置了专门的 entrypoint/usr/local/bin/docker-entrypoint-core.sh源文件即 scripts/docker-entrypoint-core.sh由 Dockerfile 拷入其流程以root启动对$OPENHUMAN_WORKSPACE与$HOME/.openhumanOPENHUMAN_CORE_TOKEN未设置时core.token的写入目录执行mkdir -p递归chown openhuman:openhumanexec gosu openhuman openhuman-core $降权并移交给二进制。该过程幂等全新卷上 chown 修复 root 归属已修复的卷上 chown 是 no-op已有正确归属的条目被跳过。从旧镜像升级无需手动docker volume rm。entrypoint 只接入根DockerfileE2E 镜像e2e/docker-entrypoint.sh不受影响。配合 docker-compose.yml 的cap_drop: ALLcap_add: [CHOWN, SETUID, SETGID]使用若偏好零能力可固定user: 10001:10001让 entrypoint 直接 exec 二进制——代价是失去修复 root 归属卷的能力。冒烟测试守护云部署路径的两类故障模式仓库定义了两种失败模式来回归验证云部署路径docker-image设置OPENHUMAN_CORE_TOKEN且不挂卷——保护 DigitalOcean App Platform 路径.do/app.yamltoken 总是预置、无持久卷docker-volume-permissions不设OPENHUMAN_CORE_TOKEN且挂一个全新匿名卷到/home/openhuman/.openhuman——精确复现 issue #2065 的失败模式断言/health返回 200 且日志中不出现Permission denied (os error 13)。本地运行冒烟检查docker build -t openhuman-core:smoke . # 可选调整构建 profile 与 Cargo 并行度。 # 受限构建机上保持 CARGO_BUILD_JOBS1大机器可调高。 docker build --build-arg CARGO_PROFILErelease --build-arg CARGO_BUILD_JOBS4 -t openhuman-core:release . # token 已置路径App Platform docker run -d --name oh-smoke -p 7788:7788 \ -e OPENHUMAN_CORE_TOKENsmoke-test-token \ openhuman-core:smoke curl -fsS http://localhost:7788/health docker rm -f oh-smoke # 新卷 / 无 token 路径Docker Compose、VPS docker volume create oh-vol-test docker run -d --name oh-vol-smoke -p 7789:7788 \ -v oh-vol-test:/home/openhuman/.openhuman \ openhuman-core:smoke curl -fsS http://localhost:7789/health docker rm -f oh-vol-smoke docker volume rm oh-vol-test从 Dockerfile 看默认构建 profile 是ci比release峰值内存低适合小型 VPS/CI 构建机CARGO_BUILD_JOBS默认为 1运行时阶段是debian:bookworm-slim安装了curl和gosu分别供 HEALTHCHECK 与 entrypoint 降权使用并预设了OPENHUMAN_WORKSPACE、OPENHUMAN_CORE_HOST0.0.0.0、OPENHUMAN_CORE_PORT7788、OPENHUMAN_DOCKER1等环境变量容器级 HEALTHCHECK 每 30s 探测curl -sf http://localhost:7788/health。小结OpenHuman 的云部署本质上是把 headlessopenhuman-core7788端口、/health公开 /rpcbearer 保护部署到四种托管形态中而生产可靠性的三个支柱是一致的永远显式设置OPENHUMAN_CORE_TOKEN、workspace 必须落持久卷并处理好 uid 归属entrypoint 已内置幂等修复、公网部署走 TLS 并禁用 RPC 可变更新OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse。配置完成后桌面端只需在app/.env.local设置OPENHUMAN_CORE_RUN_MODEexternalOPENHUMAN_CORE_RPC_URL token即可通过首次运行选择器的 Test connection 按钮一键验证连通性。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenHuman 云部署实战指南：headless openhuman-core JSON-RPC 服务的四条部署路径
OpenHuman 云部署实战指南headless openhuman-core JSON-RPC 服务的四条部署路径【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhumanOpenHuman 本身是桌面应用但其 Rust 编写的核心openhuman-core是一个可独立托管的 headless JSON-RPC 服务器监听7788端口。本文基于仓库文档 cloud-deploy.md 及对应的部署配置.do/app.yaml、docker-compose.yml、.fly/fly.toml、Dockerfile 与 src/core/auth.rs 等实现源码完整覆盖 DigitalOcean App Platform一键 doctl 手动、任意 VPS 上的 Docker Compose、Fly.io 四条部署路径以及 bearer token 管理、持久化卷权限修复、无 Docker 安装与自更新契约等生产运维要点。读完你可以把 core 独立部署到云端供多台桌面客户端访问并正确配置长期运行的 cron/webhook 场景。你要部署的是什么headless openhuman-coreOpenHuman 的 Rust 核心openhuman-core是一个 headless JSON-RPC 服务器独立部署它适用于三类场景多设备访问多台桌面客户端指向同一个托管 core内部测试者没有本地 Rust 工具链的同事也可以连入同一 core长时任务需要比笔记本会话存活更久的 cron 任务 / webhook。所有部署路径部署的其实是同一个东西一个运行openhuman-core serve的单一容器监听7788端口。公开主机应置于提供商的 TLS 之后如https://core.example.com/rpc仅私有网络localhost、RFC1918 内网、Tailscale tailnet不可被公网触达时可用明文 HTTP如http://100.x.x.x:7788/rpc。从源码看容器实际暴露的端点及其鉴权策略定义在 src/core/auth.rs 中GET /health—— 公开的 liveness 探针所有部署路径的 healthcheck 都用它源码中的PUBLIC_PATHS白名单包含/、/health、/auth、/auth/telegram、/oauth/mcp/callback、/schema、/events等只读或流式路径POST /rpc—— bearer 保护的 JSON-RPC 入口所有可执行面都走这里GET /events、GET /ws/dictation—— 流式通道浏览器EventSource/WebSocket无法设置自定义 header因此这些路由由 handler 内部强制校验 bind-token / bearerQUERY_TOKEN_PATHS允许?token…查询参数形式。桌面应用已经知道如何与远程 core 通信在app/.env.local中设置OPENHUMAN_CORE_RPC_URL与OPENHUMAN_CORE_TOKEN后启动即可。远程 UI 的现状core 远程、UI 本地OpenHuman 当前支持的远程部署形态是core 远程、UI 本地在 Linux 服务器上运行openhuman-core桌面客户端指向其 RPC URL。已部署的 core 尚不作为生产级 Web 应用提供完整的 React/Tauri UI。桌面专属能力托盘控制、原生 deep link、CEF 账号扫描、OS keychain 集成、窗口/屏幕交互仍然依赖 Tauri 外壳。在私有服务器上获得浏览器可访问的 UI目前推荐用 Vite web 构建作为开发/预览面连接远程 core# 在服务器上用显式 token 启动 core。 export OPENHUMAN_CORE_HOST0.0.0.0 export OPENHUMAN_CORE_PORT7788 export OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) openhuman-core serve # 在另一个 shell 中仅在 loopback 上服务 UI。 pnpm --dir app dev -- --host 127.0.0.1 --port 1420然后从工作站把两个端口隧道过来ssh -L 1420:127.0.0.1:1420 -L 7788:127.0.0.1:7788 userserver打开http://127.0.0.1:1420在首次运行界面选择 remote/core 选项填入http://127.0.0.1:7788/rpc和服务器上的OPENHUMAN_CORE_TOKEN值。如果从非 loopback 来源服务浏览器 UI必须把该 origin 精确加入 core 的 CORS 白名单export OPENHUMAN_CORE_ALLOWED_ORIGINShttps://openhuman-ui.example.comLoopback Vite originhttp://127.0.0.1:1420、http://localhost:1420自动放行公网http://origin 不推荐因为每次 RPC 调用都携带 bearer token。Bearer Token 单一可信源远程部署的第一规则所有/rpc调用都携带Authorization: Bearer token。从 src/core/auth.rs 的源码看token 初始化有三条路径全部汇入进程级OnceLock单一可信源所有传输层通过get_rpc_token()读取内存直传桌面 Tauri 专用init_rpc_token_with_value由 Tauri 外壳把内存中的 bearer 直接交给内嵌 coretoken 从不出现在进程环境里避免出现在/proc/pid/environ或 macOSps eww中环境变量Docker / 云 / systemd 部署的正式通道init_rpc_token读取OPENHUMAN_CORE_TOKEN原样使用从不写文件standalone CLI 回退仅当前两者都未提供时core 生成全新的 256-bit token 并写入{workspace}/core.tokenUnix 上 owner 只读供 CLI 客户端cat读取。两条启动路径被刻意设计为互斥OPENHUMAN_CORE_TOKEN环境变量由调用方Tauri shell、Docker、App Platform、systemd unit预置。core 原样使用不写任何文件{workspace}/core.token文件仅当OPENHUMAN_CORE_TOKEN未设置时由 core 首次启动生成。独立openhuman core run用它这样 CLI 客户端可以读文件。经验法则任何远程 / 容器化部署永远显式设置OPENHUMAN_CORE_TOKEN。不要依赖容器里的core.token——临时文件系统会在重新部署时丢失它容器外的客户端读到的会是陈旧或空值。混用这两条路径是我重新部署后 dashboard 返回 401的最常见原因。要检查运行中的 core 正在使用哪个来源在宿主机或docker compose exec进容器运行 scripts/print-core-token.shscripts/print-core-token.sh --where # 打印 env 或 file:/path scripts/print-core-token.sh --redact # 前 8 个 hex 字符 …可安全写日志 scripts/print-core-token.sh # 完整值可直接管道给客户端桌面应用的首次运行选择器在 Core RPC URL token 输入框旁还有一个Test connection按钮它会用你输入的 token 向该 URL 发core.ping在持久化配置前内联报告Connected ✓/Auth failed/Unreachable。开始前必须准备的环境变量变量必需说明OPENHUMAN_CORE_TOKEN是客户端发往/rpc的 bearer token用openssl rand -hex 32生成。任何拿到此 token 的人都可驱动整个 core。BACKEND_URL是core 与之通信的 Tinyhumans 后端生产为https://api.tinyhumans.ai。OPENHUMAN_APP_ENV否production或staging默认production。OPENHUMAN_CORE_HOST否容器内默认0.0.0.0Dockerfile 中显式ENV OPENHUMAN_CORE_HOST0.0.0.0。OPENHUMAN_CORE_PORT否默认7788。RUST_LOG否info足够排障时用debug。OPENHUMAN_WORKSPACE目录容器内为/home/openhuman/.openhuman保存 core 的配置、sqlite 数据库和 skill 状态。每个生产部署都必须把它挂到持久卷上否则重启即丢数据。这一点在 docker-compose.yml 中通过命名卷openhuman-workspace落实在 Fly.io 路径中通过[[mounts]]落实。路径一DigitalOcean App Platform仓库内置 App Platform 部署规范 .do/app.yaml它同时服务两个入口页面一键部署按钮从该仓库的.do/app.yaml创建应用和doctl命令行。从该 spec 源码可以看到实际部署形态name: openhuman-core region: nyc services: - name: core dockerfile_path: Dockerfile # 用仓库根 Dockerfile 构建 github: repo: tinyhumansai/openhuman branch: main deploy_on_push: false # 改为 true 即可开启 git push 滚动重部署 instance_count: 1 instance_size_slug: basic-xs http_port: 7788 health_check: http_path: /health # 30s 一次初始延迟 20s envs: - key: OPENHUMAN_CORE_HOST # 0.0.0.0 - key: OPENHUMAN_CORE_PORT # 7788 - key: OPENHUMAN_APP_ENV # production - key: BACKEND_URL # https://api.tinyhumans.ai - key: RUST_LOG # info - key: OPENHUMAN_CORE_TOKEN # type: SECRET占位值 CHANGE_ME_BEFORE_DEPLOY一键部署后的关键操作务必在首次部署完成前打开Settings → App-Level Environment Variables把占位的OPENHUMAN_CORE_TOKEN替换为强随机值openssl rand -hex 32并标记为加密若部署 staging把OPENHUMAN_APP_ENV改为staging、BACKEND_URL改为https://staging-api.tinyhumans.ai点SaveApp Platform 会用新 secret 重新部署。App Platform 负责 TLS、崩溃自动重启、日志流以及在deploy_on_push: true时按git push滚动重部署。持久化注意App Platform Basic 档不提供块存储。core 的 workspace 落在容器临时文件系统里重新部署即丢失。需要持久化时挂载托管数据库或升级到支持卷的档位自托管替代方案见下面 Docker Compose 路径开箱即带持久卷。用 doctl 手动部署# 一次性安装并认证 doctl。 doctl auth init # 编辑 .do/app.yaml把 OPENHUMAN_CORE_TOKEN 设为真实值 # 或 create 时通过 --spec 配合 envsubst 注入。然后 doctl apps create --spec .do/app.yaml # 观察构建 doctl apps list doctl apps logs app-id --type build --follow编辑 spec 后更新既有应用doctl apps update app-id --spec .do/app.yaml路径二任意 VPS 上的 Docker Compose适用于任何装有 Docker Engine ≥ 24 和 Compose 插件的宿主机DigitalOcean Droplet、Hetzner、Linode、EC2 或家庭服务器。每个生产 release 会向 GHCR 发布多标签镜像docker pull ghcr.io/tinyhumansai/openhuman-core:latest # 跟踪最新生产构建 docker pull ghcr.io/tinyhumansai/openhuman-core:v1.2.4 # 按 GitHub Release tag 固定 docker pull ghcr.io/tinyhumansai/openhuman-core:1.2.4 # 按 SemVer 固定镜像是linux/amd64。arm64 主机应拉取同一 GitHub Release 附带的独立 tarballopenhuman-core-version-aarch64-unknown-linux-gnu.tar.gz或在 arm64 构建机上从源码构建。用已发布镜像快速启动docker run -d --name openhuman-core -p 7788:7788 \ -e OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) \ -e BACKEND_URLhttps://api.tinyhumans.ai \ -e OPENHUMAN_APP_ENVproduction \ -v openhuman-workspace:/home/openhuman/.openhuman \ ghcr.io/tinyhumansai/openhuman-core:latest用仓库内 Compose 文件docker-compose.yml 默认从仓库 Dockerfile 本地构建镜像若改用已发布镜像把build:换成image: ghcr.io/tinyhumansai/openhuman-core:latest即可。该 Compose 文件包含一组值得注意的加固项从源码看read_only: truetmpfs: /tmp容器根文件系统只读cap_drop: ALL后仅回填CHOWN、SETUID、SETGID三个能力——分别对应 entrypoint 的卷权限修复chown和gosu降权setuid/setgid其余能力全部拒绝restart: unless-stopped宿主机重启后 core 自动回来命名卷openhuman-workspace挂到/home/openhuman/.openhumanmem_limit默认 4g与cpus默认 2.0可通过OPENHUMAN_CORE_MEM_LIMIT/OPENHUMAN_CORE_CPUS覆盖容器级 healthcheck 每 30s 探测curl -fsS http://localhost:7788/health。完整流程# 在服务器上 git clone https://github.com/tinyhumansai/openhuman.git cd openhuman # 配置 secret cp .env.example .env # 编辑 .env至少设置 # BACKEND_URLhttps://api.tinyhumans.ai # OPENHUMAN_CORE_TOKENopenssl rand -hex 32 的结果 # OPENHUMAN_APP_ENVproduction # 构建并启动 docker compose up -d # 验证 docker compose ps curl -fsS http://localhost:7788/health.env模板见仓库根 .env.example其中OPENHUMAN_CORE_PORT7788等默认值与上表一致。无 Docker 的 headless 安装宿主跑不了 Docker 时取最新 GitHub Release 附带的独立 CLI tarball# 选择与宿主架构匹配的 tarball。 ARCH$(uname -m) case $ARCH in x86_64) TARGETx86_64-unknown-linux-gnu ;; aarch64) TARGETaarch64-unknown-linux-gnu ;; *) echo Unsupported arch: $ARCH; exit 1 ;; esac VERSION1.2.4 # 改成你想要的 release curl -fsSL https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz \ | tar -xz -C /usr/local/bin openhuman-core --version然后在你偏好的服务管理器systemd、supervisord…下以相同环境变量运行openhuman-core serve。从源码看serve与run是同一入口src/core/cli.rs 中run | serve run_server_command(...)启动完整的 HTTP/JSON-RPC 服务器。Headless 自更新契约headless 部署应把openhuman.update_apply视为安全原语它下载 release 资产、把新二进制原子地写到当前二进制旁边然后返回进程不会自行退出。openhuman.update_run遵循config.update.restart_strategyself_replace默认暂存二进制、发布进程内重启请求让运行中的 core 自行重生supervisor暂存二进制并返回restart_requestedfalse由外层服务管理器负责重启进程。长时间运行的 Linux 服务建议配置[update] restart_strategy supervisor rpc_mutations_enabled false或等价环境变量OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGYsupervisor OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse推荐的 systemd 姿态Restartalways ExecReload/bin/kill -HUP $MAINPID运维流程调openhuman.update_check发现新 release配置restart_strategy supervisor或在update.toml/ 环境变量中设置让 core 只暂存二进制而不 re-exec 自身然后调openhuman.update_apply或openhuman.update_run。注意restart_strategy是配置项不是RPC 参数显式重启单元systemctl restart openhuman。下载或暂存失败时运行中的二进制保持不动、也不请求重启若暂存的新二进制重启后出问题回滚方法就是从包管理器、镜像 tag 或 release 产物恢复旧二进制再重启 supervisor。更新、日志、token 轮换与 TLS更新compose 构建流git pull docker compose build docker compose up -d对暴露 RPC 的生产部署建议保持OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse走既有的镜像 tag 或包管理流程做滚动发布。日志docker compose logs -f openhuman-core轮换 bearer tokenOPENHUMAN_CORE_TOKEN是公网与完整 RPC 权限之间唯一的屏障应定期轮换并在任何疑似泄露后立即轮换# 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 rm /tmp/new-token .env.bak # 2. 重启容器使新值生效。 docker compose up -d --force-recreate openhuman-core # 3. 确认运行中容器使用新 token脱敏。 docker compose exec openhuman-core /bin/sh -c \ echo -n $OPENHUMAN_CORE_TOKEN | head -c 8; echo … # 4. 更新所有桌面客户端Switch mode → 重新粘贴或改 app/.env.local # 中的 OPENHUMAN_CORE_TOKEN 后重启。仍持旧 token 的客户端在下次 /rpc # 调用会得到 HTTP 401 —— 这是预期行为不是回归。App Platform 上同理在Settings → App-Level Environment Variables中编辑 secret等平台重新部署。没有额外的 token 文件需要删除环境变量就是唯一状态。TLS在:7788前面用 Caddy、nginx 或 Traefik 做反向代理最小Caddyfilecore.example.com { reverse_proxy localhost:7788 }路径三Fly.ioFly.io 很适合openhuman-core自动处理 TLS、所有档位支持持久卷、可自动停机闲置机器省成本。前置条件安装并认证flyctlfly auth login有 Fly.io 账号。Step 1启动应用fly launch --no-deploy --config .fly/fly.tomlFly.io 会自动检测到仓库根Dockerfile选择离用户近的区域并在询问时跳过首次部署。Step 2配置 .fly/fly.toml——仓库已提供模板填入fly launch时选择的应用名与区域app your-app-name primary_region your-region [build] dockerfile Dockerfile [env] OPENHUMAN_CORE_HOST 0.0.0.0 OPENHUMAN_CORE_PORT 7788 OPENHUMAN_WORKSPACE /home/openhuman/.openhuman RUST_LOG info [[mounts]] source openhuman_workspace destination /home/openhuman/.openhuman [http_service] internal_port 7788 force_https true auto_stop_machines stop auto_start_machines true # min_machines_running 0 空闲时完全停机最省钱但空闲后首请求 # 要付冷启动代价容器启动 Rust 二进制初始化数秒。设为 1 可保热。 min_machines_running 0 processes [app] [[http_service.checks]] interval 30s timeout 5s grace_period 10s method GET path /health [[vm]] memory 1gb cpus 1Step 3创建持久卷不挂卷每次重部署都会丢数据fly volumes create openhuman_workspace --size 5 --region your-region --config .fly/fly.tomlStep 4设置 secrets# 必需 fly secrets set OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32) fly secrets set BACKEND_URLhttps://api.tinyhumans.ai fly secrets set OPENHUMAN_APP_ENVproduction # 任何公网可达部署都建议 fly secrets set OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse fly secrets set OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGYsupervisor # 可选 —— 错误上报与分析 fly secrets set OPENHUMAN_CORE_SENTRY_DSNhttps://keyoorg.ingest.sentry.io/project fly secrets set OPENHUMAN_ANALYTICS_ENABLEDtrue保存OPENHUMAN_CORE_TOKEN的值后面连接桌面应用要用。任何拿到它的人都可驱动 core请按密码对待疑似泄露后用fly secrets set OPENHUMAN_CORE_TOKEN$(openssl rand -hex 32)轮换。Step 5部署并验证fly deploy --config .fly/fly.toml curl -fsS https://your-app-name.fly.dev/healthStep 6把桌面应用指向托管 core详见下一节。持续部署在.github/workflows/fly-deploy.yml添加 push 触发的工作流name: Fly Deploy on: push: branches: - main paths: - src/** - Cargo.toml - Cargo.lock - Dockerfile - .fly/fly.toml - scripts/docker-entrypoint-core.sh jobs: deploy: name: Deploy openhuman-core runs-on: ubuntu-latest concurrency: deploy-group steps: - uses: actions/checkoutv4 # 把 Fly action 固定到 tag/commit SHA 而不是 master——跟踪活动分支 # 意味着信任该分支上所有后续提交包括被攻陷账号推的提交。 - uses: superfly/flyctl-actions/setup-flyctl1.5 - run: flyctl deploy --remote-only --config .fly/fly.toml env: FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}用fly tokens create deploy生成部署 token存为仓库 secretFLY_API_TOKEN。更新与日志fly deploy --config .fly/fly.toml fly logs --config .fly/fly.toml版本固定部署时更新.fly/fly.toml中的镜像 tag 后重部署[build] image ghcr.io/tinyhumansai/openhuman-core:v1.2.4已知坑卷上的 UID 不匹配从Dockerfile构建的镜像创建openhuman用户为UID 10001Dockerfile 中useradd --uid 10001 --gid 10001 ... openhuman而预构建 GHCR 镜像历史上用UID 1000——在两者之间切换会让持久卷里已写下的文件归属旧 UID启动时Permission denied (os error 13)。同类问题还会出现在跨镜像升级后幸存的 Docker 命名卷以及任何被root身份的docker exec写过的 workspace——docker exec不走 entrypoint默认以 root 落盘会留下root:root的config.tomlcore 以 0600 权限写它运行时用户根本打不开。scripts/docker-entrypoint-core.sh 现在会自动修复每次启动递归chown workspace跳过已正确归属的条目。若修复无法执行cap_drop: ALL且未cap_add: CHOWNentrypoint 会拒绝启动并打印应执行的chown命令——这比启动一个/health返回 200 但所有 config RPC 都报Permission denied的僵尸容器更好。容器日志中找[docker-entrypoint] pre-heal/FATAL行。手动修复旧容器Flyfly ssh console --config .fly/fly.toml chown -R openhuman:openhuman /home/openhuman/.openhuman/ exit fly machine restart --config .fly/fly.tomlDocker 等价操作。UID 从容器内的用户动态推导而非硬编码保证对任何镜像都正确docker exec -u 0 openhuman-core sh -c \ chown -Rh $(id -u openhuman):$(id -g openhuman) /home/openhuman/.openhuman docker restart openhuman-core修复前先查看当前归属。注意docker exec默认是root所以要对运行时用户显式询问docker exec openhuman-core sh -c id openhuman; ls -ln /home/openhuman/.openhuman/config.toml把桌面应用指向托管 core在桌面应用的环境文件app/.env.local中# 使用托管 core而不是派生本地 sidecar。 OPENHUMAN_CORE_RUN_MODEexternal OPENHUMAN_CORE_RPC_URLhttps://core.example.com/rpc OPENHUMAN_CORE_TOKEN与服务器相同的 token无公网 IP 的私有 tailnet VM 则用 tailnet 地址OPENHUMAN_CORE_RUN_MODEexternal OPENHUMAN_CORE_RPC_URLhttp://100.x.x.x:7788/rpc OPENHUMAN_CORE_TOKEN与服务器相同的 token重启桌面应用即可。App.tsx中的 provider 链会把所有 RPC 调用路由到远程 core其余无需改动。应用选择器会拒绝公网http://主机任何公网可达的 core 必须走 HTTPS。排障云运行时上 OAuth 后登录失败症状浏览器中 OAuth 完成关闭此页返回应用桌面端却显示登录错误——而同一账号在本地内嵌运行时登录正常issue #3025。根因几乎总在远程 core而非桌面端。auth_store_session会先让 core 拿新会话 token 去后端校验GET /auth/me再持久化云运行时上这次调用发生在你的服务器上因此远程 core 到不了后端 / 无法认证后端时就会失败BACKEND_URL未设置或错误。它是必需项见环境变量表生产必须为https://api.tinyhumans.ai或 staging 地址。缺失是最常见原因服务器到后端不通出口防火墙、DNS、TLS 拦截→ core 在/auth/me上看到网关/超时core 版本过旧。旧版本没有allowPendingBackendValidation同步校验无宽限把服务器升级到当前 releaseRPC token 错误。token 不匹配表现为/rpc的 HTTP 401重贴 token见 token 轮换一节。在远程 core 日志中查Session validation failed (GET /auth/me)及其 status/reason。桌面端现在会对这些情况给出云环境专属的可操作提示而不是通用的再试一次issue #3025。命名卷归属与 Docker entrypoint 机制Docker 默认以root:root创建命名卷。core 以非 root 的openhuman用户UID 10001运行若不先修复归属启动横幅后的第一次写入init_rpc_token → write_token_file写入$OPENHUMAN_WORKSPACE就会抛Permission denied (os error 13)。镜像内置了专门的 entrypoint/usr/local/bin/docker-entrypoint-core.sh源文件即 scripts/docker-entrypoint-core.sh由 Dockerfile 拷入其流程以root启动对$OPENHUMAN_WORKSPACE与$HOME/.openhumanOPENHUMAN_CORE_TOKEN未设置时core.token的写入目录执行mkdir -p递归chown openhuman:openhumanexec gosu openhuman openhuman-core $降权并移交给二进制。该过程幂等全新卷上 chown 修复 root 归属已修复的卷上 chown 是 no-op已有正确归属的条目被跳过。从旧镜像升级无需手动docker volume rm。entrypoint 只接入根DockerfileE2E 镜像e2e/docker-entrypoint.sh不受影响。配合 docker-compose.yml 的cap_drop: ALLcap_add: [CHOWN, SETUID, SETGID]使用若偏好零能力可固定user: 10001:10001让 entrypoint 直接 exec 二进制——代价是失去修复 root 归属卷的能力。冒烟测试守护云部署路径的两类故障模式仓库定义了两种失败模式来回归验证云部署路径docker-image设置OPENHUMAN_CORE_TOKEN且不挂卷——保护 DigitalOcean App Platform 路径.do/app.yamltoken 总是预置、无持久卷docker-volume-permissions不设OPENHUMAN_CORE_TOKEN且挂一个全新匿名卷到/home/openhuman/.openhuman——精确复现 issue #2065 的失败模式断言/health返回 200 且日志中不出现Permission denied (os error 13)。本地运行冒烟检查docker build -t openhuman-core:smoke . # 可选调整构建 profile 与 Cargo 并行度。 # 受限构建机上保持 CARGO_BUILD_JOBS1大机器可调高。 docker build --build-arg CARGO_PROFILErelease --build-arg CARGO_BUILD_JOBS4 -t openhuman-core:release . # token 已置路径App Platform docker run -d --name oh-smoke -p 7788:7788 \ -e OPENHUMAN_CORE_TOKENsmoke-test-token \ openhuman-core:smoke curl -fsS http://localhost:7788/health docker rm -f oh-smoke # 新卷 / 无 token 路径Docker Compose、VPS docker volume create oh-vol-test docker run -d --name oh-vol-smoke -p 7789:7788 \ -v oh-vol-test:/home/openhuman/.openhuman \ openhuman-core:smoke curl -fsS http://localhost:7789/health docker rm -f oh-vol-smoke docker volume rm oh-vol-test从 Dockerfile 看默认构建 profile 是ci比release峰值内存低适合小型 VPS/CI 构建机CARGO_BUILD_JOBS默认为 1运行时阶段是debian:bookworm-slim安装了curl和gosu分别供 HEALTHCHECK 与 entrypoint 降权使用并预设了OPENHUMAN_WORKSPACE、OPENHUMAN_CORE_HOST0.0.0.0、OPENHUMAN_CORE_PORT7788、OPENHUMAN_DOCKER1等环境变量容器级 HEALTHCHECK 每 30s 探测curl -sf http://localhost:7788/health。小结OpenHuman 的云部署本质上是把 headlessopenhuman-core7788端口、/health公开 /rpcbearer 保护部署到四种托管形态中而生产可靠性的三个支柱是一致的永远显式设置OPENHUMAN_CORE_TOKEN、workspace 必须落持久卷并处理好 uid 归属entrypoint 已内置幂等修复、公网部署走 TLS 并禁用 RPC 可变更新OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLEDfalse。配置完成后桌面端只需在app/.env.local设置OPENHUMAN_CORE_RUN_MODEexternalOPENHUMAN_CORE_RPC_URL token即可通过首次运行选择器的 Test connection 按钮一键验证连通性。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考