dsh-plugin-mobile-gateway

让 iPhone 通过经过设备鉴权的 WebSocket 连接 DeepSeek Harness。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。

• WebSocket：/ws/mobile
• 局域网：ws://<局域网 IP>:3081/ws/mobile
• Linux 服务器公网：wss://<公网 IP>/ws/mobile
• 协议文档：PROTOCOL.md

配套 iOS 客户端

DeepSeek Harness Mobile 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、工作区内创建文件夹、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop、模型与权限设置。

工作区首页	实时对话	设备配对

安装插件

前提：已经安装 dsh CLI 和 pnpm，并能正常启动 dsh web。可先执行 pnpm --version 确认当前用户的环境能够找到 pnpm。

局域网使用只需安装插件：

dsh plugin --profile web add dsh-plugin-mobile-gateway@latest

需要在 Linux 服务器通过公网 IP 接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：

npx --yes dsh-plugin-mobile-gateway@latest init

init 会把当前正在执行的 npm 包精确版本安装到 DSH profile，并仅对该版本跳过 pnpm 的新版本等待期，确保插件与 Helper 版本一致。

安装后停止并重新启动 WebUI：

dsh web

打开 WebUI，确认左侧边栏底部出现“移动设备”。

局域网配对

适用于 DSH 电脑和 iPhone 位于同一个可互访的局域网。

1. 打开 WebUI 的“移动设备”。
2. 开启“允许移动设备连接”。
3. 保持“设备鉴权”开启。
4. 确认面板显示 ws://<电脑局域网 IP>:3081/ws/mobile。
5. 填写设备名称并点击“生成配对二维码”。
6. 在 iOS 客户端打开“设备认证”，扫描二维码。
7. WebUI 的可信设备显示“在线”后即完成。

如果系统防火墙拦截连接，只允许私有网络访问 TCP 3081。不要把 3081 开放到公网。

Linux 服务器公网 IP 配对

[!NOTE]
本文所说的“公网 IP 配对”特指 Linux 服务器。一键公网安装从 v0.6.4 开始提供，适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器。服务器需要已经安装 Node.js、pnpm 和 dsh CLI；当前尚不支持 CentOS。

1. 准备公网端口

在云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP 80 和 443。不要将 DSH WebUI 端口或 TCP 3081 开放到公网。

2. 一键初始化

先确认普通 DSH 用户可以直接调用 pnpm：

pnpm --version

然后使用同一个普通用户执行（不要使用 root 或 sudo npx）：

npm_config_registry=https://registry.npmjs.org \
npx --yes dsh-plugin-mobile-gateway@latest init

该命令会安装或更新插件，并请求一次 sudo 权限安装 Nginx、Certbot、系统 Helper 和证书续期定时器。init 会确保 DSH profile 与 Helper 使用同一个精确版本。

完成后启动或重新启动 WebUI：

dsh web

3. 打开远程 WebUI

优先使用 VS Code、Cursor 等 IDE 自带的端口转发。也可以在自己的电脑执行：

ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服务器公网 IP>

然后在本地浏览器打开：

http://127.0.0.1:<本地端口>

4. 在 UI 配置公网入口

打开左侧的“移动设备”，在“公网接入”填写云厂商控制台提供的公网 IPv4，然后点击“配置公网接入”或“更新公网配置”。Helper 会自动读取当前 dsh web 端口并配置 Nginx、TLS 证书和 wss://<公网 IP>/ws/mobile。

5. 配对移动设备

1. 开启“允许移动设备连接”，保持“设备鉴权”开启。
2. 填写设备名称并点击“生成配对二维码”。
3. iPhone 打开“设备认证”并扫描二维码。
4. WebUI 的可信设备显示“在线”后即完成。

二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。

Windows / macOS 家用电脑远程连接

家用电脑通常没有固定公网 IP，不建议配置路由器端口转发。可以使用 Tailscale 长期连接，或使用 Cloudflare Quick Tunnel 临时调试。两种方式都转发到插件专用的 3081 端口，不会公开 DSH WebUI。

使用前先启动 dsh web，并在“移动设备”面板开启“允许移动设备连接”和“设备鉴权”。

Tailscale（推荐长期使用）

1. 在电脑和 iPhone 安装 Tailscale，并登录同一个 Tailnet。
2. 在 Windows PowerShell 或 macOS 终端执行：

tailscale serve --bg 3081

3. 执行 tailscale serve status 查看生成的 https://<设备名>.<tailnet>.ts.net 地址。
4. 将地址改为 wss://<设备名>.<tailnet>.ts.net/ws/mobile，填入 WebUI 的“WebSocket 地址”，再生成二维码配对。

Tailscale Serve 只允许同一 Tailnet 中符合访问规则的设备连接，并自动提供 HTTPS。可用 tailscale serve reset 停止转发。参见 Tailscale Serve 文档。

Cloudflare Quick Tunnel（仅临时调试）

1. 安装 cloudflared。
2. 在 Windows PowerShell 或 macOS 终端执行：

cloudflared tunnel --url http://127.0.0.1:3081

3. 命令行会显示随机的 https://<随机名称>.trycloudflare.com 地址。
4. 将地址改为 wss://<随机名称>.trycloudflare.com/ws/mobile，填入 WebUI 的“WebSocket 地址”，再生成二维码配对。

保持该命令运行；停止命令后隧道立即失效。Quick Tunnel 的地址每次可能变化，且没有可用性保证，不适合正式或长期使用。公网调试时必须保持“设备鉴权”开启。参见 Cloudflare Quick Tunnel 文档。

网关配置方式总览

Linux 服务器公网入口管理

查看状态：

sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest status

移除公网入口：

sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove

更新插件

重新运行初始化命令会同时更新插件和系统 Helper：

npx --yes dsh-plugin-mobile-gateway@latest init

随后停止并重新启动 dsh web。

卸载插件

dsh plugin --profile web remove dsh-plugin-mobile-gateway

如需同时移除系统 Helper（不会删除现有 Nginx 公网配置）：

sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove-helper

常见问题

源码开发

dsh plugin --profile web add file:/absolute/path/to/dsh-plugin-mobile-gateway
npm test

源码修改后需要重新安装插件并重启 dsh web。