手机访问 Hongjun1-RGB/dsh-phone-access

dsh-phone-access

在 DSH 界面里拨一个开关，手机浏览器就能接着当前会话用 —— 同一个进程、同一个会话，两端消息实时同步。

┌─────────┐ 临时隧道 ┌──────────────┐ ┌─────────────┐ │ 手机 │ ─────────────▶ │ 本地代理 │ ──────▶ │ DSH 本体 │ │ 浏览器 │ trycloudflare │ （插件内起） │ loopback│ （你正在用）│ └─────────┘ └──────────────┘ └─────────────┘

它解决什么问题

想从外面访问家里的 DSH，通常卡在三件事上：

1. 绑不了 0.0.0.0 —— DSH 出于安全只允许 127.0.0.1 / 0.0.0.0，而后者会把「能执行任意命令的界面」暴露给整个局域网。
2. /api 的 Host 信任栅栏 —— 只放行 loopback 或配置里声明过的域名，而隧道域名每次都是随机的，无法预先声明。
3. 主连接是 WebSocket —— 普通反向代理不处理升级握手，界面会一直停在「重新连接中」。

本插件的做法：在本地起一个只监听 127.0.0.1 的微型反向代理，把转发给 DSH 的 Host 改写成 loopback（栅栏于是放行），剥掉 Origin / Sec-Fetch-（避免被判为跨站），并原样透传 WebSocket 升级。DSH 始终只监听本机，不开任何入站端口。

界面

开关长在鲸鱼娘插件上（如果装了 dsh-whale-widget）：

- 点鲸鱼娘的 ☰ 设置菜单 → 多一行 「手机访问」，带拨动开关和一个小齿轮；
- 点击后开关立刻到位并保持，鲸鱼开始转圈表示加载；
- 彻底开好之后鲸鱼身后亮起圆形绿色呼吸光晕；
- 点那一行右边的 ⚙ 打开推送设置（见下）；
- 没装鲸鱼插件时，回退成自带的小鲸鱼图标（可拖动，右键打开推送设置）。

安装

dsh plugin add dsh-phone-access

装好后重启 DSH，开关即出现。

配置

推送：直接在界面里填（推荐）

点 ☰ 菜单里「手机访问」那行的 ⚙：

┌──────────────────────────────────┐
│ 手机访问 · 推送设置 │ │ 推送方式 [Server酱（微信服务号）▾] │ │ 密钥 [••••••••••••••••••••] │ │ 已配置：SCT4••••••••lMZ │ │ 每日上限 [8 ] │
│ [ 测试 ] [ 保存 ] │
│ [ 清除已存密钥 ] │
└──────────────────────────────────┘

- 测试：立刻发一条到你的微信，验证填对没有（用的是输入框里的值，不保存也能测）。
- 密钥存在本机 $DSH_HOME/remote-access/config.json，权限 0600。
- 界面永远不显示密钥原文 —— 已配置时只显示一串掩码（头 4 位尾 3 位）；接口也不提供任何取回原文的途径。

推送：写进 profile 配置（适合批量部署）

在 profile 的 cordis.patch.yml 里覆盖。这里的值优先于界面里存的：

- id: phone-access
config:
cloudflaredPath: '' # 已安装的 cloudflared 路径。留空则查 PATH / 常见位置，都没有才下载 proxyPort: 19389 # 本地代理端口；被占用会自动顺延 rebuildMinutes: 130 # 主动更换隧道的间隔（分钟） autoStart: false # 载入即开启；出于安全默认 false pushKind: serverchan # serverchan | wxpusher | pushplus | webhook pushKey: '' # 对应渠道的密钥 pushCapPerDay: 8 # 每日推送上限，避免触发推送服务的风控

推送渠道

微信没有个人消息接口，只能经推送服务中转：

| pushKind | 说明 | 是否需实名 |
| serverchan | Server酱，消息进微信服务号，微信扫码即得 SendKey | 否 |
| wxpusher | WxPusher，扫码取 SPT | 否 |
| pushplus | pushplus，消息进微信 | 是 |
| webhook | 企业微信群机器人 Webhook 地址 | 否 |

