跳到内容
MagicFrog

云电脑

创建、登记并管理你的 agent 工作所用的计算机。

MagicFrog agent 不必只在客户端所在的机器上工作。每一台计算机——你创建的云电脑(cloud computer)、你自己的机器,或本机本身——都是一等执行目标,agent 可以在其上执行浏览器、命令、文件与桌面操作。

每台计算机由一个稳定的 computerId 标识。IP 地址不是身份:地址会变,同一台路由器后的两台机器还可能共享一个地址。computerId 才是你选择的目标,也是每一次工具调用被授权的依据。

MagicFrog 网页控制台:Computers 页的空态与 Provision 表单

图为 Computers 页的空态与 Provision 表单(如实呈现,未做修饰)。


计算机从哪里来

类型 来源 典型用途
local 恒定存在。客户端所在的那台机器,以 id local 注册。 在你面前的这台机器上工作。
docker 平台创建:以容器形态运行的 Linux 云电脑。 一次性 Linux 工作负载,带浏览器与 shell 访问。
windows 平台创建:Windows 云电脑。 Windows 专属的浏览器、shell 与桌面工作。
enrolled 你通过 CLI 登记:既有的物理机、服务器或 VM。 把你自己的硬件编入名册。

docker 与 windows 计算机由平台托管创建(provisioned)——创建、启动、停止与销毁都归平台所有。local 计算机就是客户端所在的那台机器。已登记计算机则不同:MagicFrog 从未创建它,也从不删除它。吊销一台已登记计算机只是移除登记,仅此而已。


范围:一个控制面,一台服务器

MagicFrog 刻意做成单服务器。控制面只在它所在的那台服务器上、经由该主机自己的容器 runtime 来创建、启动、停止、销毁托管创建的云电脑。没有办法注册第二台物理主机、添加节点资源池、把 runtime 指向远程 Docker daemon,或把计算机调度到另一台机器上——这些面在配置和 API 里都不存在。这是产品边界,不是你可以调大的默认值。

单文件 SQLite 数据库是同一边界的技术对应物:持久化就是一块卷上的一个数据库,不是共享集群存储。

已登记计算机在这个范围之外。它们由你用 CLI 自行登记;控制面从不托管创建、启动或销毁它们,只通过它们主动外连的 daemon 连接向它们派发工作。所以「一台服务器」限制的是控制面创建什么,而不是你的 agent 能操作哪些机器。


生命周期

托管创建的云电脑与已登记机器的生命周期各不相同。

托管创建的计算机

托管创建的计算机(docker 或 windows)经历这些状态:

  • creating——容器或 VM 正在被创建。若创建超时或镜像缺失,半成品实例会被清理,创建以显式错误失败。
  • ready——实例已就绪并接受工作。Linux 计算机在其容器运行并就绪时到达此状态;Windows 计算机在其克隆运行且远程桌面端口开始监听时到达此状态。
  • stopped——实例已停机,但其磁盘(容器卷或 VM 镜像)保留。再次启动会回到 ready。
  • destroyed——终态。容器/VM 及其卷被删除。

计算机还有活跃 run 或租约时,启动与停止都会被拒绝,所以停一台计算机不会抽掉正在运行的任务脚下的地板。

已登记计算机

已登记机器走自己的状态:

  • pairing——CLI enroll 正在进行,等待你确认配对码。
  • enrolled——活跃且已登记。
  • revoked——终态。登记已消失:设备凭据失效,既有连接在数秒内被切断,该计算机不再作为可用目标出现。

离线

任何计算机还可能处于 offline。已登记机器运行 daemon,每 15 秒向服务端报一次活;连续两次心跳未到,约 30 秒后该计算机被标记为 offline。路由到 offline 计算机的调用显式失败——它们绝不静默改投另一台机器。


能力

计算机的能力是探测出来的,不是声明出来的。enroll 期间 daemon 探测真实主机并如实上报——shell 与文件访问恒可用,浏览器在运行时验证,桌面控制取决于平台(macOS 需要屏幕录制权限;Windows 需要启用远程桌面)。上报的能力集包含主机的操作系统与 CPU 架构。

你不需要手工配置能力。当工具需要目标不具备的能力时——例如在一台 headless 机器上执行桌面操作——调用会以显式能力错误失败,而不是静默降级。


登记你自己的计算机

你掌控的任何机器都能作为已登记计算机加入你的账号:

magicfrog enroll --server https://<your-host>:4096

CLI 会登录你的账号,请求一个短期配对码,并等待你确认。确认之后,这台机器获得自己的设备身份,并以已登记计算机的形式出现在你的账号下。

  • 设备凭据本地存放在 ~/.magicfrog/credentials/device.json(权限 0600),与你的用户登录相互独立。
  • 设备 token 可随时被独立吊销。
  • magicfrog enroll --unenroll(或从服务端侧吊销)只移除登记,不触碰机器上的任何东西。

CLI 命令详见 CLI 文档。


列出计算机

控制面暴露你账号下的计算机:

GET /v1/computers

每一条目都携带其 computerId、来源(托管创建或已登记)、生命周期状态与探测到的能力——与 daemon 上报的同一份事实,而不是静态配置。

计算机一旦存在,每一个触碰机器的 agent 工具都以 computerId 指名目标。该路由与授权模型见 Computer ID 路由。