<!-- 文档分类: OPS-MAN-030 | 阶段: 运维 | 原路径: docs/指南/移动端远程指南.md -->
# KHY Remote — 移动端连接指南

通过基于网页的界面，用手机远程控制 KHY-OS AI 助手。

---

## 先选路：`khy mobile` 还是 `khy bridge`？

KHY 有**两条**手机访问路径，先按需求选：

| | `khy mobile`（推荐，最省心） | `khy bridge`（高级，本指南主线） |
| --- | --- | --- |
| 做什么 | 在终端打印一个**二维码**，手机扫码直达网关管理/对话页 | 启动一个带鉴权的远程控制 bridge 服务 |
| 端口 | `:9090`（网关管理页，默认入口 `/admin/ai-gateway`） | `:9222` |
| 鉴权 | 跟随网关自身（无独立账号体系） | PIN / 账号 JWT（见下文） |
| 是否起服务 | 否，纯展示二维码（指向已运行的网关页） | 是，`khy bridge start` 起独立服务 |
| 适合 | 同一 Wi-Fi 下「我自己掏出手机看一眼/操作」 | 需要账号体系、公网部署、权限审批的远程控制 |

```bash
# 最简单：扫码即用（要求网关已在运行）
khy mobile
```

> 只是想用手机快速连一下，用 `khy mobile` 即可。需要账号登录、权限审批卡片、公网部署，再看下面的 `khy bridge` 完整流程。

---

## 快速开始

### 1. 获取连接信息

bridge 服务启动后，CLI 会显示：

```
📱 Mobile: http://192.168.x.x:9222/  PIN: 836201
```

- **URL** — 在手机上打开的地址
- **PIN** — 6 位管理员快捷码（有效期 30 分钟）

你也可以随时查看：

```bash
khy bridge status
```

### 2. 从手机连接

1. 确保手机和电脑处于**同一 Wi-Fi 网络**（LAN 模式），或者在部署到服务器后使用公网 URL
2. 在手机浏览器（Safari / Chrome）中打开该 URL
3. 收藏或添加到主屏幕以便快速访问

### 3. 注册与登录

移动端页面有两种认证方式：

#### 账号登录（推荐）

首次使用：

1. 点击 **Register** 标签
2. 输入用户名（2-20 个字符，支持字母/数字/中文）
3. 输入密码（至少 6 个字符）
4. 确认密码
5. 点击 **Register** — 成功后自动登录

老用户：

1. 停留在 **Login** 标签
2. 输入用户名和密码
3. 点击 **Login**

会话保持 7 天 — 刷新页面会自动重连，无需重新登录。

#### 管理员 PIN 登录

无需注册即可快速获得管理员访问权限：

1. 点击底部的 **Admin PIN Login**
2. 输入 CLI 中显示的 6 位 PIN
3. 点击 **Connect**

PIN 在 30 分钟后过期。生成新的 PIN：

```bash
khy bridge token
```

---

## 使用远程控制台

登录后，你会看到远程控制界面：

| 区域 | 功能 |
|------|------|
| **Header** | 连接状态（绿点 = 已连接）、登出按钮 |
| **Transcript** | 实时 AI 对话输出、工具调用、思考过程 |
| **Input bar** | 输入命令，按 Enter 或点击发送 |

### 发送命令

- 在输入栏中输入并点击发送箭头（或按 Enter）
- 命令会发送到本地 KHY CLI，并像直接输入一样执行
- AI 响应实时流式返回

### 权限请求

当 AI 需要执行有风险的操作时：

- 会出现一张黄色的审批卡片，显示工具名称和输入
- 点击 **Allow** 或 **Deny** 来响应
- 会播放提示音以提醒你

### 提示

- **横屏模式**：界面会自动适配横向方向
- **键盘处理**：布局会适配 iOS/Android 虚拟键盘
- **自动滚动**：Transcript 会滚动到最新输出；向上滚动可暂停，向下滚回即可恢复
- **登出**：点击 Header 中的登出按钮即可返回登录界面

---

## 连接模式

### LAN（局域网）

默认模式 — 手机和电脑处于同一 Wi-Fi。

```
http://192.168.x.x:9222/
```

无需部署服务器。执行 `khy bridge start` 后即刻可用。

### 公网服务器

部署到带域名的服务器后：

```
https://ai.khyquant.top/remote/
```

可从任何地方访问。需要：
- 服务器部署（`khy deploy`）
- 配置好的 Nginx 反向代理
- SSL 证书（推荐）

部署说明请参阅 [部署指南-域名.md](../06_DEPLOY_部署/%5BDEPLOY-MAN-016%5D%20部署指南-域名.md)。

---

## 故障排查

### 页面无法加载

| 现象 | 解决方法 |
|---------|-----|
| Connection refused | 检查 bridge 是否在运行：`khy bridge status` |
| Timeout | 确认手机和电脑处于同一网络 |
| ERR_CONNECTION_RESET | 防火墙可能拦截了端口 9222 |

### 登录问题

| 现象 | 解决方法 |
|---------|-----|
| "Username or password incorrect" | 检查凭据；密码区分大小写 |
| "Username already exists" | 换一个用户名 |
| PIN 过期 | 运行 `khy bridge token` 获取新 PIN |
| 刷新后自动登录失败 | JWT 可能已过期（7 天上限）；请重新登录 |

### WebSocket 断连

- 断开连接时，页面每 3 秒自动重连一次
- 如果 CLI 重启，页面会自动重连
- 绿点 = 已连接，红点 = 已断开，黄点 = 认证中

### iOS 专属

- **添加到主屏幕**：Safari → 分享 → 添加到主屏幕（以独立应用形式运行）
- **键盘遮挡**：使用 `visualViewport` API 正确调整布局
- **刘海屏**：自动处理安全区域内边距

### Android 专属

- **Chrome**：效果最佳；支持添加到主屏幕
- **Samsung Internet**：完全支持
- **键盘**：虚拟键盘出现时自动调整布局

---

## 安全说明

> ⚠️ **务必先改默认管理员口令。** bridge 首次启动会自动播种一个出厂默认管理员账号 **`admin05` / `012003`**（`services/backend/src/services/bridge/bridgeAuth.js`，无环境变量开关、非测试专用）。任何能访问到 `:9222` 的人都可能用它登录。**第一次使用就请注册你自己的账号并停用/修改默认账号**，公网部署尤其如此。

- **密码**使用 bcrypt（10 轮）哈希，并存储在服务器本地
- **JWT 会话**在 7 天后过期；token 存储在 `sessionStorage` 中（浏览器标签页关闭时清除）
- **PIN 码 / 临时 token**在 30 分钟后过期，仅用于管理员快速访问
- **HTTPS** 强烈建议用于公网部署，以加密流量
- 用户数据库位置：`backend/data/bridge-users.db`