隧道：完全不需要注册

用的是 Cloudflare Quick Tunnel（cloudflared tunnel --url …）：

- 不需要 Cloudflare 账号、不需要域名、不需要任何凭据，也不花钱。
- Cloudflare 免费发一条随机域名，形如 xxx-yyy-zzz.trycloudflare.com。
- 代价是域名每次随机、且隧道会被回收（实测几十分钟到数小时）—— 所以插件会主动重建并把新地址推送给你。
- cloudflared 二进制首次使用时自动从 Cloudflare 官方 Release 下载（约 50MB），不涉及你的任何账号。

顺带做的两件优化

- 静态资源缓存：DSH 的 /assets/ 不带任何缓存头（无 Cache-Control / ETag / Last-Modified），而文件名里已含构建哈希。经隧道访问时，代理为它们补上一年强缓存 —— 否则手机每次打开都要重下约 1.4MB。图片/字体给一天缓存。
- 端口自动顺延：默认端口被占用时自动换一个，不和机器上其它隧道/代理打架。

安全说明

请务必理解这个插件做了什么：
- 默认关闭。只有你手动拨开，才会对外开洞。
- DSH 仍只监听 127.0.0.1。插件不改 DSH 的绑定，也不动防火墙；对外只有那一条隧道。
- 访问要过认证。隧道后面是 DSH 自己的会话 cookie 校验；插件自己的路由同样校验 cookie（按 DSH 的规则验签），未登录一律 401。
- cookie 由本机密钥签发。签名密钥取自 $DSH_HOME/.credentials.yaml，永不打包、永不上传；隧道域名变了会重新签发。派生出来的会话 cookie 通过 /__auth 下发并跳回首页。
- 链接即权限。拿到完整链接的人就能进入你的会话。别发群里、别贴截图、别提交进仓库。
- 隧道是临时的。Cloudflare 免费快速隧道会被回收（实测几十分钟到数小时），插件会主动重建并推送新地址。

如果你不接受「机器上存在一条通往你 DSH 的公网链路」，请不要启用它。

兼容性

- DSH 核心 0.2.0-rc.x（用到 webserver/index-inject 与 webServer.register）。
- Node 20+（用到全局 fetch）。
- Windows / macOS / Linux；cloudflared 按平台自动选择资源。

工作原理（给想改的人）

| 文件 | 作用 |
| lib/index.js | 插件主体：隧道管理、内嵌反向代理、微信推送、HTTP 路由 |
| ui/ui.js | 界面集成：鲸鱼娘光晕/转圈/菜单行，回退图标 |

HTTP 接口（均需会话 cookie）：

GET /remote-access/state 当前状态 POST /remote-access/toggle { on: boolean } GET /remote-access/ui.js 界面脚本 GET /remote-access/push-config 推送配置（只回掩码，不回密钥原文） POST /remote-access/push-config { kind, key, cap } 或 { clear: true } POST /remote-access/push-test 用表单里尚未保存的值发一条测试

几点实现上的坑，写下来省得别人再踩：

1. webserver/index-inject 的行里，kind: 'script' 的 text 会被当作内联 JS 代码包进 …。直接传 会变成嵌套 script，浏览器按内联脚本解析直接语法错误、什么都不会执行。正确做法是传一段内联 JS，由它去 document.createElement('script')（并兼顾 document.body 尚未就绪）。
2. DSH 的主连接是 WebSocket（/api/remote.mux）。代理必须处理 upgrade 并双向管道，否则界面永远停在「重新连接中」。
3. COOKIE_PREFIX 是 dsh-auth-，不是 dsh-。名字错了签名再对也验不过。
4. 加载中不要用 transform: rotate() 让元素转圈，那会覆盖它自身的 transform。用 CSS 的 rotate 属性，两者可叠加。

License

MIT

致谢

- 界面挂在 dsh-whale-widget（MIT）上协同工作，但不包含也不复制它的任何代码。
- 隧道由 cloudflared 提供。