跳到正文

配对、授权与设备管理

配对把一个具体客户端身份授权给目标 daemon。Direct 配对不需要账号；Cloud 账号也不会替代配对。每个客户端都必须通过目标 daemon 明确签发的 claim 获得自己的 grant。

配对前检查

在目标机器上确认 daemon 正常并查看设备身份：

anytty daemon status
anytty access identity

确保目标机器时间正确，并提前决定使用哪种 route、是否只授权一个 terminal、grant 应保存多久。二维码可能包含短期秘密，生成后不要让无关人员看到。

生成二维码或文本 claim

在终端中直接显示二维码：

anytty pair create

保存仅 owner 可读的二维码 PNG：

anytty pair create --qr-file anytty-pair.png

生成可复制 URI 或 CLI 导入命令：

anytty pair create --text
anytty pair create --command

默认 claim 有效期为 10 分钟，默认 grant 有效期为 90 天。可以显式设置：

anytty pair create --ttl 5m --grant-ttl 24h

未兑换的 claim 是秘密。不要把二维码、URI、raw 输出或生成的导入命令放进 shell history、日志、聊天、截图、issue 或版本控制。

AnyTTY Android App 的扫码与粘贴配对入口
安卓模拟器实拍：可以扫描二维码，也可以展开并粘贴 pairing URI；截图中未放入真实 claim。

指定 route

claim 可以携带 Direct、SSH 或严格 route URI。示例：

anytty pair create --route direct --direct-address workstation.local:41120
anytty pair create --route ssh --ssh-host workstation.example.com --ssh-user dev

SSH 配对可附带固定的 host-key fingerprint；Direct 可分别指定 signaling 与 ICE-TCP 地址。准确参数以 anytty pair create --help 为准。

收紧权限范围

默认 daemon-wide grant 可能覆盖 daemon 允许的终端和文件能力。只需要访问一个 terminal 时使用：

anytty pair create --terminal agent-main --grant-ttl 8h

优先签发完成任务所需的最小范围和最短有效期。重新导入比现有 credential 范围更大的 grant 时，CLI 默认拒绝，只有用户明确加上 --allow-scope-expansion 才会继续。

在客户端兑换

移动 App 选择添加设备并扫描二维码，也可以粘贴 pairing URI。CLI 可以从 owner-only 文件或 stdin 导入：

anytty pair inspect claim.bin
anytty pair import --id workstation --client-label "Office laptop" claim.bin

inspect 输出经过删减的 metadata，适合在兑换前核对标签、route 和过期时间；它不会把长期 credential 打印出来。成功导入后，endpoint 与 credential reference 写入当前客户端的本地存储。

信任流程

  1. daemon 创建绑定自身 identity、请求范围和一次 enrollment 的短期 claim。
  2. 客户端扫描或粘贴 claim，并用自己的客户端密钥证明身份。
  3. daemon 签发绑定到该客户端的 grant，并把 claim 标记为已经使用。
  4. 后续连接同时验证 daemon identity、客户端身份和 grant。

同一个 claim 不能重复兑换。复制 endpoint YAML 也不会复制平台保护存储中的 credential。

查看和撤销 grant

在 daemon 所在机器上运行：

anytty access list
anytty access revoke GRANT_ID

access list --json 适合管理脚本。撤销后，新连接应被拒绝；已有会话的终止时机以当前实现和连接状态为准，因此处理遗失设备时还应检查活跃连接并必要时重启服务。

更换或遗失设备

换新手机时，在新设备上重新配对，然后撤销旧设备 grant。手机丢失、送修或凭据疑似泄露时：

  1. 从安全设备连接目标 daemon。
  2. anytty access list 根据 client label 和时间识别 grant。
  3. anytty access revoke GRANT_ID 撤销访问。
  4. 检查 endpoint、终端和文件是否出现异常活动。
  5. 如果 claim 仍未兑换，等待它过期并重新生成，不要继续传播原内容。

仅从 Cloud 控制台移除 daemon 或退出 App 不会替代 daemon grant 撤销。

常见配对失败

  • claim 已过期： 重新生成，不要延长或重用旧二维码。
  • claim 已使用： 每个客户端生成一份新的 claim。
  • 设备时钟偏差过大： 同步双方系统时间后重试；实现只容忍有界偏差。
  • route 不可达： 先用 Local/SSH 检查 daemon，再修正 claim 中发布的地址。
  • identity 不匹配： 停止并确认目标机器，不能通过删除 pin 或关闭验证绕过。
  • scope expansion 被拒绝： 核对新增权限，确实需要时再明确确认。