激活机器
激活会将机器与您的账户关联,方式类似于 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、安全密钥)。服务器在处理批准的同一请求中校验第二重验证:仅凭被盗的代码或未退出的会话是不够的。
批准时会发生什么
- 您的设备随机生成一把机器密钥,并用机器的公钥将其加密封装(X25519 密钥交换)。服务器只传递一个它无法打开的不透明数据块。
- 设备用这把机器密钥加密后,仅复制范围所允许的主机、身份、SSH 密钥、已固定的主机密钥和代码片段,以及规则。保险库的其余内容不会离开您的设备(参阅范围与规则)。
- 机器接收其令牌(仅一次),打开机器密钥,确认能够解密其规则,然后将令牌和密钥存放在受保护的存储中(参阅服务与存储)。
- 您会收到一封电子邮件、一条应用通知,如果已关联 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。