设备登记 · MagicFrog Docs

用 magicfrog enroll 把一台既有计算机登记为已登记计算机（enrolled computer）——配对、设备凭据、能力与吊销。

magicfrog enroll 命令把一台既有的物理计算机、VM 或服务器登记为你的 MagicFrog 账号下的已登记计算机（enrolled computer）。enroll 完成后，机器会出现在你的计算机列表中，并经由设备 daemon 成为 agent 操作的目标。

enroll 遵循 EnrollmentState 状态机：unpaired → pairing → enrolled（unenroll 时 enrolled → revoked）。CLI 实现在 packages/cli/src/commands/enroll.ts；控制面协议为 IF-ENROLLMENT。

前置条件

待登记机器上已安装 MagicFrog CLI。
一个 MagicFrog 账号，以及一个用来登记的控制面。配对码这一步消耗的是账号凭据——传 --token，或先用 magicfrog account login 登录（没有有效账号会话时，服务端会以 401 拒绝配对码请求）。
从该机器到控制面的网络可达。

登记一台计算机

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

交互流程：

CLI 检查是否已有登记。若已存在，确认你要重新 enroll（这会替换已存凭据）。
CLI 向服务端请求短期配对码（POST /v1/pairing/code），连同过期时间一起显示。
输入配对码完成确认（交互式确认；--yes 可跳过）。
CLI 以配对码换取设备凭据（POST /v1/enrollments），同时上报计算机名、设备指纹与探测到的能力。
凭据存入本地，该计算机以已登记计算机的形式出现在你的账号下。

MagicFrog 网页终端：magicfrog enroll 显示一次性配对码，等待你回输确认

图为一次真实登记的录屏帧（现役自部署服务器）：CLI 打印配对码，回输同一配对码完成确认。

实用旗标：

旗标	作用
`--server <url>`	登记目标控制面 URL（enroll 必填）。
`--token <token>`	用于请求配对码的账号 token（默认取已存的账号会话）。
`--name <name>`	已登记计算机的显示名（默认取主机名）。
`--yes`	非交互模式：不再询问，直接接受显示的配对码并重新 enroll。

非交互登记：

magicfrog enroll --server https://<your-host>:4096 --name build-agent-01 --yes

设备凭据

凭据写入 ~/.magicfrog/credentials/device.json，文件权限 0600：

{
  "deviceId": "uuid-v4",
  "deviceToken": "bearer-token",
  "serverUrl": "https://<your-host>:4096",
  "accountId": "uuid-v4",
  "computerId": "uuid-v4",
  "enrolledAt": "ISO-8601",
  "fingerprint": "sha256(hostname:platform:arch:cpus:totalMem).slice(0,32)"
}

设备凭据是一条与你账号会话相互独立的通道：它有自己的 token，以 Authorization: Bearer <deviceToken> 呈现，并且可以被独立吊销而不影响你的账号登录。daemon 读同一份文件，所以它就是这台机器上设备身份的唯一事实源。

指纹由机器特征（主机名、平台、架构、CPU 数、总内存）推导而来，用于向控制面标识这台物理机。

能力探测

enroll 期间 CLI 上报机器的能力：

能力	探测方式
`os`	取自平台：`windows` / `macos` / `linux`。
`arch`	`x64` / `arm64`。
`shell`、`fileSystem`、`terminal`	恒可用。
`browser`	上报为可用；在运行时验证。
`desktop`	取决于平台——macOS 需要屏幕录制权限，Windows 需要启用远程桌面。仅登录账号并不授予 OS 级桌面控制。

Unenroll（吊销）

magicfrog enroll --unenroll

该命令带设备 token 调用 DELETE /v1/enrollments/{computerId}，删除本地凭据文件，机器上的数据完全不受影响——unenroll 吊销的是访问权，不会关机、不会抹盘、不会改动原计算机。之后想再次登记，正常运行 magicfrog enroll 即可。

登记之后

启动设备 daemon，机器即可接受来自控制面的工作：

magicfrog daemon status
magicfrog daemon start

连接与执行健康状况，查看 daemon 自身的状态输出即可。