dsh-remote-mobile 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +187 -106
  3. package/README_EN.md +187 -106
  4. package/lib/auth/crypto.js +35 -21
  5. package/lib/auth/gate.js +2 -1
  6. package/lib/auth/token.d.ts +13 -1
  7. package/lib/auth/token.js +53 -20
  8. package/lib/client.js +171 -89
  9. package/lib/index.d.ts +1 -1
  10. package/lib/index.js +1 -1
  11. package/lib/routes/api.js +8 -2
  12. package/lib/routes/login-page.js +54 -12
  13. package/package.json +7 -3
  14. package/lib/types/auth.d.ts +0 -49
  15. package/lib/types/auth.js +0 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.2.0] - 2026-08-22
9
+
10
+ ### Security & Cryptography (安全与加密)
11
+ - **Web Crypto 原生 OAEP 与 CSPRNG 增强**：手机登录页在现代浏览器/安全上下文中优先使用原生 `window.crypto.subtle.encrypt({ name: 'RSA-OAEP' })` 进行 2048 位 RSA 加密；回退纯 JS 垫片中使用 `crypto.getRandomValues()` 进行密码学安全随机填充。
12
+ - **URL Token 验证行为安全收敛**：移除从 URL `?token=xxx` 自动发起 `verify` 的逻辑，改为仅回填输入框，杜绝社工链接消耗受害者失败配额的间接 DoS 风险。
13
+ - **智能静态扩展名放行机制**：收敛 `/plugins/` 门禁放行规则为合法前端静态扩展名白名单（`.js`, `.css`, `.png`, `.svg`, `.woff2`, `.map` 等 20+ 种），彻底堵死未授权调用第三方插件后台动态 API 的漏洞，对用户零负担、免手动维护。
14
+
15
+ ### Robustness & Performance (健壮性与性能)
16
+ - **写盘分级与 Debounce 防抖**：拆分写盘策略，高频访问记录（`recordAuthVisit`、活跃时间戳更新）引入 500ms 防抖合并；关键路径（配对成功、密码认证、撤销、改密）保持同步即时写盘；配套 `beforeExit` 广播与 `flushPersistedData` 保证进程退出不丢数据。
17
+ - **配置一致性与反向覆盖防御**：`loadPersistedData` 完全移除对历史 `devices.json` 中 `data.config` 的读取，确保 `~/.dsh/settings.yaml` 为唯一配置权威来源，杜绝重启时的配置回滚。
18
+ - **YAML 原子性持久化**：`writeBackToSettingsYaml` 引入临时文件原子替换（`renameSync`），防止异常中断导致 `settings.yaml` 文件半写损坏。
19
+ - **RSA 密钥按需懒加载**：移除模块顶层同步生成密钥逻辑，改为在首次调用时懒加载单例，消除启动阻塞。
20
+ - **SSE 幂等注销与双向 Close 监听**：优化服务端 SSE 事件通道，同时监听 `req.on('close')` 与 `res.on('close')`，引入 `cleanup()` 幂等保护，杜绝监听器与定时器泄漏。
21
+
22
+ ### Testing & Code Hygiene (测试与代码清理)
23
+ - **测试覆盖率提升**：新增 5 项边缘场景测试用例（含设备撤销审计归因回退、URL Token 提取、data.config 忽略防覆盖、高频写盘防抖、SSE 幂等断连清理），全套测试扩展至 66 项并全部通过。
24
+ - **冗余代码清理**：移除已废弃未引用的 `src/types/auth.ts`。
25
+
26
+ ---
27
+
28
+ ## [1.1.0] - 2026-08-22
29
+ - 初始稳定版发布：Tailscale & LAN 免密直连、RSA 端到端加密、6 位动态配对码、加盐哈希密码存储、IP 5次防暴破锁定与 SSE 实时事件推送。
package/README.md CHANGED
@@ -1,99 +1,75 @@
1
- # dsh-remote-mobile
1
+ <div align="center">
2
2
 
3
- [English Documentation](./README_EN.md) | 简体中文
3
+ # dsh-remote-mobile
4
4
 
5
- `dsh-remote-mobile` 是专为 DeepSeek Hub (DSH) 设计的远程与移动端安全接入插件。
5
+ **DeepSeek Harness (DSH) 远程移动端与局域网安全接入插件**
6
6
 
