给桌面应用做局域网手机远控:relay、配对与防火墙
桌面应用原本只有云端远控:手机扫码,经厂商 relay 连回桌面。一旦本地分支屏蔽了官方账号,这条路就断了。可行的替代是在桌面进程里内置一个局域网 relay,让手机浏览器直接连过来。
看起来是「起个 HTTP 服务」,实际做下来,难点在协议边界、配对语义和「不要替用户改防火墙」这三件事。
一、先摸清云端远控的架构
不要一上来就写 relay,先读现有实现:
- 手机页面不是独立 Agent,而是通过 relay 挂到桌面已存在的 Window Host 上;手机只负责收发界面消息;
- 桌面侧启动链路:生成一次性内部票据(绑定
windowId + workspaceKey + remoteSessionId)→ 读账号 JWT(没有就停在auth-required,不注册、不建连、不显示二维码)→POST /api/v1/remote/device换device_sid→ 每次连接前申请一次性role=devicetoken(60 秒、用后作废)→ 连ws2?token&mid并发auth_init; - 二维码只包含
/remote/v4?app_version=&sid=&mid=&name=,不含 JWT、token、hash; - 手机侧选可 bridge 的 workspace 后发
workspace-bridge-open,桌面校验workspaceKey、remoteSessionId已连接、远程身份与 Host 绑定一致,目标必须在该窗口已打开,然后建MessagePortattachment。
这套设计里有两个可以直接复用的原则:票据一次性、身份与窗口绑定。自建 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、流控,缺一个都会在大消息或弱网下暴露;
- 配对语义:一次性还是可替换,取决于产品,不取决于实现方便;
- 系统边界:防火墙、提权、系统配置属于用户,应用只给提示,不代改。
最后一句:先读现有远控的架构,再决定自建哪一层。这次能两天做完,是因为云端协议的「一次性票据 + 身份绑定窗口」可以直接复用,而不是从零设计一套。