Prismer Cloud 部署指南：Runtime Daemon、容器沙箱与 macOS 自启动全解析-开发者社区

【免费下载链接】PrismerCloud

Prismer Cloud

项目地址：https://gitcode.com/gh_mirrors/pr/PrismerCloud

Prismer Cloud 是一个面向 AI Agent 的云端运行时（Intelligence Runtime），它提供 Evolution 进化引擎、记忆、消息、任务与沙箱等基础设施。本文将带你完成 Prismer Cloud 的完整部署：一行命令安装、Runtime Daemon 常驻进程管理、容器沙箱（daemon-first 镜像）启动，以及 macOS 上通过 LaunchAgent 实现开机自启动，全程面向新手，命令很少、步骤清晰。

一、部署前先了解：三种部署形态

Prismer Cloud 的本地运行时（@prismer/runtime）用同一个二进制覆盖三种场景：

形态	运行方式	典型用途
macOS 桌面	LaunchAgent 常驻 Daemon（本地服务端口`3210`）	个人开发机，宿主 Agent 常驻在线
Linux 服务器	systemd / tmux 手动托管 Daemon	自建托管环境
容器 Pod	daemon-first 镜像，Rust`sandbox-manager`监管 Daemon（端口`7878`）	云上沙箱、无人值守任务执行

无论哪种形态，Daemon 都会开一条 WebSocket连云端，声明本机托管的所有 Agent，并接收云端派发的任务。云端是数据源（source of truth），本地~/.prismer/local.db只是离线只读镜像。

二、一键安装：30 秒完成 Prismer Cloud 部署

最简单的方式是官方安装脚本（自动检测系统与架构，缺 Node.js 时用fnm自动安装，全程无需 sudo）：

curl -fsSL https://prismer.cloud/install.sh | sh

或者你已经装好 Node.js，直接运行：

npx @prismer/sdk setup

安装脚本会完成 4 件事（逻辑见 install.sh）：

检测操作系统、架构与 Shell；
若缺少 Node.js，通过fnm安装到~/.local/share/fnm；
全局安装@prismer/sdk与@prismer/mcp-server；
执行prismer setup，打开浏览器完成登录，API Key 自动写入~/.prismer/config.toml。

💡 所有文件都在用户主目录下，卸载只需删除~/.prismer与~/.local/share/fnm，或执行install.sh --uninstall。

若希望从源码了解项目结构，也可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/pr/PrismerCloud

三、macOS 自启动：LaunchAgent 配置全解析

在 macOS 上部署 Daemon 形态时，安装器会写入 LaunchAgent 配置~/Library/LaunchAgents/com.prismer.daemon.plist，并自动加载（详见 sdk/prismer/README.md）：

label：com.prismer.daemon
KeepAlive = true：进程退出后 launchd 自动拉起
RunAtLoad = true：登录即启动
ProgramArguments包含--foreground（必需，否则会陷入重启循环）

对应的 daemon 模式安装命令：

curl -fsSL https://prod.docbrew.cn/install.sh | sh -s -- \ --component=daemon --adapters=claude-code,codex,hermes

安装器会依次：检测平台 → 用 fnm 装 Node → 严格钉住@prismer/runtime@2.0.0→ 创建~/.prismer/{adapters,workspace,logs,bin}目录 → 写入 plist 并bootout+bootstrap加载 → 按--adapters列表自动安装各适配器。

一个巧妙的设计：等待 config.toml 才真正启动

Daemon 启动后如果~/.prismer/config.toml还不存在（即你还没执行prismer setup），它不会报错退出，而是每 5 秒轮询一次配置文件（实现见 sdk/prismer/src/cli/commands/daemon.ts）。这样即使 LaunchAgent 先于用户操作自启，也不会陷入 KeepAlive 重启风暴；等你完成登录后，Daemon 会在 5 秒内"苏醒"投入工作。

安装完成后只需补一步：

prismer pair # 或 prismer setup sk-prismer-...

四、Runtime Daemon 核心概念与日常命令

Daemon 源码位于 sdk/prismer/src/daemon/，核心主循环是Runner（见 runner.ts）。它的启动序列大致是：

读取config.toml，导出PRISMER_BASE_URL/PRISMER_API_KEY供子进程继承；
打开本地 SQLite（~/.prismer/local.db）、初始化资产缓存（默认 LRU 5 GiB）与prismer://URI 解析器；
建立 WebSocket 连接云端，发送agent.host.declare声明托管 Agent（每 30 秒心跳一次，防止云端判定离线）；
启动 60 秒"卡死任务收割器"：超过max(timeoutMs, 5min)的任务会被中止并回报daemon_task_timeout；
绑定本地回环 HTTP 服务（桌面127.0.0.1:3210，容器:7878），提供/healthz等只读接口。

日常运维只需要记住这组生命周期命令：

命令	作用
`prismer daemon start`	后台启动（自动 spawn`daemon run`子进程并写 PID 文件）
`prismer daemon stop`	发送 SIGTERM 优雅停止，默认等待 5 秒
`prismer daemon restart`	stop 后重新 start
`prismer daemon status`	查看 pid、WebSocket 连接状态与托管 Agent 列表
`prismer daemon logs --tail 100 --follow`	跟踪`~/.prismer/logs/daemon.log`
`prismer status`	综合体检：配置、本地服务、云端账号、本地库行数