7
- DSH 核心服务默认仅允许本地回环地址（`127.0.0.1`）访问 Web 界面。本项目通过门禁中间件与请求上下文虚拟化机制，安全地开放了 Tailscale 虚拟局域网以及本地局域网（LAN）访问能力，并提供扫码配对、长期密码认证、防暴力破解限频、落盘持久化和 SSE 实时状态推送。
7
+ [![npm version](https://img.shields.io/npm/v/dsh-remote-mobile.svg?style=flat-square&color=3b82f6)](https://www.npmjs.com/package/dsh-remote-mobile)
8
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-remote-mobile.svg?style=flat-square&color=22c55e)](https://www.npmjs.com/package/dsh-remote-mobile)
9
+ [![node](https://img.shields.io/badge/node-%3E%3D18.0.0-8b5cf6?style=flat-square)](https://nodejs.org)
10
+ [![license](https://img.shields.io/npm/l/dsh-remote-mobile.svg?style=flat-square&color=10b981)](https://github.com/IceApriler/dsh-remote-mobile/blob/master/LICENSE)
8
11
 
9
- ---
12
+ <p align="center">
13
+ <b>突破本地限制 · 扫码直连 · 工作区全功能复用 · 传输层加密</b>
14
+ </p>
10
15
 
11
- ## 🌟 主要功能
12
-
13
- ### 1. 网络接入支持
14
- - **Tailscale 虚拟私网**：自动识别本机的 Tailscale IP（`100.64.0.0/10` CGNAT 网段），生成专属访问二维码，支持端到端加密免密直连选项。
15
- - **局域网 (LAN)**：自动识别 RFC 1918 私有 IP（如 `192.168.x.x`、`10.x.x.x`、`172.16-31.x.x`），提供独立的局域网访问二维码与高危醒目警示配置。
16
- - **二维码快速配对**：支持手机相机或微信扫码直接打开登录页面。
16
+ [English Documentation](./README_EN.md) · [简体中文](./README.md)
17
17
 
18
- ### 2. 多重认证机制
19
- - **动态配对码**：生成 6 位短期配对码（5 分钟有效，一次性消费），手机扫码输入后换取 365 天有效期的认证 Cookie。
20
- - **长期访问密码**：支持设置访问密码（需包含字母与数字，长度不小于 6 位），验证成功后同样派发 365 天长效 Cookie。
21
- - **免密直连模式**：可针对 Tailscale 或局域网环境单独开启免密直连。关闭免密后会自动清理临时设备凭证并重置状态。
22
- - **设备会话管理**：实时查看已连接设备的类型、操作系统、浏览器、来源 IP 及最近活跃时间，支持单设备注销与一键全部踢出。
23
-
24
- ### 3. 企业级安全防护
25
- - **传输层加密**：登录认证接口支持 RSA 密钥加密（RSA-OAEP-SHA256 与 PKCS#1 v1.5 兼容），密文在客户端加密后再通过网络传输。
26
- - **慢哈希存储**：服务端采用 `scrypt` 加盐慢哈希算法（`scrypt:${salt}:${hash}`）对密码进行落盘存储，比对过程采用 `crypto.timingSafeEqual` 恒定时间比对以防范时序侧信道攻击。
27
- - **防暴力破解与限频**：
28
- - 连续输错 5 次凭证自动锁定该 IP 15 分钟，拦截后续验证请求并返回 HTTP 429；
29
- - 滑动窗口限频（默认 60 次/分钟），防止高频刷量；
30
- - 访问审计与锁定状态持久化保存，服务重启后自动恢复；
31
- - 支持管理员在面板中手动一键解除 IP 锁定。
32
- - **请求头安全**：仅信任底层 Socket 真实连接地址，防范 `X-Forwarded-For` 伪造。
33
-
34
- ### 4. 实时状态同步与国际化支持
35
- - **SSE 事件通道**：基于 Server-Sent Events 实现新设备配对、重连上线、会话撤销及安全告警的实时通知，无需前端轮询。
36
- - **全界面中英文双语自适应**：根据 DSH 语言偏好设置与浏览器语言，动态自适应中英文面板、提示及手机端登录界面。
37
- - **非 HTTPS 兼容补丁**：自动向 HTML 页面注入 `crypto.randomUUID` Polyfill，解决部分移动端浏览器在 HTTP 非安全上下文下缺少原生 API 的问题。
18
+ <p align="center">
19
+ <a href="#about">这是什么</a> •
20
+ <a href="#advantages">核心优势</a> •
21
+ <a href="#quick-start">快速开始</a> •
22
+ <a href="#config">必备配置</a> •
23
+ <a href="#preview">界面预览</a> •
24
+ <a href="#features">功能特性</a> •
25
+ <a href="#install">安装方式</a> •
26
+ <a href="#faq">常见问题</a>
27
+ </p>
38
28
 
39
29
  ---
40
30
 
41
- ## 🛠️ 安装与前置配置
42
-
43
- ### 步骤 1：安装插件
31
+ </div>
44
32
 
45
- #### 方式 1：通过 DSH 命令行一键安装（推荐）
33
+ <span id="about"></span>
34
+ ## 📖 这是什么
46
35
 
47
- 使用 DSH 内置的插件管理工具直接从 npm 官方仓库安装到 web profile：
36
+ `dsh-remote-mobile` 是专为 **DeepSeek Harness (DSH)** 深度定制的远程与移动端安全治理插件。
48
37
 
49
- ```bash
50
- dsh plugin --profile web add dsh-remote-mobile
51
- ```
38
+ DSH 核心服务出于安全考虑默认仅监听本地回环地址（`127.0.0.1`），手机、平板或其他电脑无法从外部访问 Web 控制台。本项目通过**访问控制中间件**与**请求隔离技术**，安全地开放了 **Tailscale 虚拟私网** 以及 **本地局域网 (Wi-Fi/LAN)** 访问能力，并提供传输加密、扫码配对、长期密码认证与防暴力破解审计体系。
52
39
 
53
- #### 方式 2：通过 Web 设置页「插件管理」图形化安装
40
+ ---
54
41
 
55
- 在浏览器打开 DSH Web 控制台：
56
- 1. 点击左下角 **设置 ⚙️ -> 插件**；
57
- 2. 切换到顶部的 **「插件管理」** Tab；
58
- 3. 在输入框中输入 npm 包名 **`dsh-remote-mobile`**，点击 **「安装」**；
59
- 4. 安装完成后重启 DSH 即可生效。
42
+ <span id="advantages"></span>
43
+ ## ⚡ 核心优势
60
44
 
61
- #### 方式 3：手动在 Profile 目录中通过包管理器安装
45
+ * 🚀 **突破网络壁垒，工作区全功能复用**：解决局域网和 Tailscale 无法访问 DSH Web 的问题。在移动端或外部设备访问时，**支持新建工作区、切换工作区、执行终端命令等桌面端核心功能**。
46
+ * 📱 **手机端与 Web 同源复用**：手机端直接复用 DSH Web 官方同源底座与完整生态插件（如 `dsh-pet` 宠物、任务看板等），后端与服务逻辑保持一致，后期只需按需适配移动端响应式样式即可，无需单独维护手机端后台。
47
+ * 🛡️ **安全门禁与传输加密**：内置 RSA 非对称公钥加密、`scrypt` 加盐慢哈希密码落盘、连续输错自动熔断锁定 IP，拦截公网/局域网未经授权的访问。
48
+ * 📲 **扫码快速配对**：自动识别并生成 Tailscale CGNAT 与局域网专属访问链接与二维码，手机扫码即可完成长效授权。
49
+ * 🔄 **SSE 实时状态推送**：设备上线、下线、注销、IP 锁定等安全事件即时推送，无需前端轮询。
62
50
 
63
- ```bash
64
- # 1. 进入 DSH Web Profile 目录
65
- cd ~/.dsh/profiles/web
51
+ ---
66
52
 
67
- # 2. 通过 pnpm 安装
68
- pnpm add dsh-remote-mobile
53
+ <span id="quick-start"></span>
54
+ ## 🚀 快速开始
69
55
 
70
- # 3. 检查 ~/.dsh/profiles/web/package.json
71
- # 确保 dsh.profile.bundles 数组中已包含 "dsh-remote-mobile"
72
- ```
56
+ ### 1. 一键安装插件
73
57
 
74
- #### 方式 4：本地开发与源码安装
58
+ 在终端执行 DSH 官方插件安装指令（推荐）：
75
59
 
76
60
  ```bash
77
- # 1. 克隆或下载源码至本地目录
78
- cd ~/Myfile/www-self/dsh-remote-mobile
79
-
80
- # 2. 安装依赖并编译打包
81
- npm install
82
- npm run build && npm test && npm pack
83
-
84
- # 3. 在 DSH 中以本地包形式安装
85
- cd ~/.dsh/profiles/web
86
- pnpm add /path/to/dsh-remote-mobile/dsh-remote-mobile-1.0.0.tgz
61
+ dsh plugin --profile web add dsh-remote-mobile
87
62
  ```
88
63
 
89
64
  ---
90
65
 
91
- ### 步骤 2：开放网络监听配置（前置必配）
66
+ <span id="config"></span>
67
+ ### 2. 必备前置配置（开放外部监听）
92
68
 
93
- 由于 DSH 默认出于安全考虑仅监听 `127.0.0.1`（本地回环），为了使 Tailscale 私网或局域网设备能够连通，请在 `~/.dsh/profiles/web/cordis.patch.yml` 中确保包含以下配置：
69
+ 由于 DSH 默认仅监听 `127.0.0.1`，为了使 Tailscale 私网或局域网设备能够正常连通，请确保在 `~/.dsh/profiles/web/cordis.patch.yml` 中包含以下配置：
94
70
 
95
71
  ```yaml
96
- # 1. 覆盖 webserver 配置监听 0.0.0.0:3080（必选：允许接收外部连接）
72
+ # 1. 允许 webserver 监听外部网络连接（必选）
97
73
  - id: webserver
98
74
  name: '@deepseek-ai/dsh-host-webserver'
99
75
  inject: [webStartup]
@@ -101,71 +77,122 @@ pnpm add /path/to/dsh-remote-mobile/dsh-remote-mobile-1.0.0.tgz
101
77
  host: '0.0.0.0'
102
78
  port: 3080
103
79
 
104
- # 2. 禁用 @linxin666/dsh-web-ui-all 全家桶自带的远程插件（必选：防止路由冲突与界面覆盖）
80
+ # 2. 禁用 @linxin666/dsh-web-ui-all 内置的远程插件（必选：防止功能冲突）
105
81
  - id: web-ui-remote-web-ui
106
82
  disabled: true
107
83
  ```
108
84
 
109
- > **💡 说明**：插件自身的注册已由 DSH Bundle 自动处理，**无需**在 `cordis.patch.yml` 中额外添加 `id: remote-mobile`。
85
+ > **💡 说明**：插件自身注册已由 DSH Bundle 体系全自动处理，**无需**在 `cordis.patch.yml` 中额外添加 `id: remote-mobile`。
110
86
 
111
87
  ---
112
88
 
113
- ### 步骤 3：启动服务
89
+ ### 3. 启动并使用
114
90
 
115
91
  ```bash
116
- dsh web
92
+ dsh web --no-open
117
93
  ```
118
94
 
119
- 启动后，在 PC 端浏览器打开 `http://127.0.0.1:3080`，进入 **设置 ⚙️ -> 远程与移动端 (Remote & Mobile)** 即可查看配对二维码或配置访问密码。
95
+ 启动后，在电脑浏览器打开 DSH Web 控制台，进入 **设置 ⚙️ -> 远程与移动端**，使用手机微信或系统相机扫描二维码即可立即开启移动端接入！
120
96
 
121
97
  ---
122
98
 
123
- ## ⚙️ 配置项说明
99
+ <span id="preview"></span>
100
+ ## 🖼️ 界面预览
124
101
 
125
- 在 `~/.dsh/settings.yaml` 中可配置插件参数（**推荐直接在 Web 面板中可视化调整**，修改后自动写回持久化）：
102
+ ### PC 端 DSH 插件控制面板
126
103
 
127
- ```yaml
128
- dsh-remote-mobile:
129
- # 免密直连开关
130
- allowTailscale: true # boolean，默认 false：Tailscale 节点访问是否免密
131
- allowLan: false # boolean，默认 false：局域网 (Wi-Fi) 设备访问是否免密
104
+ | 网络接入与扫码配对 | 长期密码、设备会话与 IP 防暴破审计 |
105
+ | :---: | :---: |
106
+ | ![PC 设置面板 - 网络与配对码](images/pc-dsh-setting-1.png) | ![PC 设置面板 - 密码与设备管理](images/pc-dsh-setting-2.png) |
132
107
 
133
- # 长期访问密码哈希（在面板中输入明文会自动生成加盐哈希保存）
134
- secretHash: '' # string，默认空
108
+ ---
135
109
 
136
- # 全局高级安全防护参数
137
- maxVisitsPerMinute: 60 # number，默认 60：单 IP 每分钟打开 /auth 页面最大允许次数
138
- maxFailedAttempts: 5 # number，默认 5：密码连续输错阈值
139
- lockDurationMs: 900000 # number，默认 900000 (15分钟)：IP 锁定持续时间（毫秒）
140
- ```
110
+ ### 手机端实机演示（同源免登与工作区全功能）
141
111
 
142
- | 配置项 | 类型 | 默认值 | 说明 |
143
- |---|---|---|---|
144
- | `allowTailscale` | `boolean` | `false` | 是否允许 Tailscale 私网 IP 免密访问 |
145
- | `allowLan` | `boolean` | `false` | 是否允许局域网私有 IP 免密访问（高危警示） |
146
- | `secretHash` | `string` | `""` | 长期密码的 scrypt 加盐哈希值 |
147
- | `maxVisitsPerMinute` | `number` | `60` | 单 IP 每分钟最大访问登录页次数 |
148
- | `maxFailedAttempts` | `number` | `5` | 连续认证失败最大次数（达到后自动封锁 IP） |
149
- | `lockDurationMs` | `number` | `900000` | 触发防暴破后的 IP 锁定时间（毫秒） |
112
+ | 手机扫码授权登录页 | 手机端完整控制 DSH 工作区与操作 |
113
+ | :---: | :---: |
114
+ | ![手机端授权登录页](images/mobile-auth.jpg) | ![手机端控制 DSH 工作区](images/mobile-dsh.jpg) |
150
115
 
151
116
  ---
152
117
 
153
- ## 📂 本地文件存储位置
118
+ <span id="features"></span>
119
+ ## 🌟 功能特性
154
120
 
155
- - **设备会话与安全审计数据**：`~/.dsh/remote-mobile/devices.json`
156
- - **RSA 传输加密密钥对**：`~/.dsh/remote-mobile/rsa-keys.json`（权限模式为 `0600`，首次启动自动就地生成）
121
+ ### 1. 网络接入支持
122
+ - **Tailscale 虚拟私网**：自动识别本机 Tailscale IP（`100.64.0.0/10` CGNAT 网段），生成专属访问二维码，支持开启免密直连（底层传输加密由 Tailscale WireGuard 隧道保障）。
123
+ - **本地局域网 (LAN / Wi-Fi)**：自动识别 RFC 1918 私有 IP（如 `192.168.x.x`、`10.x.x.x`、`172.16-31.x.x`），提供局域网专属二维码与直达链接预览，附带醒目的高危风险提示。
124
+ - **二维码快速配对**：支持手机相机或微信扫码直达授权页面。
125
+
126
+ ### 2. 多重认证机制
127
+ - **动态 6 位配对码**：生成 6 位短期配对码（5 分钟有效，一次性使用），手机端扫码输入后换取 365 天有效期的安全认证 Cookie。
128
+ - **长期访问密码**：支持设置自定义长期访问密码（长度需至少 6 位且含字母与数字），便于多设备长期固定登录。
129
+ - **免密直连模式**：可针对 Tailscale 或局域网环境单独切换免密直连。关闭免密直连后会自动清理临时设备凭证并重置状态。
130
+ - **设备会话管理**：实时查看已连接设备的类型、操作系统、浏览器、来源 IP 及最近活跃时间，支持单设备注销与一键注销全部设备。
131
+
132
+ ### 3. 安全防护
133
+ - **传输层 RSA 非对称加密**：登录认证接口支持客户端 RSA 加密。在 HTTPS 等安全上下文下优先使用 Web Crypto 原生 `RSA-OAEP-SHA256`；在 DSH 默认的 HTTP 局域网/Tailscale 访问（非安全上下文）下回退至纯 JS 垫片，并使用 `crypto.getRandomValues()` 进行密码学安全随机数填充。敏感密码与配对码在客户端加密后再通过网络传输。
134
+ - **scrypt 慢哈希存储**：服务端采用 `scrypt` 加盐慢哈希算法（`scrypt:${salt}:${hash}`）对密码进行落盘存储，比对过程采用 `crypto.timingSafeEqual` 恒定时间比较以防范时序侧信道攻击。
135
+ - **防暴力破解与限频保护**：
136
+ - 连续输错凭证达到阈值（默认 5 次）自动锁定该 IP 15 分钟，拦截后续验证请求并返回 HTTP 429；
137
+ - 滑动窗口限频（默认 60 次/分钟），防范高频恶意刷量探测；
138
+ - 访问审计与锁定状态持久化落盘，服务重启后自动恢复；
139
+ - 支持管理员在管理面板中一键解锁指定 IP。
140
+ - **智能静态资源放行机制**：安全门禁内置智能前端静态扩展名识别（放行 `.js`、`.css`、`.png`、`.svg`、`.woff2` 等 20+ 种合法资源），彻底拦截无扩展名或动态管理 API 请求（如 `/plugins/xxx/admin`），确保第三方生态插件前端正常展示的同时严密保护后台动态接口，无需用户在设置界面手动维护白名单。
141
+ - **高可靠原子持久化与防抖**：采用 500ms 写盘防抖节流保护磁盘 I/O，配合 `beforeExit` 进程退出 Flush 保证数据不丢失；配置文件采用临时文件原子替换（`renameSync`），防止异常中断损坏数据。
142
+ - **真实 IP 安全提取**：仅信任底层 Socket 真实连接地址，防范伪造的 `X-Forwarded-For` 欺骗攻击。
143
+
144
+ ### 4. 实时状态同步与国际化
145
+ - **SSE 实时事件推送**：基于 Server-Sent Events 实现新设备接入、设备重连、会话撤销及安全告警的实时通知，内置连接双向关闭监听与幂等清理。
146
+ - **全界面中英文双语自适应**：根据 DSH 全局语言偏好与浏览器环境，动态自适应中英文面板、提示及手机端界面。
147
+ - **非 HTTPS 兼容补丁**：自动注入 `crypto.randomUUID` Polyfill，解决移动端浏览器在 HTTP 非安全上下文下缺少原生 API 的报错。
157
148
 
158
149
  ---
159
150
 
160
- ## 🔒 安全建议
151
+ <span id="install"></span>
152
+ ## 📦 全部安装方式
161
153
 
162
- 1. **局域网免密风险**：若在公共 Wi-Fi、咖啡厅或共享网络环境下使用，**严禁开启 `allowLan`（局域网免密直连）**。
163
- 2. **Tailscale 推荐**：建议优先配合 Tailscale 虚拟专用网络使用，既能保障公网不可达，又能获得端到端加密传输保障。
164
- 3. **密码复杂度**：若使用长期密码，建议设置包含字母与数字且 6 位以上的高强度密码。
154
+ <details>
155
+ <summary><b>展开查看全部 4 种安装方式</b></summary>
165
156
 
166
- ---
157
+ ### 方式 1：通过 DSH 命令行一键安装（最推荐）
158
+ ```bash
159
+ dsh plugin --profile web add dsh-remote-mobile
160
+ ```
167
161
 
168
- ## 🗑️ 卸载插件
162
+ ### 方式 2：通过 Web 设置页「插件管理」图形化安装
163
+ 1. 在浏览器打开 DSH Web 控制台；
164
+ 2. 点击左下角 **设置 ⚙️ -> 插件**；
165
+ 3. 切换到顶部的 **「插件管理」** Tab；
166
+ 4. 在输入框中输入 npm 包名 **`dsh-remote-mobile`**，点击 **「安装」**；
167
+ 5. 安装完成后重启 DSH 即可生效。
168
+
169
+ ### 方式 3：在 Profile 目录中通过包管理器安装
170
+ ```bash
171
+ # 1. 进入 DSH Web Profile 目录
172
+ cd ~/.dsh/profiles/web
173
+
174
+ # 2. 通过 pnpm 安装
175
+ pnpm add dsh-remote-mobile
176
+ ```
177
+
178
+ ### 方式 4：本地源码开发与调试（软链接即时生效）
179
+ ```bash
180
+ # 1. 克隆代码至本地
181
+ git clone https://github.com/IceApriler/dsh-remote-mobile.git
182
+ cd dsh-remote-mobile
183
+
184
+ # 2. 安装依赖并编译打包
185
+ npm install
186
+ npm run build
187
+
188
+ # 3. 建立软链接到 DSH 运行环境（开发修改后 npm run build 即时生效）
189
+ rm -rf ~/.dsh/profiles/web/node_modules/dsh-remote-mobile
190
+ ln -s $(pwd) ~/.dsh/profiles/web/node_modules/dsh-remote-mobile
191
+ ```
192
+
193
+ </details>
194
+
195
+ ### 卸载插件
169
196
 
170
197
  ```bash
171
198
  dsh plugin --profile web remove dsh-remote-mobile
@@ -173,6 +200,60 @@ dsh plugin --profile web remove dsh-remote-mobile
173
200
 
174
201
  ---
175
202
 
176
- ## 📄 开源许可
203
+ ## ⚙️ 高级配置
204
+
205
+ 插件已完全接入 DSH 官方 Settings 体系，配置项支持在 Web 界面中直观调整，也可在 `~/.dsh/settings.yaml` 的 `dsh-remote-mobile` 命名空间下手动修改：
206
+
207
+ ```yaml
208
+ dsh-remote-mobile:
209
+ allowTailscale: false # boolean，默认 false：是否允许 Tailscale 虚拟私网免密访问
210
+ allowLan: false # boolean，默认 false：是否允许局域网免密访问（高危警示）
211
+ secretHash: "" # string，默认空：长期访问密码的 scrypt 加盐哈希值
212
+ maxVisitsPerMinute: 60 # number，默认 60：单 IP 每分钟最大访问登录页次数
213
+ maxFailedAttempts: 5 # number，默认 5：触发封禁的连续认证失败最大次数
214
+ lockDurationMs: 900000 # number，默认 900000 (15分钟)：IP 锁定持续时间（毫秒）
215
+ ```
216
+
217
+ ---
218
+
219
+ ## 📂 本地文件存储位置
220
+
221
+ | 文件路径 | 说明 | 安全级别 |
222
+ |---|---|---|
223
+ | `~/.dsh/settings.yaml` | 全局安全策略与免密开关配置 | 用户级读写 |
224
+ | `~/.dsh/remote-mobile/devices.json` | 已授权设备会话、IP 访问计数与安全审计数据 | 本地落盘持久化 |
225
+ | `~/.dsh/remote-mobile/rsa-keys.json` | 服务端 RSA 密钥对文件（含公钥与私钥） | 本地落盘，权限 `0o600`（仅当前用户可读写） |
226
+
227
+ ---
228
+
229
+ <span id="faq"></span>
230
+ ## ❓ 常见问题 (FAQ)
231
+
232
+ <details>
233
+ <summary><b>Q1: 手机扫码后提示「连接被拒绝」或无法打开页面？</b></summary>
234
+
235
+ **答**：请检查以下三项：
236
+ 1. 确保电脑上的 `cordis.patch.yml` 中已配置 `host: '0.0.0.0'`，且 DSH 已经重启；
237
+ 2. 局域网访问时，确保手机与电脑连接在同一个 Wi-Fi / 路由器下；
238
+ 3. 如果开启了电脑操作系统自带的防火墙，请确保允许入站访问 `3080` 端口。
239
+ </details>
240
+
241
+ <details>
242
+ <summary><b>Q2: Tailscale 免密直连和局域网免密有什么区别？</b></summary>
243
+
244
+ **答**：
245
+ * **Tailscale 免密**：高度安全。因为 Tailscale 是基于 WireGuard 的传输加密虚拟私网，只有你自己登录了同一账号的设备才能连通。
246
+ * **局域网免密**：存在安全隐患。任何连入你家 Wi-Fi 的设备（包括访客或蹭网设备）均可直接控制你的工作区，因此非完全可信环境**切勿开启**。
247
+ </details>
248
+
249
+ <details>
250
+ <summary><b>Q3: 手机端切换或新建工作区能正常使用吗？</b></summary>
251
+
252
+ **答**：**支持**。本插件通过请求隔离技术，使手机端与 PC 桌面端拥有一致的工作区管理与执行能力。
253
+ </details>
254
+
255
+ ---
256
+
257
+ ## 📄 开源许可证
177
258
 
178
- [MIT License](./LICENSE)
259
+ 本项目采用 [MIT License](LICENSE) 协议开源。