一、为什么扫地机离不开云端？

Roborock Local Server 是一个开源的本地 HTTPS 和 MQTT 云端模拟器，它能把 Roborock（石头科技）扫地机的所有云端请求重定向到你局域网里的服务器，无需 root、无需拆解硬件，即可让扫地机、实时地图和本地控制完全脱离官方云。

要理解它怎么做到这一点，先要知道扫地机与官方云之间的三条通信链路：

🔒 过去的两个"枷锁"：

1. 地图被云锁定—— 尽管地图数据就存在扫地机本地，但 Roborock 强制所有地图请求走官方云服务器；
2. 云端健康检查—— 一旦扫地机连不上官方服务器，它会反复重启自己的网络接口，本地通信随之中断。

Local Server 的思路就是：在配对阶段"接管"扫地机，让它把 REST 和 MQTT 的目的地都指到你的本地服务器。

二、逆向工程全链路：从抓包到公钥恢复

下面按项目 docs/technical_writeup.md 中作者本人的逆向笔记，还原整条技术路线。

1. 抓包逆向：摸清 onboarding 协议

最初团队使用 mitmproxy 抓取全部 REST 报文和加密的 MQTT 消息，再用 Wireshark + rvictl 让 iPhone 流量经过 Mac，观察本地 TCP 连接上部分明文消息。这条路线搞清了基础流程，但当不同机型的参数、方法各不相同时就触及了天花板。

随后转向App 逆向：用 jadx 反编译 Roborock APK 得到 onboarding 与 REST 请求的基础逻辑；再用 python-roborock 的函数下载任意机型的 React Native bundle（Hermes 字节码），用 hermes-dec 反编译后拆分成约 3000 个可读的 JS 文件，拿到各机型的命令、属性和状态码。

💡 关键洞察：配对流程是控制一切的入口。作者用自己的电脑模拟手机/扫地机两端，反复往返抓包，最终完整复现了 onboarding 流程：

1. 手机生成密钥对，向扫地机发送hello和自己的公钥；
2. 扫地机用该公钥加密返回会话密钥；
3. 手机用会话密钥（AES 加密）下发 Wi-Fi 配置和token（含地区码r）；
4. 扫地机把地区码注入模板api-%s.roborock.com，然后请求/region端点，附带设备 ID、产品 ID、nonce 和一个RSA 签名（signature）。

2. 关键转折：向扫地机注入自定义 URL

配对报文中的地区码会被注入 URL 模板，而扫地机对注入内容没有长度限制、也不做任何净化。作者把token.r设为myserver.domain.com/，扫地机请求的地址就变成了自己控制的服务器 —— 域名注入成功！

但当时的死胡同在于：官方服务器返回的 region 信息是用存放在 Roborock 服务器上的公钥加密的，本地没有这把公钥，扫地机就不认你的响应。而私钥又锁在扫地机固件里（root + 刷自定义固件才能拿到）。这条路在 2025 年初被判了"死刑"。

3. 神来之笔：用 GCD 从签名里恢复公钥

2026 年作者借助 AI Agent 重新出发：给 Agent 提供 root 后的 S7 SSH 权限、固件文件、python-roborock 库、APK 反编译结果，以及把固件跑进 QEMU ARM chroot 的模拟器，让 Agent 可以在本地反复验证假设。Agent 最终指出突破口就在/region请求里的那个signature参数。

数学原理其实很巧妙：

• RSA PKCS#1 v1.5 签名是确定性的：sig = pad(SHA256(msg))^d mod n，其中pad()是固定的 ASN.1 前缀 + 哈希；
• 验证等式为sig^e mod n == pad(SHA256(msg))，公开指数e = 65537；
• 已知sig、可自行计算pad(SHA256(msg))，唯一的未知数是模数n（即公钥本体）；
• 变形得sig^e - pad(SHA256(msg)) = k * n，也就是差值是n的整数倍；
• 收集两条不同查询串带签名的请求，各算一次差值，再取最大公约数（GCD），剔除小素因子后就是n。

一句话总结：不需要私钥，不需要破解 RSA，只需要两条带签名的请求和一次 GCD。

拿到模数后，用n + e=65537重建完整公钥，就能像官方服务器一样加密 bootstrap 响应，扫地机完全无法分辨。这部分实现位于 device_key_recovery.py，使用 gmpy2 处理 2048 位大数运算。

4. MQTT 桥接：最"简单"的一环

TLS 证书问题因为域名是自己注入的而变得平凡。真正有意思的是 MQTT 消息路由。每台设备有 4 类主题：

