激活机器

更新于 2026年11月10日

激活会将机器与您的账户关联,方式类似于 Claude Code 或智能电视:机器显示一个代码,您在一台已登录的设备上批准它。无需在机器上输入任何密码,机器也永远不会收到您保险库的密钥。

开始之前

  • 账户已启用 Studio 套餐(或其试用)。
  • 已在“安全”中启用双重身份验证(TOTP)或通行密钥:批准机器始终需要第二重验证。两者都未启用时,批准会被拒绝,并提示您启用其中一项。
  • 一台保险库已打开的设备:Konsolity 应用(Mac、Windows、Linux、iPhone、iPad、Android)或网页控制台 app.konsolity.com。

开始激活

在机器上,使用将要运行 CLI 的账户(如果作为服务运行,则使用与服务相同的账户):

konsolity login --name build-01
选项 作用
--name <name> 在机器列表中显示的名称(默认:主机名)。
--scopes <list> 请求的范围,可选 hosts、snippets、sessions、mcp,以逗号分隔。
--read-only 请求只读访问(列表和状态,不能运行命令)。

请求的范围只是一项建议:最终范围由您在批准时设定。该命令会显示:

Activating this machine on https://api.konsolity.com
1. Open this address on a device signed in to your account:
   https://app.konsolity.com/cli/activate?code=WDJB-MJHT
   or in the Konsolity app: Settings › CLI machines › Activate a machine
2. Enter this code: WDJB-MJHT
3. Check that the fingerprint shown is: 7K3Q-9XAD
Waiting for approval...

如果终端支持,还会显示完整链接的二维码,方便用手机批准。代码有效期为 15 分钟;在此期间机器只会等待,不做其他任何事情。

核对指纹

指纹(示例中为 7K3Q-9XAD)是根据机器刚刚生成的公钥计算得出的。批准页面会自行根据该公钥重新计算指纹,不依赖服务器,并将其与机器的名称、系统、架构、主机名和 IP 地址一起显示。

**只有在您刚刚亲自在这台机器上运行了 konsolity login,并且指纹一致时,才可批准。**对于无法识别的请求,一键即可拒绝。

在应用中批准

在 Konsolity 中:设置 › CLI 机器 › 激活机器,然后输入代码。保险库必须处于打开状态。

在浏览器中批准

打开 https://app.konsolity.com/cli/activate(或机器显示的完整链接),登录,然后输入代码。页面会要求输入您的主密码,以便在浏览器中打开保险库:主密码不会离开该页面,也不会发送到服务器。

选择范围和有效期

批准之前,您需要选择:

  • 范围:hosts、snippets、sessions、mcp,只读或完全访问;
  • 机器可以使用的主机和代码片段(默认:无主机);
  • 命令规则(适用于完全访问);
  • 机器的有效期。

默认:hosts 和 snippets,只读,无主机。详情请参阅范围与规则。

有效期 典型用途
1 天 一次性操作
7 天 短期任务、测试服务器
30 天 进行中的项目
90 天(默认) 管理服务器
1 年 长期使用的机器,每年续期
永不过期 仅用于您密切监控的机器

通过第二重验证确认

批准按钮会要求输入您的 TOTP 代码或使用通行密钥(Face ID、Touch ID、Windows Hello、安全密钥)。服务器在处理批准的同一请求中校验第二重验证:仅凭被盗的代码或未退出的会话是不够的。

批准时会发生什么

  1. 您的设备随机生成一把机器密钥,并用机器的公钥将其加密封装(X25519 密钥交换)。服务器只传递一个它无法打开的不透明数据块。
  2. 设备用这把机器密钥加密后,仅复制范围所允许的主机、身份、SSH 密钥、已固定的主机密钥和代码片段,以及规则。保险库的其余内容不会离开您的设备(参阅范围与规则)。
  3. 机器接收其令牌(仅一次),打开机器密钥,确认能够解密其规则,然后将令牌和密钥存放在受保护的存储中(参阅服务与存储)。
  4. 您会收到一封电子邮件、一条应用通知,如果已关联 Telegram,还会收到一条“新的 CLI 机器”消息。

随后,该命令会显示机器名称和账户的电子邮件地址。可随时查看状态:

konsolity status

每个指纹对应一台机器

每台机器都有一个机器指纹,根据系统标识符计算得出(Linux 上为 /etc/machine-id,macOS 上为 IOPlatformUUID,Windows 上为 MachineGuid)。在同一台机器上重新激活会替换之前的激活:旧条目会被自动撤销。因此,同一台电脑永远不会同时有两个有效令牌。

该指纹会随每次调用一起发送。复制到另一台电脑上的令牌会被拒绝,并触发警报。

setup-token:CI 和容器

CI 运行器或容器通常每次都会重新创建:其机器标识符会变化,也无法持久保存任何内容。针对这些情况,请创建一个长期令牌:

konsolity setup-token --name ci-deploy

流程相同(代码、指纹、通过第二重验证批准、范围)。最后,该命令会仅显示一次以 ksetup_ 开头的令牌,并且不会向磁盘写入任何内容:

Long-lived token (shown once):
ksetup_3q2Xk...
Store it in your CI secret manager, then provide it through KONSOLITY_TOKEN.

将其保存到 CI 的密钥管理器中,然后通过环境变量 KONSOLITY_TOKEN 提供给命令:

KONSOLITY_TOKEN="$KONSOLITY_TOKEN" konsolity run web-01 -- systemctl status nginx

长期令牌:

  • 不绑定机器指纹(用于临时机器):请像保护密码一样保护它;
  • 必须设置有效期,最长为创建后 1 年;
  • 不会自动轮换;
  • 在列表中显示为长期令牌,其范围、日志和撤销方式与机器相同。

遇到问题时

  • 代码已过期:重新运行 konsolity login,会生成新的代码。
  • 需要第二重验证:在“安全”中启用双重身份验证或通行密钥,然后重新开始。
  • 需要订阅:批准需要 Studio 套餐(或其试用)。
  • 已拒绝:机器会停止,不保存任何内容。
  • 机器已激活:先运行 konsolity logout,再运行 konsolity login。