设备关联与恢复

如何在新的手机或电脑上登录、何时使用对应的二维码流程，以及自托管服务器上的操作方法。

Kaiwu 目前提供了几种不同的二维码流程。它们看起来很相似，但解决的问题各不相同。

本文档将说明每种流程的适用场景、各个按钮的具体含义，以及在遇到扫码失败或服务器不可达时的应对办法。

用户的三大常见需求

绝大多数与账号或设备相关的问题，都可以归入以下三类场景：

在已登录电脑的协助下，于新手机上登录
借助另一台已登录设备，在新电脑或新浏览器中恢复访问权限
将终端接入账号，以便 CLI 或守护进程运行会话

这些流程之所以分开设计，是出于明确的功能划分：

恢复账号 / 添加手机：将新设备登录到同一个 Kaiwu 账号下
连接终端：为终端或守护进程授权，而非添加面向用户的新设备

只要理清这个区别，界面的其余部分就很容易理解了。

各个选项的含义

添加手机

在桌面端或网页端中，满足以下条件时请使用 设置 → 添加手机：

你的电脑已经处于登录状态
你希望手机也能登录到同一个 Kaiwu 账号

该界面会显示：

一个二维码
一个可复制的深度链接
手机发起访问请求时，电脑上出现的一次性批准步骤

手机扫码后，最终的批准权仍在电脑端。若 Kaiwu 在两台设备上都显示了确认码，请在点击批准前核对它们是否一致。

恢复账号

在处于未登录状态的设备上，当你希望该设备加入已有账号时，请使用 恢复账号。

后续步骤会因设备类型而异：

手机或具备摄像头支持的移动端网页： Kaiwu 会优先打开扫码界面，方便你立即扫描桌面端或网页端的二维码
桌面端或较大尺寸的网页布局： Kaiwu 会展示一个二维码，供另一台已登录设备扫描

这就是为什么恢复界面在不同设备上不尽相同：系统会根据该设备的实际操作便利性，自动调整默认操作。

改为展示二维码

在手机端恢复流程中，改为展示二维码 会切换配对方向：

不再用手机扫描电脑上的二维码，
而是由手机展示自己的二维码，
再由另一台已登录设备扫码以批准恢复。

当手机当前不方便调用摄像头扫码时，可以使用该备用方案。

改用密钥恢复

在以下情况下，请使用 改用密钥恢复：

手边没有其他已登录设备可用
无法进行扫码操作
你平时保留了手动备份或恢复手段

对于采用设备密钥机制的账号，该密钥是一项恢复凭证，能让新设备读取同一份已加密的账号数据。

扫码连接终端

仅当终端或 CLI 界面正在显示 Kaiwu 终端二维码时，才使用 扫码连接终端。

此操作不会将手机或浏览器登录到你的账号，它仅用于为终端或守护进程连接提供授权。

手动输入 URL

在以下情况下，请使用 手动输入 URL：

摄像头不可用
二维码位于另一块屏幕上，无法直接对准扫描
你从其他设备上复制了 Kaiwu 链接

这是二维码流程的手动备用方案。在权限受限的浏览器、远程设备或摄像头权限异常的环境中尤其实用。

常见用户操作流程

通过已登录的电脑添加手机

在已登录的桌面端或网页端中，打开 设置 → 添加手机
在手机端，选择 恢复账号
扫描电脑屏幕上的二维码
若 Kaiwu 显示了确认码，请核对是否一致
在电脑端点击批准

批准完成后，手机即会登录到同一个账号中。

借助另一台已登录设备，在新浏览器或桌面端恢复

在新的浏览器或电脑上，打开 恢复账号
若界面显示二维码，使用另一台已登录的设备扫描该码
在已登录设备上批准该请求

若新设备是手机，Kaiwu 通常会优先打开扫码界面。

连接终端

在 CLI 中发起终端登录
在 Kaiwu 应用中，选择 扫码连接终端
扫描终端中的二维码，或通过 手动输入 URL 粘贴链接
批准该请求

这样即可为终端赋予所需权限，同时不会改变账号界面下的已登录设备列表。

批准与安全检查

当 Kaiwu 提示已登录设备去批准某项恢复或配对请求时，请将其视为一次登录确认操作。

建议进行的核对项：

确认该请求是在你的预期操作下弹出的
若两台设备均显示了简短确认码，仔细核对二者是否一致
当 Kaiwu 显示设备标签时，确认其设备名称无误
切勿批准任何非预期的请求

二维码本身并非最终凭证。授权操作始终需要在已登录设备上人工批准。

自托管服务器与 localhost

这是本地开发及部分自托管环境中最容易产生混淆的地方。

如果你的服务器配置为 localhost、127.0.0.1、::1 或其他仅限回环的地址：

桌面端或网页端在本地依然可以正常访问该地址
手机则无法访问该地址，因为在手机上 localhost 指代的是手机本身

为避免生成不可用的移动端链接，当检测到当前服务器仅限回环地址时，Kaiwu 会特意在面向移动端的二维码和深度链接中省略服务器 URL。

遇到这种情况时：

请在手机端配置一个它实际能够访问到的服务器 URL
然后重试扫码

常见的可用方案包括：

局域网 URL，例如 http://192.168.x.x:3005
Tailscale HTTPS URL，例如 https://machine.tailnet.ts.net
自行配置的公网域名或反向代理域名

如果你是该服务器的管理者，请配置 KAIWU_PUBLIC_SERVER_URL，以便 Kaiwu 能够在二维码和深度链接中直接植入正确的共享 URL。

我应该选择哪种流程？

请参考以下速查指南：

想让手机登录到已有账号 → 添加手机
想让新浏览器、电脑或设备加入已有账号 → 恢复账号
想让 CLI 或终端完成连接 → 扫码连接终端
当前无法扫码 → 手动输入 URL 或 改用密钥恢复