• rr/d/i/{did}/{mqtt_user}—— 扫地机 → 服务器
• rr/d/o/{did}/{mqtt_user}—— 服务器 → 扫地机
• rr/m/i/{...}/{userid}/{duid}—— 用户（App）→ 服务器
• rr/m/o/{...}/{userid}/{duid}—— 服务器 → 用户

所谓"云端"做的核心事情，就是把rr/m/i上的消息转发到对应的rr/d/o，把rr/d/i上的消息转发到rr/m/o。这个桥接逻辑实现在 topic_bridge.py，用两条正则分别匹配两类主题即可完成转发。

5. 官方 App 重定向

最后让手机端也"入伙"：用 MITM 抓取 App 登录时返回的 user data（内含所有 Roborock 服务器 URL），把 URL 全部改写成你的本地服务器地址，App 后续所有 API 调用就都打向本地了，之后可以关掉 MITM。项目提供 mitm_redirect.py 脚本完成这一步，详见 docs/roborock_app.md。

三、项目结构：每个"机关"在哪里

如果你想对照源码理解整套机制，这几个位置最值得看：

• bootstrap 路由（扫地机配对时请求的/region、/nc、/time等端点）：routes/bootstrap/
  • 其中 region.py 和 nc_prepare.py 就是 URL 注入后扫地机最先打到的接口，响应会用恢复出的公钥加密。
• 公钥恢复算法：device_key_recovery.py，签名采样、GCD 求模数、公钥验证都在这里。
• MQTT Broker 与主题桥：mqtt_broker_server/ 提供 TLS MQTT 服务，topic_bridge.py 负责rr/d/*与rr/m/*的双向转发。
• 本地 API 路由表：endpoint_rules.py 集中注册了 v1~v5 的登录、用户、设备、场景等全部端点，相当于"迷你 Roborock 云"的路由索引。
• 配对脚本（在第二台电脑上运行）：start_onboarding.py 与 Web 版 start_onboarding_gui.py。

四、快速上手：从克隆到配对完成

⚠️ 前置要求：一个你拥有的域名（子域名需以api-开头，如api-rr.example.com）、能改写本地 DNS 的网络（Pi-hole / AdGuard Home / 路由器）、以及一台用于配对的辅助电脑。

1. 安装—— 按 docs/installation.md 用 Docker Compose 或 Home Assistant 插件方式部署，并先用 admin 面板完成云端数据导入（家庭、房间、已知设备清单）。注意主机名去掉api-前缀后加:端口/不能超过 32 字符，短域名更安全。
2. 选择证书路径—— 不同机型信任不同的证书链，先查 docs/tested_vacuums.md；多数用户选 ZeroSSL，老机型可考虑 Actalis。
3. 运行配对—— 在第二台电脑上执行引导脚本（详见 docs/onboarding.md）：

   uv run start_onboarding.py --server api-rr.example.com

   脚本会提示你重置扫地机 Wi-Fi、切到扫地机热点、再切回家用 Wi-Fi，然后轮询服务器等待签名样本增加、公钥恢复完成。

4. 观察结果—— 首次配对通常会增加签名采样数；若公钥尚未确定，再跑 1~3 个配对周期，直到提示 "Public Key determined" 且扫地机显示已连接本地服务器。
5. 手机 App 接入—— 按 docs/roborock_app.md 完成官方 App 重定向，或改用开源的 LocalRock 直连。

✅ 至此，扫地机的 REST、MQTT 流量全部落在你的局域网里。想撤回？重置扫地机 Wi-Fi 即可回到出厂配对模式，整个过程可逆且风险极低。

五、已知限制与兼容性

• 暂不支持入门级 Q 系列（如 Q7，注意不是 QRevo），因为证书校验方式不同；
• 固件更新、定时任务（Schedules）暂不可用；场景（Routines/Scenes）正常；
• 国行机型在境外使用会被固件rrcheck区域校验拒绝；
• 相机直播流需配合 TURN 中继，仅验证过 Saros 10R 和 Qrevo MaxV。

完整清单见 docs/known_limitations.md。

写在最后

这套方案最精妙之处在于它是一个"零风险利用"：攻击面需要物理接触扫地机和你的局域网，且几秒即可撤销。作者也坦承——Roborock 本可以让地图请求走本地连接，让设备 100% 离线工作。Local Server 用一次教科书级的协议逆向（确定性签名 + GCD 公钥恢复），把这件事变成了现实。如果你想动手，从 docs/index.md 的文档索引开始即可。