← 全部文档

配对、重新配对与共享机器

每台运行 Terminull 的机器都有一个永久身份——一个 beacon ID 加一个公钥——并会显示携带该身份的 terminull://pair 二维码。二维码有两种，扫描的结果取决于这是哪一种二维码以及由谁扫描。本节讲的就是这个区别：一种二维码把机器交出去，另一种只是把它借出去。

配对——首次连接一台机器

在 macOS 上，设置向导会在最后一页显示二维码，菜单栏中的“通过二维码添加设备”也可随时调出。在无图形界面的 Linux 上，terminull 服务会以文本形式输出配对链接（通过 SSH 无法读取终端里的二维码），你可以把它粘贴到应用中，或拖到 Mac 窗口上。

在 Windows 上，安装程序会在最后一步显示二维码，托盘图标的 Pair a phone (QR) 也可随时调出；或在任意终端中运行 terminull qr。

在应用中扫描它，即把这台机器归属到你的账户，你成为它的所有者。应用会注册 beacon ID 和公钥；机器随后获取一次永久认证令牌并上线。二维码只包含 beacon ID、机器的公钥、一次性密钥交换密钥、其归属中继地址，以及一个一次性认领码——绝不包含你的代码、会话或凭据。

在无图形界面的机器上获取二维码

刚安装好的服务在首次以未配对状态启动时，会把配对二维码打印到自己的输出中；一旦有设备完成认领便不再打印。之后若想随时获取，向正在运行的服务索取即可：

terminull-admin qr        # print a QR (needs the service running)
terminull-admin qr --url  # just the pairing link, on stdout

二维码绘制在服务的输出中，而不是你敲命令的那个终端——你的终端拿到的是链接。在 systemd 下该输出即为日志，请从日志中渲染：

journalctl --user -u terminull --no-pager -o cat -n 40

-o cat 不是可选项。不加它，journald 会在每行前面加上时间戳和单元名，使二维码的每一行横向错位；无论乍看多正常，都无法扫描。

通过 SSH 时，链接通常比图像更方便。terminull-admin qr --url 会输出可直接粘贴到应用中的纯 URL；也可以把它交给你自己的渲染工具，从而完全绕开日志：terminull-admin qr --url | qrencode -t ANSI。

有两点容易让人卡住：安装程序把该命令放在服务自身的环境中，因此若你的 shell 找不到它，请使用完整路径 ~/.local/share/terminull/venv/bin/terminull-admin；该命令通过本地套接字与运行中的服务通信，所以 “terminull is not running” 就是字面意思——用 systemctl --user start terminull 启动后再试。请把它打印出的内容视为所有者二维码，遵守上文所述的全部注意事项。

重新配对——用同一账户再次扫描

用已经拥有这台机器的账户再次扫描所有者二维码属于重新认领，可以放心重复。它会刷新已保存的公钥和名称，并重新打开令牌获取窗口。不会丢失任何东西——会话保存在机器本身而非手机上，之后它们都还在。

以下情况需要重新配对：添加你自己的第二台设备（iPhone 之外再加 iPad）、重装应用，或通过彻底卸载重置了机器身份。最后一种情况会重新生成密钥，而重新认领写回的正是这个密钥。

所有者二维码是机密。如果由另一个账户扫描，那不是加入，而是所有权转移。服务器会记录为待处理，并在机器下次轮询时生效，这台机器随即离开你的账户。持有认领码即证明可以物理接触这台机器，因此它被视为对机器的权限。若想在不交出所有权的前提下让别人使用，请使用下面的共享二维码。

在应用中打开“账户”，找到该机器并点按旁边的二维码图标。机器会生成一个有效期两分钟的新代码，向服务器注册，并显示带实时倒计时的共享二维码。（仅局域网的机器背后没有账户，因此无法共享。）

当另一个账户扫描它时，该账户会以成员身份加入：机器出现在对方列表中，对方会收到推送通知，并可在其上运行会话。所有权不会改变，机器的认证令牌也不受影响。已加入的成员随时可以再次扫描，无需你重新开启窗口。

有效期由服务器强制执行，而不只是显示出来。没有匹配代码的扫描会被拒绝并提示“这台机器当前未在共享”，超时的则提示“该共享代码已过期——请向所有者索取新的二维码”。因此旧共享二维码的截图毫无用处，这正是设计目的：共享是一次有意为之的短暂行为，而不是永久授权。

我看到的是哪种二维码？

	所有者二维码	共享二维码
在哪里找到	设置向导，或菜单栏 →“通过二维码添加设备”	应用 →“账户”→ 机器旁的二维码图标
有效多久	直到机器身份被重置	两分钟，带倒计时
你自己的账户扫描	重新配对——可安全重复	没有变化；你已经拥有它
别人的账户扫描	取得机器的所有权	以成员身份加入；你仍是所有者
可以截图吗？	不可以——请当作密码对待	两分钟过后即无害

仅局域网配对

配置为 pairing_mode = "lan" 的机器完全在你的本地网络内完成配对：其二维码标记为仅局域网，应用跳过账户认领，全程不涉及任何服务器。此时只能从同一网络访问该机器，推送通知和云端 AI 辅助均不可用。它也无法被共享——共享是经由服务器实现的概念，而这种模式下没有服务器。