Daemon 与云端的事件协议

上行：agent.host.declare（声明设备与 Agent）、task.dispatch.reply（任务结果）、task.dispatch.progress（进度）；
下行：task.dispatch.request（派单）、task.cancel（取消）、host.acked（确认并回灌离线期间积压任务）。

断线时 WebSocket 采用 1s → 60s 指数退避重连，认证失败（close code4001）则停止重连并以非零码退出，方便 launchd / k8s 感知异常。

五、容器沙箱：daemon-first 镜像如何工作

在容器环境（K8s Pod）中，Prismer Cloud 使用daemon-first 沙箱镜像，进程层级为（实现见 sandbox-manager/src/main.rs）：

tini (PID 1) → sandbox-manager（Rust 常驻监管器）→ node daemon（子进程）

启动时序：

tini拉起 Rust 编写的sandbox-manager，它以低权限账户常驻，先暴露健康检查端点（默认端口7890）；
manager 通过签名校验安装经过 OTA 验证的运行时 bundle（内含 Runtime、Cloud SDK/CLI 与 AIP 身份组件）；
manager 以sudo -u user -H --preserve-env启动 Daemon：node <bundle>/dist/cli.js daemon start --port=7878 --foreground（信号转发见 supervisor.rs）；
若 Pod 尚无经验证的 bundle，manager 保持健康状态（daemonAlive:false）并持续重试，绝不回退到镜像内置的旧 JS，保证版本可控。

容器内 Daemon 的额外行为：绑定:7878作为沙箱控制器的代理目标，并启动OutboxWatcher—— 凡丢进/workspace/_outbox/的文件都会自动上传为 sandbox 输出资产。

容器部署关键环境变量

环境变量	说明
`PRISMER_API_KEY`	必需，云端 API Key
`PRISMER_DAEMON_ID`	必需，缺省时由 hostname 推导为`container:<podName>`
`PRISMER_BASE_URL`	云端地址，默认回退到生产地址
`PRISMER_HOSTED_AGENT_FILE`/`PRISMER_HOSTED_AGENT_JSON`	静态绑定 Agent 的载荷文件（首次 declare 前的一次性安装）
`PRISMER_STATIC_BINDING_REQUIRED=true`	缺少静态绑定时直接报错（fail fast）
`PRISMER_CONTAINER_ID`	激活 OutboxWatcher 的替代开关

沙箱全生命周期 CLI

无论桌面还是容器，都可用prismer sandbox系列命令管理云端沙箱容器（实现见 sandbox.ts）：

prismer sandbox list --workspace-id <id> prismer sandbox create --workspace-id <id> --agent-id <id> prismer sandbox status <id> prismer sandbox start <id> / prismer sandbox stop <id> prismer sandbox snapshot <id> # 创建快照 prismer sandbox runCmd <id> -- <command> prismer sandbox logs <id>

snapshot支持把沙箱环境固化下来，配合 OTA bundle 机制，可实现"任务环境可复现、可回滚"。

六、部署后验证清单

按顺序执行以下命令，全部通过即代表部署成功：

prismer status—— 应显示配置、本地服务与云端账号均正常；
prismer daemon status --json—— 确认running: true且wsConnected: true；
prismer adapter doctor claude-code—— 5 项检查矩阵（二进制、适配器健康、配置记录、鉴权环境变量、Hook 配置）全绿；
prismer agent list—— 本地镜像与云端 Agent 数量一致；
curl 127.0.0.1:3210/healthz—— 返回status: ok及托管 Agent 列表。

七、常见问题快速排查

症状	原因与解法
LaunchAgent 反复重启	plist 缺少`--foreground`；重新跑 daemon 模式安装脚本即可（会自动 bootout + bootstrap）
日志一直输出 "waiting for config.toml"	属正常现象，执行`prismer pair`或`prismer setup`后 5 秒内自动恢复
提示云端不可达	多为`cloud_api_base`过期或 Key 被轮换，执行`prismer setup --force <new-key> --cloud <url>`
Agent 出现在`__unbound__`设备下	版本过旧，`agent.host.declare`未携带`daemonId`，升级到`@prismer/runtime@2.0.0`+
任务永远不返回	60 秒收割器会在`max(timeoutMs, 5min)`后中止并回报`daemon_task_timeout`，用`prismer task get <id>`查看详情

八、关键路径速查

安装脚本：install.sh
Daemon 生命周期 CLI：sdk/prismer/src/cli/commands/daemon.ts
Daemon 主循环 Runner：sdk/prismer/src/daemon/runner.ts
容器监管器（Rust）：sdk/prismer/src/daemon/sandbox-manager/
沙箱 CLI：sdk/prismer/src/cli/commands/sandbox.ts
Runtime 完整文档：sdk/prismer/README.md
旧版轻量 Daemon 实现（SDK 内置）：sdk/cloud/src/daemon.ts
项目总览：README.md · 中文文档：docs/zh/README.md

结语

至此，你已经掌握了 Prismer Cloud 的三种部署形态：macOS 上用 LaunchAgent 一行命令实现免维护自启动、Linux 服务器上手动托管 Daemon、容器中以 daemon-first 镜像让 Rust 监管器看管整个运行时。部署完成后，prismer status就是你的第一道体检门，而~/.prismer/logs/daemon.log是排查问题的第一现场。祝部署顺利！