手机同步 · DSH Mobile Sync
源码仓库：https://github.com/Wystan68/dsh-mobile-sync
在 DSH Web GUI 的左侧栏增加一个「手机同步」入口。点开后显示配对二维码；手机和电脑在同一局域网时可以扫码，电脑没有公网 IP 时也可以通过 Cloudflare 公网隧道从任意网络访问。
二维码现在打开的是一个可安装的手机 App 页面（PWA），不是直接打开桌面版网页：首页默认打开相机扫码，配对后把设备令牌保存在手机上，下次自动连接；电脑端和手机端都可以管理多台已配对设备。竖屏全宽、底部标签栏、抽屉式会话列表、适配输入法，手机连上的仍然是电脑上的同一套 DSH，会话、模型、工具和执行环境都不变。
Android 客户端也内置了原生扫码（不依赖网页相机），因此在局域网 HTTP 地址下仍可配对；配过多台电脑后，首页会变成电脑列表，可以逐台切换、重命名和删除。
使用
- 刷新 DSH Web GUI，点击左侧栏的电话图标。
- 手机相机扫描二维码，会打开手机 App；首次会自动完成配对。已配对过其他电脑时，也可以从首页的「设备」里重新扫码添加。
- 在手机浏览器里选择「添加到主屏幕」，之后从主屏幕打开，配对信息会保留，直接进入工作台。
- 电脑端面板会显示当前公网/局域网状态和已配对设备列表。可以单独重命名、断开某台手机；「重新生成配对码」会让所有手机和旧链接立即失效。
公网和局域网使用同一个二维码：公网隧道就绪时指向 https://<随机名>.trycloudflare.com/mobile-app/，否则回退到 http://<局域网 IP>:<端口>/mobile-app/。
手机 App 的操作方式
- 首页：打开相机扫描配对二维码；已配对时显示「进入工作台」和「管理设备」。手动输入配对链接是相机不可用时的兜底。
- 底部四个标签：对话（回到当前对话和输入框）、新对话、会话（从左侧滑出会话/工作区抽屉）、设备（已配对设备列表、重命名/断开、重新扫码、重新连接、安装、断开本机）。
- 电脑端「手机同步」面板有同样的设备列表：每台手机有独立名称和最近活跃时间，可以逐台断开，也可以全部断开。
- 工作台本身仍是完整的 DSH；手机壳只负责导航、配对和 PWA 安装，不复制业务逻辑。
- 配对后电脑会签发一枚 256 位设备令牌，保存在手机浏览器的
localStorage；电脑端只保存令牌的 SHA-256 哈希，配对 Cookie 是 HttpOnly。Cookie 过期后 App 会用保存的令牌自动重新登录。
- 「断开这台手机」只撤销当前设备；「重新生成配对码」会让所有手机失效。配对二维码本身是可重复使用的邀请，撤销某台手机后它仍可能重新扫码加入，因此彻底清理时要同时轮换邀请。
安装到主屏幕
- iPhone / iPad：Safari 打开 App → 分享 → 添加到主屏幕。需要 HTTPS 入口（公网二维码满足；局域网 HTTP 地址通常不能安装）。
- Android：Chrome 菜单 → 安装应用 / 添加到主屏幕。
- 也可以使用仓库内的 Android WebView 壳工程构建 APK；没有 Xcode / Android SDK 的电脑仍然可以直接用 PWA，后续升级只需刷新页面。
更新插件时
只改 mobile/ 下的页面、样式或脚本时，手机刷新页面即可；改到 proxy.js、index.js 等电脑端代码时，需要在 DSH 的插件管理器里把「手机同步」停用再启用（或重启 DSH），主机端路由才会重新加载。只刷新手机页面会继续使用旧的主机端路由。
公网访问
本机不需要公网 IP，也不需要在路由器上做端口映射。插件启动一个出站的 cloudflared Quick Tunnel，Cloudflare 分配一个临时的 HTTPS 地址，再把请求转发回本机的配对代理。
- 只建立出站连接；电脑不监听公网端口。
- 使用
--protocol http2（TCP 443）建立隧道，避免部分网络封 QUIC/UDP 导致隧道注册不上。
- 手机到 Cloudflare 是 HTTPS；Cloudflare 到本机是本地回环/局域网 HTTP。
- 临时地址在插件或 DSH 重启后会变化，二维码随之更新。
- 隧道断开时插件会自动重连几次；仍失败时面板会显示错误和「重试公网隧道」按钮。
- Quick Tunnel 没有可用性保证；Cloudflare 侧偶尔会出现 530 / DNS 未就绪，重试隧道或稍等即可。如果需要固定域名，按下文配置 Cloudflare named tunnel。
首次使用需要安装 cloudflared：
brew install cloudflared
插件会自动查找 /opt/homebrew/bin/cloudflared、/usr/local/bin/cloudflared 和 PATH；也可以通过 cloudflaredPath 指定。
固定公网地址（Cloudflare named tunnel）
Quick Tunnel 适合临时使用；如果你有 Cloudflare 账号和域名，可以让插件自动创建 named tunnel、写入 ingress、创建 DNS 记录，并得到一个固定的 https://<你的域名>/ 地址。手机 App 的主屏幕图标就不会因为隧道重启而失效。
最简方式：在插件页面填写
打开 DSH 侧栏的「手机同步」面板，滚到 固定公网地址：
- 打开「使用固定公网地址」开关；
- 填入 Cloudflare API Token；
- 填入公网域名，例如
dsh.example.com；
- Zone 可留空自动匹配，也可以填
example.com；
- 如果自动查找失败，把 Cloudflare 域名 Overview 右侧的 Zone ID 填到「Zone ID（可选）」；
- 保持「自动创建/更新 DNS 记录」勾选，点「保存并应用」。
保存后不需要重载插件：插件会立即停止旧隧道、创建/复用 named tunnel、写 ingress 和 DNS、启动新隧道，二维码会自动切到 https://dsh.example.com/mobile-app/。关闭开关再保存，会回到临时 Quick Tunnel。
- Token 保存在 DSH 凭据存储中，不会回显到页面或状态接口；输入框留空表示保留已保存的 Token。
- 页面保存的配置优先于
cordis.patch.yml；点「恢复插件配置」可丢弃页面配置，重新使用 YAML 里的配置。
- 同名 DNS 默认不覆盖；确认后才勾选「允许覆盖同名 DNS」。
如果提示“找不到 xxx 对应的 Cloudflare zone”
这通常不是隧道本身的问题，而是 API Token 看不到这个域名：
-
在 Cloudflare 控制台左上角切换到拥有该域名的账号，打开「网站 / Websites」，确认 example.com 在列表里且状态是 Active；
-
如果域名在另一个 Cloudflare 账号，必须到那个账号里重新创建 API Token，Token 不能跨账号；
-
编辑 Token，确认权限和资源范围：
- Account → Cloudflare Tunnel → Edit
- Zone → DNS → Edit
- Zone → Zone → Read
- Zone Resources 选择 All zones，或 Specific zone → example.com；
-
仍然失败时，在 example.com 的 Overview 页面右侧复制 Zone ID，填到面板的「Zone ID（可选）」再保存；这会让插件跳过按域名列表查找，直接查询该 Zone；
-
可在电脑终端验证 Token（不要把 Token 发到聊天里）：
curl -sS "https://api.cloudflare.com/client/v4/zones?name=example.com" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
result 为空 = Token 看不到这个域名；HTTP 403 = Token 权限或 IP 限制有问题。
建议公网主机名使用子域名，例如 dsh.example.com，Zone 填 example.com。如果想直接用根域名 example.com，要确保它没有和现有 A/AAAA/CNAME 记录冲突。
1. 创建 API Token
在 Cloudflare Dashboard → My Profile → API Tokens → Create Token → Custom token，权限至少包含：
| 权限 | 用途 |
|---|
| Account · Cloudflare Tunnel · Edit | 创建/复用隧道、写 ingress、取 tunnel token |
| Zone · DNS · Edit | 创建/更新 CNAME |
| Zone · Zone · Read | 自动匹配域名对应的 zone |
Account resources 选你的账号；Zone resources 选对应域名。API Token 只在插件启动/重试时使用，不会写进状态接口或二维码。
2. 用 YAML 配置（可选）
编辑当前 profile 的 cordis.patch.yml（通常在 ~/.dsh/profiles/<profile>/cordis.patch.yml），在文件末尾追加：
- id: mobile-sync
config:
enabled: true
port: 57752
publicAccess: true
cloudflare:
apiToken: '你的 API Token'
hostname: 'dsh.example.com'
zone: 'example.com'
tunnelName: 'dsh-mobile-sync'
manageDns: true
overwriteDns: false
然后刷新/重载插件。插件会自动：
- 在账号里查找名为
dsh-mobile-sync 的隧道，没有就创建；
- 把该隧道的 ingress 指向本机配对代理（
http://<局域网 IP>:<端口>）；
- 在
example.com 创建 dsh.example.com 的 CNAME，指向 <tunnel-id>.cfargotunnel.com，并开启 Cloudflare 代理；
- 用
cloudflared tunnel run 启动 named tunnel；
- 把二维码/手机 App 地址切换为固定的
https://dsh.example.com/mobile-app/。
重复重载是幂等的：已有隧道和 DNS 会复用，不会重复创建。局域网的 IP 变化后，ingress 仍指向旧 IP；重载插件会重新写入当前 IP，或者重新点一次「重试公网隧道」。
3. 字段说明
| 字段 | 必填 | 说明 |
|---|
apiToken | 是（API 模式） | Cloudflare API Token；也可以用环境变量 CLOUDFLARE_API_TOKEN |
hostname | 是 | 完整公网域名，例如 dsh.example.com；不要带 https:// |
zone | 否 | zone 根域名，例如 example.com；不填会自动匹配 |
zoneId / accountId | 否 | 已知 ID 时可直接填，省去查询 |
tunnelName | 否 | 默认 dsh-mobile-sync；已有隧道会复用 |
manageDns | 否 | 默认 true；设为 false 则只配 ingress，不碰 DNS |
overwriteDns | 否 | 默认 false；已有同名 CNAME 指向别处时默认报错，避免覆盖现有服务 |
hostname 也可以写成子域名前缀（如 dsh）并同时填 zone，插件会拼成 dsh.example.com。
4. Token-only 模式
如果隧道和 DNS 已经在 Cloudflare 后台配好，也可以只给运行 Token：
cloudflare:
tunnelToken: 'cloudflared tunnel token'
hostname: 'dsh.example.com'
manageDns: false
这种模式不会调用 Cloudflare API，也不会自动改 DNS/ingress；需要你已在后台把 Public Hostname 指向本机代理，并保证 DNS 已存在。
5. 环境变量方式（不把 Token 写进 YAML）
插件也读取：
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_HOSTNAME=dsh.example.com
CLOUDFLARE_ZONE=example.com
CLOUDFLARE_ZONE_ID=...
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_TUNNEL_NAME=dsh-mobile-sync
或者用 CLOUDFLARE_TUNNEL_TOKEN 走 token-only 模式。环境变量优先级低于配置文件里的非空值。
如果该域名启用了 Cloudflare Access，请为手机 App 的路径（至少 /mobile-app/* 和 DSH 的 /）配置 Bypass 或合适的 Service Auth；否则 App 内 iframe 会被 Cloudflare 登录页拦截。Cloudflare WAF 的自定义规则也可能拦截 WebSocket/长连接，遇到问题先检查 Security Events。
API Token 等同于账号权限。YAML 是明文，建议 chmod 600 该文件；不要把填好的配置提交到仓库。DNS 冲突时默认不会覆盖，确认后再把 overwriteDns 设为 true。
安全模型
- 代理仍然只监听一个具体的局域网 IPv4 地址（或回环地址），不使用
0.0.0.0。
- 配对二维码包含一枚 256 位邀请密钥；扫码后电脑为这台手机单独创建设备记录，签发一枚新的 256 位设备令牌。首次访问后换成
HttpOnly、SameSite=Strict 的 Cookie，公网 HTTPS 下额外带 Secure。Cookie 有效期一年。
- 电脑端设备表只保存令牌的 SHA-256 哈希、设备名、最近活跃时间和 IP；状态接口不会回传哈希或令牌。
- 手机端不会拿到 DSH 的 loopback 登录 Cookie；代理在 Host 侧持有它，并在转发时注入。
- 手机 App 的 HTML/CSS/JS/图标是公开静态资源，里面不含配对密钥；邀请密钥只存在于二维码的 URL fragment，设备令牌只存在于手机本地存储。URL fragment 不会发送给服务器。
- 手机上的设备令牌等同于该手机的访问凭证；丢失手机时，在电脑端设备列表里单独断开它，或轮换配对码让全部设备失效。
- 转发时把
Host / Origin 改写成 loopback，DSH 原有的浏览器信任检查仍然生效。
- 所有
/mobile-sync/api/* 管理接口只允许 DSH owner 调用，并且不会经代理暴露给手机。
- 二维码等同于这台电脑的控制权限。公网访问经 Cloudflare TLS 隧道，但链接本身仍是唯一凭证；不要截图或转发。
配置
默认值写在 cordis.patch.yml：
| 字段 | 默认 | 说明 |
|---|
enabled | true | 是否启动配对代理 |
port | 57752 | 代理端口；被占用时自动改用系统分配端口 |
publicAccess | true | 是否启动 Cloudflare 公网隧道；设为 false 仅保留局域网 |
bindHost | 自动检测 | 可指定一个具体局域网 IPv4；留空自动选择 en0 / 私网地址 |
cloudflaredPath | 自动查找 | cloudflared 可执行文件的绝对路径 |
代理监听地址和公网地址都只用于本机转发；公网入口是 Cloudflare 分配的随机域名。
实现
index.js：Host 插件；启动代理和隧道、持久化配对密钥、提供状态与轮换接口、生成二维码。proxy.js：HTTP / WebSocket 反向代理；配对 Cookie、Host/Origin 改写、DSH 登录 Cookie 注入与 401 重试、公网转发协议识别。tunnel.js：cloudflared 子进程管理；支持 Quick Tunnel 和 named tunnel token 两种模式，自动重连、退出清理；默认使用 HTTP/2 传输。cloudflare.js：用 API Token 自动创建/复用 named tunnel、写 ingress、创建 CNAME、获取 tunnel token；不把 Token 放进状态输出。qr.js：内置 QR Code Model 2 编码器（byte 模式、ECC M、版本 1–10、自动掩码），不依赖第三方包。client.js：左侧栏图标 + 主面板；通过 owner-only HTTP 接口读取状态。mobile/：可安装手机 App（PWA）；首页相机扫码 / 手动配对、设备令牌持久化、多设备管理、底部导航、抽屉、Service Worker、图标。App 用同源 iframe 承载 DSH，并注入 mobile/inject.css 把桌面三栏改成手机单栏 + 抽屉；对话气泡、输入框和安全区做了移动端排版。android/：原生 WebView 客户端 + ZXing 扫码；首次启动直接扫码，本地保存多台电脑档案，可切换/重命名/删除。locale/*.json、icon.svg：插件管理器和设置页的显示资源。
限制
- 公网 Quick Tunnel 是临时地址；插件/DSH 重启后会变化。已经安装到主屏幕的 App 绑定旧域名；域名变化后旧图标会打不开，需要用电脑上新二维码重新打开并重新添加。这是临时隧道方案的主要限制。
- 需要固定地址和可长期使用的主屏幕图标，可配置 Cloudflare named tunnel + 自有域名（见上文），插件会自动创建隧道和 DNS；也可以做真正的原生 App。
- Quick Tunnel 没有 SLA，Cloudflare 可能限流或短时 530；长期使用建议 named tunnel。
- 公网流量在 Cloudflare 边缘终止 TLS；对端到端隐私有更高要求时，应使用自己的隧道/域名方案。
- 电脑休眠、断网或
cloudflared 退出时，公网地址不可用；插件会自动重试几次。
- 局域网内仍是 HTTP；浏览器安全上下文限制下，网页无法调用相机。所以局域网 HTTP 地址请使用 Android App 的原生扫码，或粘贴配对链接；公网 HTTPS 地址可以直接在网页里扫码。PWA 的 Service Worker/安装也通常要求 HTTPS，安装到主屏幕请优先用公网 HTTPS 地址。
- iOS 可能把主屏幕 App 的存储与 Safari 隔离；如果安装后仍显示连接页，在 App 内粘贴一次电脑上的配对链接即可。
- 手机端的设备列表使用当前设备的配对权限读取；能看到并断开同一台电脑上的其他手机。它不会暴露其他电脑或 DSH 的管理接口。
Android APK（可选）
仓库内包含一个轻量的 Android WebView 客户端，源码在 android/。它不是把 DSH 打包进手机，而是一个可安装的外壳：电脑上的 DSH 仍需要运行，手机通过局域网或 Cloudflare 公网地址连接。
构建要求：
- JDK 17
- Android SDK Platform 34
- Android Build Tools 34.0.0
首次打开 APK 会直接进入相机扫码；识别电脑上的二维码后自动保存这台电脑并打开工作台。之后再打开会显示已配对电脑列表，可以添加多台、切换、重命名和删除。相机不可用时可以手动输入地址或完整配对链接。APK 内置 ZXing 离线解码，不依赖 Google Play Services；签名密钥不会提交到仓库。
详细构建命令见 android/README.md。
开发与测试
项目没有运行时 npm 依赖。Node.js 22+：
node test/proxy.test.mjs
node test/devices.test.mjs
node test/host.test.mjs
node test/tunnel-wiring.test.mjs
node test/cloudflare.test.mjs
node test/cloudflare-config.test.mjs
node test/cloudflare-wiring.test.mjs
node test/tunnel-named.test.mjs
也可以一次运行：
for file in test/*.test.mjs; do node "$file" || exit 1; done
安全
- 配对链接等同于电脑控制权限，不要截图、转发或提交到仓库。
- Cloudflare API Token、Tunnel Token、
android/*.keystore、.env 和本地 DSH profile 配置都不应提交。
- 如果发现安全问题，请通过 GitHub Security Advisories 私下报告，不要在公开 issue 中贴 Token 或配对链接。
- 本项目按 MIT License 发布，见 LICENSE。
