给桌面应用做局域网手机远控:relay、配对与防火墙

桌面应用原本只有云端远控:手机扫码,经厂商 relay 连回桌面。一旦本地分支屏蔽了官方账号,这条路就断了。可行的替代是在桌面进程里内置一个局域网 relay,让手机浏览器直接连过来。

看起来是「起个 HTTP 服务」,实际做下来,难点在协议边界、配对语义和「不要替用户改防火墙」这三件事。

一、先摸清云端远控的架构

不要一上来就写 relay,先读现有实现:

  • 手机页面不是独立 Agent,而是通过 relay 挂到桌面已存在的 Window Host 上;手机只负责收发界面消息;
  • 桌面侧启动链路:生成一次性内部票据(绑定 windowId + workspaceKey + remoteSessionId)→ 读账号 JWT(没有就停在 auth-required,不注册、不建连、不显示二维码)→ POST /api/v1/remote/device 换 device_sid → 每次连接前申请一次性 role=device token(60 秒、用后作废)→ 连 ws2?token&mid 并发 auth_init;
  • 二维码只包含 /remote/v4?app_version=&sid=&mid=&name=,不含 JWT、token、hash;
  • 手机侧选可 bridge 的 workspace 后发 workspace-bridge-open,桌面校验 workspaceKey、remoteSessionId 已连接、远程身份与 Host 绑定一致,目标必须在该窗口已打开,然后建 MessagePort attachment。

这套设计里有两个可以直接复用的原则:票据一次性、身份与窗口绑定。自建 relay 不需要照抄云端协议,但这两条要保留。

二、本地 relay:三个端点就够

桌面进程内起一个 HTTP + WS 服务:

  • GET / 或固定路径 → 返回打包进应用的手机页面(静态资源);
  • POST /api/v1/remote/device → 设备注册,返回 device_sid;
  • GET /ws → WebSocket,auth_init 后进入 pair / data 状态机。

监听 0.0.0.0 一次覆盖所有网卡(Wi-Fi + ZeroTier 虚拟网卡),来源只接受 RFC1918、100.64/10 与 loopback。固定端口(这次用 47821)比动态端口好排查,但要在设置页显示当前可用地址。

手机页面用 vite build --base=/remote/v4/ 构建、同源托管,避免跨域与「页面里写死别的 relay 地址」的问题。构建产物直接打进桌面包,随应用版本走。

三、传输层:分片与流控不能省

WebSocket 单帧有大小限制,而任务输出可能很大。协议里要显式定义:

  • 单逻辑消息最多 16 MiB / 64 片,单物理帧(含外层 JSON)≤ 1 MiB;
  • 每片带 messageSeq / fragmentIndex / fragmentCount / CRC32,接收端按序号重组并校验;
  • rpc-frame-ack 用累积 ACK;
  • 1 MiB / 256 KiB 高低水位做流控,重放上限 32 MiB / 45 秒;手机端 buffer 超 500 ops 或 1 MiB 就清空转 resync。

这些数字不是拍脑袋:没有分片,大消息会直接断连;没有累积 ACK,重连后无法判断从哪里续。

四、配对语义:一次性 vs 可替换

第一版把配对码做成「用后即焚」,结果验收「第二台手机替换第一台」直接失败——回看二维码时码已经失效。

正确的语义取决于产品形态:

  • 如果一台桌面只允许一台手机,配对码应该在远控生命周期内可重复使用,停止远控时统一撤销;
  • 如果要做「替换设备」,再加一个「刷新二维码」动作:生成新的随机 6 位码,同时断开已配对手机,旧码立即失效。

错误提示也要区分:码错了是「配对码无效」,远控停了是「配对已失效,请重新扫码」,地址变了是「地址不可用」。用户看到的文案决定他下一步做什么。

五、防火墙:提示,不要代改

这是这次最容易做错的地方。

一开始在启动时调 firewall-cmd --state 做检测,结果在 Fedora 45 上每次启动都弹管理员密码——firewalld 2.5.2 把这个查询归到 org.fedoraproject.FirewallD1.config,默认策略是 auth_admin_keep。用户每次开应用都要输密码,体验直接崩。

最终做法是删掉全部防火墙探测:

  • 设置页与对话框里给出按平台的手动命令(firewall-cmd --add-port=47821/tcp、ufw allow 47821/tcp);
  • 连接失败时提示「检查防火墙是否放行该端口」,而不是尝试自己改;
  • 不申请提权、不写系统配置。

理由很简单:改防火墙是用户的系统级决策,应用没有资格静默代劳;而一次查询就可能触发提权弹窗,代价比收益大。

六、验证:同源、零外部请求

本地静态托管的验证要看到「真的什么都没发出去」:

  • 手机页面加载后,Chrome DevTools 里 62 个请求全部命中本机地址,零外部请求、零 404;
  • 未登录状态下没有发出任何 /api/v1/remote/* 或云端 relay 请求——证明登录门禁在 token/设备请求之前;
  • 指定 ZeroTier 地址后,二维码与手机连接都走该网卡;
  • 关闭远控时 relay 撤销、已配对连接断开。

还要补一条:verify:pre-push 通过不代表测试真的跑了。这次门禁里 test:engineering:affected 因「选中全量」被脚本主动跳过,得单独补跑 relay 与设置分区的 16 个用例。

总结

给桌面应用做局域网远控,核心不是「起一个 WebSocket 服务」,而是三件事:

  • 协议边界:分片、CRC、累积 ACK、流控,缺一个都会在大消息或弱网下暴露;
  • 配对语义:一次性还是可替换,取决于产品,不取决于实现方便;
  • 系统边界:防火墙、提权、系统配置属于用户,应用只给提示,不代改。

最后一句:先读现有远控的架构,再决定自建哪一层。这次能两天做完,是因为云端协议的「一次性票据 + 身份绑定窗口」可以直接复用,而不是从零设计一套。