@dsh/remote-control

DSH Web 远程控制插件：在设置面板新增「远程控制」页，开启后通过 Node 反向代理把本机 DSH WebUI 暴露给局域网，页面显示局域网 IP 列表与二维码，手机扫码即可访问；未授权设备一律拦截。

功能

功能一：设置面板「远程控制」页

设置面板「插件」选项下方新增「远程控制」页（仅电脑端显示）：

• 「允许局域网访问」开关，开启后自动探测并列出本机局域网 IPv4 地址，多网卡时可切换选中；
• 二维码随选中地址实时生成：内置纯 JS QR 编码器（Byte 模式、ECC-M、版本 1~10），无第三方依赖、离线可用；
• 二维码每 60 秒自动刷新，旧码立即失效（上一 token 保留 60 秒容忍期，避免边界竞态）；
• 已授权设备白名单：显示设备名（按 User-Agent 解析，如 iPhone · Safari）、IP、授权与最近活跃时间，可单独移除；
• 开关状态仅存于宿主进程内存，重启 dsh 后默认关闭；设备白名单持久化在 ~/.dsh/remote-control/devices.json，重启后已授权设备免重新扫码。

功能二：扫码验签

• 非本机（127.0.0.1 / localhost）来源访问必须扫码授权：二维码 URL 携带一次性验签 token（?rcnt_t=<token>），token 校验通过后签发 rcnt_auth Cookie 并跳转到干净地址，后续请求凭 Cookie 放行；
• 已授权设备不受二维码刷新影响（凭 Cookie 持续访问，最长 7 天；关闭开关后新设备不再放行，白名单可随时移除设备）；
• 未授权直接访问返回 403 提示页（含 WebSocket 握手拦截）；
• 本机 localhost / 127.0.0.1 访问直连 DSH，不受影响；本机用局域网 IP 访问同样需要扫码（来源非回环，属「非本机」访问）；
• 白名单上限 32 台，超出自动移除最早授权的设备；
• 测试钩子：环境变量 RC_NO_LOOPBACK=1 强制所有来源（含本机回环）验签，仅用于本地集成测试，生产不要设置。

功能三：反向代理与兼容性处理

• 独立 Node 子进程监听 0.0.0.0:<端口>，将请求转发到 127.0.0.1:<端口>，并把 Host/Origin 头改写为 loopback，绕过 DSH /api 浏览器信任篱笆（CLI 出于安全禁止 --host 0.0.0.0，运行时绑定不可改，故用代理旁路）；
• 手机经 http://<局域网IP>:<端口> 访问时处于非安全上下文，crypto.randomUUID 不可用，代理在 HTML 响应中自动注入 polyfill；
• 代理子进程生命周期绑定插件：卸载即自动终止。

功能四：Windows 防火墙自动放行

• Windows 下开启时自动创建并复用「DSH Remote Control」入站规则（TCP），无需手动配置；
• 无管理员权限导致创建失败时，页面给出提示与手动放行指引，失败不影响代理本身启动；非 Windows 平台自动跳过。

安装

前置要求：本机已安装 dsh 与 pnpm（dsh plugin 通过 pnpm 安装插件）。

GitHub 直装

dsh plugin --profile web add "git+https://github.com/hw-cola/dsh-remote-control.git"

钉到指定版本（按 tag 锁定）：

dsh plugin --profile web add "git+https://github.com/hw-cola/dsh-remote-control.git#v1.0.0"

本地开发

dsh plugin --profile web add "link:${PATH}/dsh-remote-control"

${PATH}为下载源码的路径

更新

dsh plugin --profile web update @dsh/remote-control

若 pnpm 对 git 依赖的更新不生效，先卸载再重新安装：

dsh plugin --profile web remove @dsh/remote-control
dsh plugin --profile web add "git+https://github.com/hw-cola/dsh-remote-control.git"

卸载

dsh plugin --profile web remove @dsh/remote-control

安装后请重启 dsh web（让插件的 cordis 补丁层生效）并刷新浏览器页面；卸载后刷新页面即可恢复原生布局。

卸载会终止代理子进程；设备白名单文件（~/.dsh/remote-control/devices.json）不会自动删除，需要时手动清理。

安全提醒

验签防的是「局域网内未扫码直接访问」：通信仍是 HTTP 明文，同网段可嗅探 token/Cookie，已授权设备之间等价共享访问权；DSH WebUI 本身无登录认证。请仅在可信网络中使用，用毕务必关闭。

兼容性：插件在 DSH 0.1.1-rc.2 上开发测试。客户端 API 仍在迭代，DSH 大版本升级后若功能异常，请检查本仓库是否有对应适配版